feat: update onboarding

Author: cucupac

README.md

@@ -43,6 +43,8 @@ If you use the user-level install, ensure your user Python bin is on `PATH`:
 export PATH="$(python3 -m site --user-base)/bin:$PATH"
 ```
 
+For Codex Desktop and similar tool shells, put both the PATH export and `SHELLBRAIN_DB_DSN` in `~/.zprofile`, not `~/.zshrc`, so non-interactive login shells can see them.
+
 ## Bootstrap
 
 Export `SHELLBRAIN_DB_DSN` from your shell profile, then apply packaged migrations once:
@@ -52,6 +54,18 @@ export SHELLBRAIN_DB_DSN='postgresql+psycopg://shellbrain:shellbrain@localhost:5
 shellbrain admin migrate
 ```
 
+When running Shellbrain from Codex Desktop or a similar tool shell, treat this as the normal startup pattern:
+
+```bash
+zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'
+```
+
+Then use the same wrapper shape for actual invocations if needed:
+
+```bash
+zsh -lc "source ~/.zprofile >/dev/null 2>&1; shellbrain read --json '{\"query\":\"Have we seen this migration lock timeout before?\",\"kinds\":[\"problem\",\"solution\",\"failed_tactic\"]}'"
+```
+
 ## Migrate Existing Local Postgres
 
 If your local Docker-backed Postgres is still the older `memory-postgres` setup, run:

docs/external-quickstart.md

@@ -27,6 +27,8 @@ python3 -m pip install --user --break-system-packages --editable /absolute/path/
 export PATH="$(python3 -m site --user-base)/bin:$PATH"
 ```
 
+For Codex Desktop and similar tool shells, put that PATH export and `SHELLBRAIN_DB_DSN` in `~/.zprofile`, not `~/.zshrc`, so non-interactive login shells can see them.
+
 ## Bootstrap
 
 Set this once in your shell profile, then apply migrations:
@@ -36,6 +38,20 @@ export SHELLBRAIN_DB_DSN='postgresql+psycopg://shellbrain:shellbrain@localhost:5
 shellbrain admin migrate
 ```
 
+## Codex Startup Pattern
+
+When running Shellbrain from Codex Desktop or a similar tool shell, treat this as the normal startup step:
+
+```bash
+zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'
+```
+
+Then use the same wrapper shape for real commands when needed:
+
+```bash
+zsh -lc "source ~/.zprofile >/dev/null 2>&1; shellbrain read --json '{\"query\":\"Have we seen this migration lock timeout before?\",\"kinds\":[\"problem\",\"solution\",\"failed_tactic\"]}'"
+```
+
 ## Query First, But Query Precisely
 
 Shellbrain `read` uses lexical retrieval plus semantic similarity. Query it with the concrete problem, subsystem, constraint, or decision you are working on. Do not start with vague prompts like "what should I know about this repo?"

next_steps.md

@@ -162,7 +162,43 @@ This is worth exploring because a supervisor loop could reduce protocol entropy
   - decide later whether git-root inference is worth adding
 - Consider making first-run embedding downloads less surprising on the `read` path.
 
-### 8. Agent-Facing Context Pack Metadata
+### 8. Product Ideas Worth Borrowing
+
+- MoltBrain is worth treating as a useful comparison point for operator experience, not as a blueprint for Shellbrain's trust model.
+- Borrow the parts that improve discoverability, observability, and day-to-day usability without giving up Shellbrain's explicit evidence discipline.
+
+Near-term product ideas worth borrowing:
+
+- make the install and bootstrap path feel more like a polished user tool:
+  - prefer a crisp global-install story
+  - consider a `shellbrain doctor` or equivalent environment check
+  - make database/bootstrap state easier to verify at a glance
+- add a proper operator-facing viewer:
+  - browse memories by repo, kind, and recency
+  - inspect evidence links and utility history
+  - inspect what a read returned and why
+  - inspect episodes and episode events without raw SQL
+- add analytics and export surfaces:
+  - session-level usage summaries
+  - memory creation / retrieval / utility trends
+  - lightweight export for backup, analysis, or sharing
+- add curation affordances where they help humans manage the corpus:
+  - favorites / pins for especially important memories
+  - lightweight tags or labels if they improve navigation
+  - manual review surfaces for high-value memories
+
+What not to borrow by default:
+
+- do not make durable memory creation fully automatic
+- do not replace explicit `events -> evidence_refs -> create/update` with summary-only extraction
+- do not blur the distinction between episodic capture and durable semantic / procedural memory
+
+The right borrowing strategy is:
+
+- borrow MoltBrain's product polish and operator visibility
+- keep Shellbrain's evidence-backed, typed, case-based reasoning core intact
+
+### 9. Agent-Facing Context Pack Metadata
 
 - The read result already returns structured JSON with top-level sections:
   - `meta`
@@ -178,7 +214,7 @@ This is worth exploring because a supervisor loop could reduce protocol entropy
 - Keep `scenarios` explicitly deferred for now.
 - Do not treat scenario lift as part of the current v1 output surface until it is intentionally reintroduced.
 
-### 9. Retrieval Metadata and Usage Signals
+### 10. Retrieval Metadata and Usage Signals
 
 - Add lightweight metadata to every read result so behavior is inspectable without digging through logs.
 - Useful fields to include:
@@ -197,7 +233,7 @@ This is worth exploring because a supervisor loop could reduce protocol entropy
   - stale-shellbrain hit rate
   - duplicate / near-duplicate retrieval rate
 
-### 10. System Performance Metrics
+### 11. System Performance Metrics
 
 - Define a small metrics set that tells us whether the shellbrain setup is becoming more useful.
 - Candidate metrics:
@@ -213,15 +249,15 @@ This is worth exploring because a supervisor loop could reduce protocol entropy
 
 ## Later Work
 
-### 11. Episodes and Session Transfer Support
+### 12. Episodes and Session Transfer Support
 
 - `episodes` and `episode_events` are implemented and validated end to end.
 - Remaining work is to operationalize the rest of the episodic model:
   - wire `session_transfers` into real handoff flows
   - add execution tests that prove transfer writes work against PostgreSQL
   - decide how transfer events should participate in agent-facing analytics
 
-### 12. Later: Local Model for Triage / Filtering
+### 13. Later: Local Model for Triage / Filtering
 
 - Consider a smaller local model ahead of the main model for cheap first-pass categorization or filtering.
 - Possible uses:
@@ -231,7 +267,7 @@ This is worth exploring because a supervisor loop could reduce protocol entropy
   - perform cheap reranking before the higher-cost model sees context
 - Treat this as a later optimization after baseline metadata and metrics exist, so we can measure whether it actually improves quality, latency, or cost.
 
-### 13. Usability: Batch Questions for Memory Reads
+### 14. Usability: Batch Questions for Memory Reads
 
 - Support a single shellbrain-read call that accepts multiple questions at once, instead of forcing the LLM into sequential reads.
 - The goal is to let the model ask for "everything I need to know" in one interaction when it has several sub-questions.
@@ -243,7 +279,7 @@ This is worth exploring because a supervisor loop could reduce protocol entropy
 - This should reduce extra tool turns and token burn caused by back-to-back shellbrain queries.
 - Design the interface so batching is a first-class usability path, not just a thin wrapper around repeated single-question retrieval.
 
-### 14. Later: Scenario Lift
+### 15. Later: Scenario Lift
 
 - Keep scenario lift out of the current v1 read output.
 - Revisit it later as a separate project once the atomic-shellbrain path, metadata, and operational surface are stable.
@@ -253,7 +289,7 @@ This is worth exploring because a supervisor loop could reduce protocol entropy
   - constructor trigger boundaries
   - pack quotas and display shape
 
-### 15. V2: Automatic Related-Memory Reinforcement
+### 16. V2: Automatic Related-Memory Reinforcement
 
 - Treat this as v2, not v1.
 - Add a background task that looks at which memories are repeatedly retrieved, cited, or used together.

shellbrain/periphery/cli/main.py

@@ -26,6 +26,10 @@ class _HelpFormatter(argparse.RawDescriptionHelpFormatter):
       - `create` authors durable memories from that evidence.
       - `update` records utility, truth-evolution links, and explicit associations.
 
+    Codex shell bootstrap:
+      - In Codex Desktop or similar tool shells, start via `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'`.
+      - Use the same wrapper shape for actual Shellbrain commands when the session depends on machine-level PATH and `SHELLBRAIN_DB_DSN`.
+
     Protocol:
       1. Query with the concrete bug, subsystem, decision, or constraint you are working on.
          Avoid generic prompts like "what should I know about this repo?"
@@ -37,6 +41,7 @@ class _HelpFormatter(argparse.RawDescriptionHelpFormatter):
       - Shellbrain should already be available from a one-time global install.
       - If it is missing, restore the machine-level install (`pipx install --editable /path/to/shellbrain` or `python3 -m pip install --user --break-system-packages --editable /path/to/shellbrain`).
       - Export `SHELLBRAIN_DB_DSN` from your shell profile.
+      - In Codex Desktop or similar tool shells, put the PATH export and `SHELLBRAIN_DB_DSN` in `~/.zprofile`, not `~/.zshrc`.
       - Run `shellbrain admin migrate` once against the target database.
 
     Examples:
@@ -48,7 +53,8 @@ class _HelpFormatter(argparse.RawDescriptionHelpFormatter):
       shellbrain admin migrate
 
     Common recovery steps:
-      - `SHELLBRAIN_DB_DSN is not set`: export the database DSN before running the CLI.
+      - `shellbrain: command not found` inside Codex: verify you used the `zsh -lc 'source ~/.zprofile ...'` startup pattern before declaring Shellbrain blocked.
+      - `SHELLBRAIN_DB_DSN is not set`: verify the same startup pattern and that the export lives in `~/.zprofile`, then export the database DSN if needed.
       - No active host session found: verify Codex/Claude Code transcript availability, then rerun `events`.
       - Evidence ref rejected: rerun `events` and use the returned `episode_event` ids verbatim.
       - Wrong working tree: rerun with `--repo-root` (and optionally `--repo-id`) for the target repo.

skills/shellbrain-session-start/SKILL.md

@@ -27,8 +27,9 @@ Treat current repo state as ground truth. Treat Shellbrain as advisory long-term
 
 ## Quick Start
 
-1. Check that Shellbrain is available with `shellbrain --help`.
-2. Assume Shellbrain is already available from a one-time global install. If the CLI is missing, ask the operator to restore that machine-level install instead of reinstalling per repo. The operator should also have `SHELLBRAIN_DB_DSN` set and `shellbrain admin migrate` already applied.
+1. In Codex or similar tool shells, bootstrap Shellbrain through a login shell that sources `~/.zprofile`:
+   `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain && printf "%s\n" "$SHELLBRAIN_DB_DSN"'`
+2. Assume Shellbrain is already available from a one-time global install. If direct `shellbrain` calls fail in the current session, keep using the `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; ...'` wrapper for Shellbrain invocations before declaring Shellbrain blocked. Only ask the operator to restore the machine-level install if the wrapped check still fails. The operator should also have `SHELLBRAIN_DB_DSN` set and `shellbrain admin migrate` already applied.
 3. Resolve the target repo:
    - Use the current working directory when already inside the repo.
    - Pass `--repo-root /absolute/path/to/repo` when working from somewhere else.
@@ -41,20 +42,22 @@ Treat current repo state as ground truth. Treat Shellbrain as advisory long-term
      `shellbrain read --json '{"query":"What repo constraints or user preferences matter for this task?","kinds":["fact","preference","change"]}'`
    - area-specific facts:
      `shellbrain read --json '{"query":"What facts or changes matter in this subsystem?","kinds":["fact","change","problem","solution"]}'`
-6. Inspect the returned context pack:
+6. When running from Codex, wrap the actual Shellbrain invocations the same way if needed:
+   `zsh -lc "source ~/.zprofile >/dev/null 2>&1; shellbrain read --json '{\"query\":\"Have we seen this failure mode before?\",\"kinds\":[\"problem\",\"solution\",\"failed_tactic\"]}'"`
+7. Inspect the returned context pack:
    - `direct` = direct matches
    - `explicit_related` = linked memories, including authored associations and problem/fact chains
    - `implicit_related` = semantic neighbors and bounded associative hops
-7. Re-run `read` liberally during the task whenever the search shifts, you hit a new subproblem, or you suspect the right memory will only become relevant mid-journey.
-8. Before `create` or any evidence-bearing `update`, run `shellbrain events --json '{"limit":10}'`.
-9. Reuse returned `data.events[].id` values verbatim as `evidence_refs`.
-10. At session end, normalize the episode into durable memories:
+8. Re-run `read` liberally during the task whenever the search shifts, you hit a new subproblem, or you suspect the right memory will only become relevant mid-journey.
+9. Before `create` or any evidence-bearing `update`, run `shellbrain events --json '{"limit":10}'`.
+10. Reuse returned `data.events[].id` values verbatim as `evidence_refs`.
+11. At session end, normalize the episode into durable memories:
    - store the `problem`
    - store each `failed_tactic`
    - store the `solution`
    - store any durable `fact`, `preference`, or `change`
    - record `utility_vote` updates for memories that helped or misled
-11. Use the exact payload shapes in [references/request-shapes.md](references/request-shapes.md).
+12. Use the exact payload shapes in [references/request-shapes.md](references/request-shapes.md).
 
 ## Memory Kinds
 

skills/shellbrain-session-start/references/session-workflow.md

@@ -24,13 +24,19 @@ The point is case-based reasoning: query for similar prior problems, plans, cons
 
 ## Bootstrap
 
+In Codex desktop and similar tool shells, first retry through a login shell that sources `~/.zprofile`:
+
+```bash
+zsh -lc 'source ~/.zprofile >/dev/null 2>&1; command -v shellbrain && printf "%s\n" "$SHELLBRAIN_DB_DSN"'
+```
+
 Use Shellbrain only after confirming:
 
 - `shellbrain --help` works.
 - `SHELLBRAIN_DB_DSN` is set.
 - `shellbrain admin migrate` has been run against the target database.
 
-Assume Shellbrain comes from a one-time global install. If the CLI is unavailable, stop and ask the operator to restore the machine-level install first. Do not create per-repo installs unless the operator explicitly wants that.
+Assume Shellbrain comes from a one-time global install. If direct calls fail in the current Codex session, keep using the `zsh -lc 'source ~/.zprofile ...'` wrapper for Shellbrain invocations before declaring Shellbrain blocked. Only if the wrapped check fails should you ask the operator to restore the machine-level install. Do not create per-repo installs unless the operator explicitly wants that.
 
 ## Repo Targeting
 
@@ -181,10 +187,10 @@ Important modeling pattern for changed truth:
 ## Recovery
 
 - `shellbrain: command not found`
-  Ask the operator to restore the one-time global Shellbrain install.
+  Retry through `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'` first. Only if that still fails should you ask the operator to restore the one-time global Shellbrain install.
 
 - `SHELLBRAIN_DB_DSN is not set`
-  Ask the operator to export the DB DSN from the shell profile, then rerun `shellbrain admin migrate` if the database is fresh.
+  Retry through `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; printf "%s\n" "$SHELLBRAIN_DB_DSN"'` first. If it is still unset, ask the operator to export the DB DSN from the shell profile, then rerun `shellbrain admin migrate` if the database is fresh.
 
 - No active host session found
   Verify that the user is working in Codex or Claude Code, that transcript files exist, and that `repo_root` matches the repo used in that session.

tests/config/test_cli_surface.py

@@ -48,6 +48,7 @@ def test_shellbrain_help_should_explain_the_workflow(capsys: pytest.CaptureFixtu
     assert "utility_vote" in output
     assert "shellbrain admin migrate" in output
     assert "--repo-root" in output
+    assert "~/.zprofile" in output
     assert "--no-sync" not in output
     assert "create" in output
     assert "read" in output

tests/config/test_onboarding_assets.py

@@ -32,6 +32,7 @@ def test_docs_and_skill_should_share_the_shellbrain_protocol() -> None:
         "session end",
         "utility_vote",
         "what should I know about this repo?",
+        "~/.zprofile",
     ]
 
     for phrase in required_phrases:
@@ -51,6 +52,7 @@ def test_cli_help_should_share_the_short_protocol() -> None:
         "shellbrain admin migrate",
         "--repo-root",
         "At session end",
+        "~/.zprofile",
     ]
 
     for phrase in required_phrases: