Builder lane, still downstream of the control room

Give local coding hosts the same backup facts as a human operator.

The project is not a hosted agent platform. It is a local Apple Notes backup control room with three truthful builder surfaces: a token-gated same-machine Local Web API, an advisory AI diagnosis sidecar, and a stdio-first, read-only-first MCP provider.

Step 1 Understand the control room.

Builder work starts from the deterministic CLI and state ledger, not from agent marketing language.

Step 2 Read the proof page.

Check what the repo itself proves, what GitHub proves, and what still belongs to your host.

Step 3 Choose the right builder surface.

Local Web API, AI Diagnose, and MCP each solve a different problem. This page exists to keep them separate.

Read this after the operator story makes sense

Start with the quickstart, the compare page, or the proof page if you still need the control-room contract first. This page is the builder second lane, not the first thing every visitor needs to open.

Proof legend before you call a host supported

  • Repo-side proven: this repository ships and verifies the underlying contract itself.
  • Attach-proven: a named host attach was freshly proven on a real host session in this round, though another machine may still need its own local verification.
  • Host-side verify required: the repo contract is ready, but the last attach proof still belongs to the host on your machine.
  • Template-only: this repo gives you a starting file or pattern, not attach proof.
  • Comparison-only: this repo mentions the host only to mark scope and avoid overclaiming.

Read this legend first, then use the Builder Integration Pack or the host-specific starter packs so you do not accidentally upgrade guidance into a support claim.

Host proof levels at a glance

Host or workflow Proof level What that means today
Generic MCP-aware host Repo-side proven The stdio launch shape, tools, resources, and help contract are repo-owned truth here.
Codex Attach-proven The starter pack is productized and copyable, and a fresh Codex attach proof now exists on the current host build without turning that into a universal claim for every machine.
Claude Code Attach-proven The starter pack is productized and copyable, and a fresh Claude Code attach proof now exists on the current host build without turning that into a universal claim for every machine.
OpenCode Template-only There is a truthful local template, but not repo-owned attach proof.
OpenHands Comparison-only Use the current MCP launch shape as a reference, not as a repo-owned integration claim.
OpenClaw Attach-proven The repo now ships an MCP registry starting point, and a fresh OpenClaw attach proof now exists on the current host build without turning that into a universal claim for every machine.

Current builder entry points you can trust

  • Deterministic CLI reads: ./notesctl status --json, ./notesctl doctor --json, ./notesctl log-health --json, and ./notesctl aggregate --tail N
  • Token-gated local browser/API lane: ./notesctl web when your local workflow wants the Web console plus the same-machine JSON endpoints behind a local token gate
  • Advisory CLI layer: ./notesctl ai-diagnose --json when you want a calmer explanation around the same local facts
  • Agent substrate: ./notesctl mcp when your host can launch stdio MCP servers

Treat these as the truthful builder entry points today. This repository does not claim a hosted runtime, a public OpenAPI, or a generated SDK surface yet, even if your host is Codex or Claude Code.

Want the shortest evidence trail behind those claims first? Open the proof page, then come back here for the host matrix and copyable setup surfaces.

Need the copy-paste pack?

Open the Builder Integration Pack when you want one page with the capability matrix, same-machine contract, host status table, repo-owned copyable examples, and a short post-attach checklist that separates repo-side proof from host-side proof.

Need the host-specific install surface instead of the shared matrix? Open the Codex starter pack or the Claude Code starter pack. Need the shortest OpenClaw MCP registry path? Open the OpenClaw starter pack. Need the curated public-safe instruction subset? Open the public skills pack.

Need the same contract in a machine-readable shape instead of reading every page by hand? Use the builder contract manifest. It snapshots the current builder surfaces, proof levels, help entrypoints, and copyable assets without pretending the repo already ships an SDK or hosted platform layer.

Need the plugin-grade bundle files themselves? Open the control-room plugin bundle and the root marketplace files for Codex and Claude Code.

Exact repo-owned help entrypoints

  • ./notesctl help mcp for the narrow MCP contract
  • ./notesctl help web for the browser plus Local Web API contract
  • ./notesctl help audit for token, scope, allowlist, readonly, and rate-limit rules
  • ./notesctl help ai-diagnose for the advisory AI sidecar contract

Minimal stdio launch shape

If your local host can launch stdio MCP servers, the minimal launch contract is just the repo-owned entrypoint plus mcp. 

{
  "command": "/absolute/path/to/notesctl",
  "args": ["mcp"]
}

That is the narrow, truthful claim. Hosts differ in how they store this config, so this page documents the launch shape rather than pretending there is one universal agent setup file.

What this repository does not claim

  • No hosted agent runtime
  • No write-capable MCP surface in v1
  • No public OpenAPI or generated SDK surface today
  • No content-level AI, note QA, or semantic-search product positioning

Where to start

  • Read Builder Integration Pack if you want the copyable host matrix and setup examples first
  • Read Codex Starter Pack if you want the narrow project-scoped Codex setup surface
  • Read Claude Code Starter Pack if you want the project-scoped versus user-scoped Claude setup surface
  • Read OpenClaw Starter Pack if you want the narrow MCP registry path for OpenClaw
  • Read Public Skills Pack if you want the public-safe guidance subset instead of the repo-local .agents/skills/ tree
  • Read Local Web API if you want the browser-backed local HTTP surface
  • Read AI Diagnose if you want the operator explanation layer
  • Read MCP Provider if you want the agent-facing contract
  • Read Quickstart if you still need the first successful snapshot path before adding any AI or agent surface