@cairnkeep/cli 2.14.0 → 2.15.1

package/docs/learning/tracks/operator.md

@@ -2,7 +2,7 @@
 
 **Audience:** advanced users and platform maintainers
 **Prerequisite:** Practitioner track; L13 before operating captured evidence
-**Total time:** about 6 hours 10 minutes
+**Total time:** about 6 hours 45 minutes
 
 1. [L09 - Domain knowledge with RAG](../lessons/L09-domain-knowledge.md)
 2. [L10 - Faster context exploration](../lessons/L10-context-exploration.md)
@@ -15,6 +15,7 @@
 9. [L22 - Operate Cairnkeep on native Windows](../lessons/L22-native-windows.md)
 10. [L23 - Guided setup and Pi memory](../lessons/L23-guided-setup.md)
 11. [L24 - Reviewed knowledge exchange](../lessons/L24-okf-exchange.md)
+12. [L25 - Bounded workflow playbooks](../lessons/L25-playbooks.md)
 
 All modules are optional. The track is complete when the operator can add and
 remove each integration without breaking the standalone local workflow and can
@@ -23,8 +24,10 @@ v2.11 setup/Pi lifecycle only after the earlier storage, governance, trust, and
 native-platform boundaries.
 L24 adds portable exchange only after the immutable-pack and privacy boundaries
 are understood.
+L25 adds policy enforcement and the unauthenticated local actor boundary before
+any future team deployment.
 
 Hands-on spine: `course-04-operation`, `course-06-governance`, and
 `course-07-evaluation`, `course-10-trust-context`, and
-`course-12-guided-setup` in the public
+`course-12-guided-setup`, and `course-13-playbooks` in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/learning/tracks/practitioner.md

@@ -2,7 +2,7 @@
 
 **Audience:** developers adopting Cairnkeep in daily work
 **Prerequisite:** Quickstart track
-**Total time:** about 4 hours
+**Total time:** about 4 hours 35 minutes
 
 1. [L04 - Memory fundamentals](../lessons/L04-memory-fundamentals.md)
 2. [L05 - The daily workflow](../lessons/L05-daily-workflow.md)
@@ -11,11 +11,13 @@
 5. [L07 - Privacy and storage](../lessons/L07-privacy-and-storage.md)
 6. [L08 - Multiple machines](../lessons/L08-multiple-machines.md)
 7. [L13 - Session evidence and hindsight](../lessons/L13-session-evidence.md)
+8. [L25 - Bounded workflow playbooks](../lessons/L25-playbooks.md)
 
 The track is complete when the learner can decide what should become memory,
 review derived knowledge, run governed repository checks, locate the store, and
-perform a reversible backup or migration.
+perform a reversible backup or migration, and distinguish playbook selection
+from execution and approval.
 
 Hands-on spine: `course-02-memory`, `course-03-quality`, and
-`course-05-evidence` in the public
+`course-05-evidence`, and `course-13-playbooks` in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/learning/video-scripts/V25-playbooks.md

@@ -0,0 +1,38 @@
+# V25 - Bounded workflow playbooks
+
+**Companion lesson:** [L25](../lessons/L25-playbooks.md)
+**Target length:** 9 minutes
+
+## Recording outline
+
+1. Open with the boundary: Cairnkeep selects existing workflow actions; the
+   harness remains the agent runtime and every approval remains in force.
+2. Run guided setup in a synthetic project. Show `.ai/playbooks.json` mode and
+   the delimited Cairnkeep block inside an `AGENTS.md` that already has user
+   content.
+3. Compare `minimal`, `balanced`, and `strict` with `cairn playbook status`.
+   Customize one canonical action and show that an arbitrary command or unknown
+   field is rejected.
+4. Run `check start` for a complex unfamiliar task. Explain deterministic
+   signals versus the model-supplied complexity/familiarity assertion.
+5. Run a security-sensitive `check finish --enforce` without evidence and show
+   exit 3. Perform synthetic verification, then re-run with completed and
+   reasoned skipped evidence.
+6. Record one outcome with exact policy and decision digests. Inspect the
+   private receipt and show that changed paths, prompts, source, and output are
+   absent.
+7. Show `/cairn-work` in Claude or OpenCode and the portable `AGENTS.md`
+   guidance for Codex/Qwen. State that adapters route to the same CLI and do not
+   automatically activate skills.
+8. Remove the managed instruction block, prove user instructions remain, and
+   close on the design-only team boundary.
+
+## Recording cautions
+
+- Use only synthetic paths, actors, reasons, and project data.
+- Do not imply that an agent's `completed` assertion proves an action ran;
+  demonstrate the evidence boundary explicitly.
+- Do not describe local actor labels as authenticated identities.
+- Do not claim productivity or quality improvement without a separate measured
+  evaluation.
+- Keep all network-capable optional integrations disabled during the demo.

package/docs/native-windows.md

@@ -32,6 +32,11 @@ recovery contract as POSIX. It writes a restricted `.ai/cairnkeep.json` setup
 record and never syncs machine assets automatically. `cairn bootstrap` remains
 the deterministic compatibility primitive for existing scripts.
 
+Setup also writes private `.ai/playbooks.json` and reconciles Cairnkeep's
+delimited workflow block in `AGENTS.md` without replacing surrounding rules.
+The Node-native `cairn playbook` lifecycle, deterministic enforcement, private
+receipts, and instruction management are identical on Windows and POSIX.
+
 For Codex memory without a harness-wide sync, select only Codex:
 
 ```powershell
@@ -89,6 +94,9 @@ Load completion for the current session:
 Invoke-Expression (& cairn completion powershell | Out-String)
 ```
 
+The completer includes playbook profiles, lifecycle events, canonical actions,
+and check/record options as well as the top-level command.
+
 Place the same expression in `$PROFILE` to load it in future sessions.
 
 ## Storage and permissions
@@ -135,6 +143,10 @@ mutation it creates a timestamped bundle under
 `revert.ps1`. Durable memory and context packs remain unless their separate
 purge flags are supplied.
 
+Uninstall removes only Cairnkeep's managed `AGENTS.md` block and preserves
+surrounding project instructions. Pi and Kimi playbook adapters are handled as
+precisely owned paths alongside their graph adapters.
+
 ## Verification boundary
 
 The release gate runs from `windows-latest` using PowerShell for Node 22, 24,

package/docs/operating.md

@@ -830,6 +830,60 @@ is not an authorization boundary. See [Memory storage and deployment](storage.md
 for the placement rules, client registration, TLS requirements, project headers,
 and backup boundaries.
 
+## Project playbooks
+
+Guided setup and tracked bootstrap create private `.ai/playbooks.json` mode
+`0600` with the `balanced` profile and reconcile a delimited block in the
+project's `AGENTS.md`. `--untracked` bootstrap leaves the shared `AGENTS.md`
+untouched. The policy can select only eight canonical Cairnkeep actions; it
+cannot contain commands, prompts, URLs, or extensions.
+
+```bash
+cairn playbook list
+cairn playbook status --project .
+cairn playbook set strict
+cairn playbook enable review.security must
+cairn playbook disable learning.capture
+cairn playbook reset learning.capture
+```
+
+At task start, use `check start`; after a material risk or scope change, use
+`check check`; before completion, use `check finish`. Supply actual changed
+paths and evidence rather than trusting a model's unsupported claim:
+
+```bash
+cairn playbook check finish --changed src/auth.ts docs/security.md \
+  --risk security --public-change \
+  --completed verify.tests review.repository review.security docs.update \
+  --enforce
+```
+
+Exit 3 means applicable `must` evidence is missing. Exit 2 means the policy has
+diagnostic issues. Otherwise the check succeeded. `should` actions remain
+advisory and should carry a concrete `--skipped ACTION=REASON` when omitted.
+Checking never executes the displayed commands, contacts a service, enables a
+capability, or grants approval.
+
+Material outcomes can be stored with `cairn playbook record` using the exact
+policy and decision digests from the check. Inspect them with `cairn playbook
+receipts list|show`; validate state with `cairn playbook doctor`. Actor and
+session options are provenance labels only: v2.15 does not authenticate them
+and does not provide team ACLs. See [team mode](design/team-mode.md) for the
+future admission contract.
+
+The managed instruction lifecycle is explicit and ownership-safe:
+
+```bash
+cairn playbook instructions check
+cairn playbook instructions install
+cairn playbook instructions remove
+```
+
+Claude and OpenCode receive `/cairn-work`; Pi and Kimi receive corresponding
+thin prompt/Skill adapters when their explicit machine sync runs. Codex and
+Qwen follow the project `AGENTS.md` block. These surfaces route to the same CLI
+and do not create a Cairnkeep-owned agent loop.
+
 ## The workflow
 
 Once installed, the operating layer gives you:

package/docs/privacy-and-data-flow.md

@@ -43,12 +43,35 @@ request unless the corresponding endpoint and credential are configured.
 | Guided project setup | None | Selected scaffold assets and private `.ai/cairnkeep.json` state in the target; machine sync is never automatic |
 | Codex project setup and launcher | None | Local `.codex/config.toml` starts `cairn memory-server` over stdio only after the operator trusts the project |
 | Pi memory extension | None | Local `cairn memory-server` stdio child; no HTTP transport is inherited |
+| Playbook policy check | None | Reads local `.ai/playbooks.json`; returns bounded action IDs, rationales, commands, and digests without executing them |
+| Explicit playbook receipt | None | Private project-local `.agentfs/playbooks/receipts/`; no prompts, source bodies, diffs, credentials, or environment snapshot |
 
 Model endpoints may be local or remote. Cairnkeep cannot determine a provider's
 retention, training, or logging policy; verify it before sending confidential
 material. Disabling `CAIRN_LLM_API_KEY`, `ANYTHINGLLM_API_KEY`, remote HTTP
 registration, and delegated tools keeps the core memory workflow local.
 
+## Playbook decision and receipt flow
+
+Playbooks are local workflow policy, not model inference. A check reads the
+strict project policy, bounded caller signals, changed-path labels, and explicit
+evidence. It deterministically returns applicable canonical actions and policy
+and decision digests. It performs no network request, tool action, capability
+change, approval, or durable-memory promotion.
+
+Only an explicit `cairn playbook record` writes a receipt. The receipt stores
+project identity, digests, event, canonical action, outcome, bounded reason,
+timestamp, and the supplied actor/session labels. It excludes prompt content,
+file content, patches, command output, secrets, endpoint values, and environment
+snapshots. Changed paths influence a decision but are not copied into receipts.
+
+In v2.15, actor identity is an unauthenticated local assertion even when a
+harness supplies it. Do not use receipts for employee monitoring,
+authorization, non-repudiation, or team access decisions. The future
+[team-mode contract](design/team-mode.md) requires authenticated subjects,
+deny-by-default ACLs, tenant isolation, retention, and append-only auditing
+before shared operation can ship.
+
 ## Data at rest
 
 Memories are stored in SQLite databases. They are not encrypted by Cairnkeep at

package/docs/quickstart.md

@@ -69,7 +69,9 @@ result should survive the restart.
 ## What setup owns
 
 `cairn setup` creates only the selected harness assets plus the common `.ai`,
-`.planning`, and `.agentfs` scaffold. It initializes Git only with explicit
+`.planning`, and `.agentfs` scaffold. It also reconciles Cairnkeep's delimited
+playbook block in `AGENTS.md` while preserving every surrounding user byte and
+file mode. It initializes Git only with explicit
 `--git init`, preserves unrelated files, does not overwrite modified files it
 does not own, and records managed digests in private `.ai/cairnkeep.json`.
 
@@ -81,6 +83,20 @@ cairn doctor                                                       # diagnose
 cairn uninstall --dry-run .                                       # preview removal
 ```
 
+The generated balanced policy helps compatible agents decide which existing
+workflow checks apply. Inspect it directly before relying on agent routing:
+
+```bash
+cairn playbook status
+cairn playbook check start --complexity standard --familiarity mixed
+cairn playbook check finish --changed README.md --completed docs.update --enforce
+```
+
+`must` can produce a non-zero enforcement result; `should` is advisory with a
+recorded reason when skipped; `may` is optional. A decision executes nothing
+and grants no permission. `cairn playbook instructions remove` removes only the
+managed `AGENTS.md` block.
+
 For all harnesses, remote HTTP, storage, profiles, context packs, overlays, and
 recovery details, continue with [Operating Cairnkeep](operating.md) or the
 [learning path](learning/README.md).

package/docs/storage.md

@@ -57,6 +57,28 @@ indexes. Defaults are 5 MiB per serialized session, 256 MiB logical total and
 and then the oldest records needed to meet the logical budget. `prune
 --dry-run` reports the same decision without changing the database.
 
+## Playbook policy and receipt storage
+
+The project policy is `.ai/playbooks.json`, a strict schema-versioned file with
+private permissions. It contains a built-in profile name and bounded overrides
+for canonical actions only. The effective policy digest is derived from its
+canonical meaning, so formatting changes do not create a different policy.
+
+Recorded outcomes are immutable JSON files under
+`.agentfs/playbooks/receipts/`. Each receipt is at most 8 KiB and binds the
+canonical project identity, policy and decision digests, local actor assertion,
+session, event, action, outcome, bounded reason, and timestamp. The store is
+private, capped at 10,000 receipts, and rejects symlinks, unsafe file kinds,
+unsafe permissions, and malformed bytes. It deliberately contains no prompts,
+source bodies, diffs, credentials, or environment snapshots.
+
+Back up `.ai/playbooks.json` with project configuration and
+`.agentfs/playbooks/` with other project-local evidence. Copying receipts does
+not make their actor authenticated. Run `cairn playbook doctor --project PATH`
+after a restore. Ordinary uninstall removes the setup-owned policy and managed
+instruction block backup-first, while retained `.agentfs` evidence follows the
+normal project-data retention choice.
+
 ## Capability callback storage
 
 Managed operating callbacks use two separate versioned KV namespaces inside

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.14.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.15.1","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/kimi/skills/cairn-work/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: cairn-work
+description: Evaluate Cairnkeep's bounded workflow playbook at task lifecycle boundaries
+type: flow
+---
+
+<!-- managed-by:cairnkeep -->
+# Cairnkeep playbook check
+
+Invoke Bash exactly once with `cairn playbook check $ARGUMENTS`. Accept only
+`start`, `check`, or `finish` plus documented check options. Return the decision
+verbatim, then state how you will handle its `must`, `should`, and `may`
+actions. Policy evaluation never executes an action or grants approval.

package/mcp-memory-server/dist/playbook-cli.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+import { PLAYBOOK_ACTIONS, evaluatePlaybook, inferChangeTypes, initializePlaybook, resetPlaybook, resetPlaybookOverride, resolvePlaybookStatus, setPlaybookOverride, setPlaybookProfile, } from "./playbook.js";
+import { doctorPlaybooks, listPlaybookReceipts, readPlaybookReceipt, recordPlaybookReceipt } from "./playbook-receipt.js";
+import { PLAYBOOK_ACTION_IDS, PLAYBOOK_CHANGE_TYPES, PLAYBOOK_PROFILES, playbookActionIdSchema, playbookActorKindSchema, playbookComplexitySchema, playbookEventSchema, playbookFamiliaritySchema, playbookModeSchema, playbookOutcomeSchema, playbookProfileSchema, playbookRiskSchema, } from "./playbook-schema.js";
+process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE")
+        process.exit(0);
+    throw error;
+});
+function usage() {
+    return `cairn playbook — bounded workflow policy for coding agents
+
+Usage:
+  cairn playbook list [--json]
+  cairn playbook status [--project PATH] [--json]
+  cairn playbook init [minimal|balanced|strict] [--project PATH] [--json]
+  cairn playbook set minimal|balanced|strict [--project PATH] [--json]
+  cairn playbook enable ACTION must|should|may [--project PATH] [--json]
+  cairn playbook disable ACTION [--project PATH] [--json]
+  cairn playbook reset [ACTION] [--project PATH] [--json]
+  cairn playbook check start|check|finish [signals] [evidence] [--enforce] [--json]
+  cairn playbook record --policy DIGEST --decision DIGEST --event EVENT --action ACTION --outcome OUTCOME [identity] [--json]
+  cairn playbook receipts list|show [RECEIPT] [--project PATH] [--json]
+  cairn playbook instructions install|check|remove [--project PATH] [--json]
+  cairn playbook doctor [--project PATH] [--json]
+
+Check signals:
+  --complexity trivial|standard|complex   --familiarity known|mixed|unfamiliar
+  --risk low|normal|high|security         --public-change
+  --changed PATH...                       --change-type TYPE...
+  --completed ACTION...                   --skipped ACTION=REASON...
+  --failed ACTION=REASON...               --actor ID --actor-kind user|agent|service --session ID
+
+Policies select only Cairnkeep-owned actions. Checking never executes an action,
+contacts a network service, or grants approval. Actor identity is caller-supplied
+and unauthenticated until a future team deployment binds it to authentication.
+`;
+}
+const VALUE_OPTIONS = new Set([
+    "--project", "--complexity", "--familiarity", "--risk", "--changed", "--change-type",
+    "--completed", "--skipped", "--failed", "--actor", "--actor-kind", "--session",
+    "--policy", "--decision", "--event", "--action", "--outcome", "--reason",
+]);
+const FLAG_OPTIONS = new Set(["--json", "--enforce", "--public-change"]);
+const MULTI_OPTIONS = new Set(["--changed", "--change-type", "--completed", "--skipped", "--failed"]);
+function parse(raw) {
+    const positional = [];
+    const options = new Map();
+    const flags = new Set();
+    for (let index = 0; index < raw.length; index += 1) {
+        const value = raw[index];
+        if (FLAG_OPTIONS.has(value)) {
+            if (flags.has(value))
+                throw new Error(`Duplicate ${value}.`);
+            flags.add(value);
+            continue;
+        }
+        if (VALUE_OPTIONS.has(value)) {
+            const values = options.get(value) ?? [];
+            if (!MULTI_OPTIONS.has(value) && values.length)
+                throw new Error(`Duplicate ${value}.`);
+            let consumed = 0;
+            while (index + 1 < raw.length && !raw[index + 1].startsWith("--")) {
+                values.push(raw[index + 1]);
+                index += 1;
+                consumed += 1;
+                if (!MULTI_OPTIONS.has(value))
+                    break;
+            }
+            if (consumed === 0)
+                throw new Error(`Missing value for ${value}.`);
+            options.set(value, values);
+            continue;
+        }
+        if (value.startsWith("--"))
+            throw new Error(`Unknown option ${value}.`);
+        positional.push(value);
+    }
+    return {
+        positional,
+        options,
+        flags,
+        json: flags.has("--json"),
+        projectRoot: options.get("--project")?.[0] ?? process.cwd(),
+    };
+}
+function one(parsed, name, fallback) {
+    return parsed.options.get(name)?.[0] ?? fallback;
+}
+function many(parsed, name) {
+    return parsed.options.get(name) ?? [];
+}
+function ensureAllowed(parsed, allowedOptions, allowedFlags) {
+    for (const key of parsed.options.keys())
+        if (!allowedOptions.includes(key))
+            throw new Error(`${key} is not valid for this command.`);
+    for (const key of parsed.flags)
+        if (!allowedFlags.includes(key))
+            throw new Error(`${key} is not valid for this command.`);
+}
+function output(value, json, human) {
+    process.stdout.write(`${json ? JSON.stringify(value) : human}\n`);
+}
+function humanStatus(status) {
+    return [
+        `Profile: ${status.profile}`,
+        `Source: ${status.source}`,
+        `Policy digest: ${status.policy_digest}`,
+        `Configuration: ${status.config_exists ? ".ai/playbooks.json" : "built-in balanced default"}`,
+        `Issues: ${status.issues.length ? status.issues.join(", ") : "none"}`,
+        ...PLAYBOOK_ACTION_IDS.map((id) => `${id}\t${status.modes[id]}${status.overrides[id] ? "\toverride" : ""}`),
+    ].join("\n");
+}
+function parseEvidence(values, outcome) {
+    return values.map((value) => {
+        const separator = value.indexOf("=");
+        const action = separator < 0 ? value : value.slice(0, separator);
+        const reason = separator < 0 ? "" : value.slice(separator + 1);
+        playbookActionIdSchema.parse(action);
+        if (outcome !== "completed" && reason.trim().length === 0)
+            throw new Error(`${outcome} evidence requires ACTION=REASON.`);
+        return { action: action, outcome, reason };
+    });
+}
+function actor(parsed) {
+    const id = one(parsed, "--actor", process.env.CAIRN_PLAYBOOK_ACTOR ?? "local-agent");
+    const kind = playbookActorKindSchema.parse(one(parsed, "--actor-kind", process.env.CAIRN_PLAYBOOK_ACTOR_KIND ?? "agent"));
+    return { id, kind, authenticated: false };
+}
+function session(parsed) {
+    return one(parsed, "--session", process.env.CAIRN_PLAYBOOK_SESSION ?? `local-${process.pid}`);
+}
+function humanDecision(value) {
+    const lines = [
+        `Playbook: ${value.profile} (${value.policy_digest})`,
+        `Decision: ${value.decision_digest}`,
+        `Event: ${value.event}`,
+    ];
+    if (value.actions.length === 0)
+        lines.push("Actions: none");
+    else {
+        lines.push("Actions:");
+        for (const row of value.actions) {
+            lines.push(`  [${row.outcome === "completed" ? "x" : " "}] ${row.mode.toUpperCase()} ${row.id} — ${row.title}`);
+            lines.push(`      ${row.rationale}`);
+            lines.push(`      ${row.command}`);
+            if (row.reason)
+                lines.push(`      evidence: ${row.outcome} — ${row.reason}`);
+        }
+    }
+    lines.push(`Blocking: ${value.blocking_actions.length ? value.blocking_actions.join(", ") : "none"}`);
+    lines.push("Actor authentication: unverified local assertion");
+    return lines.join("\n");
+}
+async function check(parsed) {
+    ensureAllowed(parsed, ["--project", "--complexity", "--familiarity", "--risk", "--changed", "--change-type", "--completed", "--skipped", "--failed", "--actor", "--actor-kind", "--session"], ["--json", "--enforce", "--public-change"]);
+    if (parsed.positional.length !== 1)
+        throw new Error("check requires one lifecycle event.");
+    const event = playbookEventSchema.parse(parsed.positional[0]);
+    const explicitTypes = many(parsed, "--change-type").map((value) => {
+        if (!PLAYBOOK_CHANGE_TYPES.includes(value))
+            throw new Error(`Unknown change type ${value}.`);
+        return value;
+    });
+    const changed = many(parsed, "--changed");
+    const evidence = [
+        ...parseEvidence(many(parsed, "--completed"), "completed"),
+        ...parseEvidence(many(parsed, "--skipped"), "skipped"),
+        ...parseEvidence(many(parsed, "--failed"), "failed"),
+    ];
+    const value = await evaluatePlaybook({
+        projectRoot: parsed.projectRoot,
+        event,
+        actor: actor(parsed),
+        sessionId: session(parsed),
+        signals: {
+            complexity: playbookComplexitySchema.parse(one(parsed, "--complexity", "standard")),
+            familiarity: playbookFamiliaritySchema.parse(one(parsed, "--familiarity", "mixed")),
+            risk: playbookRiskSchema.parse(one(parsed, "--risk", "normal")),
+            public_change: parsed.flags.has("--public-change"),
+            changed_paths: changed,
+            change_types: inferChangeTypes(changed, explicitTypes),
+        },
+        evidence,
+    });
+    output(value, parsed.json, humanDecision(value));
+    if (value.issues.length)
+        process.exitCode = 2;
+    else if (parsed.flags.has("--enforce") && value.blocking_actions.length)
+        process.exitCode = 3;
+}
+async function record(parsed) {
+    ensureAllowed(parsed, ["--project", "--policy", "--decision", "--event", "--action", "--outcome", "--reason", "--actor", "--actor-kind", "--session"], ["--json"]);
+    if (parsed.positional.length !== 0)
+        throw new Error("record accepts options only.");
+    const value = await recordPlaybookReceipt({
+        projectRoot: parsed.projectRoot,
+        policyDigest: one(parsed, "--policy") ?? "",
+        decisionDigest: one(parsed, "--decision") ?? "",
+        actor: actor(parsed),
+        sessionId: session(parsed),
+        event: playbookEventSchema.parse(one(parsed, "--event")),
+        action: playbookActionIdSchema.parse(one(parsed, "--action")),
+        outcome: playbookOutcomeSchema.parse(one(parsed, "--outcome")),
+        reason: one(parsed, "--reason", ""),
+    });
+    output(value, parsed.json, `Recorded ${value.receipt_id}: ${value.action} ${value.outcome}.`);
+}
+async function main() {
+    const [command = "help", ...raw] = process.argv.slice(2);
+    if (["help", "--help", "-h"].includes(command)) {
+        if (raw.length)
+            throw new Error("help accepts no arguments.");
+        process.stdout.write(usage());
+        return;
+    }
+    const parsed = parse(raw);
+    if (command === "list") {
+        ensureAllowed(parsed, [], ["--json"]);
+        if (parsed.positional.length)
+            throw new Error("list accepts no arguments.");
+        const value = { schema_version: 1, profiles: PLAYBOOK_PROFILES, actions: PLAYBOOK_ACTIONS };
+        output(value, parsed.json, PLAYBOOK_ACTIONS.map(({ id, title, command: actionCommand }) => `${id}\t${title}\t${actionCommand}`).join("\n"));
+        return;
+    }
+    if (command === "status") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length)
+            throw new Error("status accepts no positional arguments.");
+        const value = await resolvePlaybookStatus({ projectRoot: parsed.projectRoot });
+        output(value, parsed.json, humanStatus(value));
+        if (value.issues.length)
+            process.exitCode = 2;
+        return;
+    }
+    if (command === "init" || command === "set") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length > 1 || (command === "set" && parsed.positional.length !== 1))
+            throw new Error(`${command} requires one profile.`);
+        const profile = playbookProfileSchema.parse(parsed.positional[0] ?? "balanced");
+        const value = command === "init"
+            ? await initializePlaybook(parsed.projectRoot, profile)
+            : await setPlaybookProfile(parsed.projectRoot, profile);
+        output(value, parsed.json, humanStatus(value));
+        return;
+    }
+    if (command === "enable" || command === "disable") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length !== (command === "enable" ? 2 : 1))
+            throw new Error(`${command} has invalid arguments.`);
+        const action = playbookActionIdSchema.parse(parsed.positional[0]);
+        const mode = command === "disable" ? "off" : playbookModeSchema.parse(parsed.positional[1]);
+        if (mode === "off" && command === "enable")
+            throw new Error("Use disable ACTION to turn an action off.");
+        const value = await setPlaybookOverride(parsed.projectRoot, action, mode);
+        output(value, parsed.json, humanStatus(value));
+        return;
+    }
+    if (command === "reset") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length > 1)
+            throw new Error("reset accepts at most one action.");
+        const value = parsed.positional[0]
+            ? await resetPlaybookOverride(parsed.projectRoot, playbookActionIdSchema.parse(parsed.positional[0]))
+            : await resetPlaybook(parsed.projectRoot);
+        output(value, parsed.json, humanStatus(value));
+        return;
+    }
+    if (command === "check") {
+        await check(parsed);
+        return;
+    }
+    if (command === "record") {
+        await record(parsed);
+        return;
+    }
+    if (command === "receipts") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        const operation = parsed.positional[0] ?? "list";
+        if (operation === "list" && parsed.positional.length === 1) {
+            const value = await listPlaybookReceipts(parsed.projectRoot);
+            output(value, parsed.json, value.receipts.length ? value.receipts.map(({ receipt_id, action, outcome, recorded_at }) => `${receipt_id}\t${outcome}\t${action}\t${recorded_at}`).join("\n") : "No playbook receipts found.");
+            return;
+        }
+        if (operation === "show" && parsed.positional.length === 2) {
+            const value = await readPlaybookReceipt(parsed.positional[1], parsed.projectRoot);
+            output(value, parsed.json, JSON.stringify(value, null, 2));
+            return;
+        }
+        throw new Error("receipts requires list or show RECEIPT.");
+    }
+    if (command === "doctor") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length)
+            throw new Error("doctor accepts no positional arguments.");
+        const value = await doctorPlaybooks(parsed.projectRoot);
+        output(value, parsed.json, JSON.stringify(value, null, 2));
+        if (!value.ok)
+            process.exitCode = 2;
+        return;
+    }
+    if (command === "instructions") {
+        ensureAllowed(parsed, ["--project"], ["--json"]);
+        if (parsed.positional.length !== 1 || !["install", "check", "remove"].includes(parsed.positional[0]))
+            throw new Error("instructions requires install, check, or remove.");
+        const moduleUrl = new URL("../../scripts/playbook-instructions.mjs", import.meta.url).href;
+        const instructionModule = await import(moduleUrl);
+        const value = parsed.positional[0] === "remove"
+            ? instructionModule.removePlaybookInstructions(parsed.projectRoot, { check: false })
+            : instructionModule.reconcilePlaybookInstructions(parsed.projectRoot, { check: parsed.positional[0] === "check" });
+        output(value, parsed.json, `${value.status}: ${value.path}`);
+        if (parsed.positional[0] === "check" && value.status !== "unchanged")
+            process.exitCode = 1;
+        return;
+    }
+    throw new Error(`unknown playbook command "${command}".`);
+}
+main().catch((error) => {
+    process.stderr.write(`cairn playbook: ${error instanceof Error ? error.message : "invalid command or policy"}\n`);
+    process.exitCode = 2;
+});