---
name: brain-integrate
description: Connect an existing repository and its coding agent to the hosted Brain MCP, integrate cited Context at the correct application seam, verify Records and failure states, optionally add idempotent writes, run application tests and Brain doctor, repair failures, and produce or resume a machine-readable integration receipt. Use for new Brain customer onboarding, migration, MCP setup, citation-aware memory integration, or resuming an incomplete `.brain/integration.json` journey in Codex, Claude Code, Cursor, or another coding agent.
---

# Integrate Brain

Use the customer's existing agent and application. Do not create another agent framework, memory
store, retrieval path, or answer system.

## Resume first

1. Run `brain receipt`. If `.brain/integration.json` exists, resume its first non-passing check.
2. Treat `human_action_required` as a precise pause, not a dead end. Report its `repair` and `retry`
   fields verbatim and continue after the user completes that action.
3. Never read, print, copy, or persist `BRAIN_API_KEY`. Check only whether it exists.

Read [references/integration-contract.md](references/integration-contract.md) before changing the
customer application. It defines the response fields and completion checks that must survive.

## Integration loop

1. Run `brain status --json`. Start read-only. Confirm the Brain identity, environment, exact
   scopes, and `context`/`get_record` capabilities.
2. Inspect the repository and locate one decision point where current business context materially
   improves behavior. Keep product synthesis, authority, ownership, and UI in the application.
3. Add one bounded `context` call at that seam. Preserve, without coercion:
   `status`, `citations`, `unknowns`, `conflicts`, `abstained`, `budget`, `cost`, `watermark`,
   Context id, and MCP request id.
4. Handle `processing` as retryable. Never label older evidence current. Handle unknowns,
   conflicts, and abstention as states, not empty strings or transport errors.
5. Resolve at least one returned citation through `get_record`. Keep the citation attached to any
   downstream claim or UI derived from it. Do not infer application authority from a Memory.
6. Exercise invalid-auth, missing-scope, not-found, processing, and empty/unknown states using
   fixtures or the customer's test tenant. Do not pollute a production corpus to manufacture them.
7. Run the repository's own focused tests, then its normal relevant gate. Record the exact command
   as non-secret evidence:
   `brain receipt --set application_tests_green --evidence '<command and result>'`.
8. Run `brain doctor --json --query '<known non-sensitive fact>'`. Repair every agent-repairable
   failure and rerun. Ask the user only for an action marked non-repairable.

## Optional writes

Add `remember` only when the product needs writes and `brain_status` reports `remember: true`.
Require explicit customer approval for this expansion.

Run `brain doctor --json --write-probe` only on a dedicated test Brain. It intentionally stores a
stable synthetic `shareable` Record for idempotent replay and a separate per-run freshness Record
for minimum-watermark read-your-write and citation resolution, without weakening `local_only`.

- Use stable source identity and a stable `idempotency_key` derived from the source record, never a
  random retry token.
- Treat the returned Record as accepted/processing until its state says otherwise.
- Pass the returned watermark to the next `context` call and preserve `processing` until reached.
- Prove replay returns the original Record. Never dual-write indefinitely.
- If writes are unnecessary, record `brain receipt --set not_requested --evidence 'read-only integration'`.

## Completion

Record these checks as they become true: `read_integrated`, `citations_verified`,
`failure_states_verified`, `write_integrated` or `not_requested`, and
`application_tests_green`. The doctor records `doctor` itself.

Then run:

```bash
brain receipt --set complete --evidence 'application tests and Brain doctor green'
brain support-bundle --json
```

The CLI refuses `complete` while a required check is absent. Finish with the receipt path, tests,
Brain doctor result, rollback path, and any intentionally deferred authority or write work.