Record beside the agent. Never as the broker.

Install the local Runbook MCP next to your coding agent. Server v0.4.5 · 45 closed tools: discovery, six ledger writers/readers, seven offline analysis tools, six shadow self-improvement tools, thirteen control-plane session tools, and eleven elite process tools. Preflight is deterministic and advisory. A direct brokerage tool can always bypass Runbook—so the first pilot stays disconnected.

Surface lock · static cockpit display

runbook v0.4.5 · 45 tools · attests Runbook only

toolCount45

brokerExecutionTools[] empty

openWorldHintfalse

attestsRunbook only

hasPlaceOrCancelToolsfalse

brokerEffectfalse

Closed Runbook surface: 45 tools, brokerExecutionTools=[], openWorldHint=false. Attests Runbook inventory only — not host MCP set. Not a hard gateway.

runbook-surface-only-not-host-inventory
not-broker-authorization
not-proof-host-has-no-other-mcps
static-cockpit-display-not-live-receipt

Golden journey checklist

Steps agents should take · 0/6

Read the boundary
Load runbook://docs/boundary (or prompt runbook_explain_boundary). No credentials. No trades. Advisory only.
runbook://docs/boundary
Create equity-only experiment
runbook_create_experiment with approvalRequired true and instruments limited to equity.
runbook_create_experiment
Preflight a synthetic proposal
runbook_preflight_trade with caller-supplied position, drawdown, and trade-count fields — not broker truth.
runbook_preflight_trade
Hard stop (day-1 shadow)
Do not call runbook_record_approval or runbook_record_execution unless the human operator explicitly requests it.
HARD STOP
Verify the ledger
runbook_verify_ledger — local tamper evidence only. Anyone who rewrites the whole file can recompute the chain.
runbook_verify_ledger
Run pilot-doctor
Offline readiness. Assurance is local-attestation-and-ledger-only — not system-wide broker absence.
runbook_pilot_doctor

Install in Codex

Wire the local server

From the repository root. The server defaults to ~/.runbook/events.jsonl. Point RUNBOOK_DATA_DIR only at a private absolute path outside synced folders.

pnpm setup:elite
# or: pnpm install && pnpm --filter @runbook/mcp build
codex mcp add runbook -- node "$PWD/packages/mcp/dist/server.js"
codex mcp list

Start a new Codex task after adding the server so tools are discovered. Remove later with codex mcp remove runbook. Never put broker credentials in tool arguments, event notes, environment values intended for logs, or the ledger.

{
  "name": "runbook_preflight_trade",
  "arguments": {
    "experimentId": "RUN-SHADOW-001",
    "proposalId": "proposal-vti-001",
    "symbol": "VTI",
    "instrument": "equity",
    "side": "buy",
    "notional": 100,
    "projectedPositionNotional": 100,
    "dailyTradesAfter": 1,
    "currentDrawdownPercent": 0.6,
    "hasThesis": true,
    "hasInvalidation": true,
    "evidenceSourceCount": 2,
    "idempotencyKey": "preflight-vti-001"
  }
}

Full tool inventory · 45 tools

1 discovery + 6 ledger + 7 offline + 6 shadow + 13 session + 7 elite · broker effect: none

Operator docs: packages/mcp/OPERATOR_GUIDE.md. 45 closed tools; brokerEffect always false.

Tool	Lane	Effect	Assurance
`runbook_list_surface`	discovery	Closed inventory of tools, resources, prompts	local-discovery-only
`runbook_create_experiment`	ledger	Records experiment + charter v1	local-ledger-write
`runbook_preflight_trade`	ledger	Records proposal + advisory checks	advisory-caller-supplied-state
`runbook_record_approval`	ledger	Caller-asserted human decision (unauthenticated)	caller-owned-observation-only
`runbook_record_execution`	ledger	Imports owner-controlled fill data	caller-owned-observation-only
`runbook_list_events`	ledger	Reads local ledger events	local-ledger-read
`runbook_verify_ledger`	ledger	Verifies sequence, idempotency, hash chain	local-tamper-evidence-only
`runbook_verify_capsule`	offline	Offline capsule verify	self-asserted-author-key-integrity
`runbook_verify_capability_snapshot`	offline	Offline snapshot verify	offline-reviewed-claim-analysis
`runbook_diff_capabilities`	offline	Offline capability diff	offline-reviewed-claim-analysis
`runbook_admit_capabilities`	offline	Offline admission analysis (no head mutation)	offline-reviewed-claim-analysis
`runbook_inspect_public_auth_metadata`	offline	Offline public-auth parse	offline-fixture-or-operator-capture-analysis
`runbook_pilot_doctor`	offline	Shadow pilot readiness check	local-attestation-and-ledger-only
`runbook_export_public_snapshot`	offline	Metadata-only public export	local-ledger-read
`runbook_run_shadow_curriculum`	shadow	Multi-axis synthetic curriculum report	synthetic-curriculum-process-quality-only
`runbook_improve_charter`	shadow	Recursive offline refinement (no ledger write)	synthetic-curriculum-process-quality-only
`runbook_shadow_tournament`	shadow	Multi-charter Pareto front (weak + elite + mutants)	synthetic-curriculum-process-quality-only
`runbook_activate_refined_charter`	shadow	Explicit charter.activated append	local-ledger-write
`runbook_agent_eval`	shadow	Local ledger process axes (not trading performance)	process-observation-only
`runbook_expand_curriculum_from_ledger`	shadow	Ledger-derived synthetic deny scenarios	ledger-derived-synthetic-process-labels-only
`runbook_session_create`	session	Create local control-plane session	local-session-only
`runbook_session_use`	session	Mark active session (local marker only)	local-session-only
`runbook_session_get`	session	Read control-plane session by id	local-session-only
`runbook_session_export`	session	Export session evidence pack	local-control-plane-export-only
`runbook_session_set_charter`	session	Bind advisory charter + digest	local-session-only
`runbook_session_pin_inventory`	session	Pin admitted tool inventory	local-session-only
`runbook_session_check_inventory`	session	Fail-closed observed tools vs pin	local-session-only
`runbook_session_import_tools_list`	session	Import local tools/list JSON and check vs pin	local-session-only
`runbook_session_bind_experiment`	session	Bind local ledger experimentId (+ optional head hash)	local-session-only
`runbook_session_attach_dossier`	session	Attach architecture dossier evidence	architecture-evidence-not-certification
`runbook_session_record_shadow`	session	Record shadow hardFalse metrics	synthetic-curriculum-process-quality-only
`runbook_approval_create_signed`	session	Ephemeral Ed25519 approval intent	local-device-key-attestation-only
`runbook_approval_verify`	session	Verify signed approval intent	local-device-key-attestation-only
`runbook_surface_lock_receipt`	elite	Digest closed TOOL_NAMES + version attestation	runbook-surface-only-not-host-inventory
`runbook_process_tick`	elite	Supervisor tick: inventory + dual-eval → proceed\|warn\|stop	process-layer-not-hard-gateway
`runbook_session_import_pack`	elite	Import session evidence pack JSON	local-session-only
`runbook_session_seal_capsule`	elite	Seal session as synthetic .runbook capsule	self-asserted-author-key-only
`runbook_drift_sentinel`	elite	tools/list + pin fail-closed drift receipt	operator-provided-not-runtime-confirmed
`runbook_session_clone_challenge`	elite	Clone session with charter challenge mutation	local-session-only
`runbook_dual_check_diff`	elite	Check-by-check ledger vs session charter theater	process-layer-not-capital-risk-grade
`runbook_session_attach_surface_lock`	elite	Attach surface lock receipt as session operator-note	architecture-evidence-not-certification
`runbook_gateway_quorum_demo`	elite	Local gateway quorum authorize/deny/replay theater	local-policy-theater-only
`runbook_session_list_process_ticks`	elite	List process_tick ring buffer (last 64)	local-session-only
`runbook_operator_scenario_eval`	elite	Closed curriculum + operator scenarios → HFA/HFD	synthetic-curriculum-process-quality-only
`runbook_session_process_health`	elite	Multi-axis process health (ticks + shadow HFA)	process-observation-not-composite-grade

MCP annotations are descriptive, not authorization. runbook_record_approval requires actor type human but every argument is caller-supplied—an agent can claim human authority. Execution evidence always reports humanAuthorityEstablished: false. Offline tools never mutate a durable registry head or establish a broker session.

Discovery resources

Boundary + assurance first

runbook://docs/boundaryHard safety boundary: no credentials, no trades, advisory only.
runbook://docs/tool-contractMachine-readable tool effects and brokerEffect flags.
runbook://docs/assuranceSeparate assurance axes. Composite scores prohibited.
runbook://docs/robinhood-agentic-contractDated public-doc research map. Not live inventory.
runbook://schemas/shadow-pilot-manifestStrict shadow-pilot.v1 manifest schema.
runbook://examples/shadow-pilot.manifestDisconnected zero-capital example.
runbook://examples/equity-only-charter-policyEquity-only charter policy sample.
runbook://ledger/verificationCurrent local ledger verification summary.

Offline fixture demos

Closed catalog cards

Diff 45 → 50Documentation delta · five observation tools

Compare registry.trading-45 vs registry.trading-50 via runbook_diff_capabilities. Exercises fail-closed drift — not a historical runtime claim.

{
  "name": "runbook_diff_capabilities",
  "arguments": {
    "leftFixtureId": "registry.trading-45",
    "rightFixtureId": "registry.trading-50"
  }
}

Reject risk-correctionReject · unknownRiskDecision: reject

Admit registry.trading-50-risk-correction against the public-docs-review-required policy. Active head does not advance.

{
  "name": "runbook_admit_capabilities",
  "arguments": {
    "snapshotFixtureId": "registry.trading-50-risk-correction",
    "policyFixtureId": "registry.policy.public-docs-review-required"
  }
}

Capsule twinValid root · invalid tampered twin

Verify capsule.minimal-root (valid) then capsule.minimal-tampered (payload tamper). Integrity relative to self-asserted author key only.

{
  "name": "runbook_verify_capsule",
  "arguments": {
    "fixtureId": "capsule.minimal-root"
  }
}

Owned-data bridge

Paste a public snapshot

Validate runbook.public-snapshot.v1 locally with the same strict schema used by Trust Center. Metadata only—no payloads, actor IDs, symbols, or notionals. Limit 2,097,152 bytes. No upload.

Shadow pilot doctor

Offline readiness CLI

pilot-doctor is a deterministic offline readiness check. It does not call Robinhood, inspect a remote MCP, authenticate, move capital, or execute an order. A pass means local-attestation-and-ledger-only—not system-wide broker absence.

export RUNBOOK_SHADOW_DATA_DIR="$HOME/.runbook-shadow-pilot"
pnpm --filter @runbook/mcp build
node packages/mcp/dist/cli.js pilot-doctor \
  packages/mcp/examples/shadow-pilot.manifest.json \
  --data-dir "$RUNBOOK_SHADOW_DATA_DIR" \
  --ledger-id shadow-pilot \
  --workspace-root "$PWD"

Export a metadata snapshot after a valid ledger with node packages/mcp/dist/cli.js export-public RUN-001, then paste it above or in Trust Center.

Experiment builder Control Room Shadow Process Lab Trust center Capability registry

“Allowed” on preflight means the submitted proposal passed recorded charter checks. It does not mean an account-wide control prevented other actions. Human confirmation must remain enabled and independently performed at the broker. This page never establishes a live broker session.