shellbrain 0.1.16__tar.gz → 0.1.18__tar.gz

{shellbrain-0.1.16 → shellbrain-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shellbrain
-Version: 0.1.16
+Version: 0.1.18
 Summary: Repo-scoped Shellbrain CLI with explicit evidence-backed writes.
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{shellbrain-0.1.16 → shellbrain-0.1.18}/app/core/policies/read_policy/context_pack_builder.py

@@ -75,7 +75,6 @@ def assemble_context_pack(scored_candidates: dict[str, list[dict[str, Any]]], pa
     return {
         "meta": {
             "mode": mode,
-            "query": payload.get("query"),
             "limit": limit,
             "counts": {
                 "direct": len(sections["direct"]),

shellbrain-0.1.18/app/onboarding_assets/claude/CLAUDE.md

@@ -0,0 +1,43 @@
+## Shellbrain
+
+You have a persistent memory system called Shellbrain. This section teaches you a habit for using it well.
+
+### The core habit
+
+As you work, maintain a mental summary of your current subproblem as a tuple: `goal | surface | obstacle | hypothesis`.
+
+Whenever that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This forces Shellbrain back into your local context so you can make a real decision about whether to use it.
+
+Boundary states:
+
+- The goal, surface, obstacle, or hypothesis just changed.
+- The same approach failed twice.
+- An error is repeating.
+- You are about to `create` or `update` a Shellbrain memory with evidence.
+- You are closing out a task.
+
+### What to say at the pause
+
+If prior memory might help right now:
+
+`SB: read | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then actually call the Shellbrain CLI to read.
+
+If the tuple has not meaningfully changed and there is no new evidence or failure:
+
+`SB: skip | same signature | <one-line reason>`
+
+Then move on. Do not reread just because you can. A reread is a decision, not a reflex. Skip it when there is no new failed attempt, no new evidence, and no changed hypothesis.
+
+### Before writing to Shellbrain
+
+Run `shellbrain events` before any evidence-bearing `create` or `update`. This is mandatory.
+
+### At closeout
+
+When work is solved, write durable memories (`problem`, `failed_tactic`, `solution`, `fact`, `preference`, or `change`) and run `utility_vote` updates.
+
+### Reference
+
+Use the installed `shellbrain-session-start` skill for the exact query and writeback workflow.

shellbrain-0.1.18/app/onboarding_assets/claude/skills/shellbrain-session-start/SKILL.md

@@ -0,0 +1,151 @@
+# Shellbrain Session Start
+
+## Overview
+
+Use Shellbrain as a case-based reasoning system for long-running agent work.
+
+Shellbrain has two layers:
+
+- durable memories:
+  - `problem`
+  - `solution`
+  - `failed_tactic`
+  - `fact`
+  - `preference`
+  - `change`
+- episodic evidence:
+  - transcript-derived `episode_events` that justify writes
+
+Treat current repo state as ground truth. Treat Shellbrain as advisory long-term memory that helps answer: "Have I seen anything like this before, and what was useful?"
+
+## Quick Start
+
+`shellbrain init` is first-time bootstrap and repair. It is not a per-session ritual.
+
+1. If Shellbrain has never been bootstrapped on this machine, the current repo has never been registered, or the user says Shellbrain setup is broken, run `shellbrain init`.
+2. Otherwise, do not rerun `init` just because a new agent session started. Start with focused `read` queries right away.
+3. If readiness is unclear, inspect with `shellbrain admin doctor` instead of rerunning `init` by reflex.
+4. If `doctor` reports `repair_needed`, rerun `shellbrain init` instead of trying to repair Shellbrain manually.
+5. In Claude Code, if direct `shellbrain` calls fail in the current session, retry through a login shell that sources the user's login profile:
+   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'`
+   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; shellbrain --help'`
+6. If the wrapped login-shell check still cannot find `shellbrain`, inspect Python's user script directory:
+   - `python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))"`
+   If `shellbrain` exists there, call it directly or add that directory to the login profile PATH and retry. If it does not, reinstall the Shellbrain CLI.
+7. 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
+   - treat repo path as operational context; Shellbrain should normally derive durable repo identity from normalized git remote
+8. Start with focused `read` queries about the concrete problem, subsystem, decision, or constraint you are working on. Do not start with vague prompts like "what should I know about this repo?"
+9. Use a startup read bundle when appropriate:
+   - prior attempts:
+     `shellbrain read --json '{"query":"Have we seen this failure mode before?","kinds":["problem","solution","failed_tactic"]}'`
+   - constraints and preferences:
+     `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"]}'`
+
+## Attention Programming
+
+You have a persistent memory system called Shellbrain. This section teaches you a habit for using it well.
+
+### The core habit
+
+As you work, maintain a mental summary of your current subproblem as a tuple: `goal | surface | obstacle | hypothesis`.
+
+Whenever that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This forces Shellbrain back into your local context so you can make a real decision about whether to use it.
+
+Boundary states:
+
+- The goal, surface, obstacle, or hypothesis just changed.
+- The same approach failed twice.
+- An error is repeating.
+- You are about to `create` or `update` a Shellbrain memory with evidence.
+- You are closing out a task.
+
+### What to say at the pause
+
+If prior memory might help right now:
+
+`SB: read | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then actually call the Shellbrain CLI to read.
+
+If the tuple has not meaningfully changed and there is no new evidence or failure:
+
+`SB: skip | same signature | <one-line reason>`
+
+Then move on. Do not reread just because you can. A reread is a decision, not a reflex. Skip it when there is no new failed attempt, no new evidence, and no changed hypothesis.
+
+## Query Construction
+
+When the answer is `SB: read`, build the query from the live tuple. Name the actual failure mode, subsystem, decision, or constraint.
+
+Good query shapes:
+
+- prior attempts for the current obstacle:
+  `shellbrain read --json '{"query":"Have we seen this oauth callback loop in staging before?","kinds":["problem","solution","failed_tactic"]}'`
+- constraints and preferences for the current surface:
+  `shellbrain read --json '{"query":"What repo constraints or user preferences matter for this auth refactor?","kinds":["fact","preference","change"]}'`
+- facts and changes for the subsystem you just entered:
+  `shellbrain read --json '{"query":"What facts or recent changes matter around the payments retry worker?","kinds":["fact","change","problem","solution"]}'`
+
+Avoid generic prompts like:
+
+- "what should I know about this repo?"
+- "what should I know before I start?"
+
+Those are too vague for the actual retrieval model.
+
+## Write Discipline
+
+Run `shellbrain events` before any evidence-bearing `create` or `update`. This is mandatory.
+
+```bash
+shellbrain events --json '{"limit":10}'
+```
+
+Then reuse returned `data.events[].id` values verbatim as `evidence_refs`.
+
+Hard rules:
+
+- never invent `evidence_refs`
+- skip the write if `events` returns nothing useful or the evidence is ambiguous
+- use `read` again before writing if you need to check whether the memory already exists or whether an `update` is more appropriate than a new `create`
+
+Durable memory kinds:
+
+- `problem`
+- `solution`
+- `failed_tactic`
+- `fact`
+- `preference`
+- `change`
+
+Invariant:
+
+- `solution` and `failed_tactic` require `links.problem_id`
+- `problem`, `fact`, `preference`, and `change` do not accept `links.problem_id`
+
+## Closeout
+
+When work is solved, write durable memories and run `utility_vote` updates. Normalize the episode into durable memory:
+
+1. store the `problem`
+2. store each `failed_tactic`
+3. store the `solution`
+4. store any durable `fact`, `preference`, or `change`
+5. record `utility_vote` updates for memories that helped or misled
+
+Use `scope: "repo"` by default. Use `scope: "global"` only for intentionally cross-repo knowledge such as user-wide preferences or cross-project facts.
+
+## Trusted Session Note
+
+- `events` now syncs the exact trusted caller thread instead of mixing same-repo agent threads
+- Claude trusted identity normally comes from the global Shellbrain SessionStart hook in `~/.claude/settings.json`; repo-local `.claude/settings.local.json` is the explicit override or repair path
+- successful responses may include `data.guidance`; treat that as an internal Shellbrain nudge about pending utility votes or workflow reminders
+
+## Resources
+
+- Read https://shellbrain.ai/agents if you need the deeper system docs.
+- Use the same payload shapes as the Codex skill docs when issuing `read`, `events`, `create`, or `update`.

shellbrain-0.1.18/app/onboarding_assets/codex/AGENTS.md

@@ -0,0 +1,43 @@
+## Shellbrain
+
+You have a persistent memory system called Shellbrain. This section teaches you a habit for using it well.
+
+### The core habit
+
+As you work, maintain a mental summary of your current subproblem as a tuple: `goal | surface | obstacle | hypothesis`.
+
+Whenever that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This forces Shellbrain back into your local context so you can make a real decision about whether to use it.
+
+Boundary states:
+
+- The goal, surface, obstacle, or hypothesis just changed.
+- The same approach failed twice.
+- An error is repeating.
+- You are about to `create` or `update` a Shellbrain memory with evidence.
+- You are closing out a task.
+
+### What to say at the pause
+
+If prior memory might help right now:
+
+`SB: read | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then actually call the Shellbrain CLI to read.
+
+If the tuple has not meaningfully changed and there is no new evidence or failure:
+
+`SB: skip | same signature | <one-line reason>`
+
+Then move on. Do not reread just because you can. A reread is a decision, not a reflex. Skip it when there is no new failed attempt, no new evidence, and no changed hypothesis.
+
+### Before writing to Shellbrain
+
+Run `shellbrain events` before any evidence-bearing `create` or `update`. This is mandatory.
+
+### At closeout
+
+When work is solved, write durable memories (`problem`, `failed_tactic`, `solution`, `fact`, `preference`, or `change`) and run `utility_vote` updates.
+
+### Reference
+
+Use the installed `shellbrain-session-start` skill for the exact query and writeback workflow.

shellbrain-0.1.18/app/onboarding_assets/codex/shellbrain-session-start/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: shellbrain-session-start
+description: Use when Codex should get up to speed in any repo with the installed shellbrain CLI, or when work shifts to a new surface, repeated failure suggests prior memory may help, a hypothesis changes, an evidence-bearing write is about to happen, or closeout should record durable learnings.
+---
+
+# Shellbrain Session Start
+
+## Overview
+
+Use Shellbrain as a case-based reasoning system for long-running agent work.
+
+Shellbrain has two layers:
+
+- durable memories:
+  - `problem`
+  - `solution`
+  - `failed_tactic`
+  - `fact`
+  - `preference`
+  - `change`
+- episodic evidence:
+  - transcript-derived `episode_events` that justify writes
+
+Treat current repo state as ground truth. Treat Shellbrain as advisory long-term memory that helps answer: "Have I seen anything like this before, and what was useful?"
+
+## Quick Start
+
+`shellbrain init` is first-time bootstrap and repair. It is not a per-session ritual.
+
+1. If Shellbrain has never been bootstrapped on this machine, the current repo has never been registered, or the user says Shellbrain setup is broken, run `shellbrain init`.
+2. Otherwise, do not rerun `init` just because a new agent session started. Start with focused `read` queries right away.
+3. If readiness is unclear, inspect with `shellbrain admin doctor` instead of rerunning `init` by reflex.
+4. If `doctor` reports `repair_needed`, rerun `shellbrain init` instead of trying to repair Shellbrain manually.
+5. In Codex or similar tool shells, if direct `shellbrain` calls fail in the current session, retry through a login shell that sources the user's login profile:
+   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'`
+   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; shellbrain --help'`
+6. If the wrapped login-shell check still cannot find `shellbrain`, inspect Python's user script directory:
+   - `python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))"`
+   If `shellbrain` exists there, call it directly or add that directory to the login profile PATH and retry. If it does not, reinstall the Shellbrain CLI.
+7. 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
+   - treat repo path as operational context; Shellbrain should normally derive durable repo identity from normalized git remote
+8. Start with focused `read` queries about the concrete problem, subsystem, decision, or constraint you are working on. Do not start with vague prompts like "what should I know about this repo?"
+9. Use a startup read bundle when appropriate:
+   - prior attempts:
+     `shellbrain read --json '{"query":"Have we seen this failure mode before?","kinds":["problem","solution","failed_tactic"]}'`
+   - constraints and preferences:
+     `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"]}'`
+
+## Attention Programming
+
+You have a persistent memory system called Shellbrain. This section teaches you a habit for using it well.
+
+### The core habit
+
+As you work, maintain a mental summary of your current subproblem as a tuple: `goal | surface | obstacle | hypothesis`.
+
+Whenever that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This forces Shellbrain back into your local context so you can make a real decision about whether to use it.
+
+Boundary states:
+
+- The goal, surface, obstacle, or hypothesis just changed.
+- The same approach failed twice.
+- An error is repeating.
+- You are about to `create` or `update` a Shellbrain memory with evidence.
+- You are closing out a task.
+
+### What to say at the pause
+
+If prior memory might help right now:
+
+`SB: read | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then actually call the Shellbrain CLI to read.
+
+If the tuple has not meaningfully changed and there is no new evidence or failure:
+
+`SB: skip | same signature | <one-line reason>`
+
+Then move on. Do not reread just because you can. A reread is a decision, not a reflex. Skip it when there is no new failed attempt, no new evidence, and no changed hypothesis.
+
+## Query Construction
+
+When the answer is `SB: read`, build the query from the live tuple. Name the actual failure mode, subsystem, decision, or constraint.
+
+Good query shapes:
+
+- prior attempts for the current obstacle:
+  `shellbrain read --json '{"query":"Have we seen this oauth callback loop in staging before?","kinds":["problem","solution","failed_tactic"]}'`
+- constraints and preferences for the current surface:
+  `shellbrain read --json '{"query":"What repo constraints or user preferences matter for this auth refactor?","kinds":["fact","preference","change"]}'`
+- facts and changes for the subsystem you just entered:
+  `shellbrain read --json '{"query":"What facts or recent changes matter around the payments retry worker?","kinds":["fact","change","problem","solution"]}'`
+
+Avoid generic prompts like:
+
+- "what should I know about this repo?"
+- "what should I know before I start?"
+
+Those are too vague for the actual retrieval model.
+
+## Write Discipline
+
+Run `shellbrain events` before any evidence-bearing `create` or `update`. This is mandatory.
+
+```bash
+shellbrain events --json '{"limit":10}'
+```
+
+Then reuse returned `data.events[].id` values verbatim as `evidence_refs`.
+
+Hard rules:
+
+- never invent `evidence_refs`
+- skip the write if `events` returns nothing useful or the evidence is ambiguous
+- use `read` again before writing if you need to check whether the memory already exists or whether an `update` is more appropriate than a new `create`
+
+Durable memory kinds:
+
+- `problem`
+- `solution`
+- `failed_tactic`
+- `fact`
+- `preference`
+- `change`
+
+Invariant:
+
+- `solution` and `failed_tactic` require `links.problem_id`
+- `problem`, `fact`, `preference`, and `change` do not accept `links.problem_id`
+
+## Closeout
+
+When work is solved, write durable memories and run `utility_vote` updates. Normalize the episode into durable memory:
+
+1. store the `problem`
+2. store each `failed_tactic`
+3. store the `solution`
+4. store any durable `fact`, `preference`, or `change`
+5. record `utility_vote` updates for memories that helped or misled
+
+Use `scope: "repo"` by default. Use `scope: "global"` only for intentionally cross-repo knowledge such as user-wide preferences or cross-project facts.
+
+## Trusted Session Note
+
+- `events` now syncs the exact trusted caller thread instead of mixing same-repo agent threads
+- Codex caller identity is automatic
+- Claude trusted identity normally comes from the global Shellbrain SessionStart hook in `~/.claude/settings.json`; repo-local `.claude/settings.local.json` is the explicit override or repair path
+- successful responses may include `data.guidance`; treat that as an internal Shellbrain nudge about pending utility votes or workflow reminders
+
+## Resources
+
+- Read [references/session-workflow.md](references/session-workflow.md) for the full session cadence, tuple examples, and evidence model.
+- Read [references/request-shapes.md](references/request-shapes.md) for valid JSON payloads, response-shape notes, and command examples.
+- If you need the deeper system docs, read https://shellbrain.ai/agents.

shellbrain-0.1.18/app/onboarding_assets/codex/shellbrain-session-start/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Shellbrain Session Start"
+  short_description: "Reconsider shellbrain at subproblem boundaries"
+  icon_small: "./assets/shellbrain-small.svg"
+  icon_large: "./assets/shellbrain_logo.png"
+  default_prompt: "Use $shellbrain-session-start when work shifts to a new surface, repeated failures suggest prior memory may help, a hypothesis changes, an evidence-bearing write is about to happen, or closeout should record durable learnings."

{shellbrain-0.1.16 → shellbrain-0.1.18}/app/onboarding_assets/codex/shellbrain-session-start/references/request-shapes.md

@@ -25,6 +25,22 @@ Use `read` to retrieve durable memories related to the current problem or subpro
 
 Shellbrain `read` is retrieval, not chat. Query it with concrete failure modes, subsystem names, decisions, or constraints. Avoid vague prompts like "what should I know about this repo?"
 
+Maintain a mental summary of the current subproblem as a tuple: `goal | surface | obstacle | hypothesis`.
+
+Whenever that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This forces Shellbrain back into your local context so you can make a real decision about whether to use it.
+
+If prior memory might help right now:
+
+- `SB: read | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then actually call the Shellbrain CLI to read.
+
+If the tuple has not meaningfully changed and there is no new evidence or failure:
+
+- `SB: skip | same signature | <one-line reason>`
+
+Then move on. Do not reread just because you can. A reread is a decision, not a reflex. Skip it when there is no new failed attempt, no new evidence, and no changed hypothesis.
+
 Prior attempts:
 
 ```bash
@@ -71,6 +87,7 @@ shellbrain events --json '{"limit":10}'
 Read returned ids from `data.events[].id`.
 
 `events` inspects normalized episodic evidence. Those ids are the canonical grounding for durable writes.
+`events` is a hard rule before evidence-bearing `create` and `update`.
 
 When caller identity is trusted, `events` reads from the exact caller thread instead of guessing from the repo alone.
 `shellbrain init` normally installs Claude integration through the global Shellbrain SessionStart hook in `~/.claude/settings.json`. Use `shellbrain admin install-claude-hook --repo-root ...` only when you intentionally need the repo-local override path.

{shellbrain-0.1.16 → shellbrain-0.1.18}/app/onboarding_assets/codex/shellbrain-session-start/references/session-workflow.md

@@ -117,14 +117,29 @@ Use `why_included` and `anchor_memory_id` to understand why a related item appea
 
 ### During the task
 
-Re-run `read` whenever:
+Maintain a mental summary of the current subproblem as a tuple: `goal | surface | obstacle | hypothesis`.
 
-- the search shifts to a new subproblem
-- you hit a blocker and want similar prior failures or tactics
-- you move into a new subsystem
-- you suspect a fact, preference, or change memory may matter halfway through the journey
+Whenever that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This forces Shellbrain back into your local context so you can make a real decision about whether to use it.
 
-Do not treat Shellbrain as startup-only. Query liberally while solving.
+Boundary states:
+
+- The goal, surface, obstacle, or hypothesis just changed.
+- The same approach failed twice.
+- An error is repeating.
+- You are about to `create` or `update` a Shellbrain memory with evidence.
+- You are closing out a task.
+
+If prior memory might help right now:
+
+- `SB: read | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then actually call the Shellbrain CLI to read.
+
+If the tuple has not meaningfully changed and there is no new evidence or failure:
+
+- `SB: skip | same signature | <one-line reason>`
+
+Then move on. Do not reread just because you can. A reread is a decision, not a reflex. Skip it when there is no new failed attempt, no new evidence, and no changed hypothesis.
 
 ### Before any write
 
@@ -136,6 +151,8 @@ shellbrain events --json '{"limit":10}'
 
 Then reuse returned `data.events[].id` values verbatim as `evidence_refs`.
 
+This is a hard rule before any evidence-bearing `create` or `update`.
+
 ### Session end
 
 Normalize the episode into durable memory:

{shellbrain-0.1.16 → shellbrain-0.1.18}/app/onboarding_assets/codex/shellbrain-usage-review/agents/openai.yaml

@@ -1,4 +1,6 @@
 interface:
   display_name: "Shellbrain Usage Review"
   short_description: "Review shellbrain usage across repos"
+  icon_small: "./assets/shellbrain-small.svg"
+  icon_large: "./assets/shellbrain_logo.png"
   default_prompt: "Use $shellbrain-usage-review to inspect shellbrain usage across all repos and summarize what is working, what is failing, why it is failing, and where agents are skipping expected capabilities."

shellbrain-0.1.18/app/onboarding_assets/codex/shellbrain-usage-review/assets/shellbrain-small.svg

@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 14 14" fill="none">
+  <defs>
+    <linearGradient id="shellbrainSmallBg" x1="2" y1="1.5" x2="12" y2="12.5" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#8B5CF6"/>
+      <stop offset="1" stop-color="#5B21B6"/>
+    </linearGradient>
+  </defs>
+  <rect x="1.25" y="1.25" width="11.5" height="11.5" rx="3" fill="url(#shellbrainSmallBg)"/>
+  <path d="M5.35 4.15C4.25 4.15 3.35 5 3.35 6.05C3.35 6.72 3.72 7.33 4.31 7.69C4.3 7.81 4.24 8.08 4.06 8.36C4 8.46 4 8.58 4.06 8.68C4.11 8.77 4.21 8.83 4.32 8.83C4.73 8.83 5.13 8.68 5.46 8.4C5.64 8.43 5.81 8.45 6 8.45C7.1 8.45 8 7.6 8 6.55C8 5.5 7.1 4.65 6 4.65C5.78 4.65 5.56 4.69 5.35 4.77C5.24 4.38 4.85 4.15 5.35 4.15Z" fill="white" fill-opacity="0.95"/>
+  <path d="M8.35 5.55C9.45 5.55 10.35 6.4 10.35 7.45C10.35 8.12 9.98 8.73 9.39 9.09C9.4 9.21 9.46 9.48 9.64 9.76C9.7 9.86 9.7 9.98 9.64 10.08C9.59 10.17 9.49 10.23 9.38 10.23C8.97 10.23 8.57 10.08 8.24 9.8C8.06 9.83 7.89 9.85 7.7 9.85C6.6 9.85 5.7 9 5.7 7.95C5.7 6.9 6.6 6.05 7.7 6.05C7.92 6.05 8.14 6.09 8.35 6.17C8.46 5.78 8.85 5.55 8.35 5.55Z" fill="white" fill-opacity="0.75"/>
+</svg>

shellbrain-0.1.18/app/onboarding_assets/cursor/skills/shellbrain-session-start/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: shellbrain-session-start
+description: Use when Cursor should get up to speed in any repo with the installed shellbrain CLI, or when work shifts to a new surface, repeated failure suggests prior memory may help, a hypothesis changes, an evidence-bearing write is about to happen, or closeout should record durable learnings.
+---
+
+# Shellbrain Session Start
+
+Use Shellbrain as a case-based reasoning system for long-running agent work.
+
+Shellbrain has two layers:
+
+- durable memories:
+  - `problem`
+  - `solution`
+  - `failed_tactic`
+  - `fact`
+  - `preference`
+  - `change`
+- episodic evidence:
+  - transcript-derived `episode_events` that justify writes
+
+`shellbrain init` is first-time bootstrap and repair. It is not a per-session ritual.
+
+## Quick Start
+
+1. If Shellbrain has never been bootstrapped on this machine, the current repo has never been registered, or the user says Shellbrain setup is broken, run `shellbrain init`.
+2. Otherwise, do not rerun `init` just because a new agent session started. Start with focused `read` queries right away.
+3. If readiness is unclear, inspect with `shellbrain admin doctor` instead of rerunning `init` by reflex.
+4. If `doctor` reports `repair_needed`, rerun `shellbrain init`.
+5. If direct `shellbrain` calls fail in the current Cursor shell, retry through a login shell that sources the user's login profile:
+   - `zsh -lc 'source ~/.zprofile >/dev/null 2>&1; shellbrain --help'`
+   - `bash -lc 'source ~/.bash_profile >/dev/null 2>&1; shellbrain --help'`
+6. If the wrapped login-shell check still cannot find `shellbrain`, inspect Python's user script directory:
+   - `python3 -c "import sysconfig; print(sysconfig.get_path('scripts', 'posix_user'))"`
+7. 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
+8. Start with focused `read` queries about the concrete problem, subsystem, decision, or constraint you are working on. Do not start with vague prompts like "what should I know about this repo?"
+
+## Attention Programming
+
+You have a persistent memory system called Shellbrain. This section teaches you a habit for using it well.
+
+### The core habit
+
+As you work, maintain a mental summary of your current subproblem as a tuple: `goal | surface | obstacle | hypothesis`.
+
+Whenever that tuple changes materially, or you hit a boundary state, pause and say one `SB:` line out loud by actually generating it as output. This forces Shellbrain back into your local context so you can make a real decision about whether to use it.
+
+Boundary states:
+
+- The goal, surface, obstacle, or hypothesis just changed.
+- The same approach failed twice.
+- An error is repeating.
+- You are about to `create` or `update` a Shellbrain memory with evidence.
+- You are closing out a task.
+
+### What to say at the pause
+
+If prior memory might help right now:
+
+`SB: read | <goal> | <surface> | <obstacle> | <hypothesis-or-trigger>`
+
+Then actually call the Shellbrain CLI to read.
+
+If the tuple has not meaningfully changed and there is no new evidence or failure:
+
+`SB: skip | same signature | <one-line reason>`
+
+Then move on. Do not reread just because you can. A reread is a decision, not a reflex. Skip it when there is no new failed attempt, no new evidence, and no changed hypothesis.
+
+## Write Discipline
+
+Run `shellbrain events` before any evidence-bearing `create` or `update`. This is mandatory.
+
+- `shellbrain events --json '{"limit":10}'`
+- reuse returned `data.events[].id` values verbatim as `evidence_refs`
+- never invent `evidence_refs`
+- skip the write if `events` returns nothing useful or the evidence is ambiguous
+
+## Closeout
+
+When work is solved, write durable memories and run `utility_vote` updates.
+
+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
+
+If you need deeper guidance, read https://shellbrain.ai/agents.