feat: add Codex integration stack surfaces

[Boulea7]

Summary

• add the first Codex integration stack surfaces: MCP wiring, hook assets, skills, integrations orchestration, and retrieval MCP server
• sync the Codex-first Hybrid documentation and workflow contract wording to match the new surfaces
• tighten release-facing workflow contract and blocked-apply readiness semantics for the integration layer

Test plan

• pnpm test:docs-contract
• pnpm vitest run test/hooks-command.test.ts test/integrations-command.test.ts test/mcp-command.test.ts test/skills-command.test.ts test/recall-command.test.ts
• pnpm build && pnpm test:dist-cli-smoke && pnpm pack:check && pnpm test:tarball-install-smoke

Notes

• This is PR 2 of the issue5 stack.
• Base branch is pr/issue5-01-foundation so review stays focused on the integration layer only.

---

Summary by cubic

Adds Codex integration stack surfaces with read‑only retrieval via CLI and a local MCP server, plus new retrieval health checks, a sidecar index with reindexing, and a manual mutation reviewer. Docs shift to a Codex‑first Hybrid model with safety‑gated guidance and tighter workflow/release contracts; the wrapper path stays primary.

• New Features

  • Retrieval: cam recall (search|timeline|details) with the recommended preset (state=auto, limit=8); local MCP server (cam mcp serve) exposes search_memories, timeline_memories, get_memory_details via @modelcontextprotocol/sdk. Adds a retrieval sidecar index and cam memory reindex (reports lineage/reviewer warnings). Doctor now surfaces retrieval health and repair hints. All surfaces support structured JSON for integrations.
  • MCP config: cam mcp (print-config|install|doctor|apply-guidance) with project‑scoped installs for hosts (codex, claude, gemini, generic); doctor validates canonical server config, route truth, and project pinning; print-config supports manual wiring for generic.
  • Integrations: cam integrations (install|apply|doctor) with safety‑gated AGENTS.md apply, clear fallback semantics, a route summary, and next steps.
  • Hooks/Skills: cam hooks install pins capture/recall helper versions, installs a local bridge bundle and retrieval sidecar index; cam skills install --surface <runtime|official-user|official-project> installs Codex skill assets.
  • Manual mutation reviewer: cam remember/cam forget produce review entries and follow‑up guidance, with lifecycle classification and safe text helpers.
  • Contracts/Docs/Tests: durable sync is gated to primary rollouts; startup continuity provenance and low‑signal guards are tightened; extraction trust and directive parsing are hardened; new docs/host-surfaces.md, docs/host-integration-claude-gemini.md, docs/integration-strategy.md, and AGENTS.md; release checklist tightened; expanded tests for new commands and contracts.

• Migration

  • No breaking changes; wrapper + Markdown store remain the primary path.
  • MCP retrieval: cam mcp install --host codex → cam mcp doctor → cam mcp serve.
  • Integrations: cam integrations install → cam integrations doctor → cam integrations apply (safety‑gated).
  • Optional: cam hooks install; cam skills install --surface <runtime|official-user|official-project>; cam memory reindex.
  • Query: cam recall search (uses the recommended preset by default).

^{Written for commit b70d256. Summary will update on new commits.}

[sourcery-ai]

Sorry @Boulea7, your pull request is larger than the review limit of 150000 diff characters

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cb133eac-2434-4d0d-8665-08123a6f38c7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pr/issue5-02-integration-foundation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

6 issues found across 48 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="test/skills-command.test.ts">

<violation number="1" location="test/skills-command.test.ts:18">
P2: Teardown does not correctly restore an originally unset `HOME` environment variable.</violation>
</file>

<file name="src/lib/integration/retrieval-contract.ts">

<violation number="1" location="src/lib/integration/retrieval-contract.ts:113">
P2: `appendCliCwdFlag` uses JSON escaping for shell command construction, which can allow shell expansion (`$...`, `$(...)`) in `--cwd` values.</violation>
</file>

<file name="test/integrations-command.test.ts">

<violation number="1" location="test/integrations-command.test.ts:67">
P2: Restore `HOME` with delete-on-undefined semantics; direct assignment can leave an invalid env value when HOME was originally unset.</violation>
</file>

<file name="docs/claude-reference.en.md">

<violation number="1" location="docs/claude-reference.en.md:95">
P2: Section 6 heading is duplicated with section 7, but section 6 content is actually about `autoMemoryDirectory` config-safety boundaries.</violation>
</file>

<file name="test/recall-command.test.ts">

<violation number="1" location="test/recall-command.test.ts:23">
P2: Teardown incorrectly restores HOME when it was originally unset; assigning `undefined` to `process.env.HOME` produces the literal string `"undefined"` instead of removing the variable.</violation>
</file>

<file name="docs/native-migration.md">

<violation number="1" location="docs/native-migration.md:6">
P2: This Chinese-side scope rewrite is not mirrored in the English counterpart, creating cross-language contract drift for a core design doc.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}