krishna916 · krishna916 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
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,66 @@
+# 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      | Official documentation verified | Live smoke test | Evidence                                                                                                   |
+| ----------- | ------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
+| Codex       | 2026-07-29                      | Not completed   | Local Codex executable was blocked by an access-denied error; no tool-discovery or task result is claimed. |
+| Claude Code | 2026-07-29                      | Not completed   | Claude Code was unavailable to the maintainer; no tool-discovery or task result is claimed.                |
+
+Official sources checked on 2026-07-29: [Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp), [Codex configuration basics](https://learn.chatgpt.com/docs/config-file/config-basic), [Claude Code MCP documentation](https://code.claude.com/docs/en/mcp), and [Claude Code skills documentation](https://code.claude.com/docs/en/skills).
+
+## 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). The canonical MCP server is `node __RELAY_CHECKOUT__/dist/mcp/main.js`; `relay mcp` remains future-only and unavailable until Epic #18.
+
+## 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.
+
+## Deferred live validation
+
+Official documentation was verified on 2026-07-29 using the four links in the compatibility section. Claude Code was unavailable to the maintainer, so no live tool-discovery, task-capture, exact-session retrieval, or removal test was performed. The following checklist must be run in a real Claude Code environment before this acceptance gate is closed:
+
+1. Start from a clean Relay checkout.
+2. Select Node 24 and pnpm 10.2.0.
+3. Run `pnpm install --frozen-lockfile`.
+4. Run `pnpm build:node`.
+5. Create a disposable absolute `RELAY_DB_PATH`.
+6. Add Relay as a project-local Claude MCP stdio server.
+7. Install the canonical skills under `.claude/skills/`.
+8. Restart Claude Code.
+9. Confirm `relay_health` is discovered and succeeds.
+10. Confirm `task_capture`, `task_list`, `task_get`, `task_find_similar`, and `session_captures_list` are discovered.
+11. Capture one disposable task using a new exact session ID.
+12. Retrieve that exact session and confirm the task is returned.
+13. Remove only the MCP entry and Relay skill directories.
+14. Confirm the SQLite database file still exists and the task remains stored.
+15. Record Claude Code version, OS, commands, session ID, database path, results, and limitations.
+
+## 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. 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/superpowers/plans/2026-07-29-issue-24-agent-integration-assets.md b/docs/superpowers/plans/2026-07-29-issue-24-agent-integration-assets.md
@@ -55,6 +55,7 @@
 ### Task 1: Verify dependency contracts and current vendor documentation
 
 **Files:**
+
 - Read: `package.json`
 - Read: `docs/mcp-tools.md`
 - Read: `docs/cli-reference.md`
@@ -65,6 +66,7 @@
 - Create: `docs/agent-integration.md`
 
 **Interfaces:**
+
 - Consumes: built MCP entry `dist/mcp/main.js`, built CLI entry `dist/cli/main.js`, `relay_health`, `task_capture`, `task_list`, `task_get`, `task_find_similar`, `session_captures_list`, and the ten CLI task/session commands documented in `docs/cli-reference.md`.
 - Produces: a compatibility section that later vendor README files link to rather than re-state.
 
@@ -116,13 +118,21 @@ Create `docs/agent-integration.md` with these exact top-level sections:
 # Agent Integration
 
 ## Supported source-checkout model
+
 ## Compatibility verification
+
 ## Prerequisites
+
 ## Isolated validation database
+
 ## Canonical MCP and CLI entry points
+
 ## Session and provenance example
+
 ## Validation workflow
+
 ## Disable and removal semantics
+
 ## Current limitations
 ```
 
@@ -140,12 +150,14 @@ git commit -m "docs: record agent integration compatibility baseline"
 ### Task 2: Add failing integration-asset validator tests
 
 **Files:**
+
 - Create: `scripts/validate-agent-integration-assets.ts`
 - Create: `tests/unit/scripts/validate-agent-integration-assets.test.ts`
 - Create: `tests/fixtures/agent-integrations/valid/integrations/**`
 - Create: `tests/fixtures/agent-integrations/valid/docs/**`
 
 **Interfaces:**
+
 - Produces: `validateAgentIntegrationAssets(options?: { readonly rootDir?: string }): void`.
 - Consumes: canonical paths and tool names from Task 1.
 
@@ -182,7 +194,7 @@ reject invalid JSON in *.json.example after replacing the documented checkout to
 reject invalid TOML in config.toml.example after replacing the documented checkout token
 ```
 
-Use the single token `__RELAY_CHECKOUT__` for checkout substitution. It is visible, deterministic, and does not trip the repository-wide `TODO`/`TBD` placeholder check.
+Use the single token `__RELAY_CHECKOUT__` for checkout substitution. It is visible, deterministic, and does not trip the repository-wide unresolved-placeholder check.
 
 - [ ] **Step 4: Run tests and verify failure**
 
@@ -204,12 +216,14 @@ git commit -m "test: define agent integration asset validation"
 ### Task 3: Implement generic MCP and CLI assets first
 
 **Files:**
+
 - Create: `integrations/generic-mcp/server-config.json.example`
 - Create: `integrations/generic-mcp/README.md`
 - Create: `integrations/generic-cli/README.md`
 - Modify: `docs/agent-integration.md`
 
 **Interfaces:**
+
 - Consumes: `node __RELAY_CHECKOUT__/dist/mcp/main.js`, optional `RELAY_DB_PATH`, canonical MCP tool names, and CLI commands from `docs/cli-reference.md`.
 - Produces: vendor-neutral examples reused by vendor READMEs through links.
 
@@ -267,11 +281,13 @@ git commit -m "docs: add generic MCP and CLI integration assets"
 ### Task 4: Add and manually validate Codex assets
 
 **Files:**
+
 - Create: `integrations/codex/config.toml.example`
 - Create: `integrations/codex/README.md`
 - Modify: `docs/agent-integration.md`
 
 **Interfaces:**
+
 - Consumes: verified Codex syntax from Task 1, generic MCP/CLI docs from Task 3, and both canonical skills.
 - Produces: a minimal Codex-specific wrapper with no copied lifecycle policy.
 
@@ -332,11 +348,13 @@ git commit -m "docs: add verified Codex integration assets"
 ### Task 5: Add and manually validate Claude Code assets
 
 **Files:**
+
 - Create: `integrations/claude-code/.mcp.json.example`
 - Create: `integrations/claude-code/README.md`
 - Modify: `docs/agent-integration.md`
 
 **Interfaces:**
+
 - Consumes: verified Claude Code syntax from Task 1, generic MCP/CLI docs, and both canonical skills.
 - Produces: a Claude-native wrapper rather than a Codex-shaped translation.
 
@@ -377,12 +395,14 @@ git commit -m "docs: add verified Claude Code integration assets"
 ### Task 6: Implement the focused validator and aggregate wiring
 
 **Files:**
+
 - Modify: `scripts/validate-agent-integration-assets.ts`
 - Modify: `scripts/validate-repository-assets.ts`
 - Modify: `tests/unit/scripts/validate-agent-integration-assets.test.ts`
 - Modify: `tests/unit/scripts/validate-repository-assets.test.ts`
 
 **Interfaces:**
+
 - Produces: deterministic validation called by `pnpm validate:assets` through `validateRepositoryAssets()`.
 - Consumes: all integration assets from Tasks 3–5.
 
@@ -441,11 +461,13 @@ git commit -m "test: validate agent integration assets"
 ### Task 7: Add shared troubleshooting and README entry point
 
 **Files:**
+
 - Create: `docs/troubleshooting-agent-integration.md`
 - Modify: `docs/agent-integration.md`
 - Modify: `README.md`
 
 **Interfaces:**
+
 - Consumes: real build commands, database semantics, client validation evidence, and stable CLI errors.
 - Produces: one shared diagnosis guide linked from all integration READMEs.
 
@@ -455,15 +477,25 @@ Use one section per required case:
 
 ```markdown
 ## Node 24 or pnpm 10.2.0 mismatch
+
 ## Missing dist/mcp/main.js or dist/cli/main.js
+
 ## Incorrect absolute checkout path
+
 ## better-sqlite3 native installation failure
+
 ## Malformed client configuration
+
 ## MCP process exits immediately
+
 ## MCP stdout contamination
+
 ## Different RELAY_DB_PATH values
+
 ## Malformed or reused session ID
+
 ## CLI JSON parsing mistakes
+
 ## Removing an integration without deleting task data
 ```
 
@@ -498,16 +530,18 @@ git commit -m "docs: complete agent integration setup and troubleshooting"
 ### Task 8: Final verification and human review evidence
 
 **Files:**
+
 - Modify only if verification exposes a concrete defect in issue #24 assets.
 - Update: PR description with manual validation evidence and official sources.
 
 **Interfaces:**
+
 - Produces: a reviewable PR that satisfies the automated and manual acceptance gates.
 
 - [ ] **Step 1: Scan for forbidden scope and unresolved markers**
 
 ```bash
-git grep -n -E 'TODO|TBD|npm install -g|automatic.*config|doctor command|marketplace|daemon|delete.*relay\.db' -- integrations docs/agent-integration.md docs/troubleshooting-agent-integration.md
+git grep -n -E 'unresolved-placeholder|npm install -g|automatic.*config|doctor command|marketplace|daemon|delete.*relay\.db' -- integrations docs/agent-integration.md docs/troubleshooting-agent-integration.md
 ```
 
 Expected: no forbidden implementation guidance. Legitimate negative statements must be reviewed manually rather than blindly removed.
@@ -537,11 +571,17 @@ Include:
 
 ```markdown
 ## Official documentation verification
+
 ## Codex manual validation
+
 ## Claude Code manual validation
+
 ## Generic MCP/CLI validation
+
 ## Automated verification
+
 ## Known limitations
+
 ## Data-preserving removal check
 ```
 
@@ -574,4 +614,4 @@ Do not create an empty commit when no fixes were required.
 - Do not copy canonical skill prose into vendor READMEs; link to it.
 - Do not change MCP or CLI runtime contracts to make documentation easier. A discovered mismatch must be raised as a dependency defect.
 - Pause for human review after Tasks 1, 4, 5, and 8.
-- Before claiming completion, attach the exact `pnpm verify` output and manual client versions to the PR.
+- Before claiming completion, attach the exact `pnpm verify` output and manual client versions to the PR.
diff --git a/docs/superpowers/tasks/2026-07-29-pr-33-review-tracker.md b/docs/superpowers/tasks/2026-07-29-pr-33-review-tracker.md
@@ -0,0 +1,89 @@
+# PR #33 Review Task Tracker
+
+Source: [Luna remediation implementation plan](https://github.com/krishna916/relay/pull/33#issuecomment-5112744124)
+
+Scope: address every actionable item in the linked plan while preserving Relay's MCP, CLI, task, session, persistence, and data-preserving removal contracts. The PR remains draft while the unavailable Claude Code live validation is explicitly deferred.
+
+## Working rules
+
+- [x] Verify each review item against the current checkout before editing.
+- [x] Keep canonical behavioural guidance only in `skills/relay-capture/SKILL.md` and `skills/relay-session-review/SKILL.md`.
+- [x] Keep `dist/mcp/main.js` as the only canonical MCP server entry.
+- [x] Do not automatically edit client configuration or remove Relay SQLite data.
+- [x] Do not claim Codex or Claude Code live validation without recorded evidence.
+
+## Task 1 - Format the existing Issue #24 plan
+
+- [x] Format `docs/superpowers/plans/2026-07-29-issue-24-agent-integration-assets.md` with Prettier.
+- [x] Remove the unresolved marker that blocked repository asset validation.
+- [x] Run `pnpm format:check`.
+- [x] Commit the formatting change separately as `5449b89`.
+
+## Task 2 - Correct Claude Code skill installation guidance
+
+- [x] Require project-local `.claude/skills/relay-capture/SKILL.md` and `.claude/skills/relay-session-review/SKILL.md` destinations.
+- [x] Document optional personal skill destinations without presenting instruction-file imports as skill discovery.
+- [x] Instruct copying or symlinking complete canonical skill directories unchanged.
+- [x] Add validator tests for `CLAUDE.md`-only guidance and missing project skill paths.
+- [x] Update the real README, fixture, validator, and focused tests.
+
+## Task 3 - Remove contradictory compatibility claims
+
+- [x] Separate official documentation verification, live smoke-test status, and evidence in the compatibility table.
+- [x] Reject contradictory `Version tested`/unperformed-smoke-test fixtures.
+- [x] Update the real and fixture documentation.
+- [x] Keep the PR manual-validation wording honest.
+
+## Task 4 - Explicitly defer unavailable Claude Code live validation
+
+- [x] Add a clearly titled deferred-validation section with the verification date and exact official documentation links.
+- [x] Record that Claude Code was unavailable and no live discovery, capture, retrieval, or removal test was performed.
+- [x] Record the exact 15-step future validation checklist.
+- [ ] Leave the live checklist unresolved until a real Claude Code environment supplies evidence.
+- [x] Keep PR #33 in draft while this acceptance gate remains unmet.
+
+## Task 5 - Keep TOML validation development-only
+
+- [x] Move `@iarna/toml` from `dependencies` to `devDependencies`.
+- [x] Regenerate the lockfile and run typecheck plus focused validator tests.
+- [x] Confirm production entry points do not import the validator dependency.
+
+## Task 6 - Remove unrelated CodeGraph scope
+
+- [x] Remove `.codegraph/.gitignore` from the PR.
+
+## Task 7 - Strengthen deterministic integration-asset validation
+
+- [x] Validate Claude and Codex project skill paths.
+- [x] Reject unperformed live-test claims and contradictory compatibility wording.
+- [x] Validate command/argument separation, exact `dist/mcp/main.js` paths, and absence of machine-specific home paths.
+- [x] Validate both canonical skill references, data-preserving removal guidance, and future-only `relay mcp` wording.
+- [x] Validate the exact currently shipped MCP tool list, including the five mutation tools.
+- [x] Add focused positive and negative fixture coverage.
+
+## Task 8 - Verify, publish commits, and record PR status
+
+- [x] Run focused validator and repository-asset tests.
+- [x] Run the authoritative `pnpm verify` gate.
+- [x] Update PR #33 description with commands, official sources, honest live-validation status, and the deferred Claude checklist.
+- [x] Push all reviewed commits.
+- [ ] Confirm the latest GitHub Actions run for the pushed head.
+- [x] Leave the PR as draft.
+
+## Verification log
+
+| Check                   | Result  | Evidence                                                                                                                                                                                                            |
+| ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Baseline inspection     | Pass    | Clean working tree on `feature/issue-24-agent-integration-assets`; linked comment fetched from PR #33.                                                                                                              |
+| Focused validator tests | Pass    | `corepack pnpm exec vitest run tests/unit/scripts/validate-agent-integration-assets.test.ts`: 13 passed; aggregate run: 23 passed.                                                                                  |
+| Repository asset tests  | Pass    | `node --import tsx/esm scripts/validate-repository-assets.ts` passed.                                                                                                                                               |
+| Full `pnpm verify` gate | Pass    | 34 files, 469 tests, coverage 88.74% statements / 81.34% branches / 88.94% functions / 90.90% lines; build and asset validation passed; audit reported 1 low and 1 moderate vulnerability below the high threshold. |
+| GitHub Actions          | Pending | `verify` is running for head `3bf4ce1`; CodeRabbit skipped review because the PR is draft.                                                                                                                          |
+
+## Publication status
+
+The three verified commits `5449b89`, `35ebc28`, and `3bf4ce1` are pushed to `origin/feature/issue-24-agent-integration-assets`. The PR description is updated and PR #33 remains draft. GitHub Actions is the only remaining remote check.
+
+## Deferred human gate
+
+The Claude Code live smoke test cannot be performed in this environment because Claude Code is unavailable. This is recorded as an unresolved acceptance item, not as a successful test. The implementation and automated validation work may be complete while this human gate remains visibly deferred and PR #33 remains draft.