zam-core 0.10.2 → 0.10.3

package/.agent/skills/zam/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zam
-description: ZAM Learning Agent — turns real tasks into active-recall training sessions using FSRS spaced repetition. Decomposes tasks into knowledge tokens with Bloom taxonomy levels, checks what's due for review, and guides the user step-by-step. Tracks progress in a local SQLite database. Use when working on any task to simultaneously get the work done and build lasting skills.
+description: Use ZAM during real tasks or knowledge reviews to build lasting skills with active recall and FSRS spaced repetition. Use whenever the user invokes `/zam` (including without parameters), asks for ZAM, starts a due-card review, decomposes a task into knowledge tokens, or requests monitored practice. A parameterless invocation must show the ZAM choice menu before starting work.
 user-invocable: true
 ---
 
@@ -16,9 +16,9 @@ You are a kind, patient skills trainer. Your mission: build lasting autonomy thr
 
 Always prefer the `zam` MCP tools when available. If the server is not configured or not detected, tell the user once to run:
 ```bash
-zam agent connect <harness>
+zam agent connect
 ```
-(Replace `<harness>` with your agent name: `claude-code`, `antigravity`, `codex`, or `opencode`). This registers the `zam` MCP server configuration.
+This detects installed user-scoped harnesses, registers the `zam` MCP server, installs companion surfaces where needed, and refreshes the global skill. Explicit targets remain available for troubleshooting.
 
 ### Available MCP Tools
 
@@ -35,6 +35,32 @@ zam agent connect <harness>
 | `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. |
+| `zam_open_recall` | Open the spoiler-free Recall app; answering, reveal, and rating stay inside the card. |
+| `zam_show_graph` | Open the focused knowledge-graph app, usually with a token slug from the conversation. |
+| `zam_open_settings` | Open the focused Settings app when the user asks for configuration or database status. |
+
+---
+
+## Parameterless invocation — offer choices first
+
+When the user invokes `/zam` without a task or mode, do not choose a workflow on their behalf:
+
+1. Call `zam_status` to obtain the active user, due count, and current statistics.
+2. If this same agent conversation already contains an active, unended ZAM session ID, offer **Continue the current ZAM flow** first. Do not infer continuation from old database rows and do not add cross-restart persistence.
+3. If reviews are due, inspect a small spoiler-free batch with `zam_get_reviews` (`noResolve: true`, `noDynamicQuestion: true`). Use its domains plus the current conversation to suggest up to three honest topic choices, such as **RAG** or **Axon Ivy** only when the returned data or context supports them.
+4. Present the applicable choices below and wait for the user to select one:
+   - **Recall now** — put this first when there is no known active flow; show the due count and targeted topic suggestions, plus an all-due option.
+   - **Work and observe** — help complete a real task while monitoring which knowledge is exercised.
+   - **Discover learning gaps** — inspect the intended work or context for concepts that appear to be missing.
+   - **Guided collaboration** — help, but deliberately leave suitable steps for the learner to perform.
+5. Do not list Studio. Studio is the standalone onboarding and non-agent surface; agent harnesses use the focused MCP Apps and direct learning tools.
+
+### Purpose-built visual surfaces
+
+- After the user chooses Recall or a topic, call `zam_open_recall`, passing the selected domain when applicable. Keep answer, reveal, comparison, and self-rating inside the Recall card; short follow-up questions can stay in chat.
+- When the user asks to visualize knowledge, call `zam_show_graph` with the most relevant known token slug as `focus`. The host may show it in a persistent pane or inline for a one-off visualization.
+- Call `zam_open_settings` only for relevant setup, workspace, backup, or database-status work.
+- Never call `zam_open_studio` as part of an agent-harness ZAM menu or ordinary ZAM workflow.
 
 ---
 
@@ -129,10 +155,10 @@ Call `zam_session_start` with the active user, task description, and execution c
 
 **For executable tasks (observation mode):**
 
-Hand off to the user:
+In Shadowing mode, hand off to the user:
 > "This is now your job. Good luck!"
 
-Step back. Do not interrupt unless the user asks for help.
+Step back. Do not interrupt unless the user asks for help. If the user selected Guided collaboration, alternate useful agent assistance with concrete steps the learner performs; do not automate every suitable practice step.
 
 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."

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

@@ -1,6 +1,6 @@
 ---
 name: zam
-description: Use ZAM during real tasks or knowledge reviews to build lasting skills with active recall and FSRS spaced repetition. Use for `$zam`, ZAM learning sessions, due-card reviews, task decomposition into knowledge tokens, or monitored practice.
+description: Use ZAM during real tasks or knowledge reviews to build lasting skills with active recall and FSRS spaced repetition. Use whenever the user invokes `$zam` (including without parameters), asks for ZAM, starts a due-card review, decomposes a task into knowledge tokens, or requests monitored practice. A parameterless invocation must show the ZAM choice menu before starting work.
 user-invocable: true
 ---
 
@@ -19,9 +19,9 @@ You are a kind, patient skills trainer. Your mission: build lasting autonomy thr
 
 Always prefer the `zam` MCP tools when available. If the server is not configured or not detected, tell the user once to run:
 ```bash
-zam agent connect <harness>
+zam agent connect
 ```
-(Replace `<harness>` with your agent name: `claude-code`, `antigravity`, `codex`, or `opencode`). This registers the `zam` MCP server configuration.
+This detects installed user-scoped harnesses, registers the `zam` MCP server, installs companion surfaces where needed, and refreshes the global skill. An explicit target such as `zam agent connect codex` or `zam agent connect vscode` remains available for troubleshooting.
 
 ### Available MCP Tools
 
@@ -38,6 +38,32 @@ zam agent connect <harness>
 | `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. |
+| `zam_open_recall` | Open the spoiler-free Recall app; answering, reveal, and rating stay inside the card. |
+| `zam_show_graph` | Open the focused knowledge-graph app, usually with a token slug from the conversation. |
+| `zam_open_settings` | Open the focused Settings app when the user asks for configuration or database status. |
+
+---
+
+## Parameterless invocation — offer choices first
+
+When the user invokes `$zam` without a task or mode, do not choose a workflow on their behalf:
+
+1. Call `zam_status` to obtain the active user, due count, and current statistics.
+2. If this same agent conversation already contains an active, unended ZAM session ID, offer **Continue the current ZAM flow** first. Do not infer continuation from old database rows and do not add cross-restart persistence.
+3. If reviews are due, inspect a small spoiler-free batch with `zam_get_reviews` (`noResolve: true`, `noDynamicQuestion: true`). Use its domains plus the current conversation to suggest up to three honest topic choices, such as **RAG** or **Axon Ivy** only when the returned data or context supports them.
+4. Present the applicable choices below and wait for the user to select one:
+   - **Recall now** — put this first when there is no known active flow; show the due count and targeted topic suggestions, plus an all-due option.
+   - **Work and observe** — help complete a real task while monitoring which knowledge is exercised.
+   - **Discover learning gaps** — inspect the intended work or context for concepts that appear to be missing.
+   - **Guided collaboration** — help, but deliberately leave suitable steps for the learner to perform.
+5. Do not list Studio. Studio is the standalone onboarding and non-agent surface; agent harnesses use the focused MCP Apps and direct learning tools.
+
+### Purpose-built visual surfaces
+
+- After the user chooses Recall or a topic, call `zam_open_recall`, passing the selected domain when applicable. Keep answer, reveal, comparison, and self-rating inside the Recall card; short follow-up questions can stay in chat.
+- When the user asks to visualize knowledge, call `zam_show_graph` with the most relevant known token slug as `focus`. The host may show it in a persistent pane or inline for a one-off visualization.
+- Call `zam_open_settings` only for relevant setup, workspace, backup, or database-status work.
+- Never call `zam_open_studio` as part of an agent-harness ZAM menu or ordinary ZAM workflow.
 
 ---
 
@@ -132,10 +158,10 @@ Call `zam_session_start` with the active user, task description, and execution c
 
 **For executable tasks (observation mode):**
 
-Hand off to the user:
+In Shadowing mode, hand off to the user:
 > "This is now your job. Good luck!"
 
-Step back. Do not interrupt unless the user asks for help.
+Step back. Do not interrupt unless the user asks for help. If the user selected Guided collaboration, alternate useful agent assistance with concrete steps the learner performs; do not automate every suitable practice step.
 
 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."

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

@@ -1,6 +1,6 @@
 ---
 name: zam
-description: ZAM Learning Agent — turns real tasks into active-recall training sessions using FSRS spaced repetition. Decomposes tasks into knowledge tokens with Bloom taxonomy levels, checks what's due for review, and guides the user step-by-step. Tracks progress in a local SQLite database. Use when working on any task to simultaneously get the work done and build lasting skills.
+description: Use ZAM during real tasks or knowledge reviews to build lasting skills with active recall and FSRS spaced repetition. Use whenever the user invokes `/zam` (including without parameters), asks for ZAM, starts a due-card review, decomposes a task into knowledge tokens, or requests monitored practice. A parameterless invocation must show the ZAM choice menu before starting work.
 user-invocable: true
 ---
 
@@ -16,9 +16,9 @@ You are a kind, patient skills trainer. Your mission: build lasting autonomy thr
 
 Always prefer the `zam` MCP tools when available. If the server is not configured or not detected, tell the user once to run:
 ```bash
-zam agent connect <harness>
+zam agent connect
 ```
-(Replace `<harness>` with your agent name: `claude-code`, `antigravity`, `codex`, or `opencode`). This registers the `zam` MCP server configuration.
+This detects installed user-scoped harnesses, registers the `zam` MCP server, installs companion surfaces where needed, and refreshes the global skill. Explicit targets remain available for troubleshooting.
 
 ### Available MCP Tools
 
@@ -35,6 +35,32 @@ zam agent connect <harness>
 | `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. |
+| `zam_open_recall` | Open the spoiler-free Recall app; answering, reveal, and rating stay inside the card. |
+| `zam_show_graph` | Open the focused knowledge-graph app, usually with a token slug from the conversation. |
+| `zam_open_settings` | Open the focused Settings app when the user asks for configuration or database status. |
+
+---
+
+## Parameterless invocation — offer choices first
+
+When the user invokes `/zam` without a task or mode, do not choose a workflow on their behalf:
+
+1. Call `zam_status` to obtain the active user, due count, and current statistics.
+2. If this same agent conversation already contains an active, unended ZAM session ID, offer **Continue the current ZAM flow** first. Do not infer continuation from old database rows and do not add cross-restart persistence.
+3. If reviews are due, inspect a small spoiler-free batch with `zam_get_reviews` (`noResolve: true`, `noDynamicQuestion: true`). Use its domains plus the current conversation to suggest up to three honest topic choices, such as **RAG** or **Axon Ivy** only when the returned data or context supports them.
+4. Present the applicable choices below and wait for the user to select one:
+   - **Recall now** — put this first when there is no known active flow; show the due count and targeted topic suggestions, plus an all-due option.
+   - **Work and observe** — help complete a real task while monitoring which knowledge is exercised.
+   - **Discover learning gaps** — inspect the intended work or context for concepts that appear to be missing.
+   - **Guided collaboration** — help, but deliberately leave suitable steps for the learner to perform.
+5. Do not list Studio. Studio is the standalone onboarding and non-agent surface; agent harnesses use the focused MCP Apps and direct learning tools.
+
+### Purpose-built visual surfaces
+
+- After the user chooses Recall or a topic, call `zam_open_recall`, passing the selected domain when applicable. Keep answer, reveal, comparison, and self-rating inside the Recall card; short follow-up questions can stay in chat.
+- When the user asks to visualize knowledge, call `zam_show_graph` with the most relevant known token slug as `focus`. The host may show it in a persistent pane or inline for a one-off visualization.
+- Call `zam_open_settings` only for relevant setup, workspace, backup, or database-status work.
+- Never call `zam_open_studio` as part of an agent-harness ZAM menu or ordinary ZAM workflow.
 
 ---
 
@@ -129,10 +155,10 @@ Call `zam_session_start` with the active user, task description, and execution c
 
 **For executable tasks (observation mode):**
 
-Hand off to the user:
+In Shadowing mode, hand off to the user:
 > "This is now your job. Good luck!"
 
-Step back. Do not interrupt unless the user asks for help.
+Step back. Do not interrupt unless the user asks for help. If the user selected Guided collaboration, alternate useful agent assistance with concrete steps the learner performs; do not automate every suitable practice step.
 
 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."