@korso/shepherd 0.4.4 → 0.5.0

package/README.md

@@ -1,327 +1,336 @@
-# @korso/shepherd — Shepherd MCP Server
-
-Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory coordination tools backed by the shared hub: `work`, `done`, `announce`, and `sync`. The agent **joins the workspace automatically** on startup (no `join` tool), and the server ships standing instructions so the agent self-coordinates without the user prompting it.
-
-> **New here?** The [developer quickstart](https://github.com/Korsoai/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y @korso/shepherd` with the env vars below.
-
----
-
-## CRITICAL: WORKSPACE must match the hub exactly
-
-> **`WORKSPACE` defaults to `default`. If you override it, the value must equal the hub's `ALLOWED_WORKSPACE` env var exactly.**
-
-The server fires an automatic `join` call to the hub at startup. If the workspace it sends does not match the hub's `ALLOWED_WORKSPACE`, that call returns HTTP 400 and coordination degrades: every tool reports "session not ready … proceeding uncoordinated" instead of a landscape. The safe default is to **leave `WORKSPACE` unset** so it resolves to `default` — only set it when a maintainer points you at a different workspace. If your agent never sees teammates, check `WORKSPACE` (and `TEAM_TOKEN`) first.
-
----
-
-## Install
-
-The server is published to npm and runs via `npx` — no clone or build required
-(Node 18+):
-
-```sh
-npx -y @korso/shepherd
-```
-
-You won't normally run that by hand; you put it in your MCP client config (below)
-with the required env vars. `npx` caches the package, so startup is fast after the
-first fetch, and `@korso/shepherd@latest` picks up updates automatically.
-
-> Hacking on the server itself? See **[Develop from source](#develop-from-source)**
-> at the bottom.
-
----
-
-## 2. Environment variables
-
-**Only two are required:**
-
-| Variable | Description | Example |
-|---|---|---|
-| `HUB_URL` | Base URL of the deployed hub | `https://shepherd.example.com` |
-| `TEAM_TOKEN` | Shared bearer token accepted by the hub | `tok_abc123` |
-
-Missing either causes an immediate startup failure with a clear error on stderr
-listing which vars are absent. (No other var triggers this.)
-
-**Everything else is optional** — each identity field is resolved at startup as
-**env var → git detection → fallback**, so a plain `npx -y @korso/shepherd` with
-just the two required vars produces a valid, fully-identified session. Set an
-override only to replace what's detected:
-
-| Variable | If omitted | Example |
-|---|---|---|
-| `WORKSPACE` | defaults to `default` (**must match hub's `ALLOWED_WORKSPACE` if overridden**) | `shepherd` |
-| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korsoai/shepherd` |
-| `BRANCH` | `git rev-parse --abbrev-ref HEAD`, else `HEAD` | `main` |
-| `BASE_BRANCH` | `origin/HEAD`, else `origin/main` / `origin/master` (used for the change-awareness heads-up) | `origin/main` |
-| `HUMAN` | git `user.name`, else local-part of `user.email`, else a generated name | `daichi` |
-| `PROGRAM` | defaults to `claude-code` | `codex` |
-| `MODEL` | omitted — **never auto-detected**, so set it if you want it shown | `claude-sonnet-4-6` |
-| `HEARTBEAT_INTERVAL_SECONDS` | defaults to `60` | `30` |
-| `SHEPHERD_INBOX_DIR` | defaults to `~/.shepherd/inbox`. Override only to relocate the **announcement-push** inbox (see below); the background heartbeat writes incoming announcements here. If you set it, point your client hook/extension at the **same** dir | `~/.shepherd/inbox` |
-
----
-
-## Announcement push (on by default)
-
-Announcements reach an agent **without it having to ask**. The background
-heartbeat pulls any pending announcements from the hub every beat and stages them
-in a local **inbox file** (per working directory, under `SHEPHERD_INBOX_DIR`,
-default `~/.shepherd/inbox`). That file is then drained by two paths:
-
-1. **Universal drainer (always on, every client).** Whenever the agent calls any
-   Shepherd tool (`work`/`sync`/`done`/`announce`), the result also includes
-   anything sitting in the inbox. So even with no hook configured, no announcement
-   is ever lost — the worst case is the old behaviour (delivered on the next
-   Shepherd tool call), never silent drops.
-2. **Passive client hook/extension (optional, per client).** To get announcements
-   **without** waiting for a Shepherd tool call — surfaced on the agent's next
-   action of any kind — wire up your client's hook below. This is the
-   "a subagent finished" style of notification.
-
-Both paths read the **same** inbox file and de-duplicate by announcement id, so
-running both is safe (the hub hands each announcement to exactly one drain; the
-merge is just defensive). It's cheap: a **local file read — no network** (the
-heartbeat already did the fetch), and it only adds to the model's context when
-something is actually waiting.
-
-It delivers to an agent **while it's active**; an idle agent picks messages up the
-moment it next does anything. (Waking a fully-idle agent is out of scope — for
-Claude Code that needs Channels; Codex/Pi have no equivalent.)
-
-### Claude Code — `PreToolUse` hook
-
-`PreToolUse` fires before every tool, giving the most frequent passive delivery.
-The hook needs no arguments — it resolves the same default inbox dir the server
-uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
-
-```json
-{
-  "mcpServers": {
-    "shepherd": {
-      "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
-      "env": {
-        "HUB_URL": "https://shepherd.example.com",
-        "TEAM_TOKEN": "tok_abc123"
-      }
-    }
-  },
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "*",
-        "hooks": [
-          { "type": "command", "command": "npx -y -p @korso/shepherd shepherd-inbox-hook" }
-        ]
-      }
-    ]
-  }
-}
-```
-
-### Codex — `UserPromptSubmit` hook
-
-Codex uses the **same** hook contract as Claude Code (JSON on stdin, a
-`hookSpecificOutput.additionalContext` reply), so the **same bin** serves it. Use
-`UserPromptSubmit` — Codex's `PreToolUse` only fires for Bash, not `apply_patch`
-or MCP calls. Hooks must be enabled with `features.hooks = true`. In
-`~/.codex/config.toml`:
-
-```toml
-[features]
-hooks = true
-
-[[hooks.UserPromptSubmit]]
-command = ["npx", "-y", "-p", "@korso/shepherd", "shepherd-inbox-hook"]
-# On Windows use command_windows instead:
-# command_windows = ["cmd", "/c", "npx -y -p @korso/shepherd shepherd-inbox-hook"]
-```
-
-### Pi — extension
-
-Pi has no stdin/stdout hook; it loads in-process extensions. Ship the bundled
-extension into Pi's extensions dir:
-
-```sh
-# global, applies everywhere:
-mkdir -p ~/.pi/agent/extensions
-cp "$(npm root -g)/@korso/shepherd/dist/inboxExtension.js" ~/.pi/agent/extensions/shepherd-inbox.js
-# …or per-project: copy into .pi/extensions/ in the repo root.
-```
-
-It runs on every user turn (`before_agent_start`), drains the same inbox, and
-injects pending announcements. (Or load it ad hoc with
-`pi -e /abs/path/to/dist/inboxExtension.js`.)
-
-### Notes
-
-Every path is **fail-open**: a missing dir, unreachable hub, or any error means
-nothing is surfaced and the tool call / turn proceeds normally — coordination
-never blocks the agent. The inbox is keyed per working directory; two sessions in
-the exact same directory share it (a benign edge — they're the same repo). If you
-override `SHEPHERD_INBOX_DIR` on the server, set it on the hook/extension to the
-same value (the Claude/Codex bin and the Pi extension both read
-`SHEPHERD_INBOX_DIR`, or you can pass the dir as the first CLI arg to the bin).
-
----
-
-## 3. MCP client configuration
-
-### Claude Code
-
-> **Do not use `~/.claude/mcp.json` — Claude Code does not read it** (a config
-> there loads silently into nothing). Use `claude mcp add` (user scope, applies
-> everywhere) or a project-root `.mcp.json`. Confirm with `claude mcp list`,
-> which should show `shepherd … ✔ Connected`.
-
-Recommended — register once at user scope. Written as a **single line** so it
-pastes cleanly into PowerShell, cmd, bash, and zsh (on PowerShell the bash `\`
-line-continuation does not work). Minimal: just the two required vars (identity
-is auto-detected from git):
-
-```powershell
-claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y @korso/shepherd
-```
-
-Add any optional overrides from §2 with extra `-e` flags (e.g. `-e MODEL=claude-sonnet-4-6 -e HUMAN=daichi`).
-
-Alternative — a `.mcp.json` at the **root of the repo you're working in**
-(optional overrides shown commented-style; drop the ones you don't need):
-
-```json
-{
-  "mcpServers": {
-    "shepherd": {
-      "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
-      "env": {
-        "HUB_URL": "https://shepherd.example.com",
-        "TEAM_TOKEN": "tok_abc123",
-        "MODEL": "claude-sonnet-4-6"
-      }
-    }
-  }
-}
-```
-
-> Windows note: the server is a thin stdio client to the Linux-hosted hub, and
-> `npx` works the same on every OS — no file paths to escape. The hub itself runs
-> on Linux (Postgres), so the Windows-native durability concerns from the spike
-> don't apply to clients.
-
-### Codex (`~/.codex/config.toml`)
-
-Codex uses the same MCP stdio protocol but configures it in **TOML**, not JSON —
-at `~/.codex/config.toml` (global) or `.codex/config.toml` in a trusted project.
-The table is `mcp_servers` with an **underscore** (`mcp-servers`/`mcpServers` are
-silently ignored). Either run `codex mcp add`:
-
-```sh
-codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y @korso/shepherd
-```
-
-…or add the table directly:
-
-```toml
-[mcp_servers.shepherd]
-command = "npx"
-args = ["-y", "@korso/shepherd"]
-env = { HUB_URL = "https://shepherd.example.com", TEAM_TOKEN = "tok_abc123", PROGRAM = "codex", MODEL = "o4-mini" }
-```
-
-### Pi (`~/.pi/agent/mcp.json` or `.pi/mcp.json`)
-
-Pi uses a JSON `mcpServers` block (project config overrides global):
-
-```json
-{
-  "mcpServers": {
-    "shepherd": {
-      "command": "npx",
-      "args": ["-y", "@korso/shepherd"],
-      "env": {
-        "HUB_URL": "https://shepherd.example.com",
-        "TEAM_TOKEN": "tok_abc123",
-        "PROGRAM": "pi"
-      }
-    }
-  }
-}
-```
-
----
-
-## 4. Verify the server starts (quick smoke test)
-
-Run with the two required vars set to confirm it connects and idles on stdin.
-PowerShell (set env vars, then run):
-
-```powershell
-$env:HUB_URL = "https://shepherd.example.com"
-$env:TEAM_TOKEN = "tok_abc123"
-npx -y @korso/shepherd
-```
-
-bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y @korso/shepherd`
-
-No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
-
-**Missing env vars:** if you omit `HUB_URL` or `TEAM_TOKEN`, you will see:
-
-```
-[shepherd] Configuration error — missing or invalid env vars:
-  HUB_URL: HUB_URL is required
-  TEAM_TOKEN: TEAM_TOKEN is required
-```
-
-and the process exits 1 immediately. This is by design. The optional identity
-vars never cause this — they fall back to git detection / defaults.
-
-**Wrong WORKSPACE:** if you override `WORKSPACE` to a value the hub doesn't allow, the server starts and connects but the startup auto-join is rejected (400), so every tool call (`work`, `sync`, etc.) reports "session not ready … proceeding uncoordinated". Either leave `WORKSPACE` unset (resolves to `default`) or set it to exactly match the hub's `ALLOWED_WORKSPACE`, then restart.
-
----
-
-## Develop from source
-
-Only needed if you're changing the MCP server itself. Clone the monorepo and
-point your client at a local build instead of npx:
-
-```sh
-git clone https://github.com/Korsoai/shepherd.git
-cd shepherd
-npm install
-npm run build         # tsc -b — compiles the workspace for dev + tests
-```
-
-For an exact preview of the published artifact (a single self-contained bundle
-with `@shepherd/shared` inlined), build the package directly:
-
-```sh
-npm run build --workspace=@korso/shepherd   # runs tsup → packages/mcp-server/dist/index.js
-```
-
-Then use `node /absolute/path/to/shepherd/packages/mcp-server/dist/index.js` as
-the `command` in your MCP config (Windows: escape backslashes in JSON).
-
-### Publishing a new version
-
-```sh
-# bump "version" in packages/mcp-server/package.json, then:
-npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatically
-```
-
-`publishConfig.access` is `public`, so the scoped package publishes publicly.
-
----
-
-## Troubleshooting
-
-| Symptom | Likely cause | Fix |
-|---|---|---|
-| `Configuration error — missing or invalid env vars` | `HUB_URL` or `TEAM_TOKEN` is absent (only these two are required) | Add the missing var(s) to your client's `env` block |
-| Tools report "session not ready … proceeding uncoordinated" | Startup auto-join rejected — usually a stale `TEAM_TOKEN`, or a `WORKSPACE` override the hub doesn't allow | Re-check `TEAM_TOKEN`; leave `WORKSPACE` unset (→ `default`) or match the hub's `ALLOWED_WORKSPACE`; restart |
-| Agent shows up under a surprising name/repo/branch | Identity auto-detected from git | Override with `HUMAN`/`REPO`/`BRANCH`/`MODEL` env vars (§2) |
-| `npm error 404 … @korso/shepherd` | Package not published yet, or name typo | `npm view @korso/shepherd version` to confirm it's live |
-| Process exits immediately with no error | Rare; check for node version incompatibility | Requires Node 18+ (ESM support) |
+# @korso/shepherd — Shepherd MCP Server
+
+Shepherd's stdio MCP server. Gives any MCP-capable agent (Claude Code, Codex, etc.) four advisory coordination tools backed by the shared hub: `work`, `done`, `announce`, and `sync`. The agent **joins the workspace automatically** on startup (no `join` tool), and the server ships standing instructions so the agent self-coordinates without the user prompting it.
+
+> **New here?** The [developer quickstart](https://github.com/Korsoai/shepherd/blob/main/docs/shepherd-mcp-quickstart.md) is the fastest path. TL;DR: `npx -y @korso/shepherd` with the env vars below.
+
+---
+
+## CRITICAL: WORKSPACE must match the hub exactly
+
+> **`WORKSPACE` defaults to `default`. If you override it, the value must equal the hub's `ALLOWED_WORKSPACE` env var exactly.**
+
+The server fires an automatic `join` call to the hub at startup. If the workspace it sends does not match the hub's `ALLOWED_WORKSPACE`, that call returns HTTP 400 and coordination degrades: every tool reports "session not ready … proceeding uncoordinated" instead of a landscape. The safe default is to **leave `WORKSPACE` unset** so it resolves to `default` — only set it when a maintainer points you at a different workspace. If your agent never sees teammates, check `WORKSPACE` (and `TEAM_TOKEN`) first.
+
+---
+
+## Install
+
+The server is published to npm and runs via `npx` — no clone or build required
+(Node 18+):
+
+```sh
+npx -y @korso/shepherd
+```
+
+You won't normally run that by hand; you put it in your MCP client config (below)
+with the required env vars. `npx` caches the package, so startup is fast after the
+first fetch, and `@korso/shepherd@latest` picks up updates automatically.
+
+> Hacking on the server itself? See **[Develop from source](#develop-from-source)**
+> at the bottom.
+
+---
+
+## 2. Environment variables
+
+**Only two are required:**
+
+| Variable | Description | Example |
+|---|---|---|
+| `HUB_URL` | Base URL of the deployed hub | `https://shepherd.example.com` |
+| `TEAM_TOKEN` | Shared bearer token accepted by the hub | `tok_abc123` |
+
+Missing either causes an immediate startup failure with a clear error on stderr
+listing which vars are absent. (No other var triggers this.)
+
+**Everything else is optional** — each identity field is resolved at startup as
+**env var → git detection → fallback**, so a plain `npx -y @korso/shepherd` with
+just the two required vars produces a valid, fully-identified session. Set an
+override only to replace what's detected:
+
+| Variable | If omitted | Example |
+|---|---|---|
+| `WORKSPACE` | defaults to `default` (**must match hub's `ALLOWED_WORKSPACE` if overridden**) | `shepherd` |
+| `REPO` | `git remote origin` → `owner/repo`, else repo folder name, else `unknown-repo` | `Korsoai/shepherd` |
+| `BRANCH` | `git rev-parse --abbrev-ref HEAD`, else `HEAD` | `main` |
+| `BASE_BRANCH` | `origin/HEAD`, else `origin/main` / `origin/master` (used for the change-awareness heads-up) | `origin/main` |
+| `HUMAN` | git `user.name`, else local-part of `user.email`, else this device's **cached** last-detected name, else a generated name | `daichi` |
+| `PROGRAM` | defaults to `claude-code` | `codex` |
+| `MODEL` | omitted — **never auto-detected**, so set it if you want it shown | `claude-sonnet-4-6` |
+| `HEARTBEAT_INTERVAL_SECONDS` | defaults to `60` | `30` |
+| `SHEPHERD_INBOX_DIR` | defaults to `~/.shepherd/inbox`. Override only to relocate the **announcement-push** inbox (see below); the background heartbeat writes incoming announcements here. If you set it, point your client hook/extension at the **same** dir | `~/.shepherd/inbox` |
+
+**Device-identity cache.** Whenever `HUMAN` is unset and git **does** detect a
+name, that name is cached for your OS user at `~/.shepherd/identity.json`. A
+later launch from a directory where git can't be read (e.g. a multi-repo
+workspace root) then reuses the cached name instead of inventing a fresh random
+one each time. The cache refreshes automatically the next time git reports a
+different name, and an explicit `HUMAN` override always wins and never touches
+the cache. It is best-effort: if the file can't be read or written, resolution
+just falls back to a generated name.
+
+---
+
+## Announcement push (on by default)
+
+Announcements reach an agent **without it having to ask**. The background
+heartbeat pulls any pending announcements from the hub every beat and stages them
+in a local **inbox file** (per working directory, under `SHEPHERD_INBOX_DIR`,
+default `~/.shepherd/inbox`). That file is then drained by two paths:
+
+1. **Universal drainer (always on, every client).** Whenever the agent calls any
+   Shepherd tool (`work`/`sync`/`done`/`announce`), the result also includes
+   anything sitting in the inbox. So even with no hook configured, no announcement
+   is ever lost — the worst case is the old behaviour (delivered on the next
+   Shepherd tool call), never silent drops.
+2. **Passive client hook/extension (optional, per client).** To get announcements
+   **without** waiting for a Shepherd tool call — surfaced on the agent's next
+   action of any kind — wire up your client's hook below. This is the
+   "a subagent finished" style of notification.
+
+Both paths read the **same** inbox file and de-duplicate by announcement id, so
+running both is safe (the hub hands each announcement to exactly one drain; the
+merge is just defensive). It's cheap: a **local file read — no network** (the
+heartbeat already did the fetch), and it only adds to the model's context when
+something is actually waiting.
+
+It delivers to an agent **while it's active**; an idle agent picks messages up the
+moment it next does anything. (Waking a fully-idle agent is out of scope — for
+Claude Code that needs Channels; Codex/Pi have no equivalent.)
+
+### Claude Code — `PreToolUse` hook
+
+`PreToolUse` fires before every tool, giving the most frequent passive delivery.
+The hook needs no arguments — it resolves the same default inbox dir the server
+uses (override both with `SHEPHERD_INBOX_DIR` if you relocated it):
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123"
+      }
+    }
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "npx -y -p @korso/shepherd shepherd-inbox-hook" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Codex — `UserPromptSubmit` hook
+
+Codex uses the **same** hook contract as Claude Code (JSON on stdin, a
+`hookSpecificOutput.additionalContext` reply), so the **same bin** serves it. Use
+`UserPromptSubmit` — Codex's `PreToolUse` only fires for Bash, not `apply_patch`
+or MCP calls. Hooks must be enabled with `features.hooks = true`. In
+`~/.codex/config.toml`:
+
+```toml
+[features]
+hooks = true
+
+[[hooks.UserPromptSubmit]]
+command = ["npx", "-y", "-p", "@korso/shepherd", "shepherd-inbox-hook"]
+# On Windows use command_windows instead:
+# command_windows = ["cmd", "/c", "npx -y -p @korso/shepherd shepherd-inbox-hook"]
+```
+
+### Pi — extension
+
+Pi has no stdin/stdout hook; it loads in-process extensions. Ship the bundled
+extension into Pi's extensions dir:
+
+```sh
+# global, applies everywhere:
+mkdir -p ~/.pi/agent/extensions
+cp "$(npm root -g)/@korso/shepherd/dist/inboxExtension.js" ~/.pi/agent/extensions/shepherd-inbox.js
+# …or per-project: copy into .pi/extensions/ in the repo root.
+```
+
+It runs on every user turn (`before_agent_start`), drains the same inbox, and
+injects pending announcements. (Or load it ad hoc with
+`pi -e /abs/path/to/dist/inboxExtension.js`.)
+
+### Notes
+
+Every path is **fail-open**: a missing dir, unreachable hub, or any error means
+nothing is surfaced and the tool call / turn proceeds normally — coordination
+never blocks the agent. The inbox is keyed per working directory; two sessions in
+the exact same directory share it (a benign edge — they're the same repo). If you
+override `SHEPHERD_INBOX_DIR` on the server, set it on the hook/extension to the
+same value (the Claude/Codex bin and the Pi extension both read
+`SHEPHERD_INBOX_DIR`, or you can pass the dir as the first CLI arg to the bin).
+
+---
+
+## 3. MCP client configuration
+
+### Claude Code
+
+> **Do not use `~/.claude/mcp.json` — Claude Code does not read it** (a config
+> there loads silently into nothing). Use `claude mcp add` (user scope, applies
+> everywhere) or a project-root `.mcp.json`. Confirm with `claude mcp list`,
+> which should show `shepherd … ✔ Connected`.
+
+Recommended — register once at user scope. Written as a **single line** so it
+pastes cleanly into PowerShell, cmd, bash, and zsh (on PowerShell the bash `\`
+line-continuation does not work). Minimal: just the two required vars (identity
+is auto-detected from git):
+
+```powershell
+claude mcp add shepherd -s user -e HUB_URL=https://shepherd.example.com -e TEAM_TOKEN=tok_abc123 -- npx -y @korso/shepherd
+```
+
+Add any optional overrides from §2 with extra `-e` flags (e.g. `-e MODEL=claude-sonnet-4-6 -e HUMAN=daichi`).
+
+Alternative — a `.mcp.json` at the **root of the repo you're working in**
+(optional overrides shown commented-style; drop the ones you don't need):
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "MODEL": "claude-sonnet-4-6"
+      }
+    }
+  }
+}
+```
+
+> Windows note: the server is a thin stdio client to the Linux-hosted hub, and
+> `npx` works the same on every OS — no file paths to escape. The hub itself runs
+> on Linux (Postgres), so the Windows-native durability concerns from the spike
+> don't apply to clients.
+
+### Codex (`~/.codex/config.toml`)
+
+Codex uses the same MCP stdio protocol but configures it in **TOML**, not JSON —
+at `~/.codex/config.toml` (global) or `.codex/config.toml` in a trusted project.
+The table is `mcp_servers` with an **underscore** (`mcp-servers`/`mcpServers` are
+silently ignored). Either run `codex mcp add`:
+
+```sh
+codex mcp add shepherd --env HUB_URL=https://shepherd.example.com --env TEAM_TOKEN=tok_abc123 --env PROGRAM=codex -- npx -y @korso/shepherd
+```
+
+…or add the table directly:
+
+```toml
+[mcp_servers.shepherd]
+command = "npx"
+args = ["-y", "@korso/shepherd"]
+env = { HUB_URL = "https://shepherd.example.com", TEAM_TOKEN = "tok_abc123", PROGRAM = "codex", MODEL = "o4-mini" }
+```
+
+### Pi (`~/.pi/agent/mcp.json` or `.pi/mcp.json`)
+
+Pi uses a JSON `mcpServers` block (project config overrides global):
+
+```json
+{
+  "mcpServers": {
+    "shepherd": {
+      "command": "npx",
+      "args": ["-y", "@korso/shepherd"],
+      "env": {
+        "HUB_URL": "https://shepherd.example.com",
+        "TEAM_TOKEN": "tok_abc123",
+        "PROGRAM": "pi"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 4. Verify the server starts (quick smoke test)
+
+Run with the two required vars set to confirm it connects and idles on stdin.
+PowerShell (set env vars, then run):
+
+```powershell
+$env:HUB_URL = "https://shepherd.example.com"
+$env:TEAM_TOKEN = "tok_abc123"
+npx -y @korso/shepherd
+```
+
+bash/zsh: `HUB_URL=https://shepherd.example.com TEAM_TOKEN=tok_abc123 npx -y @korso/shepherd`
+
+No stderr output and the process blocking on stdin = healthy. Press Ctrl+C to exit.
+
+**Missing env vars:** if you omit `HUB_URL` or `TEAM_TOKEN`, you will see:
+
+```
+[shepherd] Configuration error — missing or invalid env vars:
+  HUB_URL: HUB_URL is required
+  TEAM_TOKEN: TEAM_TOKEN is required
+```
+
+and the process exits 1 immediately. This is by design. The optional identity
+vars never cause this — they fall back to git detection / defaults.
+
+**Wrong WORKSPACE:** if you override `WORKSPACE` to a value the hub doesn't allow, the server starts and connects but the startup auto-join is rejected (400), so every tool call (`work`, `sync`, etc.) reports "session not ready … proceeding uncoordinated". Either leave `WORKSPACE` unset (resolves to `default`) or set it to exactly match the hub's `ALLOWED_WORKSPACE`, then restart.
+
+---
+
+## Develop from source
+
+Only needed if you're changing the MCP server itself. Clone the monorepo and
+point your client at a local build instead of npx:
+
+```sh
+git clone https://github.com/Korsoai/shepherd.git
+cd shepherd
+npm install
+npm run build         # tsc -b — compiles the workspace for dev + tests
+```
+
+For an exact preview of the published artifact (a single self-contained bundle
+with `@shepherd/shared` inlined), build the package directly:
+
+```sh
+npm run build --workspace=@korso/shepherd   # runs tsup → packages/mcp-server/dist/index.js
+```
+
+Then use `node /absolute/path/to/shepherd/packages/mcp-server/dist/index.js` as
+the `command` in your MCP config (Windows: escape backslashes in JSON).
+
+### Publishing a new version
+
+```sh
+# bump "version" in packages/mcp-server/package.json, then:
+npm publish --workspace=@korso/shepherd   # prepublishOnly runs tsup automatically
+```
+
+`publishConfig.access` is `public`, so the scoped package publishes publicly.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Configuration error — missing or invalid env vars` | `HUB_URL` or `TEAM_TOKEN` is absent (only these two are required) | Add the missing var(s) to your client's `env` block |
+| Tools report "session not ready … proceeding uncoordinated" | Startup auto-join rejected — usually a stale `TEAM_TOKEN`, or a `WORKSPACE` override the hub doesn't allow | Re-check `TEAM_TOKEN`; leave `WORKSPACE` unset (→ `default`) or match the hub's `ALLOWED_WORKSPACE`; restart |
+| Agent shows up under a surprising name/repo/branch | Identity auto-detected from git, or reused from the device-identity cache when launched outside a git work tree | Override with `HUMAN`/`REPO`/`BRANCH`/`MODEL` env vars (§2); a correct git `user.name` on the next in-repo launch refreshes the cache, or delete `~/.shepherd/identity.json` to clear it |
+| `npm error 404 … @korso/shepherd` | Package not published yet, or name typo | `npm view @korso/shepherd version` to confirm it's live |
+| Process exits immediately with no error | Rare; check for node version incompatibility | Requires Node 18+ (ESM support) |