Copyable, same-machine, and truthful

Use this pack when you want the shortest honest path into a local coding host.

This pack does not invent a hosted platform story. It packages what the repository already ships today: deterministic CLI reads, an advisory AI Diagnose layer, a token-gated same-machine Local Web API, and a stdio-first, read-only-first MCP surface.

Before you wire any host

  1. Review config/notes_snapshot.env so the repo knows where snapshots and state should live.
  2. Run ./notesctl run --no-status at least once so Apple Notes permissions and the first local state record exist.
  3. Run ./notesctl verify and ./notesctl doctor --json so your host is reading real local state, not a first-run missing-state wrapper.
  4. Choose the builder lane that matches your workflow shape: CLI, Local Web API, AI Diagnose, or MCP.

Capability matrix

Surface Start with Transport Best fit Safe contract today Not claimed
CLI ./notesctl status --json, doctor --json, verify, aggregate --tail N Local process Deterministic reads, scripts, and first troubleshooting Canonical human and builder entrypoint No hosted API contract
AI Diagnose ./notesctl ai-diagnose --json Local process plus a local Switchyard runtime call when enabled Calmer operator explanation around the same local facts Advisory only; reads status, doctor, log-health, and recent-run summaries, then asks Switchyard for model output No system-of-record role, no note-content analysis in v1, no direct provider credentials in this repo
Local Web API ./notesctl web --host 127.0.0.1 --port 8080 Same-machine HTTP behind a token gate Browser-backed local tooling and local HTTP consumers Read endpoints plus access-policy reads are the safest builder contract today No public OpenAPI, no hosted API, no default remote exposure
MCP ./notesctl mcp Stdio MCP MCP-aware hosts that can launch a local stdio server Read-only tools and resources over the same repo-owned state No remote HTTP MCP, no write-capable MCP tools in v1

Host status matrix

Read the proof column like a safety label: repo-side proven means the repository itself proves the contract, attach-proven means a named host attach was freshly proven on a real host session in this round, host-side verify required means the repo ships the wiring kit but your machine still has to attach successfully, template-only means the repo ships a starting shape without named-host proof, and comparison-only means the repo is only drawing a boundary rather than claiming compatibility.

Host or workflow Repo-owned pack today Proof level Repo-owned starting point Copyable asset here What you still verify on the host side
Generic MCP-aware host Generic MCP pack Repo-side proven /absolute/path/to/notesctl + mcp Generic stdio MCP config That the host can launch a local stdio server and expose tools/resources
Codex Starter pack plus the generic MCP path Attach-proven on the current host build; still recheck on another machine codex mcp add apple-notes-snapshot -- /absolute/path/to/notesctl mcp Codex starter pack and Codex add command The current Codex-side registration flow, trusted-project handling, and any extra host options from the latest Codex config docs on another machine
Claude Code Starter pack plus the generic MCP path Attach proven on the current host build; still verify on another machine Project or user MCP registration that points to /absolute/path/to/notesctl and mcp Claude Code starter pack, project example, and user example Whether you want project-scoped or user-scoped registration in the current Claude Code release; this repo already proved a live attach on the current host build
OpenCode Template only Template only Local MCP server entry that points to /absolute/path/to/notesctl and mcp OpenCode template The current OpenCode config location and whether attach succeeds in your host build
OpenHands Comparison and generic MCP guidance only Comparison-only Start from the generic stdio MCP launch shape, then map it into the current host docs Generic stdio MCP config The exact OpenHands config surface, attach flow, and whether the current host build exposes the same MCP affordances
OpenClaw OpenClaw MCP registry path Attach-proven on the current host build; still recheck on another machine openclaw mcp set apple-notes-snapshot '{"command":"/absolute/path/to/notesctl","args":["mcp"]}' OpenClaw add command and OpenClaw MCP payload The current OpenClaw config location, provider wiring, and whether another host build still exposes the expected tools/resources; the official CLI has already written, read back, and locally attached to the MCP config on the current machine.
Browser-backed or HTTP-shaped local tool Yes Repo-side proven for same-machine reads ./notesctl web plus a local token Local Web API env example and curl example That you keep the surface same-machine, token-gated, and loopback-first

Repo proof vs host-side proof

  • Repo-side already proven here: the CLI contract, the same-machine Local Web API contract, the stdio MCP launch shape, and the current read-only tool/resource surface.
  • Named-host status today: Claude Code, Codex, and OpenClaw now all have fresh attach proof on the current host build; OpenCode stays template-only and OpenHands stays comparison-only.
  • Host-side still yours to verify on another machine: where your host stores config, whether attach succeeds in that host build, and any extra host-specific options or UI steps outside the current verified machine.
  • Truthful attach rule: keep OpenCode template-only and OpenHands comparison-only, and do not generalize one fresh named-host proof into a universal guarantee for every machine or release.

What counts as a stronger proof level

  • To move from template-only to host-side verify required: the repo needs a concrete setup file or install path that maps cleanly onto the host.
  • To move from host-side verify required to attach-proven: the repo needs a fresh named-host attach proof in the current round.
  • To move from host-side verify required to repo-side proven: the repo needs fresh attach proof that survives a repo-owned verification pass without hand-wavy gaps.
  • To stay comparison-only: mention the host only to stop overclaiming, not to imply a plugin, gateway, or dedicated adapter exists.

Starter packs and public skills

  • Codex starter pack: use the dedicated Codex page when you want the project-scoped install surface and trusted-project reminder in one place.
  • Claude Code starter pack: use the dedicated Claude Code page when you want the project-scoped versus user-scoped registration story in one place.
  • OpenClaw starter pack: use the dedicated OpenClaw page when you want the narrow MCP registry path instead of translating the shared matrix by hand.
  • Public skills pack: use the curated public-safe subset when you want reusable prompt, contract, and runtime-resource-hygiene rules without copying the repo-local .agents/skills tree.

Need a machine-readable inventory instead of reading the matrix by hand? Use the builder contract manifest. It packages the current builder surfaces, host proof levels, help entrypoints, and copyable assets into one repo-owned artifact.

Need the plugin-grade bundle files? Use the root marketplace files for Codex and Claude Code, then open the control-room bundle.

Plugin-like package inventory

Package surface Best fit What it gives you Still not claimed
Codex starter pack Project-scoped Codex setup Install path, trust boundary, attach path, verify path, update story, and a repo-owned local plugin bundle No official Codex directory listing or attach-proof on every host build
Claude Code starter pack Project-scoped or user-scoped Claude setup Registration choices, attach path, verify path, update story, a repo-owned local marketplace/plugin bundle, and a fresh attach proof on the current host build No official Anthropic listing claim or universal attach proof on every machine
OpenClaw starter pack OpenClaw MCP registry path and bundle-compatible host prep Registry payload, set command, verify path, truthful ClawHub boundary, and a fresh named-host attach proof on the current host build No ClawHub listing and no universal attach proof on every machine
Public skills pack Repo-scoped instruction reuse Public-safe prompt/contract rules that pair with builder hosts No raw `.agents/skills/` export and no host-native plugin claim
Generic MCP examples Any host that speaks stdio MCP Launch shape, checklist, and same-machine contract No hosted runtime, no remote MCP, no write-capable automation platform

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

Quick verification after attach

  1. If you attached through MCP, confirm the host sees get_status, run_doctor, verify_freshness, get_log_health, list_recent_runs, and get_access_policy.
  2. Read notes-snapshot://recent-runs or call get_status. If the repo has never completed a first run, the truthful result may be a missing-state wrapper instead of live snapshot data.
  3. If you attached through the Local Web API, start with /api/status, /api/recent-runs, and /api/access before you assume any action route is part of your stable builder contract.

Need the short repo-owned checklist? Use post-attach-checklist.md.

Copyable repo-owned examples

What this pack does not claim

  • No public OpenAPI or generated SDK
  • No hosted MCP or write-capable remote agent platform
  • No OpenClaw-style front-door positioning
  • No promise that every MCP-aware host is already attach-verified in this repo

Pair this pack with official host docs

The repository owns the Apple Notes Snapshot side of the contract. Host-side menus, config locations, and advanced options can change faster than this repo does, so pair the examples above with the current host docs when you register the server.