heyspex 0.1.0 → 0.2.1

package/docs/copilot-plugin-install.md

@@ -0,0 +1,162 @@
+# Installing the HeySpex (SpexCode) plugin in GitHub Copilot CLI
+
+Instructions written to be handed verbatim to a GitHub Copilot CLI agent. Follow the steps in
+order and stop at any step that fails, reporting the exact output.
+
+This guide is for a team that installs only the `heyspex` npm package. The heyspex-app repository
+is not needed and is not available to customers.
+
+Source of truth for the Copilot commands and file layout:
+<https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>.
+Hook behaviour under Copilot: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
+Both pages were read on 2026-10-16. The plugin itself is documented in `node_modules/heyspex/plugins/heyspex/README.md`.
+
+## 1. Prerequisites
+
+The heyspex-app repository is not required and is not available to customers. Everything below
+works from the published npm package `heyspex` (or a tarball your HeySpex contact hands you), which
+carries the plugin, the marketplace manifest, the hooks and the MCP server.
+
+- Node.js 20 or newer on PATH (`node --version`).
+- GitHub Copilot CLI installed and signed in (`copilot --version`).
+- A git repo of your own (the one you want governed). From its root, install the package:
+
+```bash
+npm install heyspex
+# or, from a tarball you were given:
+npm install ./heyspex-0.2.0.tgz
+```
+
+- Sign the machine in to the HeySpex console so hooks and MCP tools can reach the vault:
+
+```bash
+npx hs login
+```
+
+## 2. Pick ONE: the plugin or the repo hooks (never both)
+
+Copilot reads hooks from an installed plugin and from `.github/hooks/` in the repo. With both,
+every hook runs twice. Choose one.
+
+**Option A: the plugin (recommended).** One command registers the marketplace shipped inside the
+package and installs the plugin:
+
+```bash
+npx hs install --target . --copilot-plugin-apply
+```
+
+Without `npx hs`, the equivalent Copilot commands are:
+
+```bash
+copilot plugin marketplace add ./node_modules/heyspex
+copilot plugin install heyspex@heyspex-marketplace
+copilot plugin list
+```
+
+`./node_modules/heyspex/.claude-plugin/marketplace.json` is a Claude-format marketplace named
+`heyspex-marketplace`; its plugin `source` (`./plugins/heyspex`) resolves inside the package.
+`npx hs install --target . --copilot-plugin` (no `-apply`) only prints these commands.
+
+**Option B: repo hooks, for teammates and the Copilot cloud agent.** Writes
+`.github/hooks/heyspex.json` into your repo; commit it. Each command runs
+`node_modules/heyspex/scripts/claude-hooks/_run.mjs` and exits 0 if the package is not installed,
+so a checkout without `npm install` is never blocked.
+
+```bash
+npx hs install --target . --copilot-hooks
+```
+
+If you pass `--copilot-hooks` together with `--copilot-plugin[-apply]`, the installer warns and
+skips the hooks file.
+
+Then restart the Copilot session (`/restart`) so hooks load, and verify:
+
+```bash
+copilot plugin list      # Option A: heyspex is enabled
+npx hs doctor            # MCP, hooks and account surfaces healthy
+```
+
+## 3. What the plugin loads
+
+| Component | Source | Behaviour under Copilot |
+| --- | --- | --- |
+| Hooks | `node_modules/heyspex/plugins/heyspex/hooks/hooks.json` | PreToolUse, PostToolUse, Stop, UserPromptSubmit and SessionStart gates. Every command locates the runtime itself and exits 0 if it cannot, so a missing variable never denies a tool call. A real deny arrives as a top-level `permissionDecision` with a reason. |
+| MCP server | `node_modules/heyspex/plugins/heyspex/.mcp.json` | The `heyspex_*` vault tools and `hs-*` prompts. |
+| Slash commands | not loaded | Claude Code commands are not a Copilot component. Use MCP prompts or the `hs` CLI. |
+
+## 4. Verify the install
+
+1. In a Copilot session inside any repo, run a harmless tool call, for example read a file. It
+   must succeed. A message containing "Denied by preToolUse hook" means a hook failed; go to
+   section 7.
+2. Confirm the MCP server is up by listing MCP servers in Copilot (`/mcp`) and calling
+   `heyspex_recall_memories` with `{ "limit": 3 }`. If the server is missing, go to section 7.
+3. Confirm the gates work: send a prompt that contains a new product idea of more than 60
+   characters, then try to edit a source file without capturing. The edit should be refused with a
+   reason that names `directive-obligation-gate`. Call `heyspex_update_capture` with the prompt
+   text, then retry the edit. It should pass.
+
+## 5. Turning HeySpex off and on
+
+Run from the repo you are working in:
+
+```bash
+hs mode status     # on | off, and why
+hs mode off        # every hook exits 0 immediately, no restart needed
+hs mode on
+hs mode toggle
+```
+
+Use `npx hs mode off` when `hs` is not on PATH. The switch writes
+`.heyspex/mode.json` in the project and is git-ignored.
+
+Per-shell variants that touch no files:
+
+| Variable | Effect |
+| --- | --- |
+| `HEYSPEX_MODE=off` | Silences hooks for every harness in that shell |
+| `HEYSPEX_COPILOT_HOOKS_OFF=1` | Silences hooks only when the caller is Copilot; Claude Code and Cursor keep theirs |
+
+The config twin of the Copilot switch is `agent_behaviors.harness_hooks.copilot.enabled: false` in
+the vault's `.heyspex/config.yaml`.
+
+Four security gates ignore all of these by design: `env-vault-guard`, `research-method-guard`,
+`research-protocol-gate` and `git-identity-guard`. They only act on secret writes, built-in
+deep-research skills, unprotocolled web research and git identity changes.
+
+## 6. Everyday loop
+
+With MCP available: `heyspex_next_on_deck`, `heyspex_claim_spec`, `heyspex_report_progress`,
+`heyspex_submit_for_review`. Without MCP, the `hs` CLI (`npx hs`) covers the same loop; see
+`docs/driving-heyspex-from-copilot.md`.
+
+## 7. Troubleshooting
+
+- **Every tool call is denied.** Run `hs mode off` to unblock immediately, then capture the exact
+  deny text and the hook command it names. If the command still starts with
+  `node "$CLAUDE_PROJECT_DIR/...`, the package is old; run `npm install heyspex@latest` and reinstall the plugin.
+- **MCP server does not start.** Copilot documents `${PLUGIN_ROOT}` for its own plugin format, and
+  whether it expands `${CLAUDE_PLUGIN_ROOT}` in a Claude-format plugin is unverified. Register the
+  server explicitly:
+
+```bash
+copilot mcp add heyspex -- node ./node_modules/heyspex/plugins/heyspex/bin/launch-mcp.mjs
+```
+
+- **A hook denies with no reason shown.** That is a hook exiting 2 the old way. Report the hook
+  name; it should be answering in Copilot's JSON format.
+- **Hooks run twice.** The repo you are in also carries HeySpex rows in its own
+  `.claude/settings.json` from `hs install`. Use either the plugin or the install kit (or `.github/hooks`) in one repo,
+  not both.
+
+## 8. Report back
+
+State the Copilot CLI version, the output of `copilot plugin list`, the result of the three checks
+in section 4, and the exact text of any deny or MCP error.
+
+## Status of this document
+
+The install commands come from GitHub's plugin reference, and the hook behaviour was verified by
+replaying Copilot-shaped payloads through the registered commands, not by a live Copilot session.
+The first agent that completes section 4 is the real test. Fix history: diagnose HS-20SW and
+capture HS-HNO1 (2026-10-16).

package/docs/driving-heyspex-from-copilot.md

@@ -0,0 +1,165 @@
+# Driving HeySpex from GitHub Copilot (and other non-MCP assistants)
+
+**Capability table dated: 2026-07-10.** Harness support changes fast; re-verify against the
+sources before relying on a row. Refresh is owned by the harness-integrations pillar.
+
+HeySpex is tool-agnostic by construction. Every everyday action reaches the vault through one of
+three write paths, and at least one of them works in **any** assistant that can either speak MCP or
+run a shell command:
+
+1. **MCP tools** — `heyspex_*` tools over the Model Context Protocol (richest surface).
+2. **The `hs` CLI** — plain shell commands with stable exit codes and `--json` output. No MCP
+   client required; works in any assistant, terminal, or CI runner that can shell out.
+3. **The console web UI** — `localhost:3000`, works in any browser.
+
+This guide is the fallback path: how to drive the everyday agent loop when your assistant has
+**no** MCP tool support, using only the `hs` CLI.
+
+Grounded in [[HS-RDG9-RES-github-copilot-and-vs-code-mcp-support-t]] (the 2026 verification that
+Copilot now has a real MCP client) and [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]]
+(the broader cross-tool matrix — note its "VS Code + Copilot = shell-only, no MCP" row is stale as
+of the RDG9 refresh and is being amended separately).
+
+## Per-harness capability table (2026-07-10)
+
+**Legend** — **MCP**: native MCP client (tools, and sometimes prompts/resources). **`hs` CLI**:
+can shell out to `hs`. **Prompts**: supports MCP prompts exposed as slash commands. **Everyday
+loop**: can do see-next → claim → report progress → submit for review.
+
+| Harness                                                              |                    MCP                     |         `hs` CLI          |           Prompts            |         Everyday loop         | Honest ceiling                                                                                                                                                                                                    |
+| -------------------------------------------------------------------- | :----------------------------------------: | :-----------------------: | :--------------------------: | :---------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **VS Code agent mode (Copilot)**                                     | ✓ full (`.vscode/mcp.json`, `servers` key) |             ✓             | ✓ (`/mcp.<server>.<prompt>`) |   via MCP tools **or** `hs`   | Full MCP spec — tools, prompts, resources, sampling, OAuth. Subject to a 128-tool per-request cap; curate the exposed tool subset.                                                                                |
+| **GitHub Copilot CLI**                                               |   ✓ (auto-discovers `.github/mcp.json`)    |             ✓             |          ✓ (`/mcp`)          |   via MCP tools **or** `hs`   | Full MCP client (GA Feb 2026). Honors the org "MCP servers in Copilot" policy gate — admin approval may be required.                                                                                              |
+| **Copilot coding agent (github.com cloud)**                          |              ✓ **tools only**              | ✓ if sandbox allows shell |         ✗ no prompts         | via MCP **tools** **or** `hs` | No MCP prompts, no resources, no OAuth. Servers are configured in repo settings, not a committed file; local/allowlisted servers only. **Do not rely on slash-command prompts here — use tools or the `hs` CLI.** |
+| **Any assistant WITHOUT MCP tool support**                           |                     ✗                      |             ✓             |              ✗               |       via `hs` CLI only       | The `hs` CLI is the complete fallback. Everything in the loop is a plain shell command; nothing is unreachable just because the assistant lacks tool support.                                                     |
+| **Claude Code / Cursor / Cline / Continue.dev / Google Antigravity** |                  ✓ native                  |             ✓             |              ✓               |    via MCP tools (primary)    | First-class MCP today; the `hs` CLI is available as a fallback. See [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]].                                                                            |
+
+Design consequence: keep the primary UX in **tools**, not MCP prompts, because the cloud coding
+agent doesn't support prompts. Treat slash-command prompts as a VS Code / Copilot-CLI enhancement,
+and the `hs` CLI as the universal floor. HeySpex does **not** promise native slash-command parity on
+a surface that cannot support prompts.
+
+## The everyday loop with the `hs` CLI
+
+Run these from anywhere inside the vault (the CLI walks up to find `specs/`; or set
+`HS_VAULT_ROOT`). All four commands are pure shell — no MCP client involved. Add `--json` for
+machine-readable output.
+
+### 1. See what's next
+
+```bash
+hs next --summary --json
+```
+
+Returns the on-deck brief (spec id, title, summary, and a claim target). Drop `--json` for the
+human-readable prompt; drop `--summary` for the full post-claim execution brief.
+
+### 2. Claim the work
+
+```bash
+hs claim acquire HS-WJ1C-TASK --json
+```
+
+Atomic: two concurrent acquires for one spec yield exactly one success and one `already_claimed`
+conflict (exit 9) that names the existing claimant. Release on hand-off with
+`hs claim release HS-WJ1C-TASK`.
+
+### 3. Report progress
+
+```bash
+hs claim progress HS-WJ1C-TASK --stage Grounding --ac 0
+```
+
+`--stage` takes a work-stage verb (Grounding, Breaking down, Drafting, Validating, Testing,
+Reviewing). `--ac <n>` is the 0-based acceptance-criterion index you are on — it drives the live
+checklist on the What's Next surface. Call it again as you move between stages and complete criteria.
+
+### 4. Submit for review
+
+```bash
+hs mcp call heyspex_submit_for_review --arg spec_id=HS-WJ1C-TASK --json
+```
+
+`hs mcp call` runs a single MCP tool as a **one-shot shell command** — it does not require your
+assistant to be an MCP client. This close-out step validates acceptance-criteria progress against
+your claim, PATCHes the status API (never hand-edit frontmatter `status:`), applies review-grain
+coercion and parent rollup, releases the claim, and returns close-out guidance. A `409` on submit is
+a real reason (e.g. incomplete criteria) — report it, don't work around it.
+
+> Why `hs mcp call` and not a dedicated `hs submit` verb: see-next, claim, and report-progress each
+> have a first-class `hs` verb; submit-for-review is reached through the generic one-shot MCP-call
+> escape hatch, which reuses the exact close-out logic the MCP tool runs. It is still a plain shell
+> command with no MCP-client requirement.
+
+## Configuring MCP where it IS supported
+
+For VS Code agent mode and Copilot CLI you get the richer MCP tool surface. The MCP config
+templates (`.vscode/mcp.json` with the `servers` key, `.github/mcp.json` for Copilot CLI
+auto-discovery) and the Copilot instructions file are owned by the harness-integrations config work
+and documented separately — this guide covers only the universal `hs` CLI fallback.
+
+## Hooks under Copilot
+
+Copilot CLI runs the HeySpex hooks it finds in `.claude/settings.json` (and the plugin's `hooks/hooks.json`), so the
+gates (capture-on-idea obligation, claim-before-build, naming guards) apply to Copilot agents too. What differs:
+
+- **Fail-closed**: Copilot denies a tool call when a `preToolUse` command crashes or exits non-zero. Every registered
+  command is therefore a self-locating bootstrap that does not need `$CLAUDE_PROJECT_DIR` and exits 0 when it cannot find
+  the HeySpex runtime; `_run.mjs` itself never exits non-zero except for a deliberate deny (translated to Copilot's
+  top-level `{"permissionDecision":"deny"}` JSON with exit 0).
+- **Turn it off**: `hs mode off` (all harnesses, per project; `hs mode on|status|toggle`), `HEYSPEX_MODE=off` for one
+  shell, or `HEYSPEX_COPILOT_HOOKS_OFF=1` / `agent_behaviors.harness_hooks.copilot.enabled: false` for Copilot only.
+  The four always-on security gates (`env-vault-guard`, `research-method-guard`, `research-protocol-gate`,
+  `git-identity-guard`) ignore all three.
+- **Stopgap on an older checkout** (before the bootstrap ships): `HEYSPEX_MODE=off` only helps if the hook command can
+  start, and the old command needs `CLAUDE_PROJECT_DIR`; export it (`CLAUDE_PROJECT_DIR=<repo>`) alongside `HEYSPEX_MODE=off`.
+
+### One source of hooks, and the cloud agent
+
+Plugin OR repo hooks, never both: Copilot CLI loads the heyspex plugin AND the repo's `.claude/settings.json` /
+`.github/hooks/*.json`, so a repo with both fires every hook twice. `npm run doctor` (check `hook-double-fire`) warns
+about that and reports `unknown`, not a failure, when it cannot read a plugin registry.
+
+The Copilot **cloud agent** loads no plugins: its only hook source is `.github/hooks/*.json` on the **default branch**.
+`npm run hooks:write-github` generates `.github/hooks/heyspex.json` (bash `command` entries only, camelCase events,
+resolving `node_modules/heyspex/scripts/claude-hooks/_run.mjs` then `./scripts/claude-hooks/_run.mjs`, else exit 0).
+Requirements: the sandbox must contain `node_modules/heyspex` (install it in `copilot-setup-steps`), the firewall must
+allow the console URL (claim heartbeats), and MCP is configured in repository settings (tools only, no OAuth).
+
+### Gates that are weaker or absent on Copilot
+
+Generated from `scripts/lib/hook-dispositions.mjs` (a test fails when this block is stale). The MCP preflight refusals
+(`heyspex_claim_spec`, `heyspex_submit_for_review`, `heyspex_save_research`) are the hook-independent hard floor on every
+surface that connects the MCP server.
+
+<!-- hook-dispositions:copilot:begin (generated by scripts/lib/hook-dispositions.test.mjs; UPDATE_HOOK_DOCS=1 refreshes) -->
+| Gate | Disposition | Compensating control / what is lost |
+| --- | --- | --- |
+| `research-method-guard` | unportable | MCP preflight refusal on heyspex_save_research (hard floor, hook-independent) + .github/copilot-instructions.md research rule; Copilot has no Skill or Workflow tool to hook. |
+| `deep-research-cost-gate` | unportable | MCP preflight refusal on heyspex_save_research + .github/copilot-instructions.md cost-confirmation rule; Copilot has no Skill or Workflow tool to hook. |
+| `plan-review-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
+| `plan-exit-ingest-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
+| `preflight-reminder` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Real enforcement is the MCP preflight refusal. |
+| `intent-classifier-trigger` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. The hook still runs and arms obligation state; the HS-20SW directive-obligation-gate turns that state into a hard deny. |
+| `inject-communication-style` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. |
+| `inject-vault-context` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Per-prompt vault retrieval has no Copilot channel at all. |
+| `claim-before-code-gate` | advisory-degraded | Armed only by plan-exit-ingest-gate, which has no Copilot trigger (no ExitPlanMode tool), so it stays dormant; covered by the HS-20SW claim-before-build rule. |
+| `diagnose-capture-reminder` | advisory-degraded | Copilot preToolUse has no context channel for an inject, so this advisory is silent (lost). |
+<!-- hook-dispositions:copilot:end -->
+
+Plan mode: Copilot has no `ExitPlanMode` tool, so the plan gates cannot fire. State the plan in chat and claim the spec
+before editing code (`.github/copilot-instructions.md`); the HS-20SW claim-before-build deny backs that up.
+
+**Unverified** (no official page read, or not run live): the VS Code 128-tool per-request cap (the microsoft/vscode issue
+below is the only source); the spelling of MCP tool names inside hook payloads (hooks match by suffix); whether
+`${CLAUDE_PLUGIN_ROOT}` expands in the plugin `.mcp.json` under the Copilot CLI (documented for VS Code only); how the MCP
+server learns the Copilot session id (its preflight marker falls back to a 4 hour TTL); whether the CLI reads a Claude-format
+`hookSpecificOutput` deny.
+
+## Sources
+
+- [[HS-RDG9-RES-github-copilot-and-vs-code-mcp-support-t]] — Copilot MCP support verified mid-2026 (cloud agent = tools only).
+- [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]] — cross-tool compatibility matrix (Copilot row being amended).
+- [MCP and GitHub Copilot cloud agent — GitHub Docs](https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent) — cloud coding agent supports MCP tools only.
+- [Adding MCP servers for GitHub Copilot CLI — GitHub Docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) — `.github/mcp.json` auto-discovery.
+- [Hard tool limit (128) in VS Code agent mode — microsoft/vscode#290356](https://github.com/microsoft/vscode/issues/290356) — 128-tool per-request cap.

package/docs/mcp-client-config.md

@@ -13,6 +13,12 @@ points at `node ${CLAUDE_PROJECT_DIR}/vendor/heyspex-mcp/cli.mjs` — a path tha
 exists inside a clone of the HeySpex source repository** and is therefore useless to
 anyone who installed the package.
 
+**Working from a clone of this repo instead?** `heyspex` is not published on the
+public npm registry yet, so `npm install -g heyspex` below 404s. Skip to
+[§1b — clone + `npm link`](#1b-clone--npm-link-working-from-source), and see
+[Working from a clone](#working-from-a-clone-of-this-repo) below for how to sign in
+once linked.
+
 ## 1a. Install the package (customers)
 
 ```sh
@@ -36,6 +42,16 @@ name, which is unambiguous:
 npx --yes --package heyspex heyspex-mcp
 ```
 
+**What the agent kit injects at session start.** With the kit hooks installed (`hs install` /
+`hs connect`, or the plugin), the `inject-doctrine` SessionStart hook adds the **baseline
+edition of SpexCode Doctrine** to each session: a short list of general working principles
+(verify before claiming done, report what failed, ask before irreversible writes, stay in scope),
+read from `spexharness/doctrine/baseline/SPEXCODE-DOCTRINE.baseline.json` inside the installed
+package. That is all it injects. It does not inject anything about how HeySpex itself is built
+(no dev-server, database, or build-fleet rules), any learned principles from HeySpex's own
+development sessions, or anything read from your repo, and it does not include a SpexCode Profile.
+If the baseline file is missing, the hook injects nothing. Set `HEYSPEX_DOCTRINE_OFF=1` to turn it off.
+
 ## 1b. Clone + `npm link` (working from source)
 
 `npm install` in a clone does **not** put `hs` on your PATH. Nothing does, except
@@ -153,18 +169,131 @@ heyspex mcp pair <code>
 > clone has no `hs` at all. Run `npm run doctor` — its **`hs` on PATH → this
 > checkout** check names the cause.
 
+## Working from a clone of this repo
+
+`npm install -g heyspex` above needs the package published on the public npm
+registry, and it is not yet — that command 404s today. Until it ships, a machine
+working from a clone of this repo signs in through the repo's own dispatcher instead
+of a global `hs`/`heyspex` command:
+
+```sh
+node bin/hs.mjs login
+```
+
+Run that from the repo root (or pass an absolute path to `bin/hs.mjs` from any
+folder). It opens the console, mints a pairing code, and writes the token to
+`~/.heyspex/credentials.yaml` — the same file `heyspex login` writes once the package
+is installed globally.
+
+**Do not run `hs login` or `npx hs login` on a fresh clone.** Nothing in `npm install`
+links the `hs` binary onto PATH, so a bare `hs login` fails with "command not found."
+`npx hs login` fails worse: `hs` is the name of an unrelated package already on the
+public registry, so `npx hs login` silently installs and runs *that* package instead
+of this repo's — no error, just the wrong tool. `npm run doctor` reports which form of
+the command actually runs on your machine (the `hs command form` check) — trust that
+line over guessing.
+
+Linking `hs` globally (`npm link` from the repo root) is available if you want the
+bare `hs` command on this one machine, but it is not required and not the default —
+it points `hs` at whatever branch happens to be checked out, so a machine that
+switches branches often is better served by the dispatcher form above. See
+[[HS-I6HT-EKYU-DIAG-every-message-tells-the-user-to-run-hs]] for why linking isn't the
+shipped fix.
+
 ## Which vault the server reads
 
-Resolution order, highest first:
+Resolution order, highest first. The directory the process actually started
+in outranks the machine-wide active pointer: a server started inside one vault
+must never write its bookkeeping into whichever vault another terminal last
+marked active.
 
 | # | Source | Notes |
 |---|---|---|
-| 1 | An explicit vault id | `hs vault use <id>` |
-| 2 | `active_vault_id` in `~/.heyspex/registry.json` | the offline active-vault pointer |
-| 3 | `HEYSPEX_VAULT_ROOT` | the repository root; what the config above sets |
-| 4 | `HEYSPEX_VAULT_DIR` | the `specs/` directory itself |
-| 5 | The working directory | used when it contains a `specs/` directory |
+| 1 | An explicit vault id | `hs vault use <id>`, or `hs --vault <id> <cmd>` |
+| 2 | `HEYSPEX_VAULT_ROOT` / `HEYSPEX_VAULT_DIR` | the repository root / the `specs/` directory itself; what the config above sets |
+| 3 | A vault or a satellite attachment at or above the working directory | walks up from the working directory; the nearest match wins, and an attachment beats a `heyspex.yaml` / `specs/` marker found at the same or a higher level |
+| 4 | `active_vault_id` in `~/.heyspex/registry.json` | the offline active-vault pointer — reached only when the working directory sits inside no vault at all |
+| 5 | The working directory | last resort, when nothing above matched |
+
+Tier 3 is what makes [satellite repos](#satellite-repos-code-here-specs-elsewhere)
+work, and why they do not depend on the active pointer.
+
+## Satellite repos: code here, specs elsewhere
+
+A **satellite** is a code repo that gets the full agent tooling while its specs
+live in a different, already-registered vault. It owns no `specs/` and no
+`heyspex.yaml` — it is not a vault, it is attached to one. Use it whenever the
+code and the vault are separate checkouts.
+
+```bash
+cd /path/to/your-code-repo
+hs install --attach-vault <vault-id>     # `hs vault list` shows the ids
+```
+
+The target is the repo you are standing in. `--attach-vault` also accepts the
+vault repo's path (absolute or relative) instead of its id.
+
+This writes the same MCP manifests and agent contract as a normal install, with
+one difference: `HEYSPEX_VAULT_ROOT` is pinned to the **attached** vault's
+absolute path instead of the client placeholder.
+
+```jsonc
+{
+  "mcpServers": {
+    "heyspex": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/abs/path/to/heyspex/vendor/heyspex-mcp/cli.mjs"],
+      "env": {
+        // a normal install writes "${CLAUDE_PROJECT_DIR:-.}" here
+        "HEYSPEX_VAULT_ROOT": "/abs/path/to/the-vault-repo"
+      }
+    }
+  }
+}
+```
+
+That pin **is** the attachment — there is no marker file, so there is nothing to
+drift. Every surface reads it: the MCP server resolves the vault through it,
+and `hs connect --check`, `hs doctor` and `hs` itself use it to recognize the
+repo as a satellite.
+
+### What the tooling does differently
+
+- `hs connect --check` reports **Connected (satellite)** and evaluates the four
+  vault rows (marker, `specs/`, vault registered, workspace registered) against
+  the **attached** vault, plus a `satellite_attachment` row. A satellite never
+  reads as "missing heyspex.yaml".
+- `hs connect` (full run) skips every vault-creating step, so it will not
+  scaffold a second vault into your code repo. It still installs plugin
+  surfaces and git hooks, and it needs no sign-in (it performs no cloud write).
+- `hs doctor` audits the **attached vault**, because `hs` resolves the pin into
+  `HS_VAULT_ROOT` before doctor runs. It does not report the satellite's own
+  connection rows — use `hs connect --check` in the repo for those.
+
+### Rules and refusals
+
+Every refusal happens before anything is written.
 
+| Situation | Result |
+|---|---|
+| Vault id unknown, or a path with no registry row | exit 11 — register it first with `hs vault register --path <dir>` |
+| The registered vault is missing from this machine | exit 11 |
+| Attaching a vault to itself | exit 11 |
+| A manifest already pins a **different** vault, or carries no pin | exit 11 — re-run with `--force` to re-pin |
+| Both manifests already pin this vault | no-op, exit 0 |
+| `--register-vault` or `--workspace` | exit 1 — a satellite never registers a vault of its own |
+| `--no-cursor --no-claude` | exit 1 — nowhere to record the pin |
+| `--remote` | exit 1 — the cloud endpoint resolves the vault from your **account**, not a local pin, so Claude Code and Cursor could read different vaults with nothing reporting the split |
+
+### Known limitation: the attachment does not survive a fresh clone
+
+The pin is an absolute, machine-local path, so the manifests carrying it are
+not committed. A teammate cloning a satellite gets a repo with no `specs/`, no
+marker and no pin — indistinguishable from an unwired code repo, and `hs
+connect` there would scaffold a vault into it. `hs connect` prints a
+non-blocking warning when it can recognize the shape, but it cannot always
+tell. Re-run `hs install --attach-vault <id>` after cloning.
 ## Which console the server calls
 
 Resolution order, highest first:
@@ -198,3 +327,127 @@ The real check is in the client: after restarting it, the `heyspex_*` tools shou
 listed. If they are not, the client did not restart, or the command is not on your
 `PATH` — from a clone run `npm link` (§1b); from an install, try the
 `npx --package heyspex heyspex-mcp` form.
+
+## Remote (cloud) MCP — no local server
+
+The console also serves MCP directly over HTTPS at `https://app.heyspex.com/api/mcp`
+(MCP Streamable HTTP, JSON-response mode). A customer machine needs no `heyspex-mcp`
+process, no checkout and no `HEYSPEX_VAULT_ROOT` — only a token.
+
+### Get a token
+
+The endpoint accepts the same `hsmcp_…` bearer the local server uses. Either command
+writes it as `mcp_token:` in `~/.heyspex/credentials.yaml`:
+
+```sh
+heyspex login                # opens the console, mints a pairing code, redeems it
+heyspex mcp pair <code>      # redeem a code minted elsewhere (no browser needed)
+```
+
+Read `mcp_token` out of that file (or mint one from the console's MCP pairing page)
+and pass it as `HEYSPEX_MCP_TOKEN` below. Treat it like a password.
+
+### Claude Code
+
+```sh
+claude mcp add --transport http heyspex https://app.heyspex.com/api/mcp \
+  --header "Authorization: Bearer ${HEYSPEX_MCP_TOKEN}"
+```
+
+or, project scope, in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "heyspex": {
+      "type": "http",
+      "url": "https://app.heyspex.com/api/mcp",
+      "headers": {
+        "Authorization": "Bearer ${HEYSPEX_MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Claude Code expands `${HEYSPEX_MCP_TOKEN}` from your environment at startup, so the
+token never sits in the checked-in file. Any other Streamable-HTTP MCP client works
+the same way: POST JSON-RPC to the URL with that `Authorization` header.
+
+### Let the CLI write it
+
+Either verb generates exactly the block above — always with the **env reference**,
+never the literal token:
+
+```sh
+hs install --remote                       # full bootstrap; .mcp.json gets the http form
+hs install --remote=https://my-preview.example.dev   # a preview deployment
+hs mcp install --remote                   # print only (no vault bootstrap)
+hs mcp install --remote --write           # …and write .mcp.json into the vault root
+hs mcp install --remote --json            # { url, mcp_json, claude_command, wrote }
+```
+
+Both print the equivalent `claude mcp add --transport http …` one-liner. A bare
+origin is normalized (`https://host` → `https://host/api/mcp`). `hs install --remote`
+changes only the Claude Code `.mcp.json`; `.cursor/mcp.json` keeps the stdio form,
+so a project can run local-first in Cursor and cloud in Claude Code.
+
+### Transport details
+
+- **POST** — JSON-RPC in, one JSON reply out. `initialize` mints an `Mcp-Session-Id`
+  that later requests echo back. `initialize`'s `serverInfo.version` reports the
+  deployed package version (baked at build time, so it is real, not `0.0.0-unknown`).
+- **GET** with `Accept: text/event-stream` — opens the Streamable-HTTP event stream.
+  It is deliberately **silent**: one opening comment, then a `: keepalive` comment
+  every 15 s, closed when the client aborts. No server-initiated messages are ever
+  sent on it, so a conforming client parses zero messages; it exists so clients that
+  open the channel are not met with a 405. A GET without that `Accept` is still 405.
+- **DELETE** — acknowledges a session end with `200` and a small JSON body
+  (`{ ok, session_id, note }`). Sessions are stateless, so there is nothing to free.
+
+### What it serves, and what it does not
+
+The remote endpoint runs the very same tool handlers as the local server, acting as
+the account the token belongs to, but only the **cloud-safe subset** — the tools that
+work entirely through the console API:
+
+- session + procedures: `heyspex_recall_memories`, `heyspex_list_procedures`,
+  `heyspex_get_procedure`, `heyspex_preflight`, `heyspex_handoff_load`,
+  `heyspex_handoff_record`
+- the claim contract: `heyspex_next_on_deck`, `heyspex_claim_spec`,
+  `heyspex_release_spec`, `heyspex_report_progress`, `heyspex_submit_for_review`,
+  `heyspex_record_wip`, `heyspex_defer_spec`, `heyspex_claim_list`,
+  `heyspex_claim_acquire`, `heyspex_claim_release`
+- filing + context: `heyspex_file_spec`, `heyspex_active_capture`,
+  `heyspex_milestone_show`, `heyspex_events_show`, `heyspex_list_known_tags`
+- focus / pin: `heyspex_pin_get`, `heyspex_pin_set`, `heyspex_get_focus_areas`,
+  `heyspex_set_focus_areas`
+
+The authoritative list is `vendor/heyspex-mcp/cloud-tool-surface.mjs`. Calling any
+other `heyspex_*` tool returns a JSON-RPC error saying it needs the local server —
+those tools read or write the vault checkout on disk (research capture and
+promotion, `push_plan`, `backfill_epic`, spec edits, alignment recording, the design
+system, `dev_mode` switching, `update_capture`'s offline outbox). Keep the local
+stdio server for those; the two can be registered side by side under different names.
+
+Current limitations:
+
+- **No server-initiated messages.** POST always answers with JSON (never an SSE
+  body), and the GET stream carries only keepalive comments — no notifications, no
+  progress, no server-side requests, no sampling/elicitation.
+- **Stateless sessions.** `initialize` returns an `Mcp-Session-Id`; later calls echo it
+  and `DELETE` acknowledges it, but nothing is kept server-side, so there is no
+  `heyspex_load_tools` progressive surface (the list above is the whole list) and the
+  local server's PreToolUse/PostToolUse hooks and on-disk preflight proof-of-use gate
+  do not run remotely.
+- **Enrichment degrades.** `heyspex_next_on_deck`'s core brief (scheduler cohort,
+  the spec itself, its task graph) is served from the cloud, and so is the previous
+  session's WIP block when the hand-off landed in the Neon `wip_ledger`. Extras the
+  local server reads from the checkout — plan amendments, memory scoring, the
+  file-based `.heyspex/wip-state.json` fallback — stay empty on the remote path,
+  because a serverless runtime has no vault checkout to read them from.
+- **`heyspex_file_spec`'s landing probe reports the cloud verdict only.** It cannot
+  stat a local file (there is none), so `local_file_exists` is `null` and the verdict
+  rests on the console's own write response.
+- **Cursor is stdio-only here.** `hs install --remote` rewrites the Claude Code
+  `.mcp.json`; point Cursor at the same URL by hand if you want it cloud-backed.