feat(adk): the operator runbook and starter kit, first cut (ADK item 5; R1, R2, R7)

[LamaSu]

ADK item 5: the operator runbook and starter kit (first cut)

This covers the operator's R1 ("a complete runbook, device to verified kernel, against the current code"), R2 ("the agent asks only what it can't do or find"), and the pack side of R7 (report every phase). It is a starter kit that three runtimes load: Claude Code (CLAUDE.md), Codex (AGENTS.md) and PCC's hosted agent (item 14). It lives in starter/ until the operator picks its public repo.

What's in it

Path	What
starter/runbook/	Ten phases: prerequisites, identify, intake, research, build, register, verify, operate, publish, session. Each has a goal, exact commands, done-when checks, the only questions to ask, and a report call. runbook.json is the machine-readable graph, and its phases are painpoints' contract v1 enum.
starter/runbook/index.json	R6: 22 events keyed <phase>.<event> ("don't know", a 4xx on register, the e-stop set, a leaked key…), each with what to do, the runbook section, and what to report.
starter/bin/pcc-report	Reports each phase in contract v1. It persists sessionId and seq, redacts on the client side, sends no transcript, builds the session roll-up from local logs, and never blocks the onboarding. Stdlib only.
starter/CLAUDE.md, starter/AGENTS.md	The same rules for both harnesses.

The participant-facing starter/README.md is pcc-launch's, in its own PR from master (item 5 is split by file).
| starter/.gitignore | .pcc/, which holds this attempt's secrets (mode 600) and state. |

How it was grounded

• The path is R0's. Every command follows the path rehearsal R0 proved against a master gateway: provision → kernel → capability → device → a buyer job via submit-from-discovery → the node's evidence-then-status finish.
• The routes are master's. Each route and body was checked in master's code (the pack has excerpts).
• Known gaps say so. Each one reads "on the current code" with the workaround, and "coming" with the change that closes it: fix(pcc-node): announce capabilities through the heartbeat, not the store-nothing stub #390, fix(gateway): setup test-job exercises the operator's own machine or says it did not (N59, ADK item 8) #450, fix(pcc-node): keys live under ~/.pcc-node, owner-only; the node honours the emergency stop (item 9) #454, feat(gateway): operator status derives readiness from canonical rows (ADK D4(a)) #428, item 12, sensors' R8, kits' intake and research, economics' split.

Safety lines it holds

• Gateway: use only the one you were given, and never call production unless told to.
• Secrets: only in .pcc/ (0600), and never printed. The node's private key is made locally and never sent (provisioning sends publicKey). curl sends the API key from .pcc/auth.header (-H @file), so no command line carries it for ps to show. Provisioning output goes straight to a file, since it includes a private key.
• Money and safety are never defaulted. The safety envelope is drafted from cited sources and confirmed once by the human.
• Typed operations only. A job's raw parameters never reach the device (bus #4121).
• No false "verified". test-job is not used as proof, prove is self-attestation, and a by-hand run is stored unverified until the operating agent's signed evidence arrives (D4a, feat(gateway): operator status derives readiness from canonical rows (ADK D4(a)) #428).

Tests (stdlib unittest, 25)

• 10 for pcc-report: redaction, seq, the contract body, the roll-up, a real POST to a local server, and an unreachable gateway.
• 15 guards for the runbook:
  • the phase graph, and every phase reporting;
  • no curl to production;
  • pcc-node[crypto] with a version or a pinned SHA;
  • pcc_job_complete and test-job only as warnings;
  • provisioning written to .pcc/;
  • .pcc/ git-ignored;
  • no key expanded onto a command line, and every authenticated call sends -H @.pcc/… (mutation-checked);
  • every provisioning call sends its own publicKey (mutation-checked);
  • the index: keys match phases, every section is a real heading, and reports use the contract (mutation-checked).

Run: python3 -m unittest discover -s starter/bin -p 'test_*.py'.

Commits after the first cut:

• 0d3910b: what master's /api/feedback keeps (summary and detail) until painpoints' feat(gateway): attempt reports on /api/feedback (ADK track item 3) #458;
• 19b566a: a manual channel instead of a file one;
• e2b09e1: the key in a header file;
• f70604d: pcc-report also scrubs PEM keys, base64 keys and secret-named fields;
• 27f7346: recovering from a placeholder node key;
• 81eb9fc: the top-level README goes to pcc-launch;
• 61343d7: the R6 event index;
• 9b54a22: rehearsal R0's P9. Phase 0 makes the node key locally and provisions with its public half, so no response carries a private key.

Next: R1 (10-08) exercises it end to end, and the final cut is due 10-15.

🤖 Generated with Claude Code