zam-core 0.10.1 → 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."

package/README.md

@@ -57,11 +57,13 @@ your work, and guiding you step by step. ZAM connects to the agent apps you alre
 | **Codex** | `zam agent connect codex` |
 | **Antigravity** | `zam agent connect antigravity` |
 | **OpenCode** | `zam agent connect opencode` |
-| **GitHub Copilot** | `zam agent connect copilot` |
+| **GitHub Copilot** (CLI / app) | `zam agent connect copilot` |
 | **Goose** | `zam agent connect goose` |
 
-One command writes the MCP config (your agent may ask you to approve the server). Then
-just type **`/zam`** — or say "let's do this together with ZAM" — and work normally.
+One command writes the MCP config (your agent may ask you to approve the server). For
+GitHub Copilot, it also installs user-scoped Studio, Recall, Graph, and Settings canvases;
+restart Copilot or start a new session after connecting. Then just type **`/zam`** — or
+say "let's do this together with ZAM" — and work normally.
 
 ### 2. ZAM Desktop Studio — *setup, content & graph*