heyspex 0.1.0 → 0.2.0

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.