@cairnkeep/cli 2.15.4 → 2.16.0

package/docs/README.md

@@ -0,0 +1,79 @@
+# Cairnkeep documentation
+
+This is the versioned documentation index for Cairnkeep. Start with the path
+that matches what you are trying to do; detailed configuration belongs in the
+linked guides rather than the project landing page.
+
+## Start here
+
+| Goal | Guide |
+|---|---|
+| Install Cairnkeep and configure a first project | [Quickstart](quickstart.md) |
+| Understand how coding agents should use Cairnkeep | [Cairnkeep for coding agents](agents.md) |
+| Compare Claude Code, OpenCode, Codex, Kimi, Qwen, Pi, and generic MCP support | [Harness compatibility](harness-compatibility.md) |
+| Follow the complete operator reference | [Operating Cairnkeep](operating.md) |
+| Learn Cairnkeep progressively or produce the video series | [Learning paths and video scripts](learning/README.md) |
+
+## Agents and harnesses
+
+- [Cairnkeep for coding agents](agents.md) explains retrieval-first behavior,
+  memory authority, playbooks, approvals, and graceful fallback.
+- [Harness compatibility](harness-compatibility.md) records the exact commands,
+  hooks, plugins, launchers, skills, and MCP surfaces available in each client.
+- [MCP tool annotations and least-authority profiles](mcp-tool-profiles.md)
+  explains observation/action metadata and project tool allowlists.
+- [Immutable context packs](context-packs.md) covers approved external documents
+  and skills that remain read-only context rather than executable harness assets.
+- [Validated skill improvement](skill-improvement.md) describes the reviewed,
+  measured, reversible path for changing a live skill.
+
+## Operations, storage, and privacy
+
+- [Operating Cairnkeep](operating.md) is the full CLI and configuration
+  reference.
+- [Memory storage and deployment](storage.md) documents local and remote stores,
+  retention, backup, migration, and uninstall behavior.
+- [Privacy and data flow](privacy-and-data-flow.md) maps what each opt-in feature
+  reads, stores, and may send over the network.
+- [Git-linked work evidence](work-evidence.md) covers bounded local session-to-Git
+  provenance without prompt or reasoning capture.
+- [Optional document knowledge](domain-knowledge.md) covers the separately
+  configured document-RAG integration.
+
+## Deployment and platforms
+
+- [Containers](containers.md) covers rootless Podman, OCI images, authenticated
+  HTTP, and persistent storage.
+- [Native Windows](native-windows.md) covers x64 setup, launchers, ACLs,
+  scheduling, process cleanup, and recovery.
+- [Git providers](git-providers.md) describes provider-neutral Git-linked
+  workflows.
+
+## Exchange and ecosystem
+
+- [Open Knowledge Format exchange](open-knowledge-format.md) covers importing
+  and exporting portable knowledge bundles.
+- [Companion tools and related projects](ecosystem.md) lists optional tools that
+  complement Cairnkeep without becoming runtime dependencies.
+
+## Overlays and teams
+
+- [Building an overlay](building-an-overlay.md) explains how to add private
+  provider or organization policy without forking the core.
+- [Managed overlay distributions](overlay-distributions.md) covers wrapper CLIs,
+  policy locks, private registries, and rollback.
+- [Team-mode design](design/team-mode.md) records the current team workflow
+  boundary and deferred multi-user concerns.
+- [Meta-agent design](design/meta-agent.md) records the bounded workflow design
+  behind Cairnkeep playbooks.
+
+## Contributing and releases
+
+- [Contributing](../CONTRIBUTING.md)
+- [Release process](releasing.md)
+- [Support](../SUPPORT.md)
+- [Security policy](../SECURITY.md)
+
+These files ship with the repository and npm package, so documentation stays
+reviewable and version-aligned with the code. A website or GitHub Wiki may
+mirror them later, but should not become a second source of truth.

package/docs/agents.md

@@ -0,0 +1,173 @@
+# Cairnkeep for coding agents
+
+Cairnkeep gives a coding agent durable project context and bounded workflow
+guidance. It does not replace repository inspection, decide what is true, or
+turn a harness into an autonomous Cairnkeep runtime.
+
+This guide is for both agents and the people configuring them.
+
+## The agent contract
+
+For a nontrivial task that may depend on previous decisions, conventions,
+constraints, recurring failures, or prior work:
+
+1. Derive one short query directly from the user's task.
+2. If `memory_search` is available, make that project-scoped search the first
+   tool or command. Do not inspect the repository first merely to formulate the
+   query.
+3. Treat every result as a locator. Read and verify the maintained repository
+   sources it references before using it to make a change.
+4. If the tool is unavailable or the result is irrelevant, continue with
+   ordinary repository inspection. Do not repeat or broaden searches simply to
+   force a memory hit.
+5. Do not call `memory_write`, supersede a record, approve content, or promote
+   durable knowledge unless the user or an applicable reviewed workflow
+   explicitly requests capture.
+
+This protocol improves continuity without allowing stale memory to outrank
+code, tests, current documentation, or the user's request.
+
+## What setup installs
+
+`cairn setup` reconciles a delimited Cairnkeep block in the project's
+`AGENTS.md` while preserving surrounding user content and file mode. The block
+contains the durable-context contract above and bounded playbook instructions.
+It can be removed independently with:
+
+```bash
+cairn playbook instructions remove
+```
+
+The selected harness determines which project assets setup creates. Setup
+reports but never performs machine-level sync. Claude Code and OpenCode receive
+the complete operating layer only after the operator runs the reported
+`cairn sync --apply` command; Codex, Qwen, Kimi, and Pi have narrower
+integrations. See [Harness compatibility](harness-compatibility.md) for the
+exact tested surface. Instruction presence is not evidence that an agent
+actually invoked a tool.
+
+## Memory scopes and authority
+
+Use `scope: project` for task-specific decisions and conventions. Broader
+scopes may be configured, but an agent should not widen a search merely to find
+an answer. The read-only virtual `all` scope is useful only when the task truly
+crosses configured scopes.
+
+Memory remains a secondary source:
+
+```text
+user request + maintained repository sources
+                    ↓ verify
+           durable memory locator
+                    ↓ apply
+             implementation decision
+```
+
+If a memory record conflicts with current code, tests, policy, or explicit user
+direction, follow the current authoritative source and report the conflict.
+Correct or supersede the durable record only through an explicitly approved
+workflow.
+
+## Bounded playbooks
+
+The project policy in `.ai/playbooks.json` helps an agent decide which existing
+recall, planning, verification, review, security, documentation, and learning
+steps apply. Check it at task boundaries:
+
+```bash
+cairn playbook check start \
+  --session SESSION \
+  --complexity standard \
+  --familiarity mixed
+
+cairn playbook check check
+
+cairn playbook check finish \
+  --session SESSION \
+  --changed PATH... \
+  --risk normal \
+  --completed ACTION... \
+  --skipped ACTION=REASON... \
+  --enforce
+```
+
+Complexity accepts `trivial`, `standard`, or `complex`; familiarity accepts
+`known`, `mixed`, or `unfamiliar`; risk accepts `low`, `normal`, `high`, or
+`security`. Follow every applicable `must` action, apply `should` actions unless
+there is a concrete reason to skip them, and use judgment for `may` actions.
+Re-check when scope, familiarity, complexity, or risk changes materially. Exit
+3 means enforced `must` evidence is missing; exit 2 means invalid input or a
+policy diagnostic. Neither is permission to relabel failed work as complete.
+
+A playbook result selects existing actions only. It cannot:
+
+- execute a command or workflow;
+- enable a disabled feature or capability;
+- activate a context-pack skill;
+- grant approval or authorize destructive work;
+- write or promote durable memory automatically; or
+- prove that an agent followed the recommendation.
+
+After a successful finish check, material outcomes can be recorded with the
+exact policy and decision digests returned by the check. Run
+`cairn playbook record --help` for the bounded values. Actor identity is a
+caller-supplied local label, not authenticated identity.
+
+## Tool authority
+
+Every Cairnkeep MCP tool has explicit read-only, destructive, idempotent, and
+open-world annotations. Operators can restrict discovery with a `read-only` or
+exact custom profile:
+
+```bash
+cairn mcp-tools status
+cairn mcp-tools set read-only
+cairn mcp-tools set custom --tool memory_read --tool memory_search
+```
+
+Effective discovery is the intersection of available feature gates, the
+capability contract, and the MCP tool profile. A profile can remove tools but
+cannot enable a disabled feature. An annotation describes a tool; it does not
+grant permission or replace the harness's approval policy. See
+[MCP tool profiles](mcp-tool-profiles.md).
+
+## Documents and skills from context packs
+
+Enabled context-pack documents are read-only external context. Skill files are
+invisible until an operator approves their exact project, pack digest, path,
+and file digest. Even then, they are discoverable text through MCP—not copied
+into a harness, automatically activated, or executed. A pack update invalidates
+the old approval. See [Immutable context packs](context-packs.md).
+
+## Graceful fallback
+
+Cairnkeep should never block ordinary engineering merely because optional
+context is unavailable:
+
+- No memory tool: inspect the repository and state the limitation.
+- No relevant memory: continue after the single bounded search.
+- No playbook CLI or capability: follow the documented policy intent manually;
+  never invent a successful check or receipt.
+- Embedding endpoint failure: supported searches fall back to deterministic
+  local substring matching.
+- Disabled tool or feature: do not work around the operator's authority
+  boundary.
+
+Run `cairn doctor` when the project is expected to have Cairnkeep wiring but a
+tool, launcher, or managed asset is missing.
+
+## Operator checklist
+
+Before expecting an agent to use Cairnkeep:
+
+1. Configure the project with `cairn setup` for the intended harness.
+2. Run `cairn doctor` and review any operator-owned files reported as skipped.
+3. Inspect the managed `AGENTS.md` block and `.ai/playbooks.json` policy.
+4. Review the effective catalog with `cairn mcp-tools status`.
+5. Keep durable memory concise and point it at maintained sources whenever
+   possible.
+6. Treat runtime evidence—not instruction presence—as proof of tool use.
+
+Continue with the [quickstart](quickstart.md), the
+[operating guide](operating.md), and the
+[privacy and data-flow reference](privacy-and-data-flow.md).

package/docs/ecosystem.md

@@ -0,0 +1,23 @@
+# Companion tools and related projects
+
+Cairnkeep's core memory server, project setup, wiki, and review assets run
+without any of the tools below. Optional delegated exploration, routing, and
+graph workflows have their own explicit companion requirements.
+
+## Related project
+
+- [token-miser](https://github.com/cairnkeep/token-miser) owns context
+  exploration and request routing. Cairnkeep's optional `context_explore` and
+  `route_check` MCP tools are thin, environment-gated delegates to it.
+
+## Optional companion tools
+
+| Tool | What it adds | Integration |
+|---|---|---|
+| [lean-ctx](https://github.com/yvgude/lean-ctx) | Compressed file reads, searches, shell output, and directory maps | Register it as an MCP server in the chosen harness |
+| [token-miser](https://github.com/cairnkeep/token-miser) | Model routing and compact codebase exploration | Configure `CAIRN_ROUTE_ENDPOINT` and/or `CAIRN_EXPLORE_BINARY` |
+| [rtk](https://github.com/rtk-ai/rtk) | Token-reduced output for common Git, npm, and Cargo commands | Install as a shell-level proxy; Cairnkeep wiring is not required |
+
+These integrations are accelerators, not part of Cairnkeep's trust boundary or
+runtime dependency set. Review each project's installation and data-flow
+documentation independently before enabling it.

package/docs/learning/CURRICULUM-MAP.md

@@ -1,6 +1,6 @@
 # Curriculum Coverage Map
 
-**Baseline:** Cairnkeep 2.15.4
+**Baseline:** Cairnkeep 2.16.0
 **Last reviewed:** 2026-08-19
 
 This map prevents the course from drifting behind the product. It assigns each

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.15.4
+**Baseline:** Cairnkeep 2.16.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
@@ -67,7 +67,7 @@ prerequisites for ordinary memory.
 | Wiki and alignment | `/wiki-ingest`, `/wiki-query`, `/wiki-lint`, alignment files | Written only when invoked; reviewable `.planning/` artifacts | Re-run lint, inspect source citations, revert tracked changes normally | `course-02-memory` |
 | Local code graph | `cairn graph build|query|status|diff|explain|path`; `/graphify` delegates | Default off; optional isolated `graphify` executable; incremental work under `graphify-out/`, published view under `.planning/graphs/` | Ignore both derived locations; check status and source before trusting a result; use `--force` only after intentional deletion; uninstall adapters separately | `course-08-graph` |
 | 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` |
+| Guided project setup | `cairn setup [PATH]` selectors; deterministic `--git`, `--harness`, `--memory`, and `--yes` flags | Arrow-key Git/memory choices and harness checkboxes in capable terminals; text fallback otherwise; reconciles only selected assets; 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 and durable-context guidance | `cairn playbook check start|check|finish`; project `minimal`, `balanced`, or `strict` policy; managed `AGENTS.md` retrieval protocol | Balanced by default; private `.ai/playbooks.json`; one task-derived project search when applicable; optional receipts in `.agentfs/playbooks/`; checks are offline and execute nothing | Verify the actual memory tool event and maintained source, inspect status/digests, enforce truthful `must` evidence, inspect receipts, reset overrides, remove only the managed `AGENTS.md` block | `course-13-playbooks` |
 

package/docs/learning/README.md

@@ -19,6 +19,9 @@ Choose the shortest track that matches your goal:
 
 For a single view of every released surface, its default, storage boundary,
 restart requirement, and rollback path, use the [feature guide](FEATURE-GUIDE.md).
+The public [coding-agent guide](../agents.md) is the concise normative reference
+for retrieval-first behavior, memory authority, playbooks, and graceful
+fallback used throughout the lessons.
 The public [course labs](https://github.com/cairnkeep/cairnkeep-course-labs)
 provide one synthetic project with tagged checkpoints shared by lessons,
 articles, workshops, and videos.

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 10 minutes
-**Tested with:** Cairnkeep 2.15.4
+**Tested with:** Cairnkeep 2.16.0
 
 ## Outcome
 
@@ -92,4 +92,6 @@ configuration and are taught later.
 - Derived knowledge remains subordinate to canonical sources.
 - Optional services are not prerequisites.
 
+Reference: [Cairnkeep for coding agents](../../agents.md).
+
 Next: [L01 - Try it safely](L01-safe-trial.md).

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.15.4
+**Tested with:** Cairnkeep 2.16.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.14.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.16.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.14.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.16.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.15.4 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.16.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.14.0
+   npm install --global @cairnkeep/cli@2.16.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.15.4
+**Tested with:** Cairnkeep 2.16.0
 
 ## Outcome
 
@@ -26,20 +26,19 @@ recall it from a new session.
    cd "$HOME/cairnkeep-course/first-project"
    ```
 
-2. Choose one harness and run the deterministic form of guided setup. The
-   explicit flags make the
-   exercise reproducible while exercising the same preflight as interactive
-   `cairn setup`:
+2. Run the interactive setup and choose a harness. Use Up/Down and Enter for
+   Git and memory choices; use Space to tick Claude Code or Codex CLI in the
+   harness checklist. Review the plan before selecting **Yes, apply the plan**:
 
    ```bash
-   # Full operating-layer route from L02:
-   cairn setup "$PWD" --git init --harness claude --memory local --yes
-
-   # Or the self-contained Codex memory route:
-   # cairn setup "$PWD" --git init --harness codex --memory local --yes
+   cairn setup "$PWD"
    cp .ai/env.example .ai/.env
    ```
 
+   For a reproducible non-interactive exercise, the equivalent Claude Code
+   command is `cairn setup "$PWD" --git init --harness claude --memory local
+   --yes`; replace `claude` with `codex` for the self-contained Codex route.
+
    Setup must create the Git repository, generate only the selected harness
    assets, and write the private `.ai/cairnkeep.json` setup record. Codex also
    receives `.codex/config.toml`; review it and accept Codex's project-trust

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.15.4
+**Tested with:** Cairnkeep 2.16.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.15.4 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.16.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.15.4 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.16.0 and Node.js 22 or newer
 **Time:** 40 minutes
 
 ## Outcome

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Operator
 **Time:** 30 minutes
-**Tested with:** Cairnkeep 2.15.4, Windows x64, and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.16.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.14.0
+npm install --global @cairnkeep/cli@2.16.0
 cairn version
 
 $Lab = Join-Path $env:TEMP 'Cairnkeep Windows Lab'

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

@@ -3,13 +3,14 @@
 **Status:** Ready
 **Track:** Quickstart and Operator
 **Time:** 35 minutes
-**Tested with:** Cairnkeep 2.15.4; Pi 0.84.1; Node.js 22, 24, and 26
+**Tested with:** Cairnkeep 2.16.0; Pi 0.84.1; Node.js 22, 24, and 26
 
 ## Outcome
 
-You can classify a missing or empty target, replay setup without a TTY, explain
-the limitations of Git-less mode, verify Pi's local stdio memory bridge, and
-recover or uninstall every managed asset without hidden machine changes.
+You can use the guided terminal selectors, classify a missing or empty target,
+replay setup without a TTY, explain the limitations of Git-less mode, verify
+Pi's local stdio memory bridge, and recover or uninstall every managed asset
+without hidden machine changes.
 
 The selected harnesses come from Cairnkeep's declarative registry. Codex is a
 supported selection: it receives `.codex/config.toml` and a launcher, while Pi
@@ -24,6 +25,18 @@ continues to require its separate explicit machine sync.
 
 ## Exercise
 
+First experience the interactive path:
+
+```bash
+cairn setup /tmp/cairnkeep-guided-selector-lab
+```
+
+Choose Git with Up/Down and Enter, tick Pi with Space in the harness checklist,
+keep local memory, then inspect the plan before confirming. Pressing Escape or
+Ctrl-C cancels; redirected and limited terminals use the documented text-input
+fallback. Remove that disposable selector lab before continuing if you applied
+the plan.
+
 Start with a missing target. The explicit flags make this deterministic and
 safe to replay from a non-interactive or non-TTY process:
 
@@ -112,7 +125,7 @@ and context packs remain unless their separate purge flags are supplied.
 
 | Symptom | Cause | Recovery |
 |---|---|---|
-| Setup refuses a missing target | The non-interactive command omitted an explicit choice or `--yes` | Supply the target, `--git`, `--harness`, `--memory`, and `--yes` together |
+| Setup refuses a missing target | The non-interactive command omitted an explicit choice or `--yes` | Run `cairn setup PATH` in a terminal, or supply the target, `--git`, `--harness`, `--memory`, and `--yes` together |
 | Setup refuses `--git existing` | The target is not inside a Git work tree | Choose an existing repository, or explicitly authorize `--git init`; use `--git none` only when limited mode is intended |
 | Doctor reports missing or drifted Pi assets | Project setup selected Pi but machine sync is incomplete | Run `cairn sync-pi --apply`, then `cairn sync-pi --check` and `cairn doctor` |
 | A cancelled call ends the session | The Pi/bridge version does not satisfy the per-call cancellation contract | Preserve sanitized diagnostics, close the session, and do not claim release readiness |

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

@@ -1,7 +1,7 @@
 # L24 - Reviewed knowledge exchange
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.15.4 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.16.0 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

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

@@ -1,7 +1,7 @@
 # L25 - Bounded workflow playbooks
 
 **Status:** Ready
-**Tested with:** Cairnkeep 2.15.4 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.16.0 and Node.js 22 or newer
 **Time:** 35 minutes
 
 ## Outcome

package/docs/native-windows.md

@@ -13,6 +13,11 @@ and `--untracked` bootstrap. Explicit `--git none` provides the same documented
 limited mode as POSIX setup.
 The optional `sqlite3.exe` command enables WAL-safe `cairn memory export`.
 
+From an interactive PowerShell or Command Prompt, `cairn setup $Project`
+presents native arrow-key Git and memory selectors plus a Space-toggle harness
+checklist. The explicit form below remains preferable for scripts and fleet
+automation:
+
 ```powershell
 npm install --global @cairnkeep/cli
 cairn version

package/docs/operating.md

@@ -24,6 +24,9 @@ sync command but never runs it automatically. This guide covers all three.
   memory MCP, launcher, and opt-in graph Skill; Qwen Code receives the memory
   MCP and launcher. Pi receives a maintained local stdio MCP extension, native
   trajectory adapter, graph prompt, and launcher after explicit machine sync.
+- Cairnkeep 1.x remains the legacy line for older Node.js runtimes. New
+  installations should use the supported Cairnkeep 2.x and Node.js 22-or-newer
+  matrix.
 - Optional: the `sqlite3` CLI for `cairn memory export`. Runtime memory and
   `cairn memory import` do not require it.
 - Optional: an OpenAI-compatible LLM endpoint for memory extraction and
@@ -61,9 +64,11 @@ Invoke-Expression (& cairn completion powershell | Out-String)
 
 ## Guided project setup
 
-Interactive terminals may run `cairn setup` and answer the target, Git,
-harness, memory, and confirmation questions. Automation must make every choice
-explicit:
+Interactive terminals may run `cairn setup [PATH]`. Use Up/Down and Enter for
+Git and memory, Space to tick one or more harness checkboxes, `a` to toggle all
+harnesses, and the final selectable confirmation before anything is written.
+If the terminal cannot provide raw keyboard input, Cairnkeep falls back to the
+original text questions. Automation must make every choice explicit:
 
 ```bash
 cairn setup /path/to/project --git init --harness claude,pi --memory local --yes
@@ -890,6 +895,19 @@ Inspect receipts with `cairn playbook receipts list|show`; validate state with
 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 corresponding process overrides are optional:
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `CAIRN_PLAYBOOK_PROFILE` | project policy, then `balanced` | Select `minimal`, `balanced`, or `strict` without changing the project file |
+| `CAIRN_PLAYBOOK_ACTOR` | `local-agent` | Supply the unauthenticated local actor label used by checks and receipts |
+| `CAIRN_PLAYBOOK_ACTOR_KIND` | `agent` | Classify the local actor as `user`, `agent`, or `service` |
+| `CAIRN_PLAYBOOK_SESSION` | `local-<process-id>` | Supply the bounded local session label used by decisions and receipts |
+
+Command-line `--actor`, `--actor-kind`, and `--session` values take precedence
+over these process defaults. None of these labels establish identity or grant
+authority.
+
 The managed instruction lifecycle is explicit and ownership-safe:
 
 ```bash

package/docs/quickstart.md

@@ -7,18 +7,19 @@ the default store stays on this computer.
 ## Codex CLI
 
 Install Cairnkeep, then let guided setup initialize an empty project and write
-Codex's project-scoped MCP entry:
+Codex's project-scoped MCP entry. Select **Initialize a Git repository**,
+tick **Codex CLI** with Space, keep local memory, review the plan, and apply it:
 
 ```bash
 npm install --global @cairnkeep/cli
-cairn setup /path/to/project --git init --harness codex --memory local --yes
+cairn setup /path/to/project
 cd /path/to/project
 cairn doctor
 ./.ai/start-codex.sh
 ```
 
-Use `--git existing` instead when the target is already a Git work tree. On
-native Windows, launch with `.\.ai\start-codex.cmd`.
+The wizard recommends the existing repository mode when the target is already
+a Git work tree. On native Windows, launch with `.\.ai\start-codex.cmd`.
 
 Before the first session, review `.codex/config.toml` and accept Codex's project
 trust prompt. The generated entry runs `cairn memory-server` locally. Setup
@@ -53,6 +54,13 @@ cairn doctor
 Setup reports machine-level commands but never executes them. This keeps
 project scaffolding separate from harness-wide changes.
 
+For scripts, CI, or reproducible fleet setup, skip the selector and provide all
+choices explicitly:
+
+```bash
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+```
+
 ## First memory cycle
 
 In a harness with Cairnkeep commands, remember one durable fact and recall it: