@cairnkeep/cli 2.13.1 → 2.15.0

package/docs/learning/lessons/L23-guided-setup.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart and Operator
 **Time:** 35 minutes
-**Tested with:** Cairnkeep 2.13.1; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.15.0; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 
@@ -134,7 +134,7 @@ prompts, approve skills, create an autonomous loop, or add remote access.
 
 ## Release boundary
 
-Ready means this lesson and its deterministic contracts pass against v2.13.1.
+Ready means this lesson and its deterministic contracts pass against v2.14.0.
 Release readiness requires a non-skipping acceptance run
 against separate Pi 0.84.1 minimum and explicitly versioned registry-current
 installations, plus the documented Node.js, Bash 3.2, and native Windows matrix.

package/docs/learning/lessons/L24-okf-exchange.md

@@ -0,0 +1,111 @@
+# L24 - Reviewed knowledge exchange
+
+**Status:** Ready
+**Tested with:** Cairnkeep 2.15.0 and Node.js 22 or newer
+**Time:** 35 minutes
+
+## Outcome
+
+Validate and import an OKF bundle as immutable project context, inspect its
+structured provenance and deterministic links, then export an explicitly
+selected, redacted OKF 0.2 bundle without confusing exchange with durable
+memory or publisher trust.
+
+## Exercise
+
+Create a disposable OKF 0.2 bundle:
+
+```bash
+lab=$(mktemp -d)
+mkdir -p "$lab/source/concepts" "$lab/project"
+cat >"$lab/source/index.md" <<'EOF'
+---
+okf_version: "0.2"
+---
+# Local catalog
+
+* Policy
+EOF
+printf '%s%s\n' '* [Policy]' '(concepts/policy.md)' >>"$lab/source/index.md"
+cat >"$lab/source/concepts/policy.md" <<'EOF'
+---
+type: Policy
+title: Synthetic policy
+description: Offline course fixture.
+sources:
+  - resource: urn:course:fixture
+verified: { by: human:course-reviewer }
+---
+# Synthetic policy
+
+This content is deliberately non-sensitive.
+EOF
+export CAIRN_PACK_BASE_DIR="$lab/store"
+cairn pack validate-okf "$lab/source"
+cairn pack import-okf "$lab/source" --id course-okf \
+  --version 1.0.0 --license CC0-1.0 --json >"$lab/import.json"
+digest=$(node -e 'process.stdout.write(require(process.argv[1]).digest)' "$lab/import.json")
+cairn pack enable "$digest" --project "$lab/project"
+```
+
+Start the project memory server with `CAIRN_CONTEXT_PACKS=1`. Through an MCP
+client, confirm that list/search/read results contain `okf.version`, concept
+type, source, trust tier, freshness state, links, and diagnostics. Call
+`context_pack_related` for `concepts/policy.md`; it performs no URL fetch and
+returns only enabled files from the same digest-pinned pack.
+
+Now preview and apply an allowlist-only export:
+
+```bash
+mkdir -p "$lab/project/docs"
+printf '# Reviewed decision\n\nSynthetic approved text.\n' \
+  >"$lab/project/docs/decision.md"
+cairn pack export-okf --project "$lab/project" --output "$lab/export" \
+  --file docs/decision.md --check
+# Copy the printed preview digest only after inspecting the file list.
+cairn pack export-okf --project "$lab/project" --output "$lab/export" \
+  --file docs/decision.md --apply --confirm PREVIEW-DIGEST
+cairn pack validate-okf "$lab/export"
+```
+
+## Common failures
+
+- A concept without YAML `type`, a YAML alias, a symlink, invalid UTF-8, or an
+  unsafe path fails validation.
+- Git input needs an explicit `--ref`; local validation/import does not use the
+  network.
+- Export rejects broad private/runtime paths and accepts only named Markdown or
+  promoted shared notes.
+- Any selected-byte or redaction change invalidates the preview digest. An
+  existing output directory is never replaced.
+
+## Privacy and trust boundary
+
+Import metadata is reported, not vouched for. A pack digest proves byte
+integrity but not publisher authenticity, and OKF computation/attestation
+metadata is never executed. Optional embedding search can send chunks to the
+configured endpoint; substring search and link traversal stay local. Export
+applies redaction, but explicit review of both preview and output is still
+required before publication.
+
+An external knowledge adapter remains deferred unless a representative task
+demonstrates a necessary capability that memory, promoted notes, context packs,
+links, embeddings, and OKF exchange cannot provide with lower operational and
+privacy cost.
+
+## Recovery and acceptance
+
+```bash
+cairn pack disable course-okf --project "$lab/project"
+cairn pack remove "$digest"
+unset CAIRN_PACK_BASE_DIR
+rm -rf "$lab"
+```
+
+- Validation and import preserve OKF 0.1/0.2 provenance without modifying the
+  source.
+- Related-document retrieval is deterministic, closed-world, and read-only.
+- The regression fixture detects wrong top results, stale metadata, missing
+  provenance, and broken links.
+- Export check performs no writes; apply requires the exact recomputed digest
+  and creates only the reviewed destination.

package/docs/learning/lessons/L25-playbooks.md

@@ -0,0 +1,114 @@
+# L25 - Bounded workflow playbooks
+
+**Status:** Ready
+**Tested with:** Cairnkeep 2.15.0 and Node.js 22 or newer
+**Time:** 35 minutes
+
+## Outcome
+
+Configure a project playbook, evaluate it at start and finish, satisfy a
+deterministic `must` gate with honest evidence, and inspect one private receipt
+without mistaking agent self-selection for authorization or execution.
+
+## Exercise
+
+Create a disposable project and a strict policy:
+
+```bash
+lab=$(mktemp -d)
+mkdir -p "$lab/project/.ai"
+cd "$lab/project"
+cairn playbook init strict
+cairn playbook status
+cairn playbook check start --session course-playbook \
+  --complexity complex --familiarity unfamiliar
+```
+
+The start decision should select recall, focused exploration, and a bounded
+plan. It displays existing Cairnkeep actions; it does not run them. In a real
+task, perform the applicable actions through the harness and retain truthful
+evidence.
+
+Now model a security-sensitive public code-and-documentation change. First
+observe the enforcement failure:
+
+```bash
+set +e
+cairn playbook check finish --session course-playbook \
+  --changed src/auth.ts docs/security.md --risk security --public-change \
+  --enforce --json >"$lab/missing.json"
+test "$?" -eq 3
+set -e
+```
+
+Inspect `blocking_actions`; do not merely label them complete. After running
+the relevant tests, repository review, security audit, and documentation
+checks, provide the resulting evidence:
+
+```bash
+cairn playbook check finish --session course-playbook \
+  --changed src/auth.ts docs/security.md --risk security --public-change \
+  --completed verify.tests review.repository review.security docs.update \
+  --skipped learning.capture='no stable reusable learning' \
+  --enforce --json >"$lab/decision.json"
+```
+
+Record one material result with the exact returned digests:
+
+```bash
+policy=$(node -p "require('$lab/decision.json').policy_digest")
+decision=$(node -p "require('$lab/decision.json').decision_digest")
+cairn playbook record --policy "$policy" --decision "$decision" \
+  --event finish --action verify.tests --outcome completed \
+  --session course-playbook --reason 'targeted synthetic tests passed'
+cairn playbook receipts list
+cairn playbook doctor
+```
+
+Try a bounded customization, then restore the profile behavior:
+
+```bash
+cairn playbook disable learning.capture
+cairn playbook reset learning.capture
+cairn playbook set balanced
+```
+
+## Common failures
+
+- Exit 3 is missing required evidence, not a request to weaken the policy.
+- `--skipped` and `--failed` require `ACTION=REASON`; they do not satisfy a
+  `must` action.
+- Unknown actions, fields, modes, commands, URLs, path traversal, symlinks,
+  unsafe permissions, and oversized policy files fail closed.
+- A changed policy makes an old policy digest stale for new receipts.
+- `CAIRN_PLAYBOOK_PROFILE` overrides the project profile for that process; use
+  `cairn playbook status` to see the effective source.
+
+## Privacy and trust boundary
+
+Checks are offline and store nothing. Explicit receipts contain bounded
+identifiers, digests, event/action/outcome/reason, and a timestamp, but no
+prompt, file body, diff, command output, credential, or environment snapshot.
+Changed-path labels affect the decision but are not stored in the receipt.
+
+The v2.15 actor field is caller-supplied and unauthenticated. It is useful for
+local provenance, not access control, employee monitoring, or non-repudiation.
+Playbooks cannot enable capabilities, grant mutation approval, execute harness
+commands, or promote a learning into durable memory. Team authentication,
+ACLs, tenant isolation, and shared review queues remain design-only.
+
+## Recovery and acceptance
+
+```bash
+cairn playbook instructions remove --project "$lab/project"
+cd /
+rm -rf "$lab"
+```
+
+- Identical policy, signals, event, and evidence produce the same decision
+  digest.
+- Missing applicable `must` evidence exits 3 under `--enforce`; completed
+  evidence clears the relevant block.
+- The receipt is private, project-bound, bounded, and visible to `doctor`.
+- Removing managed instructions preserves all surrounding `AGENTS.md` content.
+- No check executes an action, contacts a network service, or grants approval.

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 5 hours 35 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)
@@ -14,14 +14,20 @@
 8. [L21 - Immutable context packs and skill approval](../lessons/L21-context-packs.md)
 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
 explain its storage, network, credential, and rollback boundaries. L23 adds the
 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/V24-okf-exchange.md

@@ -0,0 +1,31 @@
+# V24 - Reviewed knowledge exchange
+
+**Companion lesson:** [L24](../lessons/L24-okf-exchange.md)
+**Target length:** 9 minutes
+
+## Recording outline
+
+1. State the boundary: OKF is portable context exchange, not a second memory
+   owner, agent loop, trust authority, or background sync service.
+2. Show a two-concept synthetic OKF 0.2 directory and run
+   `cairn pack validate-okf`.
+3. Import it with an ID, semantic version, and license; point out that the
+   source directory remains unchanged and the pack digest is authoritative.
+4. Enable the digest for one disposable project. Show structured `okf`
+   provenance in list/search/read and traverse one local link with
+   `context_pack_related`.
+5. Break a link and make a concept stale in a second fixture. Show diagnostics
+   without implying that Cairnkeep verified the source claims.
+6. Select one project Markdown file, run `export-okf --check`, and emphasize
+   that no output exists. Inspect the allowlist, redaction count, and digests.
+7. Apply with the exact preview digest and validate the result. Demonstrate one
+   rejected private path and one mismatched confirmation.
+8. Close with the external-adapter gate: demand a measured, otherwise
+   impossible workflow before accepting another network and data owner.
+
+## Recording cautions
+
+- Use only synthetic paths, content, sources, and credentials.
+- Keep embeddings disabled so the recording proves the offline fallback.
+- Do not claim publisher authenticity, semantic correctness, or quality gains.
+- Remove the disposable pack object and project pointer on camera.

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/open-knowledge-format.md

@@ -0,0 +1,100 @@
+# Open Knowledge Format exchange
+
+Cairnkeep can ingest Open Knowledge Format (OKF) 0.1 and 0.2 bundles as
+immutable context packs and can export an explicitly reviewed subset of local
+knowledge as OKF 0.2. This is an exchange boundary, not a second memory store,
+an agent runtime, or a synchronization service.
+
+## Validate and import
+
+```bash
+cairn pack validate-okf ./knowledge
+cairn pack import-okf ./knowledge \
+  --id reviewed-knowledge --version 1.0.0 --license CC-BY-4.0
+cairn pack enable reviewed-knowledge --project ./project
+```
+
+The importer accepts a local directory without network access. A Git source
+requires `--ref`; Cairnkeep resolves and records the exact commit using the
+system `git` executable. Repository metadata is excluded. Import copies only
+validated UTF-8 bundle files into a new immutable object and never modifies the
+source.
+
+Validation rejects symlinks, devices, unsafe paths, invalid UTF-8, YAML aliases,
+missing concept `type`, duplicate YAML keys, and the normal context-pack size
+limits. Unknown concept metadata remains available for forward-compatible
+reading. A future OKF version produces a diagnostic and is consumed on a
+best-effort basis rather than being treated as fully supported.
+
+OKF 0.2 provenance is preserved in the `okf` field returned by
+`context_pack_list`, `context_pack_search`, and `context_pack_read`. It includes
+the format version, file role, concept identity and type, declared sources,
+generation and verification events, trust tier, status, staleness, links, and
+diagnostics. These are source assertions: Cairnkeep reports them but does not
+turn them into publisher authenticity or executable authority.
+
+## Deterministic links and retrieval
+
+With `CAIRN_CONTEXT_PACKS=1`, imported packs also expose the read-only,
+closed-world `context_pack_related` MCP tool. It traverses local Markdown links
+in `outbound`, `inbound`, or `both` directions. External URLs are never fetched.
+Broken and unsafe local links remain diagnostics. The derived graph cache lives
+outside immutable objects and is keyed by the authoritative pack digest; it can
+always be rebuilt from the object.
+
+Search still follows the context-pack retrieval contract: deterministic
+substring matching is always available, while configured embeddings are an
+optional enhancement with a clean lexical fallback. Regression fixtures cover
+the expected top result, source/trust preservation, stale-content warnings,
+missing-metadata diagnostics, broken links, and embedding-independent graph
+results.
+
+## Privacy-reviewed export
+
+Export is allowlist-only and uses a two-step confirmation:
+
+```bash
+cairn pack export-okf --project ./project --output ./reviewed-okf \
+  --file docs/decision.md --note shared-example --check
+
+cairn pack export-okf --project ./project --output ./reviewed-okf \
+  --file docs/decision.md --note shared-example \
+  --apply --confirm PREVIEW-DIGEST
+```
+
+`--check` writes nothing. It reads only the named Markdown files and promoted
+shared notes, applies the local redaction policy, and returns the exact output
+list, output digests, redaction count, and confirmation digest. `--apply`
+recomputes that plan and writes atomically only when the digest matches. It
+refuses an existing output directory.
+
+Private runtime directories, Git metadata, dependencies, and most planning
+state cannot be selected. The reviewed wiki subtree is the sole planning-state
+exception and is mapped to `wiki/`. Project hindsight and provenance notes are
+not exportable: only already-corroborated `shared` notes pass the note reader.
+The resulting bundle can still contain sensitive domain content, so review the
+preview and the output before publishing it.
+
+## External adapter decision gate
+
+No live external knowledge-system adapter is included. Native memory, promoted
+notes, immutable packs, deterministic links, optional embeddings, and OKF
+import/export already cover local capture, reviewed sharing, retrieval, and
+portable exchange.
+
+An adapter should be added only when a concrete workflow demonstrates all of
+the following:
+
+1. It needs a capability Cairnkeep cannot express through those native
+   surfaces, not merely another UI or duplicate graph.
+2. The benefit is measured on a representative task set and exceeds the added
+   privacy, availability, migration, and operational cost.
+3. Cairnkeep remains the sole owner of durable-memory mutations; the adapter is
+   read-only or has an explicit, reversible write boundary.
+4. Authentication, data egress, deletion, backup, and failure behavior are
+   testable without weakening local/offline defaults.
+5. A provider-neutral interface and fixture can be maintained without adding a
+   background agent loop or automatic activation.
+
+Until a use case passes that gate, OKF exchange is the smaller and safer
+integration seam.

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:
@@ -1302,3 +1356,17 @@ an `--apply --confirm CANDIDATE-DIGEST`. Use `cairn pack skills` and exact-diges
 approval before a bundled skill can be read through MCP. HTTP needs the separate
 `CAIRN_CONTEXT_PACK_HTTP=1` flag and all existing authentication/Host/CORS
 controls. See [Immutable context packs](context-packs.md).
+
+Validate and import an OKF bundle without converting it by hand:
+
+```bash
+cairn pack validate-okf ./knowledge
+cairn pack import-okf ./knowledge --id reviewed-knowledge \
+  --version 1.0.0 --license CC-BY-4.0
+```
+
+Imported OKF packs preserve structured source/trust/freshness metadata and add
+read-only related-document traversal. Privacy-reviewed export is an explicit
+`export-okf --check` followed by `--apply --confirm PREVIEW-DIGEST`; only named
+Markdown files and promoted shared notes are eligible. See
+[Open Knowledge Format exchange](open-knowledge-format.md).

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

@@ -19,6 +19,8 @@ request unless the corresponding endpoint and credential are configured.
 | Local context-pack install/list/read/substring search | None | Verified immutable files and project pointers under `CAIRN_PACK_BASE_DIR` |
 | Embedding-ranked context-pack search | Enabled file chunks not already cached, plus the query | The explicitly configured embedding endpoint; failure falls back locally |
 | Authenticated HTTP context-pack retrieval | MCP requests and enabled document/approved-skill content | The explicit Cairnkeep HTTP server; requires separate pack HTTP consent |
+| Local OKF validation/import/link traversal | None | Source files are read locally; immutable object and digest-keyed graph cache remain under `CAIRN_PACK_BASE_DIR` |
+| Privacy-reviewed OKF export | None | Only explicitly named Markdown/promoted shared notes are redacted into the operator-selected local output directory after exact preview confirmation |
 | Optional Graphify workflow | The repository path, exact query/symbol names, root `graphify-out/` work directory, and local `.planning/graphs/` publication are passed to or produced by the operator-installed `graphify` executable | Local Graphify subprocess with a minimal environment and no provider credentials; managed build uses code-only `update`, never semantic document extraction |
 | Remote HTTP memory | MCP requests and responses, including memory content | The explicitly registered Cairnkeep HTTP server |
 | Opt-in trajectory capture | None | Local `<project>/.agentfs/trajectory.db` only; no model or HTTP path exists |
@@ -41,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).