overlord-cli 0.2607280953.0 → 0.2607292110.0

package/dist/connectors/README.md

@@ -13,6 +13,8 @@ OpenCode, Antigravity, and others). A connector is what lets an agent speak the
 - [For Developers](#for-developers)
   - [Contract Component](#contract-component)
   - [The four layers](#the-four-layers)
+  - [Adapter capability matrix](#adapter-capability-matrix)
+  - [Generated files](#generated-files)
   - [Documentation](#documentation)
 
 ## For Users
@@ -66,6 +68,50 @@ or the harness extension catalog (→ Extension System, see [Database module](..
 - **Plugin Adapters** — package plugins into a harness via its native plugin/connector manager (Claude, Codex, Cursor).
 - **Prompt Wrappers** — instructions + key data wrapping the user's prompt at LLM submission time.
 
+### Adapter capability matrix
+
+Adapters deliberately differ. This table records what each one ships and, where a
+mechanism is absent, whether the gap is a decision or simply unported work — so a
+contributor adding an adapter can tell signal from neglect. Source of truth for the
+"ships" columns is each adapter's `conformance-manifest.yaml`.
+
+| Adapter | Commands | Hooks | Local MCP shim | MCP config | Rules | Native resume |
+|---|---|---|---|---|---|---|
+| `claude` | `commands/` | `hooks/hooks.json` (4 types) | — | — | — | — |
+| `codex` | — | `.codex-plugin/hooks.json` + `scripts/*.sh` (2 types) | rendered | `.mcp.json` | — | yes |
+| `cursor` | `commands/` | `hooks/*.sh` (4 types) | rendered | `mcp.json` | `rules/` | — |
+| `antigravity` | `skills/*.md` | `hooks.json` + `scripts/*.sh` (2 types) | rendered | `mcp_config.json` | — | — |
+| `pi` | — | `extensions/overlord.ts` (`input` event) | — | — | — | yes |
+
+Intentional omissions:
+
+- **`claude` ships no local MCP shim.** The Claude plugin reaches Overlord's hosted
+  MCP server, so a local stdio bridge would duplicate it.
+- **`pi` ships no shim, hooks directory, or commands.** PI integrates through a
+  single TypeScript extension, and it has no native permission-request hook — its
+  `input` event carries follow-up capture only.
+- **`antigravity` passes no model or effort flag.** Antigravity selects the model
+  internally; see [05 — Connectors and Agent Plugins](docs/05-connectors-and-agent-plugins.md#antigravity-connector).
+- **`cursor` passes no effort/thinking flag.** Deferred, not declined — recorded in
+  the Cursor requirements as "no thinking/effort flag required initially".
+
+Unconfirmed gaps — read these as unported rather than declined, and file feature
+work as its own mission rather than folding it into a docs change:
+
+- `codex` ships no `commands/` while `claude` and `cursor` do, and `antigravity`
+  achieves the same surface through `skills/*.md`. No harness constraint is recorded.
+- `codex` and `antigravity` register no `PostToolUse` or `Stop` hooks; whether their
+  harnesses expose the equivalent events is not documented here.
+
+### Generated files
+
+The local MCP shim (`scripts/overlord-mcp.mjs`) is **generated**, not committed per
+adapter. One source — [`core/scripts/overlord-mcp.mjs`](core/scripts/overlord-mcp.mjs) —
+is rendered per adapter at `ovld agent-setup` time, substituting the adapter key into
+`DEFAULT_AGENT` and `serverInfo.name`. Edit the core file; there is no adapter copy to
+edit. The rendered artifact stays a standalone runnable `.mjs`, since harnesses start it
+directly from the install path.
+
 ### Documentation
 
 - [Connector Core](core/README.md): shared workflow instructions and protocol references consumed by connector plugins.

package/dist/connectors/VERSION

@@ -1 +1 @@
-0.3.6
+0.3.10

package/dist/connectors/adapters/antigravity/README.md

@@ -73,12 +73,20 @@ This connector is intentionally reviewable against the four connector layers in
 - `skills/overlord-mission/SKILL.md` — Antigravity adapter template with a `<!-- @connector-core -->` marker; setup interpolates shared core content at install time.
 - `skills/attach.md`, `skills/connect.md`, `skills/load.md`, `skills/create.md`, `skills/prompt.md`, `skills/discuss-objective.md`, `skills/add-objectives.md`, `skills/record-work.md`, `skills/spawn.md` — one skill per protocol operation; Antigravity auto-registers each as a `/<name>` slash command.
 - `hooks.json` + `scripts/pre-invocation-hook.sh` + `scripts/pre-tool-use-hook.sh` — follow-up and permission activity capture through `ovld protocol` (see mapping notes below).
-- `mcp_config.json` + `scripts/overlord-mcp.mjs` — MCP bridge to common `ovld protocol` operations.
+- `mcp_config.json` + `scripts/overlord-mcp.mjs` — MCP bridge to common `ovld protocol` operations. The shim is **generated**: it is rendered from `connectors/core/scripts/overlord-mcp.mjs` at setup time with the adapter key substituted, and there is no copy in this directory to edit.
 - `conformance-manifest.yaml` — connector conformance declaration for the Overlord contract.
 - `prompt-wrapper.md` — Antigravity launch guidance.
 
 The shared Connector Core source lives at `connectors/core/overlord-mission`. `ovld agent-setup antigravity` interpolates that core into the adapter skill template and installs core reference files so the runtime package is self-contained.
 
+### Omissions
+
+- **No model or effort flag at launch.** Antigravity selects the model internally, so Overlord passes neither. Deliberate.
+- **No `commands/` directory.** Antigravity auto-registers each `skills/*.md` as a `/<name>` slash command, so a separate commands surface would be redundant. Deliberate.
+- **No `PostToolUse` or `Stop` hooks.** Only follow-up and permission capture are mapped; whether Antigravity exposes the equivalent events is not yet established. Treat as open work.
+
+See the [adapter capability matrix](../../README.md#adapter-capability-matrix) for how this compares across adapters.
+
 ### Notes on the Antigravity hook mapping
 
 Antigravity's native hook events are `PreToolUse`, `PostToolUse`, `PreInvocation`, `PostInvocation`, and `Stop` — it has no event literally named `UserPromptSubmit` or `PermissionRequest` the way Claude Code and Codex do. This adapter maps Antigravity's native events onto Overlord's canonical hook-type vocabulary the same way the Cursor adapter maps `beforeSubmitPrompt` onto `UserPromptSubmit`:

package/dist/connectors/adapters/antigravity/conformance-manifest.yaml

@@ -1,4 +1,4 @@
-contractVersion: "0"
+contractVersion: "37"
 componentType: connector
 componentKey: antigravity
 label: "Antigravity Connector"

package/dist/connectors/adapters/antigravity/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "overlord",
-  "version": "0.3.6",
+  "version": "0.3.10",
   "description": "Chat-driven access to Overlord mission protocol workflows with hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",

package/dist/connectors/adapters/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.3.6",
+  "version": "0.3.10",
   "description": "Overlord mission protocol workflow for Claude Code — attach/update/ask/deliver, slash commands, and hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",

package/dist/connectors/adapters/claude/README.md

@@ -91,3 +91,10 @@ This connector is intentionally reviewable against the four connector layers in
 - `prompt-wrapper.md` — Claude launch context-file guidance.
 
 The shared Connector Core source lives at `connectors/core/overlord-mission`. `ovld agent-setup claude` interpolates that core into the adapter skill template and installs core reference files so the runtime package is self-contained.
+
+### Deliberate omissions
+
+- **No local MCP shim.** The Claude plugin reaches Overlord's hosted MCP server, so the local stdio bridge that Codex, Cursor, and Antigravity install would only duplicate it.
+- **No native resume flag.** Sessions are re-entered through the plugin's own surfaces rather than a `--session` launch flag.
+
+See the [adapter capability matrix](../../README.md#adapter-capability-matrix) for how this compares across adapters.

package/dist/connectors/adapters/claude/conformance-manifest.yaml

@@ -1,4 +1,4 @@
-contractVersion: "35"
+contractVersion: "37"
 componentType: connector
 componentKey: claude
 label: "Claude Code Connector"

package/dist/connectors/adapters/codex/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.3.6",
+  "version": "0.3.10",
   "description": "Chat-driven access to Overlord mission protocol workflows with hook-driven activity capture.",
   "author": {
     "name": "Cooperativ",

package/dist/connectors/adapters/codex/README.md

@@ -70,9 +70,16 @@ This connector is intentionally reviewable against the four connector layers in
 
 - `skills/overlord-mission/SKILL.md` — Codex adapter template with a `<!-- @connector-core -->` marker; setup interpolates shared core content at install time.
 - `.codex-plugin/hooks.json` + `scripts/*.sh` — `UserPromptSubmit` follow-up capture and `PermissionRequest` notifications through `ovld protocol`.
-- `.mcp.json` + `scripts/overlord-mcp.mjs` — MCP bridge to common `ovld protocol` operations.
+- `.mcp.json` + `scripts/overlord-mcp.mjs` — MCP bridge to common `ovld protocol` operations. The shim is **generated**: it is rendered from `connectors/core/scripts/overlord-mcp.mjs` at setup time with the adapter key substituted, and there is no copy in this directory to edit.
 - `assets/` — branded plugin assets for Codex install surfaces.
 - `conformance-manifest.yaml` — connector conformance declaration for the Overlord contract.
 - `prompt-wrapper.md` — Codex launch guidance.
 
 The shared Connector Core source lives at `connectors/core/overlord-mission`. `ovld agent-setup codex` interpolates that core into the adapter skill template and installs core reference files so the runtime package is self-contained.
+
+### Omissions
+
+- **No `commands/` directory.** Codex reaches protocol operations through the MCP bridge and the mission skill. This is unported rather than declined — no Codex constraint is recorded against slash commands — so treat it as open work with its own mission, not as a settled decision.
+- **No `PostToolUse` or `Stop` hooks.** Only `UserPromptSubmit` and `PermissionRequest` are registered; the equivalent Codex events are not yet mapped.
+
+See the [adapter capability matrix](../../README.md#adapter-capability-matrix) for how this compares across adapters.

package/dist/connectors/adapters/codex/conformance-manifest.yaml

@@ -1,4 +1,4 @@
-contractVersion: "0"
+contractVersion: "37"
 componentType: connector
 componentKey: codex
 label: "Codex Connector"

package/dist/connectors/adapters/cursor/.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "overlord",
-  "version": "0.3.6",
+  "version": "0.3.10",
   "description": "Overlord mission protocol workflow for Cursor — attach/update/ask/deliver, slash commands, MCP bridge, and follow-up capture.",
   "author": {
     "name": "Cooperativ",

package/dist/connectors/adapters/cursor/README.md

@@ -80,10 +80,17 @@ This connector is intentionally reviewable against the four connector layers in
 - `hooks/overlord-post-tool-use.sh` — records `postToolUse` file edits and shell-mediated changes for exact per-session delivery attribution.
 - `hooks/overlord-stop.sh` — checks pending delivery through `ovld protocol hook-event`; when needed, it asks Cursor to continue once so the agent can finish delivery.
 - `rules/overlord-local.mdc` — always-on workflow rules for Cursor sessions.
-- `mcp.json` + `scripts/overlord-mcp.mjs` — MCP bridge to common `ovld protocol` operations.
+- `mcp.json` + `scripts/overlord-mcp.mjs` — MCP bridge to common `ovld protocol` operations. The shim is **generated**: it is rendered from `connectors/core/scripts/overlord-mcp.mjs` at setup time with the adapter key substituted, and there is no copy in this directory to edit.
 - `conformance-manifest.yaml` — connector conformance declaration for the Overlord contract.
 - `prompt-wrapper.md` — Cursor launch guidance.
 
 The shared Connector Core source lives at `connectors/core/overlord-mission`. `ovld agent-setup cursor` interpolates that core into the adapter skill template and installs core reference files so the runtime package is self-contained.
 
+### Deliberate omissions
+
+- **No effort/thinking flag.** Launch passes a model flag only; the Cursor requirements record no thinking/effort flag as needed initially. Deferred, not declined.
+- **No native resume flag.** Cursor sessions are re-entered through the harness rather than an Overlord-passed session flag.
+
+See the [adapter capability matrix](../../README.md#adapter-capability-matrix) for how this compares across adapters.
+
 Cursor's generic `preToolUse` hook is intentionally not used for permission capture. Cursor currently documents that `ask` is not enforced for `preToolUse`; the narrower shell and MCP hooks expose the native permission-decision schema without changing the user's policy. Cursor also documents hook execution as fail-open by default, so Overlord telemetry failures do not strand the agent.

package/dist/connectors/adapters/cursor/conformance-manifest.yaml

@@ -1,4 +1,4 @@
-contractVersion: "35"
+contractVersion: "37"
 componentType: connector
 componentKey: cursor
 label: "Cursor Connector"

package/dist/connectors/adapters/pi/README.md

@@ -40,3 +40,11 @@ When PI supplies a native session ID, Overlord's review UI can reopen it with:
 ```bash
 pi --session <session-id>
 ```
+
+## Deliberate omissions
+
+- **No local MCP shim and no MCP config.** PI integrates through the single `extensions/overlord.ts` extension, which calls `ovld protocol` directly.
+- **No permission hook.** PI exposes no native permission-request event, so there is nothing to observe.
+- **No `commands/` directory or rules file.** Protocol operations are reached through the mission skill and the extension.
+
+See the [adapter capability matrix](../../README.md#adapter-capability-matrix) for how this compares across adapters.

package/dist/connectors/adapters/pi/conformance-manifest.yaml

@@ -1,4 +1,4 @@
-contractVersion: "0"
+contractVersion: "37"
 componentType: connector
 componentKey: pi
 label: "PI Connector"

package/dist/connectors/core/README.md

@@ -46,7 +46,24 @@ When building a Connector Plugin, adapter skill templates include `<!-- @connect
 `connectors/core/overlord-mission/` into that marker and copies core reference files
 into the installable plugin package. Do not fork the core protocol rules into each adapter.
 
+The same rendering path carries the local MCP shim. `scripts/overlord-mcp.mjs` is the
+single source for the stdio MCP bridge that Codex, Cursor, and Antigravity install;
+`ovld agent-setup <agent>` substitutes `__OVERLORD_ADAPTER_KEY__` with the adapter key
+(`DEFAULT_AGENT` and `serverInfo.name`) and writes the result into the adapter's install
+path. There are no adapter-local copies to keep in step. Two constraints hold when
+editing it:
+
+- It must stay a standalone runnable `.mjs`. The rendered file is copied into the
+  user's home and started directly by the harness, so it may not import anything
+  repo-local or require a build step.
+- The tool list must stay in parity with the hosted MCP catalog; `backend/mcp.test.ts`
+  asserts this against `mcp/tool-catalog.ts`.
+
+`connectors/VERSION` drives the reported `serverInfo.version`; patch it with
+`yarn connectors:version:sync`, never by hand.
+
 ### Files
 
 - `overlord-mission/SKILL.md` — shared mission lifecycle workflow.
 - `overlord-mission/reference/` — shared protocol, context, device, MCP/API, and shell-escaping references.
+- `scripts/overlord-mcp.mjs` — shared local MCP shim, rendered per adapter.

package/dist/connectors/core/overlord-mission/SKILL.md

@@ -407,6 +407,7 @@ Field shape, inline vs stdin piping, and `record-change-rationales` syntax are i
 - The `summary` in deliver is what the PM reads first, so write it as a narrative, not a command list.
 - When a summary or question contains backticks, `$vars`, or other shell-special characters, always use `--summary-file -` (or `--question-file -`) with a single-quoted heredoc (`<<'EOF'`). Never retry by stripping or escaping content — pipe stdin instead. See [reference/shell-escaping.md](reference/shell-escaping.md).
 - Use `write-context` for facts a future agent session should know.
+- Use `update-artifact` (or MCP `overlord_update_artifact`) to revise an existing mission artifact in place instead of delivering a duplicate when a later objective updates a plan or notes.
 - If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
 - If you must run `ovld auth login`, `--organization-id <id>` is optional — it validates/scopes that login or command but does not create a stored default organization.
 - Do not add or commit changes unless the user explicitly asks you to commit.

package/dist/connectors/core/overlord-mission/reference/context.md

@@ -3,6 +3,8 @@
 ```bash
 ovld protocol read-context --session-key <sessionKey> --mission-id $MISSION_ID
 ovld protocol write-context --session-key <sessionKey> --mission-id $MISSION_ID --key "key" --value '"json-value"'
+ovld protocol update-artifact --mission-id $MISSION_ID --artifact-id <artifact-id> \
+  --expected-revision <n> --label "Revised plan" --content-text-file -
 ovld protocol attachment-list --session-key <sessionKey> --objective-id <objective-id>
 ovld protocol attachment-upload-file --session-key <sessionKey> --objective-id <objective-id> --file ./spec.pdf --content-type application/pdf
 ovld protocol attachment-download-url --session-key <sessionKey> --attachment-id <attachment-id>
@@ -10,6 +12,10 @@ ovld protocol attachment-download-url --session-key <sessionKey> --attachment-id
 
 The `attach` and `load-context` responses already include an `attachments` array plus `previousObjectives` and `futureObjectives` arrays — use those for `<attachment-id>` and `<objective-id>` values. The objective currently being executed is not repeated in those arrays; it is the top-level `objective`. `previousObjectives` are the objectives already worked (before the current one) and `futureObjectives` are the ones queued after it. Run `attachment-list` mid-session if new files have been uploaded since attach. `--mission-id` is optional for attachment calls when `--objective-id` or `--attachment-id` lets the server derive the mission.
 
+## Updating existing artifacts
+
+When a later objective or follow-up must revise a plan, notes, or URL artifact created earlier, call `update-artifact` (or MCP `overlord_update_artifact`) instead of delivering a duplicate. Use the artifact `id` and `revision` from the mission `artifacts` array (or `ovld mission artifacts`). Provide at least one of `--label`, `--content-text` / `--content-text-file`, or `--external-url`. No session key is required. Stale `--expected-revision` returns a conflict — refresh and retry. Delivery/session/objective provenance and `contentJson` remain immutable.
+
 ## Large Artifacts
 
 For large artifacts such as planning documents, architecture decisions, research summaries, or design documents: **save the full content as a markdown file in the linked repository, then summarize it in the artifact returned to the mission.**
@@ -18,5 +24,5 @@ For large artifacts such as planning documents, architecture decisions, research
 - Commit the file as part of the mission's work so it appears in `changeRationales`.
 - In the delivery, include a `note` or `decision` artifact with a concise summary and the repository file path — not the full document content.
 
-This keeps the mission feed readable while preserving the full document in version control where it can be reviewed, diffed, and referenced later.
+This keeps the mission feed readable while preserving the full document in version control where it can be reviewed, diffed, and referenced later. If that summary artifact already exists on the mission, revise it with `update-artifact` rather than creating another copy.
 

package/dist/connectors/core/overlord-mission/reference/mcp.md

@@ -7,5 +7,6 @@
 - Execution request tools (`request_execution`, `claim_execution`, `list_execution_requests`, `clear_execution_requests`, `complete_execution_launch`, `fail_execution_launch`) back the local runner queue. Agents normally work missions with `attach`/`update`/`deliver`; runner processes use these queue tools.
 - `record_change_rationales` (MCP) and `ovld protocol record-change-rationales` (CLI) both write to the same `file_changes` table. The dedicated CLI route is `POST /api/protocol/record-change-rationales`.
 - `overlord_record_work` (hosted MCP) and `ovld protocol record-work` (CLI) record already-completed chat work as a single review-column mission with a completed objective, file-change rationales, and the standard Gemini delivery summary — no `attach`/`deliver`. Hosted MCP requires `projectId` (it never chooses a project implicitly); the CLI resolves the project from the working directory or `--project-id`. The submission format is in [record-work.md](record-work.md). The route is `POST /api/protocol/record-work`.
+- `overlord_update_artifact` (hosted MCP) and `ovld protocol update-artifact` (CLI) revise an existing mission artifact's label, Markdown content, and/or HTTP(S) URL in place. Required: `missionId` / `--mission-id`, `artifactId` / `--artifact-id`, `expectedRevision` / `--expected-revision`. Provide at least one editable field. No session key is required. Same service as REST `PATCH /api/missions/:id/artifacts/:artifactId`. The route is `POST /api/protocol/update-artifact`.
 - Objective attachment tools follow the `<verb>_<noun>` MCP naming: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`. CLI commands use `attachment-*`. `mission_id` / `missionId` is optional for attachment calls when the objective or attachment id lets the server derive mission scope.
-- "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above.
+- "Artifacts" in `deliver` are the structured records an agent submits at delivery time (next_steps, test_results, migration, decision, note, url) — not user-uploaded files. Files attached by users live on objectives via the attachment tools above. Prefer `update-artifact` / `overlord_update_artifact` when a later pass must revise an artifact already on the mission.

package/dist/connectors/{adapters/antigravity → core}/scripts/overlord-mcp.mjs

@@ -6,7 +6,7 @@ import { promisify } from 'node:util';
 const execFileAsync = promisify(execFile);
 const OVLD_BIN = process.env.OVLD_BIN?.trim() || 'ovld';
 const PROTOCOL_VERSION = '2025-06-18';
-const DEFAULT_AGENT = 'antigravity';
+const DEFAULT_AGENT = '__OVERLORD_ADAPTER_KEY__';
 let buffer = Buffer.alloc(0);
 
 function send(message) {
@@ -211,6 +211,10 @@ const tools = [
         missionId: stringProperty('Mission UUID or workspace display id.'),
         sessionKey: stringProperty('Session key returned by overlord_attach_session.'),
         summary: stringProperty('Delivery summary.'),
+        artifacts: {
+          type: 'array',
+          description: 'Optional mission artifacts to persist with this delivery.'
+        },
         noFileChanges: {
           type: 'boolean',
           description: 'Set true when the MCP run changed no files.'
@@ -235,6 +239,26 @@ const tools = [
       ['missionId', 'sessionKey', 'summary']
     )
   },
+  {
+    name: 'overlord_update_artifact',
+    title: 'Update mission artifact',
+    description:
+      'Revise an existing mission artifact in place (label, Markdown content, and/or URL) using optimistic concurrency via expectedRevision.',
+    inputSchema: objectSchema(
+      {
+        missionId: stringProperty('Mission UUID or workspace display id.'),
+        artifactId: stringProperty('Artifact id from mission context.'),
+        expectedRevision: {
+          type: 'number',
+          description: 'Current artifact.revision. Stale values return a conflict error.'
+        },
+        label: stringProperty('Optional new human-facing label.'),
+        contentText: stringProperty('Optional new Markdown/text content.'),
+        externalUrl: stringProperty('Optional HTTP(S) URL.')
+      },
+      ['missionId', 'artifactId', 'expectedRevision']
+    )
+  },
   {
     name: 'overlord_record_work',
     title: 'Record completed work as a mission',
@@ -360,6 +384,7 @@ function callOverlordTool(name, args) {
       'session-key': requiredString(args, 'sessionKey'),
       summary: requiredString(args, 'summary'),
       ...(args.noFileChanges === true ? { 'no-file-changes': true } : {}),
+      ...(Array.isArray(args.artifacts) ? { 'artifacts-json': args.artifacts } : {}),
       ...(Array.isArray(args.changeRationales)
         ? { 'change-rationales-json': args.changeRationales }
         : {}),
@@ -387,6 +412,25 @@ function callOverlordTool(name, args) {
         : {})
     });
   }
+  if (name === 'overlord_update_artifact') {
+    if (typeof args.expectedRevision !== 'number' || !Number.isInteger(args.expectedRevision)) {
+      throw new Error('expectedRevision must be an integer');
+    }
+    const hasLabel = typeof args.label === 'string';
+    const hasContentText = typeof args.contentText === 'string';
+    const hasExternalUrl = typeof args.externalUrl === 'string';
+    if (!hasLabel && !hasContentText && !hasExternalUrl) {
+      throw new Error('Provide at least one of label, contentText, or externalUrl');
+    }
+    return runProtocol('update-artifact', {
+      'mission-id': requiredString(args, 'missionId'),
+      'artifact-id': requiredString(args, 'artifactId'),
+      'expected-revision': String(Math.trunc(args.expectedRevision)),
+      ...(hasLabel ? { label: args.label } : {}),
+      ...(hasContentText ? { 'content-text': args.contentText } : {}),
+      ...(hasExternalUrl ? { 'external-url': args.externalUrl } : {})
+    });
+  }
   if (name === 'overlord_record_work') {
     return runProtocol('record-work', {
       'project-id': requiredString(args, 'projectId'),
@@ -433,7 +477,7 @@ process.stdin.on('data', async chunk => {
         result: {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: { tools: { listChanged: false } },
-          serverInfo: { name: 'overlord-antigravity', version: '0.3.6' }
+          serverInfo: { name: 'overlord-__OVERLORD_ADAPTER_KEY__', version: '0.3.10' }
         }
       });
       continue;

package/dist/connectors/docs/05-connectors-and-agent-plugins.md

@@ -46,6 +46,25 @@ Required content:
 - Do not continue implementation after delivery unless follow-up execution is explicitly requested.
 - Run local repair/diagnostic commands before asking the user to fix connector setup.
 
+## Canonical Local MCP Shim
+
+Source location:
+
+- `connectors/core/scripts/overlord-mcp.mjs`
+
+Codex, Cursor, and Antigravity each install a local stdio MCP bridge that delegates to `ovld protocol`. All three are rendered from this one core script at `ovld agent-setup` time: the adapter key is substituted for `__OVERLORD_ADAPTER_KEY__` in `DEFAULT_AGENT` and `serverInfo.name`. Adapter directories contain no committed copy — edit the core file.
+
+Requirements:
+
+- The rendered shim must remain a standalone runnable `.mjs`; harnesses start it directly from the install path, so no bundler or repo-local import may appear at runtime.
+- Adapter-specific behavior beyond the agent identifier belongs in the adapter, not in a fork of the shim.
+- The shim tool list must stay in parity with the hosted MCP catalog (`mcp/tool-catalog.ts`).
+- `serverInfo.version` follows `connectors/VERSION` through `scripts/sync-connector-versions.mjs`.
+
+## Adapter Capability Differences
+
+Adapters intentionally differ in which mechanisms they ship. The per-adapter matrix, the omissions that are decisions, and the gaps that are merely unported are recorded in the [connectors module README](../README.md#adapter-capability-matrix). Update that table when an adapter gains or drops a mechanism.
+
 ## Codex Connector
 
 Requirements:

package/dist/connectors/docs/agent-harness-configuration-architecture.md

@@ -50,7 +50,7 @@ fingerprint.
 
 | Concern | Owner | Overlord storage | Notes |
 | --- | --- | --- | --- |
-| Built-in agent connector capabilities | Overlord | Connector registry or static config | Examples: `codex`, `claude`, `cursor`. |
+| Built-in agent connector capabilities | Overlord | Connector registry or static config | Examples: `codex`, `claude`, `cursor`. Which mechanisms each adapter ships, and which omissions are deliberate, are recorded in the [adapter capability matrix](../README.md#adapter-capability-matrix). |
 | Agents and models available by default | Workspace | `workspaces.settings_json`, future `workspace_agent_catalog` | Model config is workspace-level, not project-level. |
 | Personal custom harness extensions | User | `user_harness_extensions` | User-owned source of truth for draft/private custom connectors. |
 | Workspace custom harness extensions | Workspace admin/member with permission | `workspace_harness_extensions` | Workspace-installed catalog entries, optionally copied from a personal extension version. |