@mthanh/vespercli 1.8.0 → 2.0.0

package/README.md

@@ -1,23 +1,27 @@
 # Vesper Agent Suite
 
-CLI tool to manage AI agents, prompts, instructions, and skills for your workspace — for GitHub Copilot Chat in VS Code, and for Claude Code.
+A CLI that provisions an AI agent suite into your project for **Claude Code** or **GitHub Copilot Chat (VS Code)**: an orchestrator persona, specialist subagents, skills, and maintenance workflows.
 
-**Vesper** is a comprehensive agent suite that supercharges your AI coding assistant with specialized agents, reusable skills, and structured workflows. It supports two platforms — **GitHub Copilot** (VS Code) and **Claude Code** — chosen via a multi-select during `vespercli init`; a single workspace can run both at once, sharing the same `.vesper/` tracking state.
+**Vesper** gives your AI coding assistant specialized agents, reusable skills, and structured workflows. Each workspace runs **exactly one host**, Claude Code or GitHub Copilot, and you pick it with `vespercli init --host claude|copilot`. The project's workflow state (`.vesper/.tracking/`, including the run ledger, and `.vesper/memory.jsonl`) is host-neutral and survives a host switch.
+
+> **Upgrading from 1.x?** Vesper 2.0 is a breaking release. Running `vespercli init` once migrates a 1.x workspace in place and backs up everything it removes. See [Upgrading from 1.x](#upgrading-from-1x) and [`CHANGELOG.md`](CHANGELOG.md).
 
 ## The Vesper Lifecycle
 
-Vesper is a **pure orchestrator** — it routes, gates, and approves every hand-off, but never does the work itself. Each task travels one revolution of the cycle: the violet **delivery loop** ships it (specialist subagents research, plan, implement, review, and test, with every step reading and writing tracking documents under `.vesper/.tracking/`), and the amber **learning loop** mines what just happened — comparing plan vs. actual, then minting skills, instructions, and knowledge-graph memory that are re-injected into the next task.
+Vesper is a **pure orchestrator**: it routes, gates, and approves every hand-off, but never does the work itself. Each task travels one revolution of the cycle. The violet **delivery loop** ships it: specialist subagents research, plan, implement, review, and test, and every step reads and writes tracking documents under `.vesper/.tracking/`. How much of the loop a task travels is set by its **scope tier** — S (implement, gate, log), M (short research, plan, implement, one review, gate) or L (the full pipeline with architect validation, two reviewers and unit tests) — and every tier ends in `vespercli gate`, a pass/fail the orchestrator reads by exit code without reading the work. The amber **learning loop** then mines what just happened. It compares plan with actual, then turns the result into skills, instructions, and knowledge-graph memory that feed the next task.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/lifecycle-ring-dark.svg">
   <img src="docs/images/lifecycle-ring-light.svg" alt="Vesper lifecycle ring: Research, Plan, Validate, Implement, Review + Test (delivery), then Retrospect, Store, Re-inject (learning), with Vesper orchestrating at the center" width="760">
 </picture>
 
-Every revolution leaves the system smarter: divergences from plan become glob-scoped instructions, repeated patterns become skills, and task context survives interruption — across sessions and across both client targets.
+Every revolution leaves the system smarter: divergences from plan become glob-scoped instructions, repeated patterns become skills, and task context survives interruption, across sessions and across a host switch.
 
 ### Tracking documents — the paper trail
 
-Delegation prompts pass **paths, never contents**. Each document has one writer and defined readers, so a fresh-context subagent can pick up mid-pipeline — even a subagent on the *other client* (Copilot ↔ Claude Code share `.vesper/` by design).
+Delegation prompts pass **paths, never contents**. Each document has one writer and defined readers, so a fresh-context subagent can pick up mid-pipeline. The tracking state is host-neutral, so a story researched before a host switch can be implemented after it.
+
+The mechanics around the documents are CLI calls, not model calls. The orchestrator brackets every pipeline with `vespercli log started …` and `vespercli log completed …`, which append one JSON row each to the **run ledger** (`.vesper/.tracking/runs/YYYYMMDD-<slug>.jsonl`), and moves a story between status folders with `vespercli story move <slug> <folder>`. Resumption reads `vespercli story list` and `vespercli log tail`. On Claude Code a `SubagentStart` hook adds a `delegated` row per subagent spawn as optional enrichment; nothing depends on it. The 1.x `history.md` file and its logging agent are gone; the memory graph holds project knowledge, never pipeline state.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-ledger-dark.svg">
@@ -26,7 +30,7 @@ Delegation prompts pass **paths, never contents**. Each document has one writer
 
 ### Implementation runs on prompts, not vibes
 
-The planner doesn't just plan — it writes the *executable brief* each developer will follow:
+The planner doesn't just plan — it writes the *executable brief* each developer will follow. After the developers return, one LLM review (`code-reviewer`; `principal-software-engineer` joins on L only) and then `vespercli gate` — the project's own checks, plan conformance on L, the diff-size cap and protected paths — decide whether the change moves on; a `GATE FAIL` sends the headline, and nothing else, back to the developer. Documentation runs only when the public surface changed, the retrospective only on L or when the reviewer reports a new pattern, and three failed review or gate loops stop for the user before the hard cap of ten.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-chain-dark.svg">
@@ -35,7 +39,7 @@ The planner doesn't just plan — it writes the *executable brief* each develope
 
 ### Task tracker — board is the source of truth
 
-The Task Management section of the orchestration file names the system (ClickUp, Jira, …) and its Task Agent; the pipeline never talks to a board directly. **Local mode** works with zero configuration — the story folders alone carry status.
+The Task Management section of the team roster names the system (ClickUp, Jira, …) and its Task Agent; the pipeline never talks to a board directly. **Local mode** works with zero configuration — the story folders alone carry status.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-tracker-dark.svg">
@@ -57,323 +61,389 @@ Capture is worthless without injection — every knowledge output has a named co
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="docs/images/panel-reentry-dark.svg">
-  <img src="docs/images/panel-reentry-light.svg" alt="Four re-entry points: memory search before research, current_task recall before planning, roster skill injection on every delegation, and glob-bound instruction auto-apply on every matching edit" width="920">
+  <img src="docs/images/panel-reentry-light.svg" alt="Four re-entry points: memory search before research, ledger-driven resume before planning, roster skill injection on every delegation, and glob-bound instruction auto-apply on every matching edit" width="920">
 </picture>
 
-The design optimizes for compounding: mistakes convert to rules, workflows convert to skills, and state survives interruption, `/clear`, and even a client switch. When a fix loop caps out (10 iterations), unresolved issues are written to `issues/` and the pipeline continues — dead ends become documents, not lost context.
+The design optimizes for compounding: mistakes convert to rules, workflows convert to skills, and state survives interruption, `/clear`, and a host switch. When a fix loop caps out (10 iterations), unresolved issues are written to `issues/` and the pipeline continues. Dead ends become documents, not lost context.
+
+## Requirements
+
+- Node.js >= 22.13.0 (the `vesper-indexing` MCP server uses the built-in `node:sqlite` module)
+- git (worktree bootstrap, hooks and host resolution read the repository)
+- One host: Claude Code (CLI, VS Code extension, JetBrains, or desktop app), or VS Code with GitHub Copilot Chat
 
 ## Installation
 
 ```bash
-# Global installation
-npm install -g @mthanh/vespercli
-
-# Or use with npx
-npx @mthanh/vespercli <command>
+npm install -g @mthanh/vespercli   # global install (recommended: the hooks call `vespercli`)
+npx @mthanh/vespercli <command>    # or run it without installing
 ```
 
-## Quick Start
+The session-start triggers and git hooks call `vespercli` from `PATH`. They do nothing when it isn't installed, so a global install is what makes them work.
+
+## Quick start
 
 ```bash
-# Initialize Vesper in your project — multi-select GitHub Copilot and/or Claude Code
-# (pass --target copilot,claude or --target all to skip the prompt)
-vespercli init
+vespercli init --host claude     # or: --host copilot
+vespercli init                   # interactive: asks "Which AI host is this workspace for?"
 ```
 
+A non-interactive run (no TTY) never guesses. It re-uses the host the checked-out tree already carries, and otherwise needs `--host`. `-y`/`--force-default` default the follow-up questions only, never the host choice.
+
 Then say hello:
 
-- **GitHub Copilot** — reload VS Code (`Developer: Reload Window`), open Copilot Chat, select **Vesper** from the agent dropdown, and prompt `Vesperize` — Vesper scans the workspace and assembles your team.
-- **Claude Code** — start a session and prompt `init` — Vesper detects the missing Team Roster and runs the full workspace setup automatically.
+- **Claude Code**: start a session in the project. It opens as the `vesper-orchestrator` agent. The first time, Claude Code asks you to trust the workspace, which loads the `vesper` plugin. Prompt `init`, and Vesper detects the missing Team Roster and runs the workspace setup.
+- **GitHub Copilot**: reload VS Code (`Developer: Reload Window`), open Copilot Chat, pick **vesper-orchestrator** in the agent dropdown, and prompt `Vesperize`.
 
-## Settings-based Asset Injection
+Commit what `init` wrote (see the tables below). The committed files are what make the project a Vesper project for every clone, worktree, and teammate.
 
-Vesper integrates by **pointing your AI client at the packaged catalog** instead of copying assets into your repo — VS Code workspace settings for Copilot, a user-level plugin for Claude Code. Only project-specific files (roster, context, tracking) live in the workspace.
+## What gets written where
 
-<details>
-<summary><b>GitHub Copilot</b> — VS Code settings + MCP servers</summary>
+Vesper writes only inside the project, and every file it writes is recorded in an ownership ledger (see [Ownership and removal](#ownership-and-removal)).
 
-`vespercli init` (with Copilot selected):
+### Claude Code (`--host claude`)
 
-- Creates/updates `.vscode/settings.json` to point Copilot Chat at Vesper's packaged assets.
-- Configures core MCP servers in `.vscode/mcp.json`:
-  - `vesper-indexing`: Fast code search
-  - `sequential-thinking`: Complex reasoning
-  - `memory`: Persistent knowledge graph
-- Does **not** copy agents/prompts/instructions/skills into your workspace.
-- Still creates `.github/agents/vesper.agent.md` so you can select **Vesper** in Copilot Chat.
+The specialist catalog is **not copied** into the project. It ships inside the npm package as a Claude Code **marketplace** (`vesper-marketplace`) holding a **core plugin** (`vesper`) and the stack **packs** (`vesper-frontend`, `vesper-playwright`, `vesper-backend`, `vesper-polyglot`, `vesper-docs`, `vesper-integrations`, and the opt-in `vesper-styles`), all referenced in place. Core specialists resolve as `vesper:<name>` and core skills as `/vesper:<name>`; a packed one as `vesper-<pack>:<name>` / `/vesper-<pack>:<name>`. Core is always enabled; a pack is enabled per project — see [Packs](#packs).
 
-Vesper writes these VS Code settings:
+| Path | Committed? | What it is |
+|---|---|---|
+| `.claude/settings.json` | yes | Vesper's keys only: `enabledPlugins["vesper@vesper-marketplace"]` plus one `enabledPlugins["vesper-<pack>@vesper-marketplace"]` per enabled pack, `agent: "vesper-orchestrator"` (every session opens as Vesper), MCP tool permissions, the `SessionStart` guard hook and the `SubagentStart` run-ledger hook (`vespercli log delegated … --stdin`, optional enrichment). Your other keys are kept. |
+| `.claude/settings.local.json` | no (gitignored) | `extraKnownMarketplaces.vesper-marketplace`, pointing at this machine's npm install. Regenerated per machine, so the committed settings stay portable. |
+| `.claude/agents/vesper-orchestrator.md` | yes | The thin main-thread persona (committed fallback). |
+| `.claude/skills/{reinit,compact-knowledge,revalidate-knowledge,revalidate-team}/` | yes | The four maintenance skills, `disable-model-invocation: true` (user-invoked only). |
+| `.claude/rules/vesper-orchestrator.md` | yes | The orchestrator playbook, always-on. |
+| `.claude/rules/vesper-orchestration.md`, `.claude/rules/vesper-context.md` | yes | This project's Team Roster and slim whitepaper, always-on. Seeded once, then maintained by the Vesper agent. |
+| `.claude/rules/vesper-styles.md` | yes | Only with the opt-in `styles` pack enabled: a ~10-line Vesper-authored pointer rule that applies the third-party output styles (see [Third-party skills](#third-party-skills-packs)). |
+| `.claude/vesper/context/` | yes | The on-demand context tier (read only when needed). |
+| `CLAUDE.md` | yes | A short guarded prose pointer (`<!-- vesper:start -->…<!-- vesper:end -->`). No `@import`: the rules load natively. |
+| `.mcp.json` | no (gitignored) | The three core MCP servers plus any you added. Regenerated at every session start. |
 
-- `chat.agentFilesLocations`
-- `chat.instructionsFilesLocations`
-- `chat.promptFilesLocations`
-- `chat.agentSkillsLocations`
+### GitHub Copilot (`--host copilot`)
 
-Example (illustrative):
+The generated Copilot catalog stays **inside the npm package** (`assets/copilot/`). Vesper points VS Code at it through workspace settings. Every package agent is generated with `user-invocable: false`, so the agent picker shows the built-in agents plus one Vesper agent.
 
-```json
-{
-	"chat.agentFilesLocations": [
-		"${workspaceFolder}/.vesper/agents",
-		"/absolute/path/to/vesper/assets/agents"
-	],
-	"chat.instructionsFilesLocations": [
-		"${workspaceFolder}/.vesper/instructions",
-		"/absolute/path/to/vesper/assets/instructions"
-	],
-	"chat.promptFilesLocations": [
-		"${workspaceFolder}/.vesper/prompts",
-		"/absolute/path/to/vesper/assets/prompts"
-	],
-	"chat.agentSkillsLocations": [
-		"${workspaceFolder}/.vesper/skills",
-		"/absolute/path/to/vesper/assets/skills"
-	]
-}
-```
+| Path | Committed? | What it is |
+|---|---|---|
+| `.vscode/settings.json` | yes | Vesper's keys only: the `chat.agentFilesLocations`, `chat.promptFilesLocations`, `chat.agentSkillsLocations` and `chat.instructionsFilesLocations` entries (the core package folders, one `assets/copilot/packs/<pack>/{agents,skills}` folder per enabled pack — see [Packs](#packs) — plus `${workspaceFolder}/.vesper/{agents,instructions,skills}`), and the managed chat/MCP/auto-approval settings. Your other keys and array entries are kept. |
+| `.vscode/tasks.json` | yes | The `Vesper: worktree bootstrap` folder-open task, running `vespercli guard --running-host copilot`. Your other tasks are kept. |
+| `.vesper/agents/vesper-orchestrator.agent.md` | yes | The one pickable Vesper agent. |
+| `.vesper/instructions/vesper-orchestrator.instructions.md` | yes | The orchestrator playbook, always-on. |
+| `.vesper/instructions/vesper-{orchestration,context}.instructions.md` | yes | The Team Roster and slim whitepaper, always-on, seeded once. |
+| `.vesper/context/` | yes | The on-demand context tier. |
+| `.vscode/mcp.json` | no (gitignored) | The three core MCP servers plus any you added. Regenerated at every session start. |
 
-</details>
+The four maintenance workflows (`reinit`, `compact-knowledge`, `revalidate-knowledge`, `revalidate-team`) are package-resident Copilot prompt files, so they are available as native slash commands. A Copilot workspace gets **no** `.claude/*` file (apart from the cross-host trigger below) and **no** `.github/*` file.
 
-<details>
-<summary><b>Claude Code</b> — user-level plugin + project orchestrator files</summary>
+### Both hosts
 
-Claude Code has no equivalent of VS Code's `chat.agentFilesLocations` setting, so the specialist catalog is distributed as a **user-level plugin** instead: `vespercli init` (with Claude Code selected) installs it once to `~/.claude/skills/vesper/`, making it available in **every** Claude Code project on the machine. In the current project it creates only:
+| Path | Committed? | What it is |
+|---|---|---|
+| `.vesper/.tracking/` (run ledger `runs/` included), `.vesper/memory.jsonl` | yes | Shared workflow state. Host-neutral; never touched by a host switch, a reset, or the migration. |
+| `.vesper/history-archive/` | yes | Read-only archive. `init` moves a 1.x `.vesper/history.md` here as `history-<YYYYMMDD>.md` (never deleted); only `/revalidate-knowledge` reads it. |
+| `.gitignore`, `.gitattributes` | yes | Guarded Vesper blocks: local state ignored; `merge=vesper-memory` for the memory graph, `merge=union` for the recent-decisions ring buffer. |
+| `.git/hooks/pre-commit`, `.git/hooks/post-checkout` | local | A marked Vesper block (see [Git hooks](#git-hooks)). |
+| `.vesperrc` | no (gitignored) | The worktree's ownership ledger (see [Which host is this?](#which-host-is-this)). |
+| `.vesper/index.db` | no (gitignored) | The shared code index read by `vesper-indexing`. |
+| Cross-host trigger | yes | A Claude workspace gets a `Vesper: host guard` task in `.vscode/tasks.json`; a Copilot workspace gets a `SessionStart` guard hook in `.claude/settings.json`. Each one only warns when the *other* host opens the project. |
 
-- `CLAUDE.md` — a small guarded `@import` block pointing at the three files below (never touches the rest of your `CLAUDE.md`)
-- `.claude/vesper/orchestrator.md` — the orchestration playbook (routing rules, delegation), refreshed on every `init`/`update`
-- `.claude/vesper/orchestration.md` — this project's Team Roster + Task Management config
-- `.claude/vesper/context.md` — this project's architecture/stack/conventions, as a slim, freshness-stamped core (≤200 lines, auto-injected into every session); a fuller **on-demand** tier under `.claude/vesper/context/` (conventions, integrations, technical debt, a bounded Recent-Decisions ring buffer) fills in as the Vesper agent learns the workspace, and is read only when an agent needs that detail
-- `.mcp.json` and `.claude/settings.json` — the `vesper-indexing` MCP server + its tool permissions
+### Never written
 
-No editor dependency — these files are read by the Claude Code engine itself, so the same install works from the terminal CLI, VS Code extension, JetBrains, or the desktop app. During install you're asked once whether to prefix catalog names with `vesper-` to avoid collisions with other Claude Code kits.
+Vesper 2.0 never writes a user-level location. Its write primitives refuse these paths:
 
-Two slash commands manage that on-demand knowledge over time: `/compact-knowledge` (size-triggered — archives old history/tracking artifacts and trims the memory graph, non-destructively) and `/revalidate-knowledge` (staleness-triggered — re-scans the codebase, re-validates archived and core knowledge against it, and rebalances the slim-core/on-demand split); Vesper only ever suggests these, never auto-runs them.
+- `~/.claude/skills`, `~/.claude/rules`, `~/.claude/agents`, `~/.claude/commands`, `~/.claude/CLAUDE.md`, `~/.claude/settings.json`
+- `~/.copilot/agents`, `~/.copilot/skills`, `~/.copilot/instructions`
 
-A single project can have both targets installed at once — `.vesper/` (code index, story tracking, `history.md`) is shared and cross-client by design, so a story researched under Copilot can be implemented under Claude Code, or vice versa.
+Two user-level paths are exempt. `~/.claude/plugins/` is Claude Code's own plugin cache: Claude Code writes it when you trust a workspace, and it stays inert in any project whose own settings don't enable the plugin. `~/.vesperrc` stores your answers to the optional vendored-skill prompts. The npm package itself lives wherever npm installs it.
 
-</details>
+`vespercli doctor` reports any Vesper file it finds in a never-write location. A 1.x install could leave some there; see [Upgrading from 1.x](#upgrading-from-1x).
 
-<details>
-<summary><b>Optional: <code>i-have-adhd</code> output-style skill</b> — opt-in, off by default</summary>
+## Claude Code: plugin, trust and degraded mode
 
-Vesper can install a **reviewed, pinned snapshot** of the third-party MIT-licensed [`i-have-adhd`](https://github.com/ayghri/i-have-adhd) skill (Copyright (c) 2026 Ayoub Ghriss) into a Claude Code project. It reshapes response *format* only — lead with the next concrete action, keep it brief and scannable — and explicitly defers to the harness system prompt and preserves safety confirmations. It's vendored once, verbatim, at a pinned commit SHA; it is never fetched at runtime and never auto-refreshed (re-vendoring is a deliberate, reviewed pull request).
+Claude Code loads the `vesper` plugin only after you trust the workspace. If you decline, approve the workspace later in Claude Code's trust settings and run `/reload-plugins`.
 
-**How you're asked**: on `vespercli init` (and re-init) for the Claude target, Vesper asks once — `Install the third-party i-have-adhd output-style skill? (MIT, reviewed snapshot, added to this repo)` — defaulting to **Yes** (a quick Enter accepts). Your answer is remembered in your user-level `~/.vesperrc` (`vendored.adhd.optIn`, a boolean-only setting — no secrets), so you're **only prompted once per machine**; later inits honor the stored answer without asking again.
+The committed fallback (the `vesper-orchestrator` agent, the always-on rules, and the four maintenance skills) resolves in **every** session. The plugin's `vesper:*` specialists and catalog skills resolve only where the plugin loads.
 
-Change or preset the answer any time:
+**Degraded mode (cloud, remote, headless `-p`, Cowork, or a declined trust dialog).** These sessions do not load the marketplace plugin, so the specialists are absent. Two routes lead there:
 
-- `vespercli init --adhd` — install and remember Yes; `vespercli init --no-adhd` — skip and remember No. Both overwrite the remembered answer non-interactively.
-- Pre-set `~/.vesperrc` to `{ "vendored": { "adhd": { "optIn": true } } }` (or `false`) before your first init to answer ahead of time and suppress the prompt. (A pre-1.8 `{ "adhd": { "optIn": … } }` key is still honored.)
+- **Verified absence.** The session-start guard emits `VESPER_PLUGIN_ABSENT` when a condition the plugin needs is verifiably missing on the machine: `vesper@vesper-marketplace` is not enabled once user, project, local and managed settings are merged; no `vesper-marketplace` source is declared in any of those files (`extraKnownMarketplaces`) nor recorded in Claude Code's plugins root (`known_marketplaces.json`); or every declared local marketplace directory is missing. On that token the orchestrator enters degraded mode at once, without a probe.
+- **Probe.** Otherwise (nothing emitted; presence is never claimed, because a disk check cannot prove the plugin loaded), at the first delegation the orchestrator sends one side-effect-free probe to `vesper:task-researcher`. If the platform answers "subagent_type not found", degraded mode follows; if the probe succeeds, the full delegation law applies.
 
-**Headless safety**: in a non-interactive run (`-y`/`--force-default` or no TTY) with no remembered answer and no flag, the skill is **skipped** — Vesper never lets the default-Yes flow into an unattended third-party install. A stored `true` installs; a stored `false` skips.
+On entering degraded mode it prints
 
-The gate is **per-user** (your answer lives once in `~/.vesperrc`), but whether the asset is actually present is tracked **per-project** (recorded in that project's `.vesperrc` once installed). This split matters for scope:
+> ⚠️ Vesper degraded mode: specialist catalog unavailable; operating directly.
 
-- `vespercli init` / re-init are the **only** commands that can *introduce* the asset into a project — they check the opt-in gate and, if enabled, install `.claude/skills/i-have-adhd/SKILL.md`, `.claude/rules/i-have-adhd.md`, and a marker-scoped `@import` in `CLAUDE.md` (outside the Vesper guard block), then record the per-project install.
-- `vespercli update` and `vespercli worktree bootstrap` only **maintain** an already-recorded install (content-compared re-write, no churn on unchanged files) — they never introduce it, even if the opt-in gate is on. On a fresh worktree or clone, the git-tracked artifacts are already there but the local per-worktree record isn't (it isn't git-tracked), so maintain is a no-op there until the project runs `init`/re-init again with the gate enabled.
-- `vespercli reset` fully removes it — the skill directory, the rule file, and the `CLAUDE.md` import region — and clears the per-project record.
+and then works as a single generalist, following the memory and run-ledger conventions inlined in the playbook. The plugin-carried skills are unavailable in degraded mode.
 
-</details>
+Session-start work also needs `vespercli`: the `SessionStart` hook is `command -v vespercli >/dev/null 2>&1 && vespercli guard --running-host claude || true`. Where `vespercli` isn't installed, nothing runs, so `.mcp.json` and the code index are not generated.
 
-<details>
-<summary><b>Optional: <code>ponytail</code> decision-ladder skill</b> — opt-in, off by default</summary>
+## Which host is this?
 
-Vesper can install a **reviewed, pinned snapshot** of the third-party MIT-licensed [`ponytail`](https://github.com/DietrichGebert/ponytail) skill (Copyright (c) 2026 DietrichGebert) into a Claude Code project. It nudges coding work toward the **laziest solution that actually works** — a YAGNI/minimalism decision ladder (does this need to exist? → reuse what's here → stdlib → native feature → existing dependency → one line → minimum code) — while never simplifying away understanding, correctness, validation, or security. **Rule-text only**: only the decision-ladder markdown is vendored. The upstream repo's auto-executing hooks, scripts, other-editor variants, and auxiliary skills are **excluded** — no executable code is vendored, and nothing is ever fetched or run at install time (see `assets/vendor/ponytail/VENDOR.md`). It's vendored once, verbatim, at a pinned commit SHA; re-vendoring is a deliberate, reviewed pull request.
+**The checked-out tree decides.** Vesper resolves the host from Vesper-only keys in files git can see, as they stand in the working tree: the plugin and `agent` keys in `.claude/settings.json` for Claude; the `.vesper/agents` settings entry and the Copilot guard task for Copilot. Generic files such as `.mcp.json` never decide the host. Every path uses this rule: the guard, bootstrap, `doctor`, `init`, `reset`, `list`, `add`, `update` and `mcp`.
 
-**How you're asked**: a second one-time prompt on `vespercli init`/re-init — `Install the third-party ponytail decision-ladder skill? (MIT, reviewed snapshot, rule-text only, added to this repo)` — defaulting to **Yes**. It's **independent** of the i-have-adhd prompt: you can accept one and decline the other. Your answer is remembered in `~/.vesperrc` (`vendored.ponytail.optIn`), so you're only prompted once per machine.
+Consequences:
 
-Change or preset the answer any time:
+- After `git switch`, the new commit decides. A Claude commit gets Claude, a Copilot commit gets Copilot, and a pre-Vesper commit (or a commit that removed Vesper) gets nothing. `git status` stays clean.
+- `.vesperrc` is gitignored and is the worktree's **ledger**: what Vesper wrote here, your opt-ins, and the version stamps. It never decides the host. Bootstrap never writes a host into it; `init` refreshes it.
+- A 1.x commit is left unmigrated whatever the ledger says, because no 1.x artifact carries a 2.0 key.
+- Both hosts' keys present at once means the workspace is ambiguous. Vesper provisions nothing, and `doctor` reports `host-ambiguous`.
 
-- `vespercli init --ponytail` — install and remember Yes; `vespercli init --no-ponytail` — skip and remember No.
-- Pre-set `~/.vesperrc` to `{ "vendored": { "ponytail": { "optIn": true } } }` (or `false`) before your first init.
+Caveats:
 
-**Headless safety** and the **introduce (init/reinit only) vs. maintain (update/bootstrap) vs. reset (full teardown)** scoping are identical to the i-have-adhd asset above — this is the same registry-driven vendored-asset engine. When enabled, init installs `.claude/skills/ponytail/SKILL.md`, a minimal always-on `.claude/rules/ponytail.md` pointer, and a marker-scoped `@import` in `CLAUDE.md`.
+- **A repository that gitignores its resolving file** (`.vscode/`, a `*.code-workspace`, or `.claude/settings.json`): the host is resolved only when the ignored key and the ledger agree. Activation then follows the worktree, not the commit, and a session start refreshes only ignored local state (MCP config, code index). `doctor` reports `host-local-only`. Commit the file to get per-commit behaviour.
+- **A Copilot workspace whose own-host task command was edited *and* whose `.vesper/agents` settings entry was removed** resolves no host until you run `vespercli init --host copilot` again.
 
-</details>
+## Session-start guard
 
-<details>
-<summary><b>Local overrides</b> — customize specific assets</summary>
+`vespercli guard` runs at session start on both hosts. It resolves the checkout's host, runs `doctor` in-process, and then either warns (a host mismatch) or runs `worktree bootstrap`.
 
-If you want to customize a specific agent/prompt/instruction/skill, use `vespercli add`.
+| Trigger | Command | Where it comes from |
+|---|---|---|
+| Claude Code opens the project | `vespercli guard --running-host claude` | `SessionStart` hook in `.claude/settings.json` |
+| VS Code opens the folder | `vespercli guard --running-host copilot` | folder-open task in `.vscode/tasks.json` |
+| `git checkout`/`git switch` of a branch | `vespercli guard` (no host) | `post-checkout` git hook |
 
-- `vespercli add` copies only the assets you select into `.vesper/`.
-- Local copies in `.vesper/` take precedence over the settings-based (package) assets.
-- This is the recommended way to make small, intentional customizations without vendoring everything.
+VS Code runs folder-open tasks only when automatic tasks are allowed in the folder.
 
-</details>
+**Host mismatch** (the host that opened the project is not the checkout's host) is a **warning, never a stop**. The guard writes `VESPER_HOST_MISMATCH` and a one-line fix (`vespercli init --host <running host>`) to stdout, runs no bootstrap, and writes nothing under `.vesper/` and no host-specific file. The only hard rule is a no-write rule: nothing is provisioned for a host the project did not choose.
 
-## Commands
+- **Claude Code**: `SessionStart` stdout goes into the model's context. The always-on playbook prints one banner — `⚠️ Vesper host mismatch: this workspace is set up for <provisioned host>; run \`vespercli init --host <running host>\` for the full team. Operating directly with reduced quality.` — and then continues in [degraded mode](#claude-code-plugin-trust-and-degraded-mode), working directly as a generalist. Reduced quality is accepted; the session is never blocked.
+- **Copilot direction, Claude workspace**: VS Code opens Claude workspaces too (a Claude Code user editing in VS Code), so that task's message is advisory: it names `vespercli init --host copilot` for Copilot users, says it removes the Claude Code setup, and tells Claude Code users to ignore it. Nothing is written.
+- **Copilot**: the folder-open task prints the same token and fix in the terminal, and the Copilot orchestrator playbook carries the same banner-and-continue rule. There is no sentinel file and no always-on refusal rule; a `.vesper/instructions/vesper-host-guard.instructions.md` left by an earlier 2.0 build is removed by the next `init`, `update` or `reset` when it is byte-identical to what Vesper wrote (an edited copy is kept and reported).
+
+**Plugin absence (Claude Code only).** On the healthy path of `vespercli guard --running-host claude`, after bootstrap has regenerated `.claude/settings.local.json`, the guard checks the conditions the plugin needs and writes `VESPER_PLUGIN_ABSENT` to stdout when one is verifiably missing (see [degraded mode](#claude-code-plugin-trust-and-degraded-mode)). It never writes a "present" token. At most one host token and one plugin token appear per run; a mismatch suppresses the plugin token, and the plugin token leaves the exit code unchanged.
 
-<details>
-<summary><b><code>vespercli init</code></b> — initialize platform(s) in your workspace</summary>
+**Without `--running-host`** (the git hook or a manual run) there is no identity claim: no mismatch check and no marker of either kind. The guard writes nothing unless the **committed** tree at `HEAD` carries the resolved host's keys and the working tree still agrees.
 
-Initialize Vesper in your workspace. Pick one or more platforms (GitHub Copilot
-and/or Claude Code) via a multi-select prompt; the CLI lays down the base setup
-for each, then the Vesper agent handles orchestration.
+**Exit codes** (direct invocation only; the installed hook and task force exit 0, and the stdout token is the contract): `0` ok, `1` degraded, `2` mismatch.
 
-- Copilot: creates/updates `.vscode/settings.json` so VS Code discovers Vesper assets from the installed package.
-- Claude Code: installs the user-level plugin catalog + this project's orchestrator/roster/context and `.mcp.json`.
-- Shared: builds the code index once (both platforms' `vesper-indexing` read the same `.vesper/index.db`).
+## `vespercli doctor`
 
-On re-init, currently-installed platforms are pre-checked; **uncheck a platform to remove it** (you'll be asked to confirm). Platform selection is always asked — `-y` / `--force-default` only default the *follow-up* questions, not the platform choice. In non-interactive runs, pass `--target`.
+A **read-only** validator. It never writes, deletes, or backs anything up. It checks host resolution, the ownership ledger against disk, MCP config drift, tracking shape, the framework version, git hooks, 1.x leftovers, and user-level residue. Each finding is `ERROR`, `WARN` or `INFO` and names its fix: `vespercli init`, `vespercli init --host <host>`, `vespercli reset --host <host>`, or `vespercli worktree bootstrap` for local-only state such as a missing git hook block. A fresh worktree's ledger carries no framework version until `init` runs there once; `doctor` reports that as `ledger-unstamped` (INFO), not as a stale framework.
 
 ```bash
-vespercli init                          # Multi-select platform(s), then initialize
-vespercli init --target copilot,claude  # Set up both in one run (no prompt)
-vespercli init --target all             # Every supported platform
-vespercli init --target claude -y       # Non-interactive: Claude with default settings
-vespercli init --path /my/project       # Specify workspace path
+vespercli doctor                                   # human-readable report
+vespercli doctor --quiet --running-host claude     # exit code only
 ```
 
-</details>
+| Exit code | Meaning |
+|---|---|
+| `0` | OK (warnings and info only) |
+| `1` | at least one ERROR (including a check that threw) |
+| `2` | host mismatch (`--running-host` differs from the checkout's host) |
 
-<details>
-<summary><b><code>vespercli add</code></b> — add local overrides</summary>
+`init` runs `doctor` after provisioning, and the guard runs it at every session start.
 
-Add local overrides (copies) for agents, prompts, instructions, or skills into `.vesper/`.
+## Switching hosts, and removing Vesper
 
 ```bash
-# Add agents
-vespercli add --agent <name> [name2...]
-vespercli add -a code-reviewer code-planner
+vespercli init --host copilot    # in a Claude workspace: asks to switch, then switches
+vespercli init --host copilot -y # same, without the confirmation
+```
 
-# Add prompts
-vespercli add --prompt <name> [name2...]
-vespercli add -p create-specification
+A switch removes only the old host's recorded artifacts, then provisions the new host. It carries over what you added: `--override` pins and opt-in instructions, optional MCP servers (e.g. `clickup`), and the enabled packs (the opt-in `styles` pack and its pointer rule included). Tracking (run ledger included) and memory are untouched. The old host's Team Roster and whitepaper are kept where they are. The new host starts from freshly seeded templates, so run the `/reinit` workflow afterwards, or copy the old files across. The switch writes a journal (`.vesper/.host-switch-journal.json`). If it is interrupted, automatic provisioning stays suspended and a plain `vespercli init` resumes toward the host you chose.
 
-# Add instructions
-vespercli add --instruction <name> [name2...]
-vespercli add -i nextjs reactjs
+```bash
+vespercli reset                           # tear down the checkout's host; roster + whitepaper kept
+vespercli reset --host copilot            # in a Claude workspace: clean Copilot leftovers only
+vespercli reset --host claude --purge-knowledge  # full teardown incl. roster, whitepaper, context tier
+```
 
-# Add skills
-vespercli add --skill <name> [name2...]
-vespercli add -s aesthetic backend-development
+`reset --host <x>` on the active host is a full teardown. On the other host it is a foreign-residue clean that leaves the active host alone. Shared state is never touched. A full teardown also removes Vesper's git-hook block, unless another worktree sharing the hooks may still use Vesper (see [Git hooks](#git-hooks)).
 
-# For Claude Code, adds go to the shared plugin catalog instead
-vespercli add agents code-reviewer --target claude
-```
+## Ownership and removal
 
-</details>
+Every Vesper write is recorded in the `.vesperrc` v2 ledger (`schemaVersion: 2`): the path, host, category and, for whole files, a LF-normalised sha256. Files Vesper shares with you (`.vscode/settings.json`, `.claude/settings.json`, `CLAUDE.md`, `.gitignore`, the MCP configs) are recorded by key or region, and Vesper only ever edits its own keys or regions in them.
 
-<details>
-<summary><b><code>vespercli list</code></b> — list local overrides</summary>
+Vesper removes only what it can prove is its own: a recorded whole file whose bytes still match, or a pinned 1.x file (see below). A file you edited is kept and reported. A directory is removed file by file, and only once it is empty, so your own file beside a Vesper file survives. Name or location alone never justifies a removal.
 
-List local override assets in `.vesper/`.
+## Upgrading from 1.x
 
-```bash
-vespercli list                    # List all local override assets
-vespercli ls                      # Alias
-vespercli list --type agents      # Filter by type
-vespercli list -t skills          # Short form
-```
+Install 2.0 and run `vespercli init` in the project. There is no flag and no dry run. The migration happens in place, with standard logging only.
+
+- **Host choice.** A 1.x workspace with one host's artifacts defaults to that host. A workspace with both (1.x dual-target) has no default: interactive runs ask, and non-interactive runs need `--host`.
+- **Clean start.** In a git repository the migration refuses to start while any path it would change has uncommitted changes, and lists them. The one exception is the leftovers of an interrupted migration on the same commit, which `init` resumes.
+- **What it does.**
+  - Removes the 1.x committed catalog (`.claude/{agents,commands,skills}`), the 1.x playbook `.claude/vesper/orchestrator.md`, and the 1.x `CLAUDE.md` `@import` block and SessionStart hooks.
+  - De-injects the 1.x Copilot settings key by key (your own keys and array entries stay).
+  - Relocates the 1.x roster and whitepaper into the chosen host's home, and rewrites `.vesperrc` to v2.
+  - Relocates a Vesper-marked `.github/instructions/orchestration.instructions.md` into the chosen host's home. `.github/copilot-instructions.md` is never removed: Vesper content in it is copied into the brain, and the file stays in place and is reported. `.github/skills/` is never touched.
+  - Tracking, memory and the history archive are never touched; a 1.x `.vesper/history.md` is moved into `.vesper/history-archive/`, never deleted.
+- **Content proof.** A 1.x file is removed only when its bytes equal what a released 1.x build wrote (`assets/legacy/claude-1x-digests.json`). An edited 1.x file is kept and reported once.
+- **User-level residue.** The 1.x machine-wide plugin folder `~/.claude/skills/vesper/` is backed up and removed when it is provably Vesper's. A rule or instruction file under `~/.claude` or `~/.copilot` is removed only when it holds nothing but Vesper guard regions. Anything else, including Vesper keys in `~/.claude/settings.json`, is **reported with the exact edit to make**, never edited. `doctor` keeps reporting it on every project until it is gone.
+- **Backups.** Everything removed without recorded ownership is first copied, verified byte-identical, to `.vesper/.migration-backup/<timestamp>/` (`project/` and `home/` subfolders; gitignored, never removed by Vesper). Nothing is ever overwritten there.
+- **Recover and roll back.** At the end, `init` prints this run's backup folder, a `cp -R …` command that recovers every removed file, and a step-by-step rollback of that one migration:
+  1. check that `HEAD` is still the migration's starting commit (the check changes nothing);
+  2. run `sh <backup>/remove-created.sh`, which removes the files the migration created, and only while each still holds the bytes the migration wrote;
+  3. copy back every whole file the migration rewrote, including the gitignored `.vesperrc`, `.mcp.json` and the git hooks;
+  4. `git restore` the starting commit's committed layout, with hooks disabled for that one command;
+  5. copy back the removed files;
+  6. reinstall the previous CLI, last: `npm install -g @mthanh/vespercli@<1.x version>`. 1.9.x was never published to npm, so for a 1.9.x workspace the guidance says to install it from the repository or pin 1.8.0.
 
-</details>
+  The rollback cannot undo a commit you already pushed after the migration.
+- **Until you migrate**, a 2.0 CLI leaves a 1.x workspace alone. Session start and bootstrap write nothing and print one warning, `update`/`add`/`list` refuse, and `doctor` reports `legacy-workspace` (ERROR), each pointing at `vespercli init`.
+- **Interruption.** The 1.x specialists and the plugin enablement change in the same `vespercli init`. If it is interrupted in between, the project has no specialists (never two competing copies) until you run `vespercli init` again, which finishes the job.
 
-<details>
-<summary><b><code>vespercli update</code></b> — refresh local overrides</summary>
+## Worktrees and bootstrap
 
-Update local override assets from the package to get the latest versions.
+`git worktree add` doesn't bring the gitignored local state along. `vespercli worktree bootstrap` regenerates it, and it already runs through the guard at session start and after a branch checkout, so you rarely call it yourself.
 
 ```bash
-vespercli update                  # Interactive confirmation
-vespercli update -y               # Skip confirmation
+vespercli worktree bootstrap                         # regenerate local state (needs a confirmed host)
+vespercli worktree bootstrap --running-host copilot  # as the host would at session start
+vespercli worktree bootstrap --quiet
 ```
 
-</details>
+On a healthy workspace, bootstrap:
 
-<details>
-<summary><b><code>vespercli reset</code></b> — remove configuration and/or overrides</summary>
+- regenerates the host's MCP config: `.mcp.json` and `.claude/settings.local.json` for Claude, `.vscode/mcp.json` for Copilot;
+- rebuilds the code index;
+- re-asserts the `.gitignore`/`.gitattributes` blocks, the memory merge driver and the git hooks;
+- self-heals the cross-host trigger;
+- refreshes the base branch's remote-tracking ref with a bounded, detached `git fetch`. It never pulls and never touches your branch.
 
-Remove Vesper configuration and/or local overrides.
+It never writes a project-committed catalog, never writes a host into `.vesperrc`, and never writes anything under `.claude/` except the cross-host trigger in a Copilot workspace. A failed step exits `1`.
 
-```bash
-vespercli reset                   # Interactive confirmation
-vespercli reset -y                # Skip confirmation
-vespercli reset --settings-only   # Only remove VS Code settings entries
-vespercli reset --local-only      # Only remove local `.vesper/` folder
-vespercli reset --full            # Remove EVERYTHING including vesper.agent.md (requires typing "YES")
-```
+It writes **nothing** when the running host disagrees with the checkout, on an unmigrated 1.x workspace, while a host switch is pending, or when nothing resolves. Without `--running-host`, it also writes nothing unless the committed tree at `HEAD` confirms the host. A repository that gitignores its resolving file is therefore bootstrapped only at session start.
 
-</details>
+The base-branch fetch is the only background network call Vesper makes (every skill is a packaged snapshot). It is non-interactive and fails fast; an authentication failure prints its cause and the fix (`ssh-add`, or run `vespercli init` in a terminal).
 
-<details>
-<summary><b><code>vespercli worktree</code></b> — bootstrap a worktree's local-only artifacts</summary>
+## Git hooks
 
-Bootstrap a git worktree (or the current workspace) with Vesper's **local-only** artifacts — files that are intentionally gitignored (`.mcp.json`, the code index `.vesper/index.db`, the gitignore guard block, the managed git hooks and `.gitattributes` merge strategy) and therefore don't come along with a plain `git worktree add`. Idempotent and safe to re-run; it already runs automatically via the Claude `SessionStart` hook, the VS Code folder-open task, and a `post-checkout` git hook, so you rarely need to invoke it by hand. No-op on a workspace that was never vesperized.
+`init` and bootstrap install a marked block (`# <!-- vesper:hook:start -->` … `# <!-- vesper:hook:end -->`) into two hooks:
 
-```bash
-vespercli worktree bootstrap            # Regenerate local-only files in this worktree
-vespercli worktree bootstrap --quiet    # Suppress non-error output (used by the hooks above)
-vespercli worktree bootstrap --path /my/project
-```
+- **`post-checkout`** runs `vespercli guard` (no host) only on an **attached branch checkout**: `$3 = 1`, `HEAD` on a branch, and no rebase or bisect in progress. It does not run on file checkouts, `checkout <sha>`, `worktree add --detach`, rebase steps or bisect steps. It makes no network call, never prompts, and never fails the checkout.
+- **`pre-commit`** refuses to commit a `mr.json` recovery artifact. When a commit touches anything outside Vesper's paths, it also **adds every dirty Vesper knowledge path to that commit**: `.claude/{agents,commands,skills,rules}`, `.claude/vesper/context`, `.vesper/{skills,instructions,agents,context}`, `.vesper/.tracking` (the run ledger included), `.vesper/memory.jsonl`, `.vesper/gates.json` and `CLAUDE.md`. It prints which ones it added.
+  - **Agents: set `VESPER_NO_SWEEP=1`** for the commit and stage your own files by path. The sweep is then skipped: the hook stages nothing and prints one line naming the dirty knowledge paths it left out. This keeps another agent's in-flight edits out of an unrelated commit. The sweep stays on for human commits. `doctor` reports a block installed before this variable existed as `git-hook-outdated`; `vespercli worktree bootstrap` rewrites it.
 
-Bootstrap also refreshes the base branch's remote-tracking ref before rebuilding anything else: it resolves the base branch from `origin/HEAD` (e.g. `origin/master`) and runs a bounded (15s) `git fetch` — never `git pull`, so your checked-out branch and working tree are never touched. This keeps anything orienting against "what's on the base branch" (like a fresh worktree) looking at a recent `origin/<base>` instead of a possibly stale local checkout. It never fails the bootstrap: offline, no configured remote, or an unreachable/auth-expired remote all just log a warning (printed even under `--quiet`) and continue with the existing local refs.
+**Opt out** for one repository with `git config vesper.hooks false`. It takes effect at once, because both blocks check it on every run, and `init`/bootstrap then install no hook block. `git config --unset vesper.hooks` turns them back on. The `.gitattributes` merge config is not affected.
 
-</details>
+Hook safety:
 
-<details>
-<summary><b><code>vespercli mcp</code></b> — manage MCP servers</summary>
+- Vesper writes a hook only inside the repository's own hooks directory. It never writes through a symlink or `core.hooksPath` that points outside the repository, into a hook git tracks, into a non-`sh` or binary hook, or into a hook that exits before the block would run.
+- In each of those cases it prints one line saying what to add by hand. It also prints one line when hooks are disabled, machine-wide, or managed by husky v9.
+- It repairs, byte-exact, a block an earlier Vesper version appended to such a hook.
+- `reset` removes the block only when no other worktree sharing the hooks may still use Vesper; an unknown state counts as "may". It never writes into a sibling worktree.
 
-Manage MCP servers for whichever target(s) are installed here — Copilot (`.vscode/mcp.json`), Claude Code (`.mcp.json`), or both at once. `mcp add`/`mcp remove`/`mcp list` are for **optional catalog servers** (e.g. `clickup`); the three Vesper-core servers (`vesper-indexing`, `sequential-thinking`, `memory`) are managed separately via `mcp enable`/`mcp disable`/`mcp sync` and are never addable/removable through `mcp add`/`mcp remove`.
+## MCP servers
+
+Every workspace gets three core servers: `vesper-indexing` (fast code search over `.vesper/index.db`), `sequential-thinking`, and `memory` (the knowledge graph in `.vesper/memory.jsonl`). The MCP config is gitignored and regenerated at every session start: `.mcp.json` (with `${VAR}` substitution) for Claude, `.vscode/mcp.json` (with `${env:VAR}`) for Copilot.
 
 ```bash
-vespercli mcp                              # Show MCP server status for the installed target(s)
-vespercli mcp status --target claude       # Status for Claude Code only; also warns if .mcp.json has drifted from .vesperrc tracking
-vespercli mcp list                         # List catalog + custom servers, and which are installed
-vespercli mcp add clickup                  # Add a catalog server (writes both .vscode/mcp.json and .mcp.json in a dual-target workspace)
-vespercli mcp add clickup --target claude  # Add for Claude Code only — writes .mcp.json (env values rewritten to Claude's ${VAR} form) and records it in .vesperrc
-vespercli mcp remove clickup               # Remove a catalog server (mirrors add's target resolution)
-vespercli mcp enable                       # Enable the core vesper-indexing server
-vespercli mcp disable                      # Disable it
-vespercli mcp sync                         # Re-sync tool auto-approval (Copilot) / refresh config (Claude)
-vespercli mcp reindex --full               # Clear and rebuild the shared code index
+vespercli mcp                   # status for the checkout's host
+vespercli mcp list              # catalog + custom servers, and which are installed
+vespercli mcp add clickup       # add an optional catalog server (recorded in .vesperrc)
+vespercli mcp remove clickup
+vespercli mcp enable | disable  # the core servers
+vespercli mcp sync              # re-sync tool auto-approval (Copilot) / refresh config (Claude)
+vespercli mcp reindex --full    # clear and rebuild the code index
 ```
 
-`mcp status`'s "Server built" line is a tri-state health check, not a simple built/not-built flag — it probes the manifests of the `vesper-indexing` server's two direct runtime dependencies (`@modelcontextprotocol/sdk`, `zod`) rather than just checking that their `node_modules` folders exist, so a corrupted install (present as a directory but missing its own `package.json`, e.g. from an interrupted install) is caught instead of misreported as healthy:
+**`mcp disable` makes no lasting change.** It removes the servers from the MCP config only **until the next session start** (or any other bootstrap), which regenerates them. MCP commands never write a host-resolving key, and a Claude MCP write on a workspace not provisioned for Claude is refused with nothing written.
 
-- `✓ yes` — built and dependencies verified.
-- `⚠ yes, but dependencies missing — run 'npm install' in src/mcp/vesper-indexing (or reinstall Vesper)` — the build output exists but a dependency is corrupted/missing; the server will crash at startup with `ERR_MODULE_NOT_FOUND` until repaired.
-- `✗ no` — not built yet; run `cd src/mcp/vesper-indexing && npm install && npm run build`.
+`mcp status`'s "Server built" line probes the `vesper-indexing` server's two runtime dependencies (`@modelcontextprotocol/sdk`, `zod`):
 
-This check is detective, not a repair itself — `npm install`/reinstalling Vesper afterward is still a manual step for an already-corrupted install. `npm install` for the bundled CLI package self-heals this automatically going forward via `postinstall.js`, which uses the same canary to decide whether to skip or re-run its own install.
+- `✓ yes`: built and verified.
+- `⚠ yes, but dependencies missing`: the build exists but a dependency is broken. Run `npm install` in `src/mcp/vesper-indexing`, or reinstall Vesper.
+- `✗ no`: not built.
 
-</details>
+## Copilot: opt-in stack-specific instructions
 
-<details>
-<summary><b><code>vespercli --version</code></b> / <b><code>--help</code></b></summary>
+Stack-specific Copilot instructions (`flutter`, `java`, `nextjs-tailwind`, `reactjs`, `tailwind-v4-vite`, `self-explanatory-code-commenting`, `task-implementation`) are **opt-in per project**. Each one you add is injected into `chat.instructionsFilesLocations` and recorded in the ledger. A host switch carries it over.
 
 ```bash
-vespercli -v                      # Display the current version
-vespercli --version
-vespercli -h                      # Display help information
-vespercli --help
-vespercli <command> --help
+vespercli add instructions            # pick from the list
+vespercli add instructions reactjs    # add one; reload VS Code to apply
 ```
 
-</details>
+`add agents|prompts|skills` is informational on Copilot, because every package agent, prompt and skill is already injected.
 
-## Asset Types
+On Claude Code every specialist and skill is served by the plugin, so `add` is informational too. `vespercli add <agents|skills> <name> --override` pins a project-level copy, which shadows the plugin's version. The copy is recorded, `reset --host claude` removes it, and a host switch carries it over. `add prompts` is refused, because 2.0 provisions no slash commands.
 
-Vesper provides a full catalog via VS Code settings, and supports optional local overrides.
+## Packs
 
-| Type | Discovered from Vesper package (settings-based) | Optional local overrides (copied by `vespercli add`) |
-|------|-----------------------------------------------|--------------------------------------------------|
-| **Agents** | `assets/agents/` | `.vesper/agents/` |
-| **Prompts** | `assets/prompts/` | `.vesper/prompts/` |
-| **Instructions** | `assets/instructions/` | `.vesper/instructions/` |
-| **Skills** | `assets/skills/` | `.vesper/skills/` |
+The catalog is a **core** plugin plus six stack **packs**, and a project enables only the packs its Team Roster needs. Core (`vesper`) holds the support, review and generic developer/tester specialists and the skills every project uses; each pack is a separate plugin in the same marketplace (`assets/claude/packs/<pack>/`, plugin `vesper-<pack>`):
 
-## After Installation
+| Pack | Plugin | Agents | Skills |
+|---|---|---|---|
+| `frontend` | `vesper-frontend` | `expert-react-frontend-engineer`, `expert-nextjs-developer`, the five `jest-react-*` | `reactjs`, `nextjs`, `nextjs-tailwind`, `react-mui-tanstack`, `vercel-react-best-practices`, `tailwind-shadcn`, `tailwind-v4-vite`, `web-frameworks`, `frontend-design`, `aesthetic`, `premium-frontend-ui`, `web-design-guidelines` |
+| `playwright` | `vesper-playwright` | the five `playwright-*` | `playwright-generate-test`, `playwright-typescript`, `chrome-devtools` |
+| `backend` | `vesper-backend` | `nodejs-express-developer`, `firebase-developer` | `backend-development`, `databases`, `better-auth`, `nestjs`, `devops` |
+| `polyglot` | `vesper-polyglot` | — | `java`, `flutter`, `google-adk-python` |
+| `docs` | `vesper-docs` | — | `document-skills`, `ai-multimodal` |
+| `integrations` | `vesper-integrations` | `clickup-agent` | `gitlab-guardrails` |
 
-- **GitHub Copilot** — reload VS Code, open Copilot Chat (`Ctrl+Shift+I` / `Cmd+Shift+I`), select **Vesper** from the agent dropdown, and prompt `Vesperize` to assemble your team.
-- **Claude Code** — start a session (terminal, VS Code extension, JetBrains, or desktop app) and prompt `init` — Vesper runs the full workspace setup automatically.
+Every pack also carries a byte-identical copy of the shared `agent-fundamentals` skill (every agent preloads it by bare name; the generator keeps the copies in sync). `vespercli catalog` (the shipped `assets/CATALOG.md`) names each asset's pack, and `assets/manifest.json` carries the same mapping for the CLI.
 
-Either way you end up with the same suite — specialized developers, planners, reviewers, and testers orchestrated by Vesper, sharing one `.vesper/` tracking state across both clients.
+**Enabling.** `vespercli packs sync` reads the Team Roster (`.claude/rules/vesper-orchestration.md` on Claude, `.vesper/instructions/vesper-orchestration.instructions.md` on Copilot), maps every named agent and assigned skill to its pack, and enables the packs needed. It never disables a pack (it reports the ones no longer needed). `init` and `update` run it, and the `/reinit` and `/revalidate-team` workflows end with it. By hand: `vespercli packs enable <pack>` / `disable <pack>`; `vespercli packs` lists what the package ships, what is enabled here and what the roster needs.
 
-## Requirements
+- **Claude Code**: one `enabledPlugins["vesper-<pack>@vesper-marketplace"]` key per enabled pack in the committed `.claude/settings.json`, recorded in the ledger like the core key. The marketplace source in `.claude/settings.local.json` already covers every plugin. A packed specialist is delegated to as `vesper-<pack>:<name>`; the roster carries that name.
+- **Copilot**: one `chat.agentFilesLocations` / `chat.agentSkillsLocations` entry per `assets/copilot/packs/<pack>/{agents,skills}` folder, injected and recorded like the core entries. Names stay plain, as everywhere on Copilot. The opt-in instructions stay a separate, per-project mechanism (`vespercli add instructions`) whichever pack their skill lives in.
 
-- Node.js >= 22.13.0 (the `vesper-indexing` MCP server uses the built-in `node:sqlite` module)
-- VS Code with GitHub Copilot, and/or Claude Code (CLI, VS Code extension, JetBrains, or desktop app)
+Only the core key resolves the host: a workspace whose settings carry pack keys alone resolves nothing. `reset --host <host>` removes the pack keys or locations with the core ones, and a host switch replays them onto the new host. `vespercli doctor` reports a roster naming an asset of a disabled pack as `pack-not-enabled` (WARN, fix `vespercli packs sync`) and an enabled pack the roster does not use as `pack-unused` (INFO). A workspace provisioned before packs keeps working: core resolves as before, and the next `init` (or `packs sync`) enables what its roster needs.
+
+## Third-party skills (packs)
+
+Third-party content is **pack content**: shipped in the npm package like every other pack asset, served through the pack's plugin (Claude) or injected folder (Copilot), pinned to an upstream commit in an `UPSTREAM.json` beside each `SKILL.md` (with the upstream `LICENSE` verbatim), never fetched at command time — and **never written into a project**. Nothing lands under `.claude/skills/` or `.vesper/skills/`; there is no consent prompt, no `--adhd`/`--ponytail` flag and no `~/.vesperrc` record any more.
+
+- In `vesper-integrations` (enabled by the Team Roster like any pack, or `vespercli packs enable integrations`): [`gitlab-ci-skill`](https://gitlab.com/gitlab-org/ci-cd/gitlab-ci-skill) and [`github-actions-to-gitlab-ci`](https://gitlab.com/gitlab-org/ci-cd/github-actions-to-gitlab-ci) (MIT, Copyright (c) 2026-present GitLab Inc.), as `/vesper-integrations:<name>`.
+- In the opt-in `vesper-styles`: [`i-have-adhd`](https://github.com/ayghri/i-have-adhd) (MIT, Copyright (c) 2026 Ayoub Ghriss), an output-style skill, and [`ponytail`](https://github.com/DietrichGebert/ponytail) (MIT, Copyright (c) 2026 DietrichGebert), a "laziest solution that works" decision ladder (rule text only; no upstream hooks or scripts ship). **`vespercli packs enable styles` is the consent.** Because both styles are meant to apply on every reply, enabling the pack also writes a ~10-line Vesper-authored pointer rule — `.claude/rules/vesper-styles.md` (Claude) or `.vesper/instructions/vesper-styles.instructions.md` with `applyTo: '**'` (Copilot) — telling the model to load `/vesper-styles:i-have-adhd` and `/vesper-styles:ponytail` at session start. The rule is recorded in the ledger (`pack-rule`), removed by `vespercli packs disable styles`, `reset --host` and a host switch (and replayed on the new host); an edited rule is kept and reported. No third-party text is ever written into the repo.
+
+A newer upstream reaches your project with the next Vesper release. `vespercli packs upstream` compares each pinned commit with the upstream `HEAD` (network, 3 s per call, never a prompt; an unreachable upstream is a row, not an error), and an attended `vespercli update` prints one advisory line per newer upstream. `doctor`, `guard`, `worktree bootstrap` and `init` never check.
+
+**Upgrading**: `init` retires the copies an older Vesper placed in the project (`.claude/skills/<name>`, `.vesper/skills/<name>`, `.claude/rules/{i-have-adhd,ponytail}.md`, `.vesper/instructions/<name>.instructions.md`, the `CLAUDE.md` import blocks) — on proof only: a recorded hash, bytes equal to the shipped snapshot, or the pinned 1.x digests. An edited copy is kept and reported once; delete it yourself. A recorded opt-in to the styles enables the `styles` pack so the behaviour you chose survives.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `vespercli init [--host claude\|copilot] [-y] [--force-default] [--path <dir>]` | Provision, switch host, re-provision, or migrate a 1.x workspace. `--target` is a deprecated alias of `--host`; `all` and comma lists are rejected. |
+| `vespercli doctor [--quiet] [--running-host <host>]` | Read-only validation; exit `0`/`1`/`2`. |
+| `vespercli guard [--running-host <host>]` | Session-start guard (installed as the hook and task). |
+| `vespercli gate [--plan <file>] [--base <ref>] [--json]` | Run the committed gate policy (`.vesper/gates.json`): checks, plan conformance, diff-size cap, protected paths. Exit `0` pass, `1` fail, `2` no config. See [Gates](#gates). |
+| `vespercli log <started\|completed\|note\|delegated\|returned> --pipeline <p> [--step <s>] [--agent <a>] [--goal <g>] [--author <a>] [--status DONE\|NEED_HELP\|BLOCKED] [--slug <slug>] [--note <text>] [--stdin] [--json]` | Append one row to the run ledger `.vesper/.tracking/runs/YYYYMMDD-<slug>.jsonl` (atomic append; `--slug` defaults to `adhoc`). `--stdin` reads a Claude Code hook's JSON. Exit `2` on a missing required field. |
+| `vespercli log tail [--slug <slug>] [-n 5] [--json]` | Print the last run-ledger rows — what the orchestrator reads on resumption. |
+| `vespercli story move <slug> <refining\|backlog\|inprogress\|inreview\|completed>` | Move a story between status folders (found by substring of the file name; refuses on 0 or >1 matches; `git mv` when tracked and clean, plain rename otherwise). Exit `1` refused, `2` usage. |
+| `vespercli story list [--folder <f>] [--json]` | List stories: folder, slug and title. |
+| `vespercli worktree bootstrap [--running-host <host>] [--quiet]` | Regenerate local state for this worktree. |
+| `vespercli reset [--host <host>] [--purge-knowledge] [-y]` | Remove a host's artifacts. |
+| `vespercli update [--host <host>]` | Refresh the checkout's host: the Claude committed fallback and playbook, or the Copilot surface. |
+| `vespercli add [type] [name] [--host <host>] [--override]` | See [opt-in instructions](#copilot-opt-in-stack-specific-instructions). |
+| `vespercli list [type] [--host <host>]` (`ls`) | List what is enabled here. |
+| `vespercli catalog` | Show the catalog from the installed package (offline). |
+| `vespercli packs [list\|enable <pack>\|disable <pack>\|sync\|upstream] [--host <host>]` | See [Packs](#packs): list what is shipped/enabled/needed, enable or disable one pack (`styles` also writes/removes its pointer rule), enable every pack the Team Roster needs, or check the third-party pack skills against their upstreams (network). |
+| `vespercli mcp <subcommand> [--host <host>]` | See [MCP servers](#mcp-servers). |
+| `vespercli settings <add\|remove\|list> [key] [value]` | Manage Vesper's VS Code settings (e.g. `read-access` paths). |
+
+On every host-scoped command `--host` names the host and the checkout decides when it is omitted; `--target` is a hidden, deprecated alias everywhere.
+
+Re-initialize with `vespercli init`. The `/reinit` maintenance skill (Claude) or prompt (Copilot) is a different thing: it asks the Vesper agent to re-scan the codebase and refresh the Team Roster and whitepaper. There is no `vespercli reinit` command.
+
+### Evals (development)
+
+The playbook and the specialists are prompts, so two eval layers guard their behavior, both real model calls and both kept out of the deterministic test gate: `npm run eval` drives `claude -p --agent vesper-orchestrator` through a fixture workspace and grades the orchestrator's classification, tiers, degraded mode, host-mismatch warning, delegation law and gate wiring (`evals/orchestrator/*.json`; exit `3` = skipped loudly when `claude` or a credential is missing); `npm run eval:plugin` runs the core plugin's [`claude plugin eval`](https://code.claude.com/docs/en/plugin-evals.md) suite (`assets/claude/evals/`) over the specialists' output and write-location contracts. `.github/workflows/evals.yml` runs both weekly and on demand, skipping with a visible warning when `ANTHROPIC_API_KEY` is not set. See [`docs/releasing.md`](docs/releasing.md#4-evals).
+
+The other maintenance workflows are `/compact-knowledge` (archives completed tracking stories, trims the memory graph), `/revalidate-knowledge` (re-validates captured knowledge against the code) and `/revalidate-team` (a roster-only review). Vesper suggests them and never runs them itself.
+
+## Gates
+
+`.vesper/gates.json` is the project's committed, host-neutral gate policy. `vespercli init` seeds it once on either host and never overwrites it; from then on it is the project's own file, like the Team Roster (`reset --host <host>` keeps it unless you pass `--purge-knowledge`). The seed detects `package.json` scripts — `test`, `lint`, and `typecheck`/`tsc`/`type-check` — and turns each into a check; a project without `package.json` starts with no checks.
+
+```json
+{
+  "schemaVersion": 1,
+  "checks": [{ "name": "test", "command": "npm test", "detected": true }],
+  "diffSizeCap": { "files": 40, "lines": 1500 },
+  "protectedPaths": []
+}
+```
+
+`vespercli gate` runs every check in order (`sh -c <command>` from the workspace root, inheriting your environment; a failure does not stop the next check), then looks at the changed files — the working tree against `HEAD` by default, or against `--base <ref>`, untracked files included:
+
+- `--plan <file>`: every changed file must be named in the plan (backticked paths, and the lists under a `Files` / `File Operations` heading; a plan's sibling `-details.md` is read too). Changes under `.vesper/.tracking/` are always allowed.
+- `diffSizeCap`: more files, or more added+deleted lines, than the cap fails.
+- `protectedPaths`: a changed file matching any glob fails.
+
+The report is fixed-format: one line per check, then `plan:`, `size:`, `protected:`, and a final `GATE PASS` or `GATE FAIL: <reasons>` line. `--json` prints one object instead. The orchestrator reads only the exit code and the headline — `0` pass, `1` fail, `2` no or invalid `.vesper/gates.json` — and never the work itself. Outside a git repository the plan, size and protected checks are skipped with a note. The command writes nothing; only the checks themselves touch the tree. `vespercli doctor` reports `gates-missing` (INFO) on an initialised workspace that has no policy yet.
 
 ## License