zam-core 0.8.0 → 0.9.1

package/.claude/skills/zam/SKILL.md

@@ -12,60 +12,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 agent connect <harness>
 ```
+(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. |
 
 ---
 
@@ -88,7 +57,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`.
 
 ---
 
@@ -115,25 +84,18 @@ The interface is pluggable — future observers replace Level 1 shell calls with
 ## 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
 
@@ -142,57 +104,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, YOU author both the concept and the recall question. The
-local LLM is reserved for review time, where it rephrases the question live so
-the learner never memorizes a fixed input->output pair. Pass a clear,
-concept-free `--question` so the offline fallback stays high quality:
-```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>
-```
+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 the Read tool (not cat) 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):**
 
@@ -201,71 +134,12 @@ Hand off to the user:
 
 Step back. Do not interrupt unless the user asks for help.
 
-**Two ways to observe:**
-
-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 Claude Code):** User runs commands with the `!` prefix (e.g. `! docker build .`). The agent sees command + output in the conversation. Simple, but no timing data.
-
-**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.
-
-**Rating scale (both 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):**
 
@@ -281,63 +155,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>`.
 
 ---
 
@@ -347,189 +199,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 `/zam` 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.
 
 ---
 
@@ -538,11 +247,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.*

package/README.md

@@ -58,11 +58,28 @@ ZAM is split into two concerns:
 
 - **Core** ([`zam-os/zam`](https://github.com/zam-os/zam)) — The AI-agnostic learning kernel, CLI, bridge protocol, and system beliefs. Shared by everyone.
 - **Personal** (fork of [`zam-os/zam-personal`](templates/personal/)) — Your beliefs, your goals, your identity. You fork it, you own it.
-
 Get started: `zam whoami --set <your-id>`
 
 ---
 
+## 🤖 Agent & MCP Integration
+
+ZAM integrates directly with your coding agents (such as Claude Code, Codex, Antigravity, or OpenCode) via the **Model Context Protocol (MCP)**. This lets your agent drive ZAM sessions automatically using tool calls.
+
+To connect your agent harness:
+```bash
+# Connect to your agent client (claude-code, antigravity, codex, or opencode)
+zam agent connect claude-code
+```
+This writes the necessary MCP server config. Your harness may still ask you to approve the server or its tools. You can also print the config changes:
+```bash
+zam agent connect claude-code --print
+```
+
+Once connected, your agent will use MCP tools (`zam_status`, `zam_get_reviews`, `zam_session_start`, etc.) with the bridge CLI as a fallback.
+
+---
+
 ## 🧹 Review maintenance
 
 Review sessions are not limited to `1`-`4` recall ratings anymore. When a card is wrong, obsolete, or unwanted, the review flow can now: