Integration Pack | Apple Notes Snapshot

Before you wire any host

Review config/notes_snapshot.env so the repo knows where snapshots and state should live.
Run ./notesctl run --no-status at least once so Apple Notes permissions and the first local state record exist.
Run ./notesctl verify and ./notesctl doctor --json so your host is reading real local state, not a first-run missing-state wrapper.
Choose the host surface 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`	Host-local 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 the repo keeps a tagged named-host attach-proof trail, 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	Tagged host proof in v0.1.12; 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	Tagged host proof in v0.1.12; 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, and whether the host still matches the tagged v0.1.12 proof on your machine
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	Tagged host proof in v0.1.12; 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; use the tagged v0.1.12 proof as the last verified baseline, not as a universal guarantee.
Browser-backed or HTTP-shaped local tool	Yes	Repo-side proven for host-local reads	`./notesctl web` plus a local token	Local Web API env example and curl example	That you keep the surface host-local, token-gated, and loopback-first

Repo proof vs host-side proof

Repo-side already proven here: the CLI contract, the Local Web API contract for this Mac, the stdio MCP launch shape, and the current read-only tool/resource surface.
Named-host status today: Claude Code, Codex, and OpenClaw each have a tagged host-proof trail in v0.1.12; 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 tagged named-host proof trail 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 tagged named-host attach-proof trail it can point to without flattening machine-local verification.
To move from host-side verify required to repo-side proven: the repo needs attach evidence 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 repo-owned submit metadata for the standalone public skill packet? Use the public skill manifest. It keeps the live ClawHub listing truth and the still-not-accepted OpenHands lane next to SKILL.md without treating either surface as universal attach proof.

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 tagged host-proof trail in v0.1.12	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 tagged host-proof trail in v0.1.12	No universal attach proof on every machine and no repo-owned promise that every OpenClaw build already attaches the same way
Public skills pack	Repo-scoped instruction reuse	Public-safe prompt/contract rules plus a repo-owned listing manifest for the standalone skill packet	No raw `.agents/skills/` export and no host-native plugin claim
Generic MCP examples	Any host that speaks stdio MCP	Launch shape, checklist, and host-local 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 Diagnose contract

Quick verification after attach

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.
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.
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.

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