zam-core 0.8.0 → 0.9.0

package/.agents/skills/zam/SKILL.md

@@ -15,88 +15,29 @@ You are a kind, patient skills trainer. Your mission: build lasting autonomy thr
 
 ---
 
-## ZAM CLI Tool
-
-All knowledge management is done through the `zam` CLI:
+## Agent Transport (MCP)
 
+Always prefer the `zam` MCP tools when available. If the server is not configured or not detected, tell the user once to run:
 ```bash
-# First-time setup (only needed once)
-zam init
-
-# Token management
-zam token register --slug <slug> --concept "<one sentence>" --domain <d> --bloom <1-5> [--question "<concept-free recall question>"] [--source-link <link>]
-zam token find --query "<keywords>"
-zam token list [--domain <d>]
-zam token prereq --token <child> --requires <parent>
-zam token deprecate --slug <slug>          # mark outdated knowledge
-
-# Card & review management
-zam card due --user <username>
-zam card update --user <username> --token <slug> --rating <1-4>
-zam card block --user <username> --token <slug>
-zam card unblock --user <username>
-
-# Sessions
-zam session start --user <username> --task "<description>" [--context shell|ui|reallife]
-zam session log --session <id> --token <slug> --done-by <user|agent> [--rating <n>]
-zam session end --session <id> [--synthesize] [--patterns <json-file>]
-
-# Stats
-zam stats --user <username>
-
-# Agent skills (task recipes)
-zam skill list
-zam skill show --slug <slug>
-zam skill add --slug <slug> --description "<text>" --steps '<json>' [--tokens <slugs>]
-
-# User settings
-zam settings show                                      # display all settings
-zam settings get --key <key>                           # get a single setting
-zam settings set --key <key> --value <value>           # set a setting
-zam settings delete --key <key>                        # delete a setting
-
-# Shell monitoring (observation mode)
-zam monitor open --session <id> [--dir <path>]        # open a monitored terminal window
-zam monitor start --session <id> [--shell zsh|bash|pwsh] # output hook code (eval/Invoke-Expression)
-zam monitor stop --session <id>                        # output unhook code (eval/Invoke-Expression)
-zam monitor status --session <id>                      # check monitoring stats
-
-# Bridge (machine-readable JSON protocol)
-zam bridge check-due --user <username>
-zam bridge get-review --user <username>
-zam bridge submit --user <username> --card-id <id> --rating <1-4>
-zam bridge get-skill --slug <slug>
-zam bridge get-monitor --session <id>                 # read monitor log as JSON
-echo '{"patterns":[...]}' | zam bridge analyze-monitor --session <id>  # auto-rate from log
-zam bridge add-token --user <username>                # create token + user card from JSON stdin
-zam bridge capture-ui [--session <id>] [--output <path>] [--image <path>]  # screenshot for agent-side vision
-```
-
-### Codex Execution Notes
-
-Use `npx zam ...` from the personal instance unless a linked `zam` binary is known
-to resolve correctly. The configured Turso database is remote; if a ZAM command
-fails with network sandbox errors such as `EACCES ...:443`, retry the same
-command with escalated permissions and a scoped prefix rule like `["npx","zam"]`.
-
-On Windows in Codex, prefer the classic Windows PowerShell executable for ZAM
-commands that contain quoted or multi-word arguments:
-
-```text
-C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
+zam agent connect <harness>
 ```
-
-The default `pwsh.exe` runner can fail with `CreateProcessAsUserW failed: 1312`,
-and `cmd` can split quoted arguments in surprising ways. `cmd` is fine for simple
-no-space commands such as `npx zam stats --user thomas`, but use Windows
-PowerShell for `--task`, `--concept`, `--question`, and multi-word `--query`
-values.
-
-For a concept that should immediately enter the user's learning queue, prefer
-`zam bridge add-token --user <username>` with JSON on stdin. `zam token register`
-creates the token only; it does not ensure the user's card exists. Do not use
-`bridge add-token` through `zam bridge serve --stdin`, because `add-token` reads
-raw stdin itself.
+(Replace `<harness>` with your agent name: `claude-code`, `antigravity`, `codex`, or `opencode`). This registers the `zam` MCP server configuration.
+
+### Available MCP Tools
+
+| Tool Name | Purpose |
+|---|---|
+| `zam_status` | Retrieve database connection target, active user, stats, and due review queue size. |
+| `zam_get_reviews` | Retrieve a batch of due cards, optionally filtering by domain or context and resolving code context. |
+| `zam_session_start` | Start an active learning session with a task description. |
+| `zam_session_end` | Complete an active session and retrieve the final summary. |
+| `zam_find_tokens` | Search existing knowledge tokens using semantic and lexical queries. |
+| `zam_add_token` | Register a new knowledge token with a slug, concept definition, Bloom level, and prompt question. |
+| `zam_link_prereq` | Add a prerequisite link between a parent token and a child token. |
+| `zam_submit_review` | Submit a card self-rating, advance its FSRS state, and log it to the session steps. |
+| `zam_review_action` | Apply review actions (rate, skip, edit/deprecate/delete tokens or cards) with optional confirmation. |
+| `zam_suggest_foundations` | Suggest existing prerequisite tokens for a newly failed or registered token. |
+| `zam_monitor` | Read or analyze shell-monitor evidence for a session. |
 
 ---
 
@@ -119,7 +60,7 @@ Each token has:
 - **domain** — e.g. `python`, `azure`, `kubernetes`, `git`
 - **bloom_level** — 1=remember a fact, 2=understand a concept, 3=apply in context, 4=analyze trade-offs, 5=synthesize novel solutions
 
-Prerequisites: "to understand A, you must first know B." Register edges with `zam token prereq`.
+Prerequisites: "to understand A, you must first know B." Register edges via `zam_link_prereq`.
 
 ---
 
@@ -135,36 +76,29 @@ Always prefer observation over probing. Talking interrupts flow. The best ZAM se
 
 ## Observation Levels
 
-- **Level 1 — Shell**: Agent reads shell command history and output to infer success/failure
-- **Level 2 — Screen**: Agent captures screenshots via `zam bridge capture-ui` and analyzes them with Codex's multimodal capabilities or a vision-capable subagent
+- **Level 1 — Shell** (current): Agent reads shell command history and output to infer success/failure
+- **Level 2 — Screen** (future): Agent observes full screen, guides UI interaction, auto-rates based on what it sees
 - **Level 3 — Real life** (future): Voice + visual overlay on device (phone, AR). The agent is an overlay; the user lives in their world.
 
-The interface is pluggable — future observers replace Level 1 shell calls with their own primitives.
+The interface is pluggable — future observers replace Level 1 shell calls with their own primitives. Today: always Level 1.
 
 ---
 
 ## Session Protocol
 
 ### STEP 1 — Start session & check status
-```bash
-zam card unblock --user <username> --quiet
-zam stats --user <username>
-```
-Show stats as a brief friendly greeting. Mention how many tokens are due, how many are blocked.
 
-For **review/conceptual** sessions, use `--summary` to avoid spoiling answers:
-```bash
-zam card due --user <username> --summary
-```
-For **executable/task** sessions, the full listing is fine since the agent needs to plan. Also query ZAM for tokens relevant to the current task to weave them into the session:
-```bash
-echo '{"context":"<1-2 sentence description of the current task>"}' | zam bridge relevant-tokens --user <username>
-```
-If relevant tokens are returned, weave them into the planning session (e.g. "We will be working on task T; you already know X, which applies here").
+Call `zam_status` to fetch connection target, current user, stats, and due review queue size. Show stats as a brief friendly greeting.
+
+For **review/conceptual** sessions, query due reviews without resolving:
+Call `zam_get_reviews` (with `includeQuestions: true`, `noResolve: true`, and `noDynamicQuestion: true`). Keep the returned question hidden until you ask it.
+
+For **executable/task** sessions, also query for tokens relevant to the current task to weave them into the session planning:
+Call `zam_find_tokens` (with the task description context). If relevant tokens are returned, weave them into the planning session (e.g. "We will be working on task T; you already know X, which applies here").
 
 Classify session type:
 - **Executable** — real commands, code, or file edits (e.g. "set up Homebrew", "commit this change")
-- **Conceptual** — pure review with no concrete output (e.g. `$zam repeat`)
+- **Conceptual** — pure review with no concrete output (e.g. `/zam repeat` or `/learn`)
 
 ### STEP 2 — Generate the knowledge plan
 
@@ -173,65 +107,28 @@ Think: *"What must a person know and understand to plan and then execute this ta
 Decompose into a dependency-ordered list of knowledge tokens.
 
 **Deduplication before registering:**
-```bash
-zam token find --query "<keywords>"
-```
-Only register genuinely new concepts. Reuse existing slugs where the concept matches. Note that `zam token find` matches paraphrases semantically.
+Call `zam_find_tokens` first. Only register genuinely new concepts. Reuse existing slugs where the concept matches.
 
 After deduplication and before registering a new token, check for existing semantically related tokens that could be prerequisites ("foundations"):
-```bash
-echo '{"concept":"<concept>","question":"<question>","domain":"<domain>"}' | zam bridge suggest-foundations
-```
-Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval link via the existing prereq path after registering.
+Call `zam_suggest_foundations` (with concept, question, and domain). Present non-flagged suggestions to the user ("Related existing concept X — link it as a foundation?"); on approval, link via `zam_link_prereq`.
 
 **Register tokens and prerequisites:**
-
-As the frontier model, author both the concept and the recall question. The
-local LLM is reserved for review time, where it can rephrase the question
-without making token registration slow or model-dependent. Pass a clear,
-concept-free `--question`; add `--source-link` when the concept is grounded in
-a file or reference:
-```bash
-zam token register --slug <slug> --concept "<one sentence>" --domain <d> --bloom <1-5> --question "<concept-free recall question>" [--source-link <link>]
-zam token prereq --token <child> --requires <parent>
-```
-
-If the token should be reviewed by this user, create the card in the same step:
-
-```bash
-printf '%s\n' '{"slug":"<slug>","concept":"<one sentence>","domain":"<d>","bloom_level":2,"question":"<concept-free recall question>"}' \
-  | zam bridge add-token --user <username>
-```
+As the frontier model, YOU author both the concept and the recall question. Pass a clear, concept-free prompt question so the offline fallback stays high quality.
+Register new tokens and link prerequisites:
+Call `zam_add_token` to register a new token.
+Call `zam_link_prereq` to link any parent prerequisites.
 
 ### STEP 3 — Start a session
 
-**For review/conceptual sessions**, load review data into a temp file so it stays out of the conversation, then start the session quietly:
-```bash
-zam bridge check-due --user <username> > /tmp/zam-review.json
-zam session start --user <username> --task "<description>" --context shell --quiet
-```
-Read `/tmp/zam-review.json` with an available file-reading tool to load card data silently. This gives you all cardIds, slugs, concepts, domains, and bloom levels for the session. **Do not call `bridge get-review` per card** — iterate through the cards from this data.
-
-**For executable/task sessions**, the normal start is fine:
-```bash
-zam session start --user <username> --task "<description>" --context shell
-```
+Call `zam_session_start` with the active user, task description, and execution context. This returns the session ID and details.
 
 ### STEP 4 — Hand off, observe, rate
 
-> **Spoiler-free console option:** For pure conceptual recall, you can hand the
-> whole review off to the standalone console harness instead of probing card by
-> card here:
-> > "Let's do your reviews in the dedicated console — run `zam learn` and rate
-> > yourself. I'll wait."
+> **Spoiler-free console option:** For pure conceptual recall, you can hand the whole review off to the standalone console harness instead of probing card by card here:
+>
+> "Let's do your reviews in the dedicated console — run `zam learn` and rate yourself. I'll wait."
 >
-> `zam learn` shows a concept-free cue, captures the answer, and only then
-> reveals the stored answer (concept + context + resolved `source_link`) before a
-> single 1–4 self-rating — all in-process. This sidesteps agent-CLI autocomplete
-> that would otherwise ghost the answer, and the per-subcommand permission
-> prompts from chained `card update` / `session log` calls. Use the verbal
-> probing below when you want to drive the discussion yourself or add depth a
-> stored answer can't (that richer mode will later be backed by an LLM).
+> `zam learn` shows a concept-free cue, captures the answer, and only then reveals the stored answer before self-rating. This sidesteps agent-CLI autocomplete and multiple permission prompts.
 
 **For executable tasks (observation mode):**
 
@@ -240,128 +137,12 @@ Hand off to the user:
 
 Step back. Do not interrupt unless the user asks for help.
 
-**Choose the observation approach:**
-
-Check the user's preference first:
-```bash
-zam settings get --key monitor_method
-```
-If set to `terminal`, default to Approach B. If set to `inline` or not set, ask the user which they prefer on first use and save it:
-```bash
-zam settings set --key monitor_method --value terminal --quiet
-```
-
-**Approach A — Inline (inside Codex):** When the user chooses agent-assisted execution, run commands with Codex's command tools so command and output remain in the conversation. For user-practice sessions, prefer Approach B so the user performs the work and ZAM can observe it.
-
-**Approach B — Shell monitor (separate terminal):** The preferred approach for real tasks. The agent opens a monitored terminal automatically:
-
-```bash
-zam monitor open --session <session-id> --dir /path/to/project
-```
-
-This spawns a new terminal window (Terminal.app or iTerm2 on macOS), already `cd`'d to the task directory, with observation hooks installed. The user just sees a shell and starts working. Tell them:
-
+To observe, tell the user to open a monitored terminal window:
 > "I've opened a terminal for you. Go ahead and work there — come back here when you're done."
+*(For systems supporting automatic shell terminal spawning, call `zam monitor open --session <id>` or instruct the user to run `zam monitor open --session <id>` in their terminal).*
 
-Shell hooks silently capture every command with timestamps, exit codes, and working directory to a JSONL log. When the user returns:
-
-```bash
-# Preview evidence, confirm each rating, and end the session
-zam session end --session <session-id> --synthesize
-
-# Supply task-specific mappings when skill-to-token links are ambiguous
-zam session end --session <session-id> --synthesize --patterns <json-file>
-```
-
-The analyzer infers ratings from:
-- **Help-seeking**: `--help`, `man`, `tldr` before a matching command → lower rating
-- **Error rate**: non-zero exit codes → lower rating
-- **Speed**: inter-command gaps, thinking pauses → lower if slow
-- **Self-corrections**: same command prefix run repeatedly with different args → lower rating
-
-Single-token agent skills supply command patterns automatically. A pattern file
-contains an array (or `{ "patterns": [...] }`) of
-`{ "slug": "<token>", "patterns": ["<command>"] }` entries. Only medium- and
-high-confidence candidates are proposed. Accept, override, or skip every
-rating; accepted ratings are applied atomically and repeated synthesis is
-idempotent.
-
-Use `zam bridge get-monitor` and `zam bridge analyze-monitor` only when raw
-diagnostic output is needed.
-
-When done, the user can simply close the monitored terminal window — hooks only live in that shell process. No cleanup command needed.
-
-**Approach C — Agent-side UI observation (Level 2):** For GUI tasks where shell hooks can't see what's happening. The agent captures screenshots and analyzes them with Codex's multimodal capabilities, preferably a cost-efficient vision-capable subagent when one is available. Do not rely on the laptop's local LLM for rating unless the user explicitly wants that; it may be too weak for UI evidence.
-
-```bash
-zam session start --user <username> --task "<description>" --context ui --skip-review --json
-```
-
-Workflow:
-1. Tell the user: *"Perform the task in the app, leave the relevant window visible, and come back when you're done."*
-2. When the user returns, capture the screen:
-   ```bash
-   zam bridge capture-ui --session <session-id> --process-name <app>
-   ```
-   Under the default observer policy (`observer.scope=window`) a capture must
-   target a window: pass `--process-name <app>` or `--hwnd <handle>`.
-   
-   If a capture is refused, the response will be `{ "granted": false, "denied": true, "denialReason": "<reason>", "reason": "<explanation>", ... }`.
-   Handle these denial reasons accordingly:
-   - `scope-requires-target`: Pass a target window (`--process-name` or `--hwnd`), or tell the user to enable full-screen captures via `zam settings set observer.scope fullscreen`.
-   - `scope-off`: The observer is disabled. Tell the user to enable it via `zam settings set observer.scope window`.
-   - `sensitive`: The targeted or active window matches the built-in sensitive filter (e.g., password manager, banking, private browsing). Skip UI observation for this step and inform the user.
-   - `denylisted`: The process is explicitly blocked by the user's denylist. Skip UI observation.
-   - `not-allowlisted`: The process is not in the user's allowlist. Suggest the user grant access via `zam observer grant <process>` if appropriate.
-
-   A granted response is JSON with `granted: true`, `imagePath`, `base64`
-   (PNG screenshot), `captureMethod`, `captureTarget` metadata, and a
-   `permission` block. Save to a stable file with `--output <path>` whenever
-   you will pass the image to a subagent.
-3. If Codex subagents are available, spawn a cheap vision-capable subagent (for example a mini model) and pass the screenshot as a local image plus the task, expected evidence, and candidate token slugs. Ask it for observed facts and suggested 1-4 ratings with brief evidence.
-4. Review `captureTarget` and the visual evidence yourself before writing
-   ratings. If `captureMethod` is `fullscreen`, the target is missing, the
-   title/process does not match the intended app, or the screenshot is
-   ambiguous, recapture with `--process-name <name>` or `--hwnd <handle>`
-   before rating. For Windows Store/UWP apps such as Calculator, the visible
-   window may belong to `ApplicationFrameHost` even when the app process is
-   `CalculatorApp`; prefer a targeted recapture and verify the returned window
-   title.
-5. Submit ratings and session logs for only the tokens the user actually exercised.
-
-The `capture-ui` command supports:
-- `--image <path>` — analyze an existing image instead of capturing
-- `--output <path>` — save the screenshot to a specific path
-- `--process-name <name>` or `--hwnd <handle>` — target a specific window when known
-
-On Windows, uses PowerShell/.NET for screen capture. On macOS, uses `screencapture`.
-
-**Observer permissions (Layer 2).** `capture-ui` enforces a
-user-configurable policy resolved from `zam settings`: `observer.scope`
-(`off` | `window` | `fullscreen`), `observer.allowlist`, `observer.denylist`,
-`observer.consent`, `observer.retention`. Set them with e.g.
-`zam settings set --key observer.scope --value window`. A built-in sensitive
-set (password managers, auth/UAC dialogs, banking) is always refused and
-cannot be allowlisted — those return `denied: true` with
-`denialReason: "sensitive"`. Treat any `denied` response as final: do not
-retry to work around it; tell the user which surface was blocked. To check the
-active scope/allow/denylist up front, call `zam bridge get-observer-policy`.
-The user can adjust it with `zam observer status | grant <app> | revoke <app>`.
-
-**Rating scale (all observation approaches):**
-- Completed correctly, no hesitation, no help → **4**
-- Slight pause or looked something up → **3**
-- Made errors, corrected themselves → **2**
-- Asked for help or couldn't proceed → **1** (then explain the concept and continue)
-
-```bash
-zam card update --user <username> --token <slug> --rating <n> --quiet
-zam session log --session <id> --token <slug> --done-by user --rating <n> --quiet
-```
-
-Use `--quiet` to suppress FSRS internals — the learner does not need to see stability, reps, or next-due dates during a session.
-
-For tokens the user never touched (agent did them silently): log `--done-by agent`, no rating.
+When the user returns, end the session:
+Call `zam_session_end` with the session ID and `synthesize: true`. The analyzer infers ratings based on command history, error rates, and speed. Confirm or adjust the returned candidates, then submit them using each candidate's `cardId` or `tokenId`.
 
 **For conceptual sessions (verbal probing):**
 
@@ -377,63 +158,41 @@ For each due token, ask a conceptual question at the right Bloom level:
 
 **CRITICAL: Stop and WAIT for the user to provide their answer. Do not ask for the rating until the user has attempted to answer the conceptual question.**
 
-After the user answers, always run this explicit review loop:
-
-1. **Check the answer first.** Compare the user's answer with the token concept, the recall question, and any resolved source context. Decide whether it is `correct`, `partially correct`, or `incorrect`.
-2. **Give learning feedback before asking for a rating.** State the verdict, give a short reference answer, and explain what was missing or incorrect. Keep this concise, but never skip it — this is where the learning happens.
-3. **Suggest a self-rating.** Propose a rating using the 1-4 scale, based on correctness and recall quality: 4 = complete and instant, 3 = correct with small hesitation or minor gap, 2 = partially correct or needed correction, 1 = blank/incorrect/needed help.
+After the user answers, run the explicit review loop:
+1. **Check the answer first.** Compare the user's answer with the concept definition, the recall question, and resolved source context.
+2. **Give learning feedback before asking for a rating.** State the verdict, give a reference answer, and explain gaps.
+3. **Suggest a self-rating.** Propose a rating from 1 to 4: 4 = instant, 3 = knew it with small gap, 2 = partial recall, 1 = blank/incorrect.
 4. **Ask the user to choose the final rating.**
-   > "My suggested rating is <n>. How do you want to rate it? 1 = drew a blank, 2 = hard recall/partial, 3 = knew it, 4 = instant"
-5. **WAIT for the user to provide a rating (1-4).**
-6. **Only then submit the rating and log the step.** Never save the suggested rating without the user's confirmation.
+5. **WAIT for the user to choose.**
+6. **Submit the rating.** Call `zam_submit_review` with the cardId, rating, sessionId, and `doneBy: "user"`.
+*(For a skipped card, call `zam_review_action`. If the agent executed the step, call `zam_submit_review` with `doneBy: "agent"`, the session ID, and no rating; this logs evidence without advancing FSRS.)*
 
 #### Leveraging Source Links for AI Agent Context
-When a token has a `source_link`, `zam bridge get-review` resolves it for you and returns a `resolvedContext` object alongside `prompt` — you no longer need to fetch the file or URL yourself. Its shape:
-
-- `sourceType: "local" | "remote_web"` → `content` is the literal file/page text, already line-sliced when the link carried a `#L10-L25` anchor. Ground your question and verification directly in it.
-- `sourceType: "dynamic_search"` → `content` is a `QUERY_DIRECTIVE: Run web search for "..."`. Run that web search yourself, then ground the review in the results.
-- `truncated: true` → the content was capped; fetch the full `filePath`/`url` only if you need more.
-- `resolvedContext: null` → no link, or resolution was disabled (`--no-resolve`); fall back to the one-sentence concept, or inspect the path yourself.
-
-Use it to:
-1. **Formulate Contextual Questions**: Instead of asking generic questions based strictly on the one-sentence concept text, use the resolved code or documentation to ask targeted, realistic, deep conceptual questions (e.g., at Bloom level 2, 3, or 4).
-2. **Verify Responses Precisely**: Reference the resolved material to verify the user's answers, addressing specific edge cases, syntax, or trade-offs present in the actual codebase or documentation.
+When calling `zam_get_reviews` or other review lookups, if a token has a `source_link`, the resolved code/documentation context will be returned. Use it to:
+1. **Formulate Contextual Questions**: Formulate deep conceptual questions grounded in the resolved material.
+2. **Verify Responses Precisely**: Check user answers against the actual codebase/documentation.
 
 ### STEP 5 — End session
-```bash
-# Monitored executable session
-zam session end --session <id> --synthesize
 
-# Conceptual or unmonitored session
-zam session end --session <id>
-zam stats --user <username>
-```
-Show progress. Be honest about what the user did vs. what the agent did. Mention 1-2 things to look forward to in the next session.
+For conceptual sessions, call `zam_session_end` to complete the active learning session and print progress. Executable sessions were already ended after synthesis above.
 
 ---
 
 ## Practice Tasks for Stale Skills
 
 When a token is long overdue and has no upcoming executable task to surface it naturally, propose a harmless practice task:
-
 > "You haven't done X in a while. Want to practice? We can install ripgrep via Homebrew, then remove it — just to keep the muscle memory alive."
 
-This is preferable to repeated verbal drilling. Doing > reciting.
-
 ---
 
 ## When the Agent Doesn't Know How
 
 If the agent cannot execute a step:
-
 1. Admit it explicitly: *"I'm not sure how to do this — I would try X or Y. Should I attempt it?"*
-2. If the user guides: attempt it, note what works
-3. Register any new concepts discovered as tokens (dedup first) — these are facts the user might later forget (e.g. "Azure DevOps Problem items require a priority field before creation"). Create user cards for them.
+2. If the user guides: attempt it, note what works.
+3. Register any new concepts discovered as tokens (dedup first).
 4. Save the successful approach as an agent skill entry:
-   ```bash
-   zam skill add --slug <slug> --description "<one sentence>" --steps '<json array>' --tokens <related-slugs>
-   ```
-5. The linked tokens get user cards — they will decay via FSRS and resurface for review like any other card. Automation does not replace retention.
+   Instruct the user to run `zam skill add --slug <slug> --description "<one sentence>" --steps '<json array>' --tokens <related-slugs>`.
 
 ---
 
@@ -443,189 +202,46 @@ A token is blocked when:
 - The user rated it 1 (forgot), AND
 - Its prerequisites have not yet been recalled at least once
 
-The agent works on prerequisites first. When all direct prerequisites reach `reps >= 1`, `zam card unblock` promotes the token back automatically (run at session start).
-
-Never present a blocked token to the user.
+Prerequisites are prioritized first. When all direct prerequisites reach `reps >= 1`, the token is unblocked automatically. Never present a blocked token to the user.
 
 ---
 
 ## Dynamic Token Decomposition
 
-**Principle:** Do not pre-create hundreds of tokens. Let the dependency graph grow
-from real gaps discovered during review. Every rating of 1 is an opportunity to
-diagnose *why* the user couldn't answer — and to create the missing foundations.
-
-This applies primarily to tokens at Bloom 3-5 (apply, analyze, synthesize) that
-cover broad learning areas. School curricula — where a single "Lernbereich" spans
-many underlying concepts — are the canonical use case.
-
-### When to split
-
-A token should be decomposed when ALL of the following hold:
+**Principle:** Do not pre-create hundreds of tokens. Let the dependency graph grow from real gaps discovered during review. Every rating of 1 is an opportunity to diagnose *why* the user couldn't answer — and to create the missing foundations.
 
+Decompose tokens when:
 1. The user rated it **1** (drew a blank / couldn't answer)
 2. The token is at **Bloom ≥ 3** (application or above)
 3. The token covers **multiple distinct concepts** (not atomic)
 4. No prerequisite tokens already exist for the specific gap you diagnose
 
-### How to diagnose
-
-After a rating of 1, pause. Do not just re-ask the same question or move on.
-Ask yourself: **"What would the user have needed to know to answer this?"**
-
-Always check for existing related foundation tokens first:
-```bash
-echo '{"slug":"<failed-token-slug>"}' | zam bridge suggest-foundations
-```
-Offer existing tokens returned as suggestions to the user first (linking them feeds the existing `confirmFoundations` path with `exists: true` and `slug`). Only generate NEW foundation proposals via the LLM for gaps that the suggestions do not cover.
-
-| Symptom | Missing foundation | Create Bloom 1-2 token for |
-|---------|-------------------|---------------------------|
-| Couldn't name key terms | Factual recall | Definitions, terminology |
-| Used terms incorrectly | Conceptual understanding | Explain the concept in own words |
-| Knew facts but couldn't connect them | Structural understanding | How A relates to B |
-| Understood but couldn't apply | Procedural knowledge | Apply concept to a simple case first |
+Query `zam_suggest_foundations` first to check for existing related foundation tokens before proposing new ones.
 
 ### Source-grounded splitting
+If the token has a `source_link` (e.g. to LehrplanPLUS or syllabus), consult it to extract explicitly listed basic terms and concepts before creating foundation tokens. The foundations must stay inside the curriculum scope.
 
-When the high-level token has a `source_link` pointing to a curriculum (LehrplanPLUS,
-school syllabus, certification exam outline), **consult it before creating any
-foundation tokens**. The source defines the official scope — your foundations must
-stay inside it.
-
-**Protocol:**
-
-1. Fetch or follow the `source_link` (WebFetch for URLs, Read for local files)
-2. Locate the relevant Lernbereich / topic section in the source
-3. Extract the **explicitly listed** basic terms, dates, concepts, and
-   "grundlegende Daten und Begriffe" (for LehrplanPLUS) or equivalent
-4. Create foundation tokens ONLY for items that appear in the source
-
-**Example of a BAD split (terms not in curriculum):**
-
-> `ge-aufklaerung-begriffe`: "Define: Aufklärung, Emanzipation, Toleranz,
-> Vernunft, Fortschritt, Naturrecht."
->
-> Problem: The LehrplanPLUS Geschichte 8 LB2 lists "Aufklärung, Menschenrechte,
-> Volkssouveränität, Gewaltenteilung, Parlament, konstitutionelle Monarchie,
-> Bürgertum" as required terms. Emanzipation, Toleranz, and Fortschrittsglaube
-> are NOT part of the 8th-grade Realschule curriculum for this Lernbereich.
-
-**Example of a CORRECT split (terms from the source):**
-
-> `ge-aufklaerung-begriffe`: "Define: Aufklärung, Volkssouveränität,
-> Gewaltenteilung, konstitutionelle Monarchie, Menschenrechte."
->
-> Every term appears in the LehrplanPLUS. The student won't be tested on
-> anything outside this list.
-
-**Rule of thumb:** For curriculum-based tokens, the source is the contract.
-If the source says "grundlegende Daten und Begriffe: X, Y, Z", only X, Y,
-and Z are fair game for Bloom 1-2 foundations. Adding extra terms is scope
-creep and undermines the learner's trust.
-
-### Registration protocol
-
-For each gap you diagnose, register a new token and wire it immediately:
-
-```bash
-# 1. Register the foundation token (Bloom 1-2, atomic, single concept)
-zam token register \
-  --slug <parent-slug>-<gap-keyword> \
-  --concept "<one atomic concept the user was missing>" \
-  --domain <same-domain> \
-  --bloom <1-or-2> \
-  --question "<direct recall or explain question>"
-
-# 2. Wire it as a prerequisite of the high-level token
-zam token prereq --token <high-level-slug> --requires <parent-slug>-<gap-keyword>
-
-# 3. Block the high-level card after all new prerequisites are wired
-zam card block --user <username> --token <high-level-slug>
-```
-
-### What happens next
-
-After wiring prerequisites and blocking the card:
-- The high-level token is removed from the review queue
-- The next review session will surface the *foundation tokens first*
-- Once all prerequisites reach `reps >= 1`, `zam card unblock` promotes the
-  high-level token back into the review queue
-
-If prerequisites already existed when the token was rated 1, the rating command
-blocks it automatically. Use `zam card block` when the missing prerequisites were
-discovered and registered only after the rating.
-
-### Example: High-school history
-
-> User rates `ge-aufklaerung` (Bloom 4: "How did Enlightenment ideas shape the
-> French Revolution and transform Europe's political order?") as **1**.
-
-Agent diagnoses:
-- *"You couldn't name the three estates. You weren't sure what 'popular sovereignty'
-  means. You mixed up 1789 and 1793."*
-
-Agent creates three foundations:
-
-| Token | Bloom | Question |
-|-------|-------|----------|
-| `ge-aufklaerung-staende` | 1 | Who belonged to each of the three estates in 18th-century France? |
-| `ge-aufklaerung-begriffe` | 1 | Define: Enlightenment, popular sovereignty, separation of powers, natural rights. |
-| `ge-aufklaerung-daten` | 1 | Name the five key events of the French Revolution (1789–1799) with dates. |
-
-Agent wires them:
-```bash
-zam token prereq --token ge-aufklaerung --requires ge-aufklaerung-staende
-zam token prereq --token ge-aufklaerung --requires ge-aufklaerung-begriffe
-zam token prereq --token ge-aufklaerung --requires ge-aufklaerung-daten
-zam card block --user <username> --token ge-aufklaerung
-```
-
-`ge-aufklaerung` is now blocked. Next session: foundations first. When they
-stick → `ge-aufklaerung` reappears — this time with a fighting chance.
-
-### Sizing rule
-
-- Create **2–4 foundations per failed high-level token**, not 10
-- Each foundation must be **genuinely atomic** — one fact or concept
-- If the user still fails a foundation, split it further (e.g. "too many dates
-  at once" → one token per date)
-- Over time this builds a **Bloom ladder**: Level 1 facts → Level 2 understanding
-  → Level 3 application → Level 4+ analysis
-
-### Safety
-
-- **Never create more than 10 new tokens in a single session** — if a rating of 1
-  reveals massive gaps, prioritize the 3 most urgent foundations and let the rest
-  emerge in subsequent sessions
-- **Always dedup before registering** — `zam token find --query "<keywords>"`. Note that `zam token find` matches paraphrases semantically, and that `add-token` returns `possible_duplicates` which the agent must surface to the user.
-- **Do not split Bloom 1-2 tokens** — they are already atomic; if the user fails
-  them, the fix is re-exposure and practice, not further decomposition
-- A rating of 1 on a Bloom 1 token means the user needs simpler wording or a
-  mnemonic, not more tokens
+### Registration and wiring:
+For each gap, call:
+1. `zam_add_token` to register the foundation (Bloom 1-2, atomic).
+2. `zam_link_prereq` with `blockUser` to wire it as a prerequisite and block the high-level card.
 
 ---
 
 ## Token Deprecation
 
-Knowledge goes stale. If a token comes up for review and the user indicates it's outdated ("that's not how it works anymore"):
-
-1. Ask: *"Should we drop this, update the concept, or keep it for legacy context?"*
-2. If drop: `zam token deprecate --slug <slug>` — archived, excluded from future reviews
-3. If update: `zam token register` a replacement token, then deprecate the old one
-4. Deprecated tokens are not deleted — they can be consulted, but won't appear in the review queue
+If a token is outdated:
+1. Confirm with the user whether to drop it.
+2. If drop: Call `zam_review_action` (action: "deprecate-token").
+3. If update: Register a replacement token first, then deprecate the old one.
 
 ---
 
 ## Three Symbiosis Modes
 
-| Mode | When | How |
-|------|------|-----|
-| **Shadowing** | User is learning the domain | Agent plans, user executes. Agent observes silently and rates. |
-| **Co-Pilot** | User has basic competence | Agent and user alternate. Agent observes and rates what user does. |
-| **Autonomy** | User has high retention | Agent handles routine. Periodic practice tasks keep skills alive. |
-
-Use `zam stats` domain competence to determine the right mode for each domain.
+- **Shadowing**: User is learning. Agent plans, user executes, agent observes/rates.
+- **Co-Pilot**: User has basic competence. Agent and user alternate.
+- **Autonomy**: User has high retention. Agent handles routine; practice tasks keep skills alive.
 
 ---
 
@@ -634,11 +250,37 @@ Use `zam stats` domain competence to determine the right mode for each domain.
 - Never present a blocked token to the user
 - Never probe synthesis (bloom 5) before all prerequisites reach reps >= 1
 - Never register a token that already exists under a different slug — dedup first
-- Never skip the knowledge plan — it's what makes this a training session, not just a task
+- Never skip the knowledge plan
 - Be honest in the session summary about what the agent did vs. what the user did
-- Rating scale is 1-4 (not 0-3 like the old PoC)
-- Agent execution (`done-by agent`) does NOT advance FSRS state — only user-rated recalls do
-- Observation ratings (from watching the user work) DO count — they are user actions
-- Prefer observation over verbal probing; interrupting flow has a cost
-- Never show card slugs or concept text to the user before asking a review question — they spoil the answer. Use `--summary` for due listings during review sessions.
+- Rating scale is 1-4
+- Agent execution (`done-by agent`) does NOT advance FSRS state
+- Observation ratings DO count
+- Prefer observation over verbal probing
+- Never show card slugs or concept text to the user before asking a review question
 - Do not deprecate tokens without the user's confirmation
+
+---
+
+## Fallback: Bridge CLI
+
+If the MCP transport is unavailable, execute the corresponding `zam` bridge CLI commands:
+
+| Action / Tool | Fallback Command |
+|---|---|
+| Get Status / Stats | `zam bridge check-due --user <id>` |
+| Check Due reviews | `zam bridge check-due --user <id>` |
+| Get Reviews Batch | `zam bridge get-reviews --user <id> --include-questions --no-resolve --no-dynamic-question` |
+| Get Single Review | `zam bridge get-review --user <id>` |
+| Start Session | `zam bridge start-session --user <id> --task "<task>"` |
+| Session Open | `zam bridge session-open --user <id> --task "<task>"` |
+| End Session | `zam bridge end-session --session <id>` |
+| Find Tokens | `zam bridge relevant-tokens` (via stdin JSON) |
+| Register Token | `zam bridge add-token --user <id>` (via stdin JSON) |
+| Link Prereq | `zam token prereq --token <child> --requires <parent>` |
+| Submit Review | `zam bridge submit --card-id <id> --rating <r> [--session <id>] [--done-by user\|agent]` |
+| Review Action | `zam bridge review-action --card-id <id> --action <a>` |
+| Suggest Foundations | `zam bridge suggest-foundations` (via stdin JSON) |
+| Read Monitor | `zam bridge get-monitor --session <id>` |
+| Analyze Monitor | `zam bridge analyze-monitor --session <id>` (via stdin JSON) |
+
+*Note: For the JSON stdin inputs, ensure JSON payloads are piped properly.*