@cairnkeep/cli 2.13.1 → 2.15.0

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable user-facing changes are documented here. This project follows
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-08-17
+
+### Added
+
+- Add strict local project playbooks with `minimal`, `balanced`, and `strict`
+  profiles, bounded canonical action overrides, deterministic start/check/finish
+  decisions, enforcement for missing `must` evidence, and stable policy and
+  decision digests.
+- Add private project-bound outcome receipts with bounded unauthenticated actor
+  provenance, lifecycle inspection, and doctor validation without storing
+  prompts, source bodies, changed paths, diffs, credentials, or command output.
+- Add ownership-safe managed `AGENTS.md` guidance plus thin Claude, OpenCode,
+  Pi, and Kimi `/cairn-work` adapters; Codex and Qwen use the portable project
+  instructions without automatic skill activation.
+- Add an implementation-ready future team-mode contract covering authenticated
+  identity, scopes, ACLs, review queues, audit history, tenant isolation,
+  retention, migration, and release gates while keeping team operation deferred.
+- Add a release-verified playbook lesson, course checkpoint, feature/curriculum
+  coverage, and companion video script.
+
+### Changed
+
+- Guided setup and tracked bootstrap now install the balanced policy and safely
+  reconcile the managed agent-instruction block. Untracked bootstrap leaves
+  shared `AGENTS.md` untouched.
+- Extend completion, native Windows, package, doctor, and backup-first uninstall
+  coverage to the playbook lifecycle and harness adapters.
+
+## [2.14.0] - 2026-08-17
+
+### Added
+
+- Add validation and immutable context-pack import for Open Knowledge Format
+  0.1/0.2 bundles, preserving structured source, trust, freshness, and gap
+  diagnostics without activating computations or instructions.
+- Add deterministic digest-keyed document links and the read-only,
+  closed-world `context_pack_related` MCP observation.
+- Add allowlist-only, redacted OKF 0.2 export for named project Markdown and
+  promoted shared notes, with a no-write preview and exact-digest atomic apply.
+- Add offline retrieval/freshness/gap regression fixtures and an explicit
+  decision gate for any future external knowledge-system adapter.
+
 ## [2.13.1] - 2026-08-17
 
 ### Fixed
@@ -356,7 +398,9 @@ stored memories.
 - Preserve executable permissions and Bash 3.2 portability on macOS.
 - Add backup-first uninstall and SQLite-safe memory export/import guidance.
 
-[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.13.1...HEAD
+[Unreleased]: https://github.com/cairnkeep/cairnkeep/compare/v2.15.0...HEAD
+[2.15.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.14.0...v2.15.0
+[2.14.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.13.1...v2.14.0
 [2.13.1]: https://github.com/cairnkeep/cairnkeep/compare/v2.13.0...v2.13.1
 [2.13.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.12.0...v2.13.0
 [2.12.0]: https://github.com/cairnkeep/cairnkeep/compare/v2.11.0...v2.12.0

package/README.md

@@ -32,11 +32,11 @@ verification, and the first remember/recall cycle.
 ## Status
 
 Shipped: the memory server, the `cairn` CLI (`setup`, `bootstrap`, `memory-server`, `sync`, `sync-pi`, `sync-kimi`,
-`doctor`, `trajectory`, `artifact`, `evidence`, `mcp-tools`, `pack`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
+`doctor`, `playbook`, `trajectory`, `artifact`, `evidence`, `mcp-tools`, `pack`, `notes`, `memory`, `eval`, `audit-timer`, `completion`, `uninstall`) installable via
 `npm i -g @cairnkeep/cli`, and the
 operating layer (commands,
 agents, hooks) installed on Claude Code and OpenCode, plus the native Pi
-trajectory extension and thin Pi/Kimi graph adapters. The generic launchers
+trajectory extension and thin Pi/Kimi graph and playbook adapters. The generic launchers
 expose wrapper seams (`.ai/pre-launch.sh`/`.ai/pre-launch.ps1`,
 `CAIRN_EXTRA_SETTINGS`, `.ai/post-exit.sh`/`.ai/post-exit.ps1`) so an enterprise wrapper can add provider/credential setup
 without forking them. Also shipped: context exploration (`/context-explore`) and
@@ -48,6 +48,9 @@ Version 2.12 adds a declarative harness registry, first-class Codex project
 setup, and a shorter path from installation to verified recall.
 Version 2.13 adds opt-in local Git-linked work evidence around generated harness
 launchers, including native Windows, without capturing prompts or replacing Git.
+Version 2.15 adds bounded project playbooks that help agents select existing
+recall, planning, verification, review, security, documentation, and learning
+steps without becoming an agent runtime or granting approval.
 
 ## Compatibility
 
@@ -199,6 +202,19 @@ patterns/transactional-migrations: Use transactional migrations for schema chang
 The exact command rendering depends on the client. Any MCP client can call
 `memory_write` and `memory_search` directly.
 
+Setup also installs a balanced `.ai/playbooks.json` policy and an ownership-safe
+managed block in `AGENTS.md`. Agents can evaluate it at task boundaries:
+
+```bash
+cairn playbook check start --complexity standard --familiarity mixed
+cairn playbook check finish --changed src/example.ts --completed verify.tests --enforce
+```
+
+The result selects only existing Cairnkeep actions. It never runs them, enables
+a disabled capability, grants approval, or promotes memory automatically. Use
+`cairn playbook status`, `set minimal|balanced|strict`, and `enable|disable` to
+inspect or customize the project policy.
+
 For Codex CLI, `cairn setup --harness codex --memory local` writes the
 project-scoped `.codex/config.toml` entry and both POSIX and native Windows
 launchers. Review the configuration and trust the project before launching.
@@ -322,9 +338,13 @@ search):
 | `CAIRN_AGENTFS_BASE_DIR` | Base dir for global memory scopes (default `~/.cairnkeep`) |
 | `CAIRN_MCP_TOOL_PROFILE` | Process override for MCP exposure: `full`, `read-only`, or `custom` |
 | `CAIRN_MCP_ALLOWED_TOOLS` | Comma-separated exact allowlist required by a custom process profile |
-| `CAIRN_CONTEXT_PACKS` | Opt in to local context-pack list/search/read tools (default off) |
+| `CAIRN_CONTEXT_PACKS` | Opt in to local context-pack list/search/read/related tools (default off) |
 | `CAIRN_CONTEXT_PACK_HTTP` | Separately consent to context-pack tools over authenticated HTTP (default off) |
 | `CAIRN_PACK_BASE_DIR` | Immutable pack objects, source records, pointers, and retrieval cache (default `~/.cairnkeep/packs`) |
+| `CAIRN_PLAYBOOK_PROFILE` | Process-only playbook profile override: `minimal`, `balanced`, or `strict` (project default: `balanced`) |
+| `CAIRN_PLAYBOOK_ACTOR` | Optional local receipt label; caller-supplied and unauthenticated in v2.15 |
+| `CAIRN_PLAYBOOK_ACTOR_KIND` | Optional local actor kind: `user`, `agent`, or `service` |
+| `CAIRN_PLAYBOOK_SESSION` | Optional bounded session label used by playbook decisions and receipts |
 | `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; default off) |
 | `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per captured session (default `5242880`, 5 MiB) |
 | `CAIRN_TRAJECTORY_STORE_MAX_BYTES` | Maximum logical bytes across local trajectories (default `268435456`, 256 MiB) |
@@ -389,10 +409,12 @@ cannot bypass capability or feature gates. See
 
 Context packs are immutable, digest-addressed local document/skill bundles.
 They are installed and project-pinned manually; no background Git sync occurs.
-With `CAIRN_CONTEXT_PACKS=1`, enabled documents are searchable through three
-read-only MCP tools. Skills remain invisible until their exact file digest is
+With `CAIRN_CONTEXT_PACKS=1`, enabled documents are searchable and their local
+links traversable through four read-only MCP tools. Skills remain invisible until their exact file digest is
 approved, and are never copied or executed. See
-[Immutable context packs](docs/context-packs.md).
+[Immutable context packs](docs/context-packs.md). OKF 0.1/0.2 import and
+privacy-reviewed OKF 0.2 export are documented in
+[Open Knowledge Format exchange](docs/open-knowledge-format.md).
 
 ### Managed capability contract (opt-in)
 
@@ -581,6 +603,7 @@ exposes trajectory data. See the [operating guide](docs/operating.md#compaction-
 - **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)
 - **MCP tool profiles** — [docs/mcp-tool-profiles.md](docs/mcp-tool-profiles.md)
 - **Immutable context packs** — [docs/context-packs.md](docs/context-packs.md)
+- **Open Knowledge Format exchange** — [docs/open-knowledge-format.md](docs/open-knowledge-format.md)
 - **Validated skill improvement** — [docs/skill-improvement.md](docs/skill-improvement.md)
 - **Git providers** — [docs/git-providers.md](docs/git-providers.md)
 - **Support** — [SUPPORT.md](SUPPORT.md)

package/claude/commands/cairn-work.md

@@ -0,0 +1,19 @@
+---
+description: Evaluate Cairnkeep's project playbook at task start, scope changes, or finish
+argument-hint: "start|check|finish [cairn playbook check options]"
+allowed-tools: Bash
+---
+
+<!-- managed-by:cairnkeep -->
+# Cairnkeep playbook check
+
+Run exactly one local command:
+
+```text
+cairn playbook check $ARGUMENTS
+```
+
+Accept `start`, `check`, or `finish` followed only by check options documented by
+`cairn playbook --help`. Safely quote every argument. Return the decision
+and explain which `must`, `should`, and `may` actions you will follow. Never
+claim that this command executed an action or granted approval.

package/docs/context-packs.md

@@ -61,9 +61,11 @@ switches only the named project.
 
 ## Retrieval and skill approval
 
-Set `CAIRN_CONTEXT_PACKS=1` and restart the memory server to register the three
-read-only, closed-world tools: `context_pack_list`, `context_pack_search`, and
-`context_pack_read`. Every file or search result includes pack ID, version,
+Set `CAIRN_CONTEXT_PACKS=1` and restart the memory server to register the
+read-only, closed-world tools: `context_pack_list`, `context_pack_search`,
+`context_pack_read`, and `context_pack_related`. The related tool is available
+for imported OKF bundles and traverses only deterministic local document links.
+Every file or search result includes pack ID, version,
 pack digest, path, kind, and file digest. Search uses the existing optional
 embedding configuration and falls back to deterministic substring matching if
 configuration or the endpoint is unavailable. Embedding cache data is stored
@@ -92,3 +94,11 @@ Authenticated HTTP deployments need the separate
 `CAIRN_CONTEXT_PACKS=1`, the existing bearer token, Host/CORS guards, and a
 project header. Pack digests prove integrity, not publisher authenticity.
 Publisher signatures remain future work.
+
+## Open Knowledge Format exchange
+
+Use `cairn pack validate-okf` and `cairn pack import-okf` to consume OKF 0.1 or
+0.2 as an immutable pack. Use the preview-and-confirm `cairn pack export-okf`
+workflow to export only named project Markdown and promoted shared notes. See
+[Open Knowledge Format exchange](open-knowledge-format.md) for the provenance,
+graph, privacy, regression, and external-adapter decision contracts.

package/docs/design/team-mode.md

@@ -0,0 +1,145 @@
+# Team mode design contract
+
+**Status:** design only; not shipped in Cairnkeep 2.15
+
+Cairnkeep 2.15 remains a local, single-operator product. Its playbook receipts
+carry provider-neutral project and actor fields so a future authenticated team
+service can preserve provenance, but those fields are caller assertions and
+must not be used for authorization. This document defines the boundary a team
+implementation must satisfy before that statement can change.
+
+## Goal and non-goals
+
+Team mode would let an organization share reviewed memory, context packs,
+policies, decisions, and workflow evidence without turning private local
+stores into a common bucket. It must retain local-first operation and explicit
+promotion. It is not collaborative editing, an agent runtime, employee
+monitoring, automatic message ingestion, or an implicit channel for prompts,
+credentials, source trees, or session transcripts.
+
+## Identity and project scope
+
+The service must authenticate a human or workload before accepting a team
+operation. Stable internal subject IDs, organization IDs, and canonical project
+IDs are authoritative; display names, email addresses, Git usernames, and the
+current 2.15 `--actor` value are labels only. Authentication adapters may use
+OIDC/OAuth, mTLS workload identity, or a locally administered service token,
+but normalized claims must include issuer, subject, audience, authentication
+time, and credential class. Tokens and raw identity claims never enter memory
+or receipts.
+
+Every object has exactly one scope:
+
+| Scope | Owner | Default visibility | Promotion |
+|---|---|---|---|
+| personal | authenticated subject | that subject | explicit review request |
+| project | canonical project | authorized project members | project review policy |
+| team | organization collection | named collection members | collection review policy |
+
+Reads never fall through from one project or organization to another. A
+personal object is not discoverable through project search until its selected,
+redacted form has been approved and copied as a new immutable project object.
+
+## Authorization
+
+Authorization must be deny-by-default and evaluated server-side after
+authentication. Minimum roles are `reader`, `contributor`, `reviewer`,
+`maintainer`, and `auditor`. Roles map to explicit operations rather than broad
+administrator shortcuts:
+
+- readers may list and read approved project objects;
+- contributors may create private proposals and submit review requests;
+- reviewers may approve or reject proposals but cannot alter their bytes;
+- maintainers may manage membership, retention, and project policy but cannot
+  approve their own content unless an explicit small-team exception is enabled
+  and audited;
+- auditors may read append-only audit records, not content by default.
+
+Capability contracts and MCP profiles remain an additional intersection. An
+ACL cannot enable a disabled capability, broaden a tool profile, satisfy a
+human confirmation, or make a destructive operation read-only.
+
+## Review and conflict model
+
+Shared durable memory and policies use immutable proposals. A proposal binds
+the source scope, source object digest, redacted candidate bytes, base revision,
+target scope, submitter identity, policy digest, and expiry. Approval creates a
+new immutable revision and an audit event; it never mutates the proposal.
+
+Concurrent proposals against the same base remain separate. The service may
+compute a deterministic conflict report but must not select or merge a winner.
+A reviewer resolves the conflict by accepting one proposal or submitting new
+combined bytes. Playbook distribution follows the same review path and may not
+silently replace a project override.
+
+## Audit and receipts
+
+Accepted operations append a canonical event containing organization,
+project, subject, credential class, operation, object identity and digests,
+authorization decision, policy revision, request ID, server time, and result.
+Rejected privileged operations append a value-free denial event. Audit records
+exclude prompt bodies, source content, secrets, tokens, full environment
+snapshots, and unredacted personal data.
+
+Audit history is append-only, hash-linked, bounded by an explicit retention
+class, exportable by auditors, and covered by backup/restore verification.
+Corrections append superseding events; they never rewrite history. A team
+playbook receipt must distinguish the authenticated server subject from any
+agent label supplied by a harness.
+
+## Tenant isolation and storage
+
+Organization and project identity must be part of every storage key and every
+cache key. Database row policies or physically separate stores must be tested
+with cross-tenant negative cases. Context-pack objects may be content-addressed
+globally only when existence, metadata, timing, and deduplication cannot leak
+across tenants; otherwise storage is tenant-local. Encryption keys, backup
+namespaces, search indexes, embedding caches, temporary files, logs, and rate
+limits observe the same boundary.
+
+The HTTP deployment must retain authentication, Host and CORS validation,
+request-size limits, timeouts, and explicit feature consent. No unauthenticated
+compatibility mode may expose team data.
+
+## Retention, deletion, and portability
+
+Each scope declares retention for content, proposals, receipts, audit events,
+indexes, and backups. Legal hold is an explicit audited state. Deletion first
+revokes visibility, then schedules content and derived indexes for removal;
+immutable audit tombstones retain only the minimum identifiers required by the
+declared policy. An organization export uses open, versioned schemas with
+digests and includes neither credentials nor another tenant's deduplicated
+metadata.
+
+## Migration and compatibility
+
+Enabling team mode is an explicit deployment and project decision. Existing
+local memory, packs, policies, and receipts remain local until individually
+selected for a previewable import. The importer validates schemas and digests,
+shows destination scope and redactions, and requires confirmation. There is no
+automatic upload, background synchronization, or inference from local paths.
+
+Offline local commands keep working when a team service is unavailable. Local
+and server configuration use separate names and provenance so failover cannot
+mistake an unverified local actor for an authenticated subject. Downgrade and
+export paths must be documented before general availability.
+
+## Admission gates
+
+Team mode is not releasable until all of the following have evidence:
+
+1. Threat model and independent security review covering authentication,
+   authorization, confused-deputy attacks, tenant isolation, and audit integrity.
+2. Cross-tenant tests for every read, search, cache, export, backup, and error
+   path, plus concurrent proposal and stale-policy tests.
+3. A privacy review with data inventory, retention/deletion exercises, and
+   proof that local projects never upload implicitly.
+4. Restore and disaster-recovery rehearsal preserving scope, audit links, and
+   revision digests.
+5. A migration pilot using synthetic data, followed by an explicitly approved
+   limited real-world pilot with rollback.
+6. Operational ownership for identity-provider failures, revocation latency,
+   incident response, audit export, and key rotation.
+
+Until these gates pass, Cairnkeep documentation and output must describe actor
+identity as unverified and team support as deferred.

package/docs/harness-compatibility.md

@@ -14,24 +14,25 @@ Cairnkeep commands, hooks or native trajectory capture.
 
 | Harness | Supported surface | Runtime status |
 |---|---|---|
-| Claude Code | Memory MCP, commands, agents, hooks, launcher | Exercised by Cairnkeep tests |
-| OpenCode | Memory MCP, commands, workflows, plugins, launcher | Exercised by Cairnkeep tests |
-| Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph Skill | Launcher tested; remote MCP tested with Kimi Code 0.30.0; graph Skill contract-tested |
-| Qwen Code | Memory MCP, launcher | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
-| Pi | Memory MCP through maintained local stdio extension, native opt-in trajectory extension, launcher, and graph prompt | Pi 0.84.1 validated minimum; deterministic and real bridge/lifecycle tests |
-| Codex CLI | Project-scoped memory MCP and launcher | Setup and launcher contract-tested on POSIX and simulated native Windows; project trust remains operator-controlled |
+| Claude Code | Memory MCP, commands (including `/cairn-work`), agents, hooks, launcher | Exercised by Cairnkeep tests |
+| OpenCode | Memory MCP, commands (including `/cairn-work`), workflows, plugins, launcher | Exercised by Cairnkeep tests |
+| Kimi Code | Memory MCP, `AGENTS.md`, launcher, opt-in graph and cairn-work Skills | Launcher tested; remote MCP tested with Kimi Code 0.30.0; Skills contract-tested |
+| Qwen Code | Memory MCP, launcher, project `AGENTS.md` playbook guidance | Launcher tested; stdio and remote MCP tested with Qwen Code 0.21.1 |
+| Pi | Memory MCP through maintained local stdio extension, native opt-in trajectory extension, launcher, graph and cairn-work prompts | Pi 0.84.1 validated minimum; deterministic and real bridge/lifecycle tests |
+| Codex CLI | Project-scoped memory MCP, launcher, and project `AGENTS.md` playbook guidance | Setup and launcher contract-tested on POSIX and simulated native Windows; project trust remains operator-controlled |
 | Other MCP clients | Memory plus optional domain-knowledge and context-pack tools | Protocol-compatible; not automatically runtime-tested |
 
 Only Claude Code and OpenCode currently receive the complete operating layer.
-Kimi receives one narrow graph Skill, while Pi receives one narrow graph prompt;
+Kimi receives narrow graph and playbook Skills, while Pi receives matching narrow prompts;
 neither is equivalent to the full commands, agents, hooks, and plugins surface.
 Qwen skills and hooks still require harness-specific adaptation and validation.
-Codex receives a project-local MCP entry and launcher, but not Cairnkeep-specific
-commands, hooks, agents, or automatic skill activation.
+Codex receives a project-local MCP entry, launcher, and portable playbook
+instructions, but not Cairnkeep-specific commands, hooks, agents, or automatic
+skill activation.
 
 Every MCP client receives complete tool annotations and may use a Cairnkeep
 least-authority profile independent of harness assets. Context-pack tools are
-ordinary read-only MCP tools and require the pack feature gate; authenticated
+ordinary read-only MCP tools (including imported-OKF link traversal) and require the pack feature gate; authenticated
 HTTP additionally requires separate pack-HTTP consent. Approved pack skills
 remain context documents, not native harness Skills or automatic instructions.
 
@@ -48,7 +49,7 @@ extension; it does not expand the other support levels.
 
 Run `cairn sync-pi --apply` explicitly to install
 `extensions/cairnkeep-memory.ts`, `extensions/cairnkeep-trajectory.ts`, and
-`prompts/graphify.md` under the Pi agent root. Use `--check` for drift and
+`prompts/graphify.md`, and `prompts/cairn-work.md` under the Pi agent root. Use `--check` for drift and
 `cairn doctor` from a project that selected Pi for setup-aware diagnosis. Setup
 reports this machine command but never runs it automatically. Uninstall removes
 only those owned paths, backup-first.

package/docs/learning/CURRICULUM-MAP.md

@@ -1,7 +1,7 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.13.1
-**Last reviewed:** 2026-08-13
+**Baseline:** Cairnkeep 2.15.0
+**Last reviewed:** 2026-08-17
 
 This map prevents the course from drifting behind the product. It assigns each
 user-facing surface to a lesson and records whether the lesson is complete or
@@ -39,6 +39,8 @@ been rehearsed.
 | Native Windows x64 CLI, hooks, ACLs, scheduling, and recovery | L22 | L22 | Ready; PowerShell-native |
 | Guided project setup, selected harness state, and Git-less limitations | L03 | L03 and L23 | Ready |
 | Pi local stdio memory bridge, trusted annotation details, and explicit lifecycle | L23 | L23 | Ready; Pi 0.84.1 validated minimum |
+| OKF 0.1/0.2 validation/import, provenance, links, regressions, and reviewed 0.2 export | L24 | L24 | Ready; local/offline by default |
+| Bounded project playbooks, managed agent guidance, enforcement, and private receipts | L25 | L25 | Ready; balanced/local by default; actor identity unverified |
 
 ## Release Review
 
@@ -69,9 +71,10 @@ repository remains the canonical source for explanations and scripts.
 | `course-07-evaluation` | L16-L17 | Package-owned offline fixture and design boundary |
 | `course-08-graph` | L18 | Optional local structural graph workflow |
 | `course-09-skill` | L19 | Validated skill improvement in a disposable project |
-| `course-10-trust-context` | L20-L21 | MCP authority profiles and offline context-pack lifecycle |
+| `course-10-trust-context` | L20-L21 and L24 | MCP authority profiles, offline context-pack lifecycle, and reviewed OKF exchange |
 | `course-11-windows` | L22 | Native PowerShell lifecycle, ACL inspection, and reversible uninstall |
 | `course-12-guided-setup` | L23 | Deterministic setup, Pi local stdio, recovery, and backup-first uninstall |
+| `course-13-playbooks` | L25 | Policy profiles, lifecycle decisions, enforcement, receipts, and ownership-safe instructions |
 
 ## Command Ownership
 
@@ -87,12 +90,13 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 | `cairn sync-pi` | L13 and L23 |
 | `cairn sync-kimi` | L02 |
 | `cairn doctor` | L03; advanced repair in L13-L14 |
+| `cairn playbook` | L25 |
 | `cairn trajectory` | L13 |
 | `cairn artifact` | L13 |
 | `cairn evidence` | L13 |
 | `cairn capabilities` | L15 |
 | `cairn mcp-tools` | L20 |
-| `cairn pack` | L21 |
+| `cairn pack` | L21 and L24 |
 | `cairn notes` | L13 |
 | `cairn eval` | L16 |
 | `cairn skill` | L19 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.13.1
+**Baseline:** Cairnkeep 2.15.0
 
 This is the step-back map for choosing and operating Cairnkeep features. The
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs) provide one
@@ -15,6 +15,11 @@ trust. See [L03](lessons/L03-first-project.md) and
 Version 2.13 adds local Git-linked work evidence around all generated harness
 launchers; [L13](lessons/L13-session-evidence.md) covers its privacy and
 retention contract.
+Version 2.14 adds OKF 0.1/0.2 import, structured provenance,
+deterministic links, and reviewed OKF 0.2 export; see
+[L24](lessons/L24-okf-exchange.md).
+Version 2.15 adds local bounded playbooks and private outcome receipts; see
+[L25](lessons/L25-playbooks.md).
 
 ## The three-layer model
 
@@ -43,7 +48,8 @@ Run setup in that order, then confirm `cairn doctor`, `cairn sync --check`, and
 | 7 | Evaluation and ablation | A concrete change needs bounded measurement |
 | 8 | Validated skill improvement | Repeated resolved hindsight warrants a measured skill change |
 | 9 | Least-authority MCP profiles | A client should receive fewer tools than the default catalog |
-| 10 | Immutable context packs | Reviewed external context should be pinned without becoming memory |
+| 10 | Immutable context packs and OKF exchange | Reviewed external context should be pinned or exchanged without becoming memory |
+| 11 | Bounded project playbooks | Agents should select proportional workflow checks under inspectable local policy |
 
 Every stage is independently useful. Stages 4-8 are opt-in and are not
 prerequisites for ordinary memory.
@@ -59,6 +65,7 @@ prerequisites for ordinary memory.
 | Repository quality | `/repo-review`, `/security-audit` | On-demand workflow; findings are hypotheses until reproduced | Require file/line evidence and regression tests | `course-03-quality` |
 | Guided project setup | `cairn setup PATH --git init\|existing\|none --harness LIST --memory local\|none --yes` | Reconciles only selected project assets from one harness registry; private `.ai/cairnkeep.json`; machine sync is never automatic | Repeat deterministically, run doctor, or replay its recovery command; Git-less mode remains limited | `course-12-guided-setup` |
 | Codex project memory | Select `--harness codex --memory local` | Writes `.codex/config.toml` plus POSIX/native Windows launchers; local stdio; user-wide configuration and trust remain untouched | Review the MCP table, accept Codex project trust, run doctor, and relaunch; uninstall is backup-first | `course-01-bootstrap` |
+| Workflow playbooks | `cairn playbook check start|check|finish`; project `minimal`, `balanced`, or `strict` policy | Balanced by default; private `.ai/playbooks.json`; optional receipts in `.agentfs/playbooks/`; checks are offline and execute nothing | Inspect status/digests, enforce truthful `must` evidence, inspect receipts, reset overrides, remove only the managed `AGENTS.md` block | `course-13-playbooks` |
 
 ## Storage and optional topology
 
@@ -73,6 +80,7 @@ prerequisites for ordinary memory.
 | Managed overlays | Separate distribution manifest, wrapper, profile lock, fleet and rollback gates | Policy and secrets belong in the private distribution/machine config, never core | `overlay info`, doctor, fleet dry run/current state, rollback | `course-04-operation` |
 | MCP tool profiles | `cairn mcp-tools set full|read-only|custom` | Strict mode-`0600` project config; process overrides take precedence; profile only removes tools | Inspect catalog/status digest; reset and restart MCP | `course-10-trust-context` |
 | Context packs | Manual local or commit-pinned Git install plus project enablement | Immutable objects and atomic pointers under `CAIRN_PACK_BASE_DIR`; no background sync | Validate, inspect digest, check/apply update, disable/remove | `course-10-trust-context` |
+| OKF exchange | `cairn pack validate-okf`, `import-okf`, and preview-confirm `export-okf` | Local import/export by default; explicit file/shared-note allowlist; redacted output | Inspect diagnostics/provenance/output list; exact-digest apply; disable/remove imported pack | `course-10-trust-context` |
 | Pi local stdio memory | Select Pi during setup, then explicitly run `cairn sync-pi --apply` | Local memory-server child; dynamic effective tool catalog; annotations retained in trusted details, not a native Pi field | `cairn sync-pi --check`, `cairn doctor`, cancel one call, then observe awaited shutdown with no orphan | `course-12-guided-setup` |
 
 ## Evidence, governance, and measurement
@@ -89,7 +97,7 @@ prerequisites for ordinary memory.
 | Capability contract | `CAIRN_CAPABILITY_CONTRACT=1` | MCP changes require restart; operating changes apply next invocation | `cairn capabilities list|status|enable|disable|reset|logging`; digest identifies state only | `course-06-governance` |
 | Evaluation | `CAIRN_EVAL=1` for the coordinator process | No harness chosen by Cairnkeep | `validate` before `run`; inspect report, missingness and evidence scope; dry-run prune/delete | `course-07-evaluation` |
 | Validated skill improvement | Reviewed recurring hindsight; proposal adapter; `CAIRN_EVAL=1` for evaluation | No server restart; explicit subprocesses only | `cairn skill list|show`; exact-digest apply; concurrent-edit-safe rollback | `course-09-skill` |
-| General meta-agent loop | Not shipped | Not applicable | Skill-file lifecycle only; no generic configuration loop or scheduler | `course-07-evaluation` |
+| General meta-agent loop | Not shipped | Not applicable | Playbooks select bounded existing actions; no generic configuration loop, command language, or scheduler | `course-07-evaluation` |
 | Pack retrieval and skills | `CAIRN_CONTEXT_PACKS=1`; HTTP needs separate consent; skills need exact-digest approval | Restart MCP server | `cairn pack skills`; revoke approval or disable pack; no automatic execution | `course-10-trust-context` |
 
 ## Harness and maintenance checks
@@ -98,8 +106,8 @@ prerequisites for ordinary memory.
 - For Codex, review `.codex/config.toml` and accept project trust; no machine
   sync is required for the memory-only integration.
 - Run `cairn sync --check` after every core upgrade; apply only reported drift.
-- Run `cairn sync-pi --check` when the Pi memory/trajectory/graph assets are installed.
-- Run `cairn sync-kimi --check` when the optional Kimi graph Skill is installed.
+- Run `cairn sync-pi --check` when the Pi memory/trajectory/graph/playbook assets are installed.
+- Run `cairn sync-kimi --check` when the optional Kimi graph/playbook Skills are installed.
 - Use `cairn doctor --repair` only after preserving the affected store and only
   for repairable derived indexes/metadata.
 - Use `cairn uninstall --dry-run` before uninstall; durable memory is retained

package/docs/learning/README.md

@@ -55,6 +55,8 @@ expanded only after their labs are executable.
 | L21 | [Immutable context packs and skill approval](lessons/L21-context-packs.md) | Ready | 40 min |
 | L22 | [Operate Cairnkeep on native Windows](lessons/L22-native-windows.md) | Ready | 30 min |
 | L23 | [Guided setup and Pi memory](lessons/L23-guided-setup.md) | Ready | 35 min |
+| L24 | [Reviewed knowledge exchange](lessons/L24-okf-exchange.md) | Ready | 35 min |
+| L25 | [Bounded workflow playbooks](lessons/L25-playbooks.md) | Ready | 35 min |
 
 The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
 feature is introduced, practised, and operated. It also marks design-only work
@@ -73,7 +75,7 @@ Every complete lesson contains:
 
 The learner should never need optional infrastructure to complete L00-L06.
 Remote memory, RAG, routing, containers, graph indexing, structured capture,
-typed nodes, capability governance, evaluation, and context packs are separate
+typed nodes, capability governance, evaluation, context packs, OKF exchange, and playbooks are separate
 opt-in modules. MCP profiles are restrictive and never activate an optional
 feature.
 

package/docs/learning/lessons/L00-why-cairnkeep.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.13.1
+**Tested with:** Cairnkeep 2.15.0
 
 ## Outcome
 

package/docs/learning/lessons/L01-safe-trial.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.13.1
+**Tested with:** Cairnkeep 2.15.0
 
 ## Outcome
 
@@ -26,7 +26,7 @@ ephemeral; the named course volume is persistent.
 1. Pull the public image:
 
    ```bash
-   podman pull ghcr.io/cairnkeep/cairnkeep:2.13.1
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.14.0
    ```
 
 2. Start the stdio server with a read-only root filesystem and no Linux
@@ -38,7 +38,7 @@ ephemeral; the named course volume is persistent.
      --read-only --cap-drop=all --security-opt=no-new-privileges \
      --tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777 \
      --volume cairnkeep-course-data:/data:Z,U \
-     ghcr.io/cairnkeep/cairnkeep:2.13.1 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.14.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it

package/docs/learning/lessons/L02-installation.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.13.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -47,7 +47,7 @@ sync. Codex project trust remains an explicit operator decision.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.13.1
+   npm install --global @cairnkeep/cli@2.14.0
    cairn --version
    ```
 

package/docs/learning/lessons/L03-first-project.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 25 minutes
-**Tested with:** Cairnkeep 2.13.1
+**Tested with:** Cairnkeep 2.15.0
 
 ## Outcome
 

package/docs/learning/lessons/L19-validated-skill-improvement.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Evidence and Evaluation
 **Time:** 50 minutes
-**Tested with:** Cairnkeep 2.13.1
+**Tested with:** Cairnkeep 2.15.0
 
 ## Outcome
 

package/docs/learning/lessons/L20-mcp-tool-profiles.md

@@ -1,7 +1,7 @@
 # L20 - Least-authority MCP tool profiles
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.13.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.0 and Node.js 22 or newer
 **Time:** 25 minutes
 
 ## Outcome

package/docs/learning/lessons/L21-context-packs.md

@@ -1,7 +1,7 @@
 # L21 - Immutable context packs and skill approval
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.13.1 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.0 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome
@@ -77,3 +77,7 @@ rm -rf "$lab"
 - `CAIRN_CONTEXT_PACKS=1` enables local read-only tools only after restart.
 - HTTP additionally requires `CAIRN_CONTEXT_PACK_HTTP=1` and existing auth.
 - A digest proves integrity, not publisher authenticity.
+
+Continue with [L24](L24-okf-exchange.md) for structured OKF provenance,
+deterministic related-document retrieval, regression diagnostics, and the
+privacy-reviewed export workflow.

package/docs/learning/lessons/L22-native-windows.md

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.13.1, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.15.0, Windows x64, and Node.js 22 or newer
 
 ## Outcome
 
@@ -16,7 +16,7 @@ perform a reversible uninstall without relying on WSL or Git Bash.
 From PowerShell:
 
 ```powershell
-npm install --global @cairnkeep/cli@2.13.1
+npm install --global @cairnkeep/cli@2.14.0
 cairn version
 
 $Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'