krishna916 · krishna916 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore
@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # Relay
 
+Agent integrations: see [setup](docs/agent-integration.md) and [troubleshooting](docs/troubleshooting-agent-integration.md).
+
 The approved agent-integration contract is documented in the [decision record](docs/decisions/0002-agent-integration-contracts.md), [MCP tool reference](docs/mcp-tools.md), [CLI reference](docs/cli-reference.md), and [session semantics](docs/session-semantics.md). The production MCP task tools and source-checkout CLI are shipped.
 
 Relay is a local task sidecar for humanâ€“AI workflows. The current MVP is usable through its local web UI and through five safe local stdio MCP task tools.

diff --git a/docs/agent-integration.md b/docs/agent-integration.md
@@ -0,0 +1,44 @@
+# Agent Integration
+
+## Supported source-checkout model
+
+Relay integrations run the built entries from an absolute source checkout: `node __RELAY_CHECKOUT__/dist/mcp/main.js` or `node __RELAY_CHECKOUT__/dist/cli/main.js`. `relay mcp` is a future packaged command owned by Epic #18 and is not available.
+
+For source development only, run `pnpm dev:mcp` from the checkout; vendor configuration should use the built Node entry so it is independent of the current working directory.
+
+## Compatibility verification
+
+| Client      | Version tested                       | Verified on | Official sources                                                                                                           | Limitations                                                    |
+| ----------- | ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| Codex       | desktop/CLI current as of 2026-07-29 | Windows     | [MCP](https://learn.chatgpt.com/docs/extend/mcp), [config basics](https://learn.chatgpt.com/docs/config-file/config-basic) | Manual client smoke test requires a local client installation. |
+| Claude Code | current docs checked 2026-07-29      | Windows     | [MCP](https://docs.anthropic.com/en/docs/claude-code/mcp)                                                                  | Manual client smoke test requires Claude Code.                 |
+
+## Prerequisites
+
+Use Node 24 and pnpm 10.2.0, install dependencies, and run `pnpm build:node`.
+
+## Isolated validation database
+
+Set `RELAY_DB_PATH` to `__RELAY_CHECKOUT__/.relay-validation/relay.db` for first validation.
+
+## Canonical MCP and CLI entry points
+
+See [generic MCP](../integrations/generic-mcp/README.md) and [generic CLI](../integrations/generic-cli/README.md). MCP tools include `relay_health`, `task_capture`, `task_list`, `task_get`, `task_find_similar`, and `session_captures_list`.
+
+## Session and provenance example
+
+Use a new valid session ID such as `relay-check-20260729-001` and retain it for capture and session lookup. Supply agent and workspace metadata through the documented adapter.
+
+## Validation workflow
+
+Build, configure one client manually, reload it, discover Relay tools, capture one disposable task, then retrieve that exact session.
+
+## Disable and removal semantics
+
+Remove only the client configuration and canonical-skill references. The SQLite database remains untouched.
+
+## Current limitations
+
+These source-checkout assets do not install packages, edit client configuration automatically, publish marketplace artifacts, or provide a daemon.
+
+Manual client smoke tests were not performed in this environment on 2026-07-29: Codex CLI was blocked by an access-denied executable and Claude Code was not installed. Consequently, no client version, tool-discovery evidence, session ID, database path, or removal result is asserted here; these remain release-review gates for a clean checkout.
diff --git a/docs/troubleshooting-agent-integration.md b/docs/troubleshooting-agent-integration.md
@@ -0,0 +1,45 @@
+# Troubleshooting agent integration
+
+## Node 24 or pnpm 10.2.0 mismatch
+
+**Symptom:** build fails. **Check:** `node --version` and `pnpm --version`. **Resolution:** use the documented versions.
+
+## Missing dist/mcp/main.js or dist/cli/main.js
+
+**Symptom:** process cannot start. **Check:** run `pnpm build:node`. **Resolution:** rebuild before configuring the client.
+
+## Incorrect absolute checkout path
+
+**Symptom:** command is not found. **Check:** replace the token with an existing absolute checkout. **Resolution:** update only the client configuration.
+
+## better-sqlite3 native installation failure
+
+**Symptom:** dependency installation fails. **Check:** Node version and compiler prerequisites. **Resolution:** repair the supported Node toolchain and reinstall dependencies.
+
+## Malformed client configuration
+
+**Symptom:** Relay is absent. **Check:** parse the JSON or TOML template. **Resolution:** preserve command and argument separation.
+
+## MCP process exits immediately
+
+**Symptom:** tool discovery fails. **Check:** run the configured Node command directly. **Resolution:** rebuild and correct its path.
+
+## MCP stdout contamination
+
+**Symptom:** MCP protocol errors. **Check:** inspect server wrappers. **Resolution:** do not add stdout logging around Relay.
+
+## Different RELAY_DB_PATH values
+
+**Symptom:** tasks appear missing. **Check:** compare both client environment values. **Resolution:** use the same database path.
+
+## Malformed or reused session ID
+
+**Symptom:** validation or mixed captures. **Check:** use one valid active-session ID. **Resolution:** generate a new ID for each independent session.
+
+## CLI JSON parsing mistakes
+
+**Symptom:** scripts cannot parse responses. **Check:** include `--output json`. **Resolution:** parse stdout JSON only.
+
+## Removing an integration without deleting task data
+
+**Symptom:** concern about data loss. **Check:** remove only configuration. **Resolution:** preserve the SQLite database; it remains untouched.
diff --git a/integrations/claude-code/.mcp.json.example b/integrations/claude-code/.mcp.json.example
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "relay": {
+      "command": "node",
+      "args": ["__RELAY_CHECKOUT__/dist/mcp/main.js"],
+      "env": {
+        "RELAY_DB_PATH": "__RELAY_CHECKOUT__/.relay-validation/relay.db"
+      }
+    }
+  }
+}
diff --git a/integrations/claude-code/README.md b/integrations/claude-code/README.md
@@ -0,0 +1,5 @@
+# Claude Code integration
+
+Build Relay and substitute an absolute checkout path. Add the stdio server with `claude mcp add relay --scope project --env RELAY_DB_PATH=ABSOLUTE_CHECKOUT/.relay-validation/relay.db -- node ABSOLUTE_CHECKOUT/dist/mcp/main.js`, or copy the template to the project root as `.mcp.json`. `local` is private to the current project, `project` is shared through `.mcp.json`, and `user` applies across projects; local takes priority. Set the same isolated `RELAY_DB_PATH` in the selected configuration.
+
+Use `claude mcp list`, `claude mcp get relay`, and `/mcp` to validate and authorize the server. Confirm `relay_health`, the task tools, a disposable capture, and the exact session lookup. In the project `CLAUDE.md`, add `@skills/relay-capture/SKILL.md` and `@skills/relay-session-review/SKILL.md` so Claude Code imports the canonical [Relay Capture](../../skills/relay-capture/SKILL.md) and [Relay Session Review](../../skills/relay-session-review/SKILL.md) guidance. Remove it with `claude mcp remove relay` or by deleting the Relay entry and imports; the SQLite database remains untouched.
diff --git a/integrations/codex/README.md b/integrations/codex/README.md
@@ -0,0 +1,5 @@
+# Codex integration
+
+Build Relay, replace `__RELAY_CHECKOUT__` with an absolute path, create `.relay-validation`, then add the template to trusted project `.codex/config.toml` or user `~/.codex/config.toml`. Restart Codex and use `/mcp` or `codex mcp list` to confirm Relay. Verify `relay_health`, the five read/capture tools, a disposable capture, and exact-session retrieval. The JSON CLI fallback is in [generic CLI](../generic-cli/README.md).
+
+Install the canonical [Relay Capture](../../skills/relay-capture/SKILL.md) and [Relay Session Review](../../skills/relay-session-review/SKILL.md) as repository skills by copying their directories to `.agents/skills/relay-capture/` and `.agents/skills/relay-session-review/`; Codex discovers repository skills from `.agents/skills` after a new session. Do not copy their policy into this README. Remove the Relay MCP configuration and those skill directories to disable it. The SQLite database remains untouched.
diff --git a/integrations/codex/config.toml.example b/integrations/codex/config.toml.example
@@ -0,0 +1,6 @@
+[mcp_servers.relay]
+command = "node"
+args = ["__RELAY_CHECKOUT__/dist/mcp/main.js"]
+
+[mcp_servers.relay.env]
+RELAY_DB_PATH = "__RELAY_CHECKOUT__/.relay-validation/relay.db"
diff --git a/integrations/generic-cli/README.md b/integrations/generic-cli/README.md
@@ -0,0 +1,13 @@
+# Generic CLI integration
+
+Use the CLI when MCP is unavailable or for an explicit one-shot operation. Build first, use the same isolated `RELAY_DB_PATH`, and parse only `--output json` stdout. For example:
+
+```bash
+node __RELAY_CHECKOUT__/dist/cli/main.js task capture --title "Disposable integration check" --agent generic-cli --session relay-check-20260729-001 --workspace relay --source-context "Issue 24 validation" --output json
+node __RELAY_CHECKOUT__/dist/cli/main.js session captures --session relay-check-20260729-001 --output json
+node __RELAY_CHECKOUT__/dist/cli/main.js task triage TASK_ID --to BACKLOG --output json
+node __RELAY_CHECKOUT__/dist/cli/main.js task complete TASK_ID --output json
+node __RELAY_CHECKOUT__/dist/cli/main.js task archive TASK_ID --output json
+```
+
+Exit codes are documented in [the CLI reference](../../docs/cli-reference.md). Capture can be autonomous; edit, triage, start, complete, and archive require explicit user direction. See [Relay Capture](../../skills/relay-capture/SKILL.md) and [Relay Session Review](../../skills/relay-session-review/SKILL.md). Removing a client integration does not delete the database; the database remains.
diff --git a/integrations/generic-mcp/README.md b/integrations/generic-mcp/README.md
@@ -0,0 +1,7 @@
+# Generic MCP integration
+
+Build Relay with `pnpm build:node`, replace `__RELAY_CHECKOUT__` in [server-config.json.example](server-config.json.example) with an absolute checkout path, then copy the command, arguments, and optional environment map into the client configuration. Keep command and arguments separate: do not use a shell or interpolation. The validation database is isolated; clients may omit `RELAY_DB_PATH` to use Relay's platform default.
+
+The stdio protocol requires clean stdout. Relay exposes `relay_health`, `task_capture`, `task_list`, `task_get`, `task_find_similar`, and `session_captures_list`, plus explicit mutation tools. Restart or reload the client, capture one disposable task, and retrieve it by the same exact session ID.
+
+Use [Relay Capture](../../skills/relay-capture/SKILL.md) and [Relay Session Review](../../skills/relay-session-review/SKILL.md) for behavioural guidance. To remove this integration, remove only the client configuration; the SQLite database remains untouched.
diff --git a/integrations/generic-mcp/server-config.json.example b/integrations/generic-mcp/server-config.json.example
@@ -0,0 +1,7 @@
+{
+  "command": "node",
+  "args": ["__RELAY_CHECKOUT__/dist/mcp/main.js"],
+  "env": {
+    "RELAY_DB_PATH": "__RELAY_CHECKOUT__/.relay-validation/relay.db"
+  }
+}
diff --git a/package.json b/package.json
@@ -56,6 +56,7 @@
     "vitest": "^4.1.10"
   },
   "dependencies": {
+    "@iarna/toml": "2.2.5",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^13.0.1",
     "react": "^19.2.8",

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml