@cairnkeep/cli 2.15.4 → 2.17.0

package/docs/README.md

@@ -0,0 +1,87 @@
+# 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.
+
+## Context intelligence
+
+- [Context intelligence](context-intelligence.md) connects progressive context-pack
+  retrieval, the frozen benchmark, usage receipts, review-gated proposals, and
+  the optional read-only OpenViking provider.
+- [Immutable context packs](context-packs.md), [domain knowledge](domain-knowledge.md),
+  and [work evidence](work-evidence.md) document each boundary in depth.
+
+## 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,193 @@
+# 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).
+
+## Progressive retrieval and reviewed-memory proposals
+
+When `context_pack_tree` is available, inspect abstracts before requesting full
+content. Use hierarchical search for broad questions, exact path/title retrieval
+for known leaves, and `explain: true` only when the bounded selection trace helps
+debug retrieval. Default flat search remains valid and compatible.
+
+Stable result references are opt-in (`include_refs: true`). If the operator also
+enables `context_usage_record`, record only whether the cited result was used;
+never put prompts or content into digest fields. Treat recording as a mutation.
+
+`cairn proposals create` may suggest reviewed-memory candidates from a stored,
+redacted trajectory, but an agent must inspect the proposal and use
+`cairn proposals apply DIGEST` explicitly. Never treat extraction output as
+reviewed truth, auto-apply it, or work around a stale-source/base-memory failure.
+
+The optional OpenViking provider changes only how `domain_knowledge_query`
+retrieves external context. It does not replace Cairnkeep's memory, evidence,
+pack, or authority model.
+
+## 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/context-intelligence.md

@@ -0,0 +1,143 @@
+# Context intelligence
+
+Cairnkeep can retrieve immutable project context progressively, measure retrieval
+quality, record privacy-preserving usage evidence, and propose reviewed-memory
+changes. These features keep the existing authority model: retrieval is an
+observation; durable-memory changes require an explicit review and apply step.
+
+## Progressive context-pack retrieval
+
+Enable context packs for the process with `CAIRN_CONTEXT_PACKS=1`. The existing
+`context_pack_list`, `context_pack_search`, and `context_pack_read` tools remain
+available, and the default search remains the compatible flat, content-level
+search. Two optional surfaces add progressive disclosure:
+
+- `context_pack_tree` returns only enabled documents and approved skills, using
+  `abstract` or `overview` detail.
+- `context_pack_search` accepts `strategy: "hierarchical"`,
+  `detail: "abstract" | "overview" | "content"`, and `explain: true`.
+
+For example:
+
+```json
+{
+  "query": "release validation",
+  "strategy": "hierarchical",
+  "detail": "overview",
+  "explain": true,
+  "include_refs": true
+}
+```
+
+Hierarchical search ranks pack, directory, and file summaries before reading
+content. An exact path or title can bypass the hierarchy and select the matching
+leaf directly. `explain` adds a bounded, sanitized decision trace. It never adds
+hidden file content to the trace.
+
+Abstracts and overviews are deterministic derived data. They are cached below
+the pack base directory in `cache/context/`, outside immutable pack objects, and
+are bound to the pack digest and exact visible-file set. `cairn doctor` validates
+this cache and can remove invalid derived entries; it does not enable a pack or
+approve a skill.
+
+Visibility is unchanged: a document must belong to an enabled pack, while a
+skill must also have a current project approval matching the pack digest, path,
+and file digest. Updating a pack therefore invalidates its old skill approvals.
+Pack SHA-256 digests establish integrity, not publisher authenticity.
+
+## Retrieval benchmark
+
+The repository includes a frozen synthetic benchmark with hierarchical files,
+multiple versions, and a hidden skill. Positive retrieval cases report Hit@1,
+Recall@5, and MRR; negative-only isolation cases report their count, pass rate,
+and leaks separately. The report also covers relevant/irrelevant bytes, an
+estimated token count, latency, network and filesystem mutations, and leakage
+from disabled packs, unapproved skills, case-specific exclusions, or undeclared
+result identities. Frozen substring and deterministic mock-embedding goldens
+make regression checks offline and reproducible.
+
+From a source checkout:
+
+```sh
+npm --prefix mcp-memory-server run build
+npm --prefix mcp-memory-server run check:retrieval-benchmark
+npm --prefix mcp-memory-server run benchmark:retrieval
+```
+
+The first command compiles the TypeScript sources. The second runs the contract
+smoke test and checks the frozen golden. The third rebuilds and emits a current
+report.
+The benchmark is an engineering baseline, not a claim about every real project.
+
+## Context-usage receipts
+
+Search results can include stable references by setting `include_refs: true`.
+Each result then has a `chunk_digest`, and the response has a `result_digest`.
+With work evidence enabled, set `CAIRN_CONTEXT_USAGE=1` as the second consent
+gate to expose the local-only `context_usage_record` MCP mutation, then record
+whether a referenced result was used. The tool is not registered unless both
+`CAIRN_WORK_EVIDENCE=1` and `CAIRN_CONTEXT_USAGE=1` are active:
+
+```json
+{
+  "task_digest": "<64-lowercase-hex-digest>",
+  "result_digest": "<64-lowercase-hex-digest>",
+  "outcome": "used"
+}
+```
+
+`outcome` is `used`, `unused`, or `unknown`. The receipt links to the active work
+evidence unless `evidence_id` is supplied explicitly. It stores digests and the
+outcome, not the query, prompt, retrieved content, or model response. The tool is
+a mutation, so the read-only MCP profile does not expose it. Receipts are strict,
+idempotent links in the existing work-evidence store and follow its retention.
+
+## Review-gated memory proposals
+
+`cairn proposals` turns a stored, redacted trajectory into candidates for
+reviewed durable memory. It never applies candidates during extraction:
+
+```sh
+cairn proposals create --session SESSION_ID --scope project --json
+cairn proposals list --json
+cairn proposals show PROPOSAL_DIGEST --json
+cairn proposals apply PROPOSAL_DIGEST --json
+cairn proposals doctor --json
+```
+
+`create` loads the named local trajectory, redacts it again before any configured
+model call, and writes an immutable, digest-addressed proposal under
+`.agentfs/memory-proposals/`. The digest binds the source, extraction, base memory,
+and candidates. `apply` accepts that exact digest, rechecks source and base-memory
+freshness, and then performs the reviewed-memory write atomically. A stale or
+tampered proposal fails instead of being rebased or silently accepted.
+
+Model extraction uses the existing `CAIRN_LLM_API_URL`, `CAIRN_LLM_API_KEY`, and
+`CAIRN_LLM_EXTRACTION_MODEL` settings. No background hook creates or applies
+proposals.
+
+## Optional OpenViking retrieval provider
+
+AnythingLLM remains the default domain-retrieval provider. OpenViking is an
+optional, read-only adapter behind two explicit settings:
+
+```sh
+CAIRN_DOMAIN_RETRIEVAL_PROVIDER=openviking
+CAIRN_OPENVIKING=1
+CAIRN_OPENVIKING_BASE_URL=http://127.0.0.1:1933
+# Optional:
+CAIRN_OPENVIKING_API_KEY=...
+CAIRN_OPENVIKING_TIMEOUT_MS=5000
+```
+
+The existing `domain_knowledge_query` tool keeps its schema. The adapter calls
+only OpenViking's search endpoint; Cairnkeep does not import, sync, watch, delete,
+or commit OpenViking data. Plain HTTP is accepted only for loopback hosts; other
+hosts require HTTPS. Embedded URL credentials, redirects, oversized responses,
+and invalid response shapes are rejected. Authenticated remote MCP deployment
+also requires the separate `CAIRN_OPENVIKING_MCP_HTTP=1` consent flag.
+
+OpenViking does not replace Cairnkeep. It can supply an external retrieval index;
+Cairnkeep still owns project identity, reviewed memory, immutable context-pack
+pins, tool authority, evidence, and approval boundaries. No OpenViking package or
+service is required for the default Cairnkeep installation.

package/docs/context-packs.md

@@ -95,6 +95,39 @@ Authenticated HTTP deployments need the separate
 project header. Pack digests prove integrity, not publisher authenticity.
 Publisher signatures remain future work.
 
+## Progressive hierarchy and stable result references
+
+The default `context_pack_search` request remains flat content search, preserving
+the established schema and response shape. Agents can opt into progressive
+disclosure without changing pack contents:
+
+```json
+{
+  "query": "deployment rollback",
+  "strategy": "hierarchical",
+  "detail": "overview",
+  "explain": true,
+  "include_refs": true
+}
+```
+
+`strategy` is `flat` or `hierarchical`; `detail` is `abstract`, `overview`, or
+`content`. The optional trace is bounded and sanitized. `context_pack_tree`
+returns the visible hierarchy at `abstract` or `overview` detail, optionally
+limited by pack ID, `id@version`, or digest.
+
+Summaries are deterministic derived cache entries below
+`${CAIRN_PACK_BASE_DIR:-~/.cairnkeep/packs}/cache/context/`. They are bound to the
+pack digest and visible-file-set digest, not stored in immutable objects, and can
+be rebuilt without choosing an enabled version or granting approval. Search with
+`include_refs: true` adds per-result `chunk_digest` values and a response-level
+`result_digest` for optional usage receipts.
+
+Only enabled documents and explicitly approved skills contribute to the tree,
+summary cache, search results, or explanation trace. A skill approval remains
+bound to project identity, pack digest, path, and file digest; a changed pack
+digest cannot inherit it.
+
 ## Open Knowledge Format exchange
 
 Use `cairn pack validate-okf` and `cairn pack import-okf` to consume OKF 0.1 or

package/docs/domain-knowledge.md

@@ -96,6 +96,35 @@ copy of the example JSON at the default user config path, or set
 and state beside the script retain that legacy behavior. To customize the
 implementation itself, set `CAIRN_ANYTHINGLLM_SYNC_SCRIPT` to the adapted copy.
 
+## Retrieval providers
+
+AnythingLLM remains the default. Selecting it explicitly is optional:
+
+```sh
+CAIRN_DOMAIN_RETRIEVAL_PROVIDER=anythingllm
+```
+
+OpenViking can instead back the existing read-only `domain_knowledge_query`
+tool. It is deliberately double-gated and has no sync or write path:
+
+```sh
+CAIRN_DOMAIN_RETRIEVAL_PROVIDER=openviking
+CAIRN_OPENVIKING=1
+CAIRN_OPENVIKING_BASE_URL=http://127.0.0.1:1933
+# CAIRN_OPENVIKING_API_KEY=...
+# CAIRN_OPENVIKING_TIMEOUT_MS=5000
+```
+
+Plain HTTP is limited to loopback. Use HTTPS for any other host. Credentials in
+the URL, redirects, invalid response shapes, and oversized bodies are rejected.
+Authenticated remote MCP use requires the additional explicit consent setting
+`CAIRN_OPENVIKING_MCP_HTTP=1`.
+
+This adapter queries `/api/v1/search/find` only. Cairnkeep does not synchronize
+documents into OpenViking, start its service, or adopt its session and memory
+model. OpenViking is optional external retrieval; Cairnkeep remains the authority
+for reviewed memory, pack pins, approvals, evidence, and MCP profiles.
+
 ## Not using RAG?
 
 Do nothing. The tools stay inert, cost nothing, and the rest of cairnkeep is

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.17.0
 **Last reviewed:** 2026-08-19
 
 This map prevents the course from drifting behind the product. It assigns each
@@ -41,6 +41,7 @@ been rehearsed.
 | 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, generic memory retrieval guidance, enforcement, and private receipts | L25 | L25 | Ready; balanced/local by default; invocation requires runtime evidence; actor identity unverified |
+| Progressive pack retrieval, frozen benchmark, context-usage receipts, review-gated memory proposals, optional provider adapter | L26 | V26 | Ready; default flat search and AnythingLLM remain compatible; OpenViking and receipt mutation are explicitly gated |
 
 ## Release Review
 
@@ -85,6 +86,7 @@ against `cairn help` so a new command cannot bypass a curriculum decision.
 |---|---|
 | `cairn bootstrap` | L03 compatibility challenge |
 | `cairn setup` | L03 for Claude/Codex; advanced Pi lifecycle in L23 |
+| `cairn proposals` | L26 |
 | `cairn memory-server` | L02 |
 | `cairn sync` | L02 |
 | `cairn sync-pi` | L13 and L23 |

package/docs/learning/FEATURE-GUIDE.md

@@ -1,6 +1,6 @@
 # Cairnkeep feature guide
 
-**Baseline:** Cairnkeep 2.15.4
+**Baseline:** Cairnkeep 2.17.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` |
 
@@ -117,5 +117,24 @@ prerequisites for ordinary memory.
 - Use `cairn uninstall --dry-run` before uninstall; durable memory is retained
   unless purge is explicitly requested.
 - Revisit the [storage guide](../storage.md) and
-  [privacy/data-flow guide](../privacy-and-data-flow.md) before enabling a new
-  network or retention path.
+[privacy/data-flow guide](../privacy-and-data-flow.md) before enabling a new
+network or retention path.
+
+## Context intelligence
+
+L26 joins five related surfaces without collapsing their authority boundaries:
+
+- the frozen retrieval benchmark measures relevance, context cost, latency,
+  mutations, and forbidden leakage offline;
+- context-pack trees and hierarchical summaries support progressive disclosure,
+  while omitted options retain compatible flat content search;
+- opt-in result digests can produce content-free usage receipts linked to work
+  evidence;
+- trajectory extraction creates an immutable proposal that must be reviewed and
+  applied by exact digest before it becomes durable memory;
+- the OpenViking adapter is optional read-only domain retrieval, with
+  AnythingLLM still the default and Cairnkeep still owning memory and evidence.
+
+See [L26](lessons/L26-context-intelligence.md), its
+[video script](video-scripts/V26-context-intelligence.md), and the
+[context-intelligence reference](../context-intelligence.md).

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.
@@ -57,6 +60,7 @@ expanded only after their labs are executable.
 | 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 |
+| L26 | [Context intelligence with explicit authority](lessons/L26-context-intelligence.md) | Ready | 45 min |
 
 The [curriculum coverage map](CURRICULUM-MAP.md) records where every public
 feature is introduced, practised, and operated. It also marks design-only work

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.17.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.17.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.17.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.17.0 stdio
    ```
 
 3. The process waits quietly for MCP input. Press `Ctrl-C` after confirming it