dsh-deeptutor 0.2.1 → 0.3.1

package/.agents/skills/deeptutor/README.md

@@ -1,7 +1,7 @@
 # DeepTutor Learning Assistant (dsh bundle + SKILL)
 
 > This README is the human-facing documentation; `SKILL.md` is the agent-facing instruction file (loaded on demand).
-> The bundle and this skill both live in `TecFancy/dsh-deeptutor`.
+> The bundle, the Claude Code plugin and this skill all live in `TecFancy/dsh-deeptutor`.
 
 Bridges **DeepTutor** (open-source personalized tutoring platform) into your
 agent: combines your **personal knowledge bases** (RAG retrieval) with
@@ -9,8 +9,9 @@ agent: combines your **personal knowledge bases** (RAG retrieval) with
 questions, and study plans — then archives your notes to a DeepTutor notebook
 for later review.
 
-Shipped as the npm bundle `dsh-deeptutor` for DeepSeek Harness (dsh); the
-installer also copies this skill to `~/.dsh/skills/deeptutor/`.
+Shipped as the npm bundle `dsh-deeptutor` for DeepSeek Harness (dsh), whose
+installer also copies this skill to `~/.dsh/skills/deeptutor/`, and as a
+Claude Code plugin (skills + an MCP server with the same tools).
 
 ## Features
 
@@ -26,7 +27,11 @@ installer also copies this skill to `~/.dsh/skills/deeptutor/`.
 ## Installation
 
 ```bash
-# One-shot: bundle + skill, from the published package
+# Claude Code: plugin = this skill + html-doc + MCP tools
+claude plugin marketplace add TecFancy/dsh-deeptutor
+claude plugin install dsh-deeptutor@dsh-deeptutor
+
+# dsh, one-shot: bundle + skill, from the published package
 pnpm dlx dsh-deeptutor --profile web
 
 # Or install the skill manually from a checkout
@@ -75,6 +80,12 @@ The agent follows the SKILL workflow automatically:
 | `deeptutor_run`  | `capability` (deep_solve / deep_question / deep_research / chat / mastery_path / …), `kbs`, `tools` (rag / web_search), `session_id`, `config`, `language` |
 | `deeptutor_kb`   | `list` / `search` (kb + query + mode) / `info`                                                                                                             |
 | `deeptutor_note` | `notebook` (auto-created), `title`, `type` (chat/question/research/solve), `content` (Markdown)                                                            |
+| `deeptutor_cli`  | `args` (anything after `deeptutor`), `confirm` (state-changing commands, only on the user's request). Destructive and interactive commands are refused.        |
+
+Capabilities are not a fixed list: `deeptutor_run` accepts whatever the
+deployment's ready modules provide (`deeptutor module list`), and every other
+CLI command is reachable through `deeptutor_cli` and discoverable with
+`--help`, so DeepTutor upgrades need no plugin release.
 
 ## Troubleshooting
 
@@ -99,12 +110,12 @@ A: Only env vars change (`DEEPTUTOR_SSH_HOST` / remote paths) — never the SKIL
 A: No. Tools query `deeptutor_kb list` dynamically; new bases are picked up automatically.
 
 **Q: Can other agents (Claude Code / Codex) use it?**
-A: Yes. The SKILL follows the Agent Skills standard and can be linked into `~/.agents/skills/`; the `deeptutor_*` tools are registered by the dsh bundle; other agents use the plain CLI path described in the SKILL.
+A: Yes. Claude Code installs the plugin and gets the skill plus the `deeptutor_*` tools over MCP. Other MCP clients can run the `dsh-deeptutor-mcp` bin (`npx -y -p dsh-deeptutor dsh-deeptutor-mcp`); agents without MCP follow the plain CLI path in the SKILL.
 
 ## Maintenance
 
 The bundle code (`src/`) and this skill live in `TecFancy/dsh-deeptutor`; edit both there.
 
-- Code: `src/index.ts` for tool wiring, `cli-exec.ts` / `turn.ts` for CLI execution, `config.ts` for env vars/helpers → `npm run typecheck && npm test && npm run build`
+- Code: `src/tools.ts` defines the tools (dsh wiring in `index.ts`, MCP in `mcp.ts`), `cli-policy.ts` the `deeptutor_cli` tiers, `discovery.ts` capability discovery, `cli-exec.ts` / `turn.ts` CLI execution, `config.ts` env vars/helpers → `npm run typecheck && npm test && npm run build`; after a DeepTutor upgrade, `npm run check:cli`
 - Skill: edit `.agents/skills/deeptutor/` directly and keep it in step with the tool parameters
 - Release: bump the version in `package.json`, push a `v*` tag → CI publishes to npm

package/.agents/skills/deeptutor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deeptutor
-description: Combine DeepTutor personal knowledge bases (RAG) with authoritative web sources to generate learning content, self-test questions, and study plans, and archive notes to a notebook. Works with both local and remote DeepTutor deployments. Use when the user wants to learn/review a technical topic (e.g. .NET, C#, SQL Server, React), get a deep explanation grounded in their own knowledge bases, generate exercises, or plan their learning.
+description: Combine DeepTutor personal knowledge bases (RAG) with authoritative web sources to generate learning content, self-test questions, and study plans, and archive notes to a notebook. Works with both local and remote DeepTutor deployments. Use when the user wants to learn/review a technical topic (e.g. .NET, C#, SQL Server, React), get a deep explanation grounded in their own knowledge bases, generate exercises, plan their learning, or manage their DeepTutor knowledge bases and notebooks.
 ---
 
 # DeepTutor Learning Assistant (Personal Knowledge Base)
@@ -9,28 +9,32 @@ Combines the user's **personal knowledge bases** (RAG retrieval) with
 **authoritative web sources** to produce learning content, self-test
 questions, and study plans, then archives notes to a DeepTutor notebook.
 
-This skill is **agent-agnostic**: every action below has two equivalent
-drivers —
+## Drivers
 
-- **dsh (with the `dsh-deeptutor` bundle installed):** the `deeptutor_*` tools.
-  They drive the DeepTutor CLI for you, locally or over SSH for remote
-  deployments.
-- **Any agent / plain CLI:** the `deeptutor` executable directly (local
-  binary on PATH, or over SSH for remote deployments). No extension needed.
+This skill is **agent-agnostic**. Use the first driver that exists in your
+environment; the action, not the tool, is what matters.
 
-Pick whichever path exists in your environment; the action, not the tool, is
-what matters.
+1. **The `deeptutor_*` tools** (preferred). dsh registers them through the
+   `dsh-deeptutor` bundle; Claude Code and other MCP clients get the same four
+   tools from the `dsh-deeptutor` plugin's MCP server (in Claude Code they are
+   named `mcp__plugin_dsh-deeptutor_deeptutor__deeptutor_run` and so on).
+2. **The plain CLI.** `deeptutor <args>` locally, or
+   `ssh <DEEPTUTOR_SSH_HOST> <DEEPTUTOR_REMOTE_BIN> <args>` for a remote
+   deployment. On Windows run it from PowerShell, not Git Bash: MSYS rewrites
+   `/home/...` env values into Windows paths.
 
-## When to Use
-
-- The user wants to learn or review a technical topic (.NET, C#, SQL Server, React, …)
-- The user wants content grounded in their own notes/knowledge bases
-- The user wants generated exercises, quizzes, or a learning plan
-- The user wants to archive study notes for later review
+| Tool             | Use it for                                                                  |
+| ---------------- | --------------------------------------------------------------------------- |
+| `deeptutor_run`  | one learning turn: explanation, questions, research, mastery path, …        |
+| `deeptutor_kb`   | list / search / info of knowledge bases                                     |
+| `deeptutor_note` | archive a Markdown note into a notebook (find-or-create, file upload)       |
+| `deeptutor_cli`  | **everything else** the CLI offers: `deeptutor <args>` behind safety tiers |
 
 ## Configuration (env vars, agent-agnostic)
 
-Nothing is hardcoded in this skill; all server parameters come from environment variables (put them in `~/.bashrc` or `~/.zshrc`; any agent — dsh / Claude Code / Codex / opencode — inherits them at startup). **Deployment mode adapts automatically**:
+Nothing is hardcoded in this skill; all server parameters come from environment
+variables that every agent inherits at startup. **Deployment mode adapts
+automatically**:
 
 ```bash
 # Remote deployment (DeepTutor on a server, driven over SSH)
@@ -38,146 +42,107 @@ export DEEPTUTOR_SSH_HOST="tencent-cloud"           # SSH host alias (set = remo
 export DEEPTUTOR_REMOTE_BIN="/home/ubuntu/my-deeptutor/.venv/bin/deeptutor"
 export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 
-# Local deployment (DeepTutor on this machine) — leave DEEPTUTOR_SSH_HOST unset for local mode
+# Local deployment: leave DEEPTUTOR_SSH_HOST unset
 # export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)
 ```
 
-- **Tools path:** the bundle runs the local `deeptutor` CLI, or the remote one
-  over SSH when `DEEPTUTOR_SSH_HOST` is set. `deeptutor serve` does not need to
-  be reachable from this machine.
-- **Plain CLI path:** run `deeptutor <subcommand>` locally, or
-  `ssh <DEEPTUTOR_SSH_HOST> <DEEPTUTOR_REMOTE_BIN> <subcommand>` for remote
-  deployments.
-- DeepTutor 1.7+ ships `kb`, `notebook` and most capabilities as optional
-  modules; `deeptutor module list` shows which are installed and enabled.
-- Migrating to another server only requires changing env vars — never this skill.
-
-## Actions Cheat Sheet
-
-| Action                       | Tools (`deeptutor_*`)            | CLI equivalent (`deeptutor …`)                               |
-| ---------------------------- | -------------------------------- | ------------------------------------------------------------ |
-| List knowledge bases         | `deeptutor_kb action=list`       | `kb list --format json`                                      |
-| Search a knowledge base      | `deeptutor_kb action=search`     | `kb search <kb> "<query>" --format json --mode hybrid`       |
-| Show a knowledge base's info | `deeptutor_kb action=info`       | `kb info <kb>`                                               |
-| Run a learning capability    | `deeptutor_run capability=<cap>` | `run <cap> "<prompt>" --format json`                         |
-| Archive a note to a notebook | `deeptutor_note`                 | `notebook add-md <nb-id> <file> --title "<t>" --type <type>` |
-| View lightweight memory      | — (CLI only)                     | `memory show`                                                |
-| List / inspect sessions      | — (CLI only)                     | `session list` · `session show <id>`                         |
-| Show a notebook's records    | — (CLI only)                     | `notebook show <name>`                                       |
-| Inspect configuration        | — (CLI only)                     | `config show` (troubleshooting)                              |
-
-Capabilities: `deep_solve` / `deep_question` / `deep_research` / `chat` /
-`mastery_path` / `visualize` / `math_animator`.
-
-Useful `run` flags: `--kb <name>` (mount a knowledge base, repeatable),
-`--tool <name>` (`rag`, `web_search`, `reason`, …, repeatable),
-`--session <id>` (continue context), `--language zh`, `--config k=v`
-(repeatable; e.g. `--config num_questions=5`), `--config-json '{"..."}'`
-(complex config), `--notebook-ref <name>` / `--history-ref <id>` (reference
-notebooks or past sessions from the prompt).
-
-## Discovering Commands
-
-The command set evolves — this cheat sheet is a curated subset, not the full
-surface. Before using a command not listed here, **discover it from the CLI
-itself** and never invent flags:
+`deeptutor serve` never needs to be reachable: every call runs the CLI.
+Changing servers only changes env vars, never this skill.
 
-```bash
-deeptutor --help              # top-level commands
-deeptutor <cmd> --help        # one subcommand's options
-```
+## Discover, don't assume
+
+DeepTutor's command set, capabilities and tools change between releases and
+between deployments (1.7+ ships them as optional modules). This skill
+deliberately lists only the core workflow. For anything else, **ask the CLI**
+and use only what it shows; never invent commands or flags:
+
+| To learn                         | Call                                                              |
+| -------------------------------- | ----------------------------------------------------------------- |
+| top-level commands               | `deeptutor_cli args=["--help"]`                                   |
+| one command's subcommands/flags  | `deeptutor_cli args=["kb","--help"]`, `["kb","search","--help"]`  |
+| capabilities ready on this host  | `deeptutor_cli args=["module","list"]` (JSON; `capabilities` of modules with `ready: true`) |
+| tools a turn can enable          | `deeptutor_cli args=["plugin","list"]`, details via `["plugin","info","<name>"]` |
+| knowledge bases                  | `deeptutor_kb action=list`                                        |
 
-Read the output, then use only what it shows. If a needed capability is not
-in `--help`, report that to the user instead of guessing.
+`deeptutor_run` also tells you the available capabilities when you pick one
+that is not ready. If a needed capability or command does not exist, say so to
+the user instead of guessing.
+
+## Safety tiers (`deeptutor_cli`)
+
+- **read**: runs directly. `--help`; verbs `list`, `show`, `info`, `search`,
+  `state`, `status`, `list-*`; `doctor`; `run`.
+- **confirm**: everything else, including commands you have just discovered
+  (`kb create`, `kb add`, `notebook add-md`, `module enable`, …). Set
+  `confirm=true` **only after the user explicitly asked for that change**;
+  never proactively, never to "try it".
+- **blocked**: destructive verbs (`delete`, `remove*`, `clear`, `uninstall`,
+  `rollback`, `login`, …) and interactive or long-running commands (`chat`,
+  `start`, `stop`, `serve`, `init`). The tool refuses them; tell the user the
+  exact command to run in their own terminal.
+
+With the plain CLI driver the same rules apply; you enforce them yourself.
 
 ## Recommended Learning Workflow
 
 ### 1. Gather material from both channels
 
-- `web_search` for **authoritative sources**: official docs (Microsoft Learn / learn.microsoft.com), official blogs, trusted tutorials. Keep the source links.
-- Search the user's personal knowledge base (pick the right one: dotnet-related → their dotnet base, database → sqlserver) to get their own curated notes:
-  - Tools: `deeptutor_kb action=search kb=<kb> query="<topic>"`
-  - CLI: `deeptutor kb search <kb> "<topic>" --format json`
-  - Always list bases first (`deeptutor_kb action=list` / `deeptutor kb list --format json`) — never assume names.
+- `web_search` for **authoritative sources**: official docs (learn.microsoft.com, …), official blogs, trusted tutorials. Keep the links.
+- Search the user's personal knowledge base. List bases first, never assume names:
+  `deeptutor_kb action=list`, then `deeptutor_kb action=search kb=<kb> query="<topic>"`.
 
 ### 2. Deep Solve
 
-- Tools: `deeptutor_run capability=deep_solve prompt="<topic>" kbs=[<kb>] tools=[rag, web_search] language=zh`
-- CLI: `deeptutor run deep_solve "<topic>" --kb <kb> --tool rag --tool web_search --language zh --format json`
+`deeptutor_run capability=deep_solve prompt="<topic>" kbs=[<kb>] tools=[rag, web_search] language=zh`
+
+(CLI: `deeptutor run deep_solve "<topic>" --kb <kb> --tool rag --tool web_search --language zh --format json`)
 
-**Always record the returned `session_id`** — reuse it for every follow-up turn so DeepTutor keeps the context (chat history, knowledge bases, tools).
+**Record the returned `session_id`** and reuse it for every follow-up turn so
+DeepTutor keeps the context (history, knowledge bases, tools).
 
 ### 3. Follow-up questions / targeted reinforcement
 
-Continue with the same `session_id`: details, code examples, common pitfalls, differences vs. authoritative sources.
+Continue with the same `session_id`: details, code examples, pitfalls,
+differences vs. authoritative sources.
 
 ### 4. Self-test
 
-- Tools: `deeptutor_run capability=deep_question prompt="<topic essentials>" session_id=<same> config={num_questions: 5} kbs=[<kb>] language=zh`
-- CLI: `deeptutor run deep_question "<topic essentials>" --session <same> --config num_questions=5 --kb <kb> --language zh --format json`
+`deeptutor_run capability=deep_question prompt="<topic essentials>" session_id=<same> config={num_questions: 5} kbs=[<kb>] language=zh`
 
-### 5. Output a study plan
+### 5. Study plan
 
-Combine all three material sources into a structured plan (Markdown):
-
-- Learning goals and prerequisites
-- Core concept list (marked: from personal KB / authoritative link)
-- Phased schedule (each phase: concept → authoritative reading → KB review → exercises)
-- Quiz questions and acceptance criteria
-- Reference list (authoritative links + KB hit sources)
+Combine the three sources into a structured Markdown plan: goals and
+prerequisites; core concepts (marked personal KB / authoritative link); phased
+schedule (concept → authoritative reading → KB review → exercises); quiz and
+acceptance criteria; references.
 
 ### 5b. Render study material to local HTML (recommended)
 
-When the user wants readable/browsable/printable study material, render the
-answers to a self-contained HTML page (dark/light toggle, TOC, collapsible
-quiz answers, print-friendly) with the **html-doc skill** (zero-dependency
-Node converter):
-
-```bash
-node skills/html-doc/scripts/md-to-html.js <answer.md> --out <page.html> --title "<主题>" --toc
-```
-
-When given the `html` param, `deeptutor_run` does this automatically:
+Pass `html` to `deeptutor_run` and the answer is rendered to a self-contained
+page (dark/light toggle, TOC, collapsible quiz answers, print-friendly) with
+the bundled **html-doc** converter, plus the `.md` source next to it:
 
 ```
-deeptutor_run capability=deep_solve  prompt=<topic>  kbs=[...]  tools=[rag, web_search]
-  html="data/study/<topic>/knowledge.html"  html_title="<主题> · 知识点"  language=zh
-deeptutor_run capability=deep_question  prompt=<topic essentials>  config={num_questions: 5}
-  html="data/study/<topic>/quiz.html"  html_title="<主题> · 自测题"  language=zh
+deeptutor_run capability=deep_solve prompt=<topic> kbs=[...] tools=[rag, web_search]
+  html="data/study/<topic>/knowledge.html" html_title="<主题> · 知识点" language=zh
 ```
 
-Then tell the user the HTML file paths so they can open them in a browser.
-
-### 6. Archive
-
-Store the final notes/plan in a server notebook (e.g. `dotnet-learning`) so they can be retrieved for review later:
-
-- Tools: `deeptutor_note notebook=<name> title="<t>" type=solve content=<markdown>`
-- CLI:
-  ```bash
-  deeptutor notebook list                       # find the notebook id
-  deeptutor notebook create <name> --description "archived"   # only if missing
-  deeptutor notebook add-md <nb-id> <notes.md> --title "<t>" --type solve
-  ```
-
-## Safety Boundaries
+Relative paths resolve against your working directory. To render other
+Markdown, use the html-doc skill's converter
+(`node <html-doc skill dir>/scripts/md-to-html.js <in.md> --out <out.html> --title "<t>" --toc`).
+Tell the user the file paths.
 
-Read-only exploration is always fine: `kb list/info/search`, `memory show`,
-`session list/show`, `config show`, `notebook list/show`.
+### 6. Archive (only on request)
 
-Never run destructive commands: `kb delete`, `memory clear`, `session delete`,
-`notebook remove-record`. Creation/update commands (`kb create/add`,
-`notebook create/add-md/replace-md`, `session rename`) only on the user's
-explicit request — never proactively.
+`deeptutor_note notebook=<name> title="<t>" type=solve content=<markdown>`
+(creates the notebook if missing).
 
 ## Notes
 
-- Tool calls run the DeepTutor CLI (locally or over SSH) and return when the turn finishes; there is no live progress stream.
-- CLI-only flags (not exposed as `deeptutor_run` tool parameters): `--notebook-ref`, `--history-ref`. The tool's `config` object is passed as `--config k=v` for scalars and `--config-json` for nested values.
-- `deep_research` can take minutes: give a generous timeout (900+) or split long tasks.
-- Results may be truncated (default 30000 chars) — ask to continue for the full content.
-- RAG hits can be noisy; treat official sources as authoritative and point out conflicts to the user.
-- Do not delete knowledge bases or run destructive operations (see Safety
-  Boundaries above); `kb create/add` is fine, but only on the user's explicit
-  request, never proactively.
-- CLI output: add `--format json` for machine-readable events; without it you get human-readable text.
+- Calls return when the turn finishes; there is no live progress stream.
+- `deep_research` can take minutes: pass `timeout` 900+ or split the task.
+- Results are truncated at `max_chars` (default 30000); ask to continue for more.
+- `deeptutor_run` covers the common flags; CLI-only flags such as
+  `--notebook-ref` / `--history-ref` go through `deeptutor_cli args=["run", …]`.
+- RAG hits can be noisy; treat official sources as authoritative and point out
+  conflicts to the user.

package/README.md

@@ -2,11 +2,13 @@
 
 **English** | [简体中文](https://github.com/TecFancy/dsh-deeptutor/blob/main/README.zh.md)
 
-A **learning-assistant extension for DeepSeek Harness (dsh)**. It connects your
-agent to a [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor) tutoring
-service, so a dsh session can explain topics in depth, quiz you, plan learning
-paths, search your personal knowledge bases, and keep a study notebook — all
-without leaving the harness.
+A **learning-assistant extension for DeepSeek Harness (dsh) and Claude Code**.
+It connects your agent to a [HKUDS/DeepTutor](https://github.com/HKUDS/DeepTutor)
+tutoring service, so a session can explain topics in depth, quiz you, plan
+learning paths, search your personal knowledge bases, and keep a study
+notebook, all without leaving the agent. In dsh it loads as a bundle; in
+Claude Code (or any MCP client) the same tools are served by a bundled MCP
+server, installed as a Claude Code plugin.
 
 Ask the agent *"teach me async/await"* and it can run a deep-solve, render the
 answer as a self-contained HTML study page you can open in a browser, and
@@ -14,20 +16,41 @@ archive a summary into your notebook.
 
 ## What it adds
 
-Three agent-facing tools that the model uses whenever you ask for learning help:
+Four agent-facing tools that the model uses whenever you ask for learning help:
 
 | Tool | What it does |
 |---|---|
-| `deeptutor_run` | Runs one learning capability: `deep_solve` (in-depth explanation), `deep_question` (self-test questions), `deep_research`, `chat`, `mastery_path` (learning-path planning), `visualize` / `math_animator` (visualization). Can mount your knowledge bases (`kbs`) and tools (`rag`, `web_search`, `reason`, `code_execution`, …); returns a `session_id` so later turns continue the same context. |
+| `deeptutor_run` | Runs one learning capability, e.g. `deep_solve` (in-depth explanation), `deep_question` (self-test questions), `deep_research`, `chat`, `mastery_path` (learning-path planning), `visualize`. Can mount your knowledge bases (`kbs`) and tools (`rag`, `web_search`, `reason`, `code_execution`, …); returns a `session_id` so later turns continue the same context, and can render the answer to an HTML study page. |
 | `deeptutor_kb` | Lists, searches, and inspects your personal knowledge bases (RAG) |
 | `deeptutor_note` | Archives Markdown study notes (plans, summaries, wrong answers) into a server notebook |
-
-The seven capabilities above are the fixed enum accepted by `deeptutor_run`.
-The underlying DeepTutor CLI may expose more — enumerate the full command set
-with `deeptutor --help` / `deeptutor <cmd> --help`. The `deeptutor` skill
-instructs the agent to discover commands this way and, when the tool's enum
-doesn't cover a capability, to drive the CLI directly (local binary or over
-SSH).
+| `deeptutor_cli` | Runs any other DeepTutor CLI command, behind safety tiers (below) |
+
+### Following DeepTutor upgrades without plugin releases
+
+The plugin does not mirror DeepTutor's command surface, so a DeepTutor upgrade
+that adds commands, capabilities or tools needs no plugin change:
+
+- **Capabilities are discovered at runtime.** `deeptutor_run` takes any
+  capability name. The plugin reads `deeptutor module list` (JSON, cached for
+  five minutes) to learn which capabilities the deployment's ready modules
+  provide; a capability whose module is not ready fails fast with the reason and
+  the list of available ones, and names no module lists are passed straight to
+  the CLI (they may come from a DeepTutor plugin).
+- **Every other command goes through `deeptutor_cli`.** The agent discovers
+  commands from the CLI itself (`args: ["--help"]`, then `["kb", "--help"]`, …)
+  instead of a list baked into the plugin. Safety tiers keep the passthrough
+  honest about commands it has never seen:
+
+  | Tier | Commands | Behaviour |
+  |---|---|---|
+  | read | `--help`, verbs `list` / `show` / `info` / `search` / `state` / `status` / `list-*`, `doctor`, `run` | runs directly |
+  | confirm | everything else, including verbs the plugin does not know yet | runs only with `confirm: true`, which the agent may set only after you explicitly asked for that change |
+  | blocked | `delete`, `remove*`, `clear`, `uninstall`, `rollback`, `login`, …; interactive or long-running `chat` / `start` / `stop` / `serve` / `init` | refused; run them in a terminal yourself |
+
+- **Drift check.** Only the few CLI shapes the dedicated tools are built on
+  (`run --format json` events, `kb search`, `notebook add-md`, `module list`)
+  can break the plugin. `npm run check:cli` checks them against the deployment
+  your env vars point at; run it after upgrading DeepTutor.
 
 ## Example session
 
@@ -51,7 +74,8 @@ study page, then archived to a notebook):
 
 ## Requirements
 
-- A working DeepSeek Harness (dsh) install, 0.1.0-rc.6 or newer. The manifest
+- An agent host: Claude Code (or another MCP client) with Node ≥ 20, or a
+  working DeepSeek Harness (dsh) install, 0.1.0-rc.6 or newer. The manifest
   declares a version floor rather than a ceiling, so a new dsh release is never
   refused at install time; a scheduled probe boots the plugin against the
   current npm `latest` and `next` hosts instead and opens an issue when
@@ -67,7 +91,40 @@ study page, then archived to a notebook):
   and most capabilities come from optional modules; check that the ones you
   use are installed and enabled with `deeptutor module list`.
 
-## Install into a profile (bundle)
+## Install into Claude Code (plugin)
+
+This repo is also a Claude Code plugin marketplace. Inside Claude Code:
+
+```text
+/plugin marketplace add TecFancy/dsh-deeptutor
+/plugin install dsh-deeptutor@dsh-deeptutor
+```
+
+or from a shell:
+
+```sh
+claude plugin marketplace add TecFancy/dsh-deeptutor
+claude plugin install dsh-deeptutor@dsh-deeptutor
+```
+
+The plugin brings the two skills (`deeptutor`, `html-doc`) and an MCP server
+named `deeptutor` that serves the four tools (Claude Code shows them as
+`mcp__plugin_dsh-deeptutor_deeptutor__deeptutor_run` and so on). Set the
+`DEEPTUTOR_*` env vars (see [Configuration](#configuration-env-vars-agent-agnostic))
+where Claude Code can inherit them, then restart Claude Code.
+
+The server is started by `scripts/mcp-launch.mjs`, which picks the first entry
+that works: compiled `lib/` → the plugin's own `src/` via Node's type stripping
+(Node ≥ 22.6, no network) → `npx dsh-deeptutor@<plugin version>` for older Node.
+Either way the server runs the code of the installed plugin version.
+
+**Other MCP clients** (Codex, Cursor, …) can run the published bin directly:
+
+```json
+{ "command": "npx", "args": ["-y", "-p", "dsh-deeptutor", "dsh-deeptutor-mcp"] }
+```
+
+## Install into a dsh profile (bundle)
 
 The package is published to npm as `dsh-deeptutor`. Recommended one-liner —
 runs the bundled installer (`scripts/install-profile.mjs`, exposed as the
@@ -125,7 +182,7 @@ install`:
 
 ```json
 {
-  "dependencies": { "dsh-deeptutor": "^0.2.0" },
+  "dependencies": { "dsh-deeptutor": "^0.3.1" },
   "dsh": {
     "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
   }
@@ -164,6 +221,7 @@ Two skills ship inside this package (`.agents/skills/deeptutor` and
 Installing a newer package version overwrites skill files in place; files not
 shipped by the package are never deleted.
 
+The Claude Code plugin loads the same skills straight from `.agents/skills/`.
 The skills are maintained in this repo under `.agents/skills/`.
 
 ## Configuration (env vars, agent-agnostic)
@@ -178,7 +236,7 @@ export DEEPTUTOR_REMOTE_HOME="/home/ubuntu/my-deeptutor"
 # export DEEPTUTOR_LOCAL_BIN="deeptutor"             # local CLI path (default: deeptutor on PATH)
 ```
 
-Restart dsh after changing env vars.
+Restart dsh or Claude Code after changing env vars.
 
 **Windows, local mode:** point `DEEPTUTOR_LOCAL_BIN` at `deeptutor.exe`
 (for a pip/venv install: `<venv>\Scripts\deeptutor.exe`). A `.cmd`/`.bat`
@@ -212,6 +270,8 @@ npm install
 npm run build        # tsc → lib/ (relative .ts imports rewritten to .js)
 npm run typecheck
 npm test             # node:test + type stripping
+npm run check:cli    # drift check against the live DeepTutor your env vars point at
+claude plugin validate . --strict   # Claude Code plugin + marketplace manifests
 npm pack             # inspect dsh-deeptutor-<version>.tgz
 npm publish          # set a scope/registry of your choice first
 ```
@@ -227,12 +287,18 @@ src/                 # TypeScript sources (dev loading, typecheck)
 lib/                 # compiled ESM (published entry, from `npm run build`)
 scripts/md-to-html.js  # zero-dependency Markdown → HTML converter
 scripts/install-profile.mjs  # one-shot profile installer (exposed as the `dsh-deeptutor` binary)
+scripts/mcp-launch.mjs # starts the MCP server for the Claude Code plugin
+scripts/check-cli.ts   # drift check against a live DeepTutor (`npm run check:cli`)
 .agents/skills/       # bundled skills: deeptutor/ + html-doc/ (installed to <DSH_HOME>/skills/)
+.claude-plugin/       # Claude Code plugin.json (skills + MCP server) + marketplace.json
 cordis.yml           # dev overlay: insert src/index.ts by absolute path
 cordis.patch.yml     # bundle patch: insert the package by name
 ```
 
-`src/index.ts` registers the tools; `config.ts` holds env config;
+`src/tools.ts` defines the four tools once, host-neutral; `index.ts` registers
+them in dsh; `mcp.ts` serves them over MCP stdio (`mcp-main.ts` is the
+`dsh-deeptutor-mcp` bin); `cli-policy.ts` holds the `deeptutor_cli` safety
+tiers; `discovery.ts` capability discovery; `config.ts` holds env config;
 `cli-exec.ts` local/SSH CLI execution; `win-cmd.ts` starting a `.cmd`/`.bat` CLI on Windows;
 `turn.ts` one learning turn (CLI JSONL event folding + formatting);
 `html-render.ts` answer → self-contained HTML.