@cairnkeep/cli 2.7.0 → 2.9.0

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

@@ -3,7 +3,7 @@
 **Status:** Ready
 **Track:** Quickstart
 **Time:** 15 minutes
-**Tested with:** Cairnkeep 2.7.0
+**Tested with:** Cairnkeep 2.9.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.7.0
+   podman pull ghcr.io/cairnkeep/cairnkeep:2.9.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.7.0 stdio
+     ghcr.io/cairnkeep/cairnkeep:2.9.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.7.0 and Node.js 22 or newer
+**Tested with:** Cairnkeep 2.9.0 and Node.js 22 or newer
 
 ## Outcome
 
@@ -41,7 +41,7 @@ machine-level steps.
 2. Install Cairnkeep:
 
    ```bash
-   npm install --global @cairnkeep/cli@2.7.0
+   npm install --global @cairnkeep/cli@2.9.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.7.0
+**Tested with:** Cairnkeep 2.9.0
 
 ## Outcome
 

package/docs/learning/lessons/L17-agent-boundary.md

@@ -6,23 +6,25 @@
 
 ## Outcome
 
-Separate Cairnkeep's shipped evidence and evaluation substrates from the
-design-only bounded meta-agent proposal, and identify which authority always
-remains with the operator and external harness.
+Separate Cairnkeep's shipped evidence, evaluation, and narrow skill-file
+lifecycle from the design-only general meta-agent proposal, and identify which
+authority always remains with the operator and external harness.
 
 ## Planned lesson
 
 - Current facts: typed capability state, local evidence, immutable evaluation
   inputs, isolated schedules, independent verification, and canonical reports.
-- Design only: natural-language form compilation, candidate generation,
-  candidate injection, comparison, proposal bundles, patch application, and
-  rollback ledgers.
+- Shipped in 2.8.0: reviewed hindsight candidates, bounded edits to one existing
+  `SKILL.md`, isolated baseline/candidate comparison, held-out confirmation,
+  exact-digest application, and rollback ledgers.
+- Design only: general natural-language configuration compilation, arbitrary
+  target types, autonomous scheduling, and an owner inference loop.
 - Cairnkeep coordinates evidence; it does not own a harness inference loop.
 - Natural language is untrusted proposal data, not executable authorization.
 - Separate human gates for form, evaluation, application, confirmation, and
   rollback.
-- Why no CLI command, schema, runtime default, or quality claim ships for the
-  proposed meta-agent loop.
+- Why the shipped `cairn skill` command does not authorize or imply the broader
+  proposed meta-agent loop or a product quality claim.
 
 ## Hands-on lab
 
@@ -36,6 +38,8 @@ be required before any future implementation could act.
 
 - No learner attempts to invoke a meta-agent command or treats an illustrative
   block as a supported schema.
+- The learner can distinguish supported `cairn skill` operations from the
+  broader design-only proposal.
 - Every inference execution remains owned by an operator-configured adapter.
 - A capability digest is not treated as approval, identity proof, or evidence
   of improvement.

package/docs/learning/lessons/L18-local-code-graph.md

@@ -0,0 +1,97 @@
+# L18 - Local code graph
+
+**Status:** Brief
+**Track:** Practitioner
+**Planned time:** 35 minutes
+**Introduced in:** Cairnkeep 2.7.0
+
+## Outcome
+
+Build and inspect an optional local structural graph without confusing derived
+graph data with canonical source code or granting an external tool ownership of
+the Cairnkeep operating layer.
+
+## Planned lesson
+
+- When a structural graph answers a code-navigation question better than
+  durable memory, the wiki, or broad text search.
+- Why the graph capability is disabled unless the managed capability contract
+  enables `graph` or the compatibility setting `graphify.enabled` is true.
+- How to install only the isolated `graphify` executable with `uv tool install
+  graphifyy` or `pipx install graphifyy`. Do not run `graphify install` because
+  Cairnkeep owns the harness commands, policies, and lifecycle.
+- How `cairn graph build`, `cairn graph status`, `cairn graph query`,
+  `cairn graph explain`, `cairn graph path`, and `cairn graph diff` share one
+  portable owner across harnesses and the shell.
+- Why builds index local code only, use a reduced subprocess environment, avoid
+  provider credentials and semantic document extraction, and publish validated
+  artifacts atomically under `.planning/graphs/` while Graphify maintains its
+  separate incremental work directory under `graphify-out/`.
+- How the previous successful graph snapshot supports `diff`, and why `--force`
+  is appropriate only when an intentional code deletion reduces the graph.
+- Why exact symbols and narrow terms are more reliable than broad prose, and
+  why every graph result must be checked against canonical source files.
+- How Claude Code and OpenCode receive managed `/graphify` wrappers while
+  `cairn sync-kimi --apply` and `cairn sync-pi --apply` install thin delegates
+  that call only `cairn graph`.
+
+## Hands-on lab
+
+Use the synthetic course repository at checkpoint `course-08-graph` in a
+disposable clone. Confirm that a disabled graph fails before Graphify or graph
+artifacts are accessed. Install only the isolated executable, enable the graph
+through one documented capability path, and then run:
+
+```bash
+cairn graph build
+cairn graph status
+cairn graph query addItem
+cairn graph explain addItem
+cairn graph path addItem writeLedger
+```
+
+Make one reversible change to the synthetic ledger, rebuild, and inspect
+`cairn graph diff`. Revert the source change, rebuild again, and verify the
+status. Inspect `.planning/graphs/` and `graphify-out/` without adding either
+derived location to Git.
+
+## Acceptance criteria
+
+- The disabled-path check creates or changes no graph artifact.
+- `status` identifies whether the published graph is present and current.
+- `query`, `explain`, and `path` return structural discovery evidence that the
+  learner verifies against `src/trail-ledger.mjs`.
+- A second successful build produces a snapshot-backed diff.
+- The learner can explain why `--force` is not a generic retry flag.
+- The repository contains no Graphify-owned harness assets and neither
+  `graphify-out/` nor a published graph artifact is staged for commit.
+- The learner can distinguish graph storage and subprocess data flow from
+  Cairnkeep memory storage and optional embedding traffic.
+
+## Common failures
+
+- If `graphify` is missing, install the isolated CLI and verify it is on
+  `PATH`; do not run its harness installer.
+- If the capability is disabled, enable it through the managed contract or the
+  compatibility setting rather than bypassing the owner.
+- If no previous snapshot exists, make a successful build after a real code
+  change before requesting `diff`.
+- If a path or explanation is empty, retry with exact symbol names and verify
+  the source directly instead of treating a broad query as proof.
+
+## Privacy and trust boundary
+
+The managed build passes the repository path to a local Graphify subprocess and
+publishes a validated view locally. Its reduced environment excludes provider
+credentials, and the managed workflow does not perform semantic document
+extraction. Graphify's incremental `graphify-out/` workspace and Cairnkeep's
+published `.planning/graphs/` view can both contain sensitive structural data.
+Keep both local by default, review ignore rules, and never present the graph as
+canonical evidence.
+
+## Source material
+
+- [Operating guide](../../operating.md#optional-graphify-workflow)
+- [Harness compatibility](../../harness-compatibility.md)
+- [Privacy and data flow](../../privacy-and-data-flow.md)
+- [L15 - Capability governance](L15-capability-governance.md)

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

@@ -0,0 +1,118 @@
+# L19 - Validated skill improvement
+
+**Status:** Ready
+**Track:** Evidence and Evaluation
+**Time:** 50 minutes
+**Tested with:** Cairnkeep 2.9.0
+
+## Outcome
+
+Turn repeated failure and demonstrated resolution evidence into one reviewed
+skill proposal, measure it on separate exploration and confirmation tasks,
+apply only the exact eligible digest, and prove rollback without risking a real
+project.
+
+## Lesson
+
+- Why harvest requires failures from at least two sessions and at least one
+  recorded resolution.
+- How `harvest`, `show`, and `review --approve` keep evidence local until the
+  learner consents to proposal-adapter egress.
+- How the strict proposal adapter receives a bounded request, a private process
+  environment, and an edit budget for one existing `SKILL.md`.
+- Why proposal generation and evaluation never modify the live target.
+- How separate committed sets with at least two disjoint task IDs and
+  definitions each, one immutable source revision, fresh Git worktrees, exact
+  adapter digests, and an independent verifier protect the gate.
+- Why improvements count distinct tasks, any regressed task rejects the
+  candidate, and small passing fixtures are not universal quality proof.
+- How full proposal-digest confirmation, backup-first atomic replacement, and
+  concurrent-edit-safe rollback limit application authority.
+
+## Hands-on lab
+
+Use the disposable `course-09-skill` checkpoint from the synthetic course
+repository. It contains bounded hindsight evidence, one existing `SKILL.md`,
+deterministic proposal and evaluation adapters, and separate committed task
+sets. Keep every generated artifact under `.course-state/`:
+
+```bash
+git switch --detach course-09-skill
+scripts/reset-course-state.sh --yes
+node scripts/setup-skill-lab.mjs
+core=$(node scripts/locate-cairnkeep-core.mjs)
+lab="$PWD/.course-state/skill-project"
+export CAIRN_AGENTFS_BASE_DIR="$PWD/.course-state/agentfs"
+
+"$core/bin/cairn" skill harvest --project "$lab" --json
+"$core/bin/cairn" skill show --project "$lab" \
+  --kind candidate --id CANDIDATE_ID
+"$core/bin/cairn" skill review --project "$lab" \
+  --candidate CANDIDATE_ID --approve --json
+"$core/bin/cairn" skill propose --project "$lab" \
+  --candidate CANDIDATE_ID --target skills/course-review/SKILL.md \
+  --adapter "$lab/fixtures/proposal-adapter.json" --json
+
+export CAIRN_EVAL=1
+"$core/bin/cairn" skill evaluate --project "$lab" \
+  --proposal PROPOSAL_ID \
+  --exploration-task-set "$lab/eval/exploration.json" \
+  --confirmation-task-set "$lab/eval/confirmation.json" \
+  --adapter "$lab/eval/eval-adapter.json" \
+  --repetitions 1 --minimum-improvement 1 --yes --json
+
+"$core/bin/cairn" skill apply --project "$lab" \
+  --proposal PROPOSAL_ID --evaluation EVALUATION_ID \
+  --confirm FULL_PROPOSAL_DIGEST --json
+"$core/bin/cairn" skill rollback --project "$lab" \
+  --application APPLICATION_ID --confirm --json
+```
+
+Before applying, deliberately try an incorrect digest and verify it is rejected.
+After rollback, compare the target with `fixtures/skill/SKILL.md` byte for byte.
+
+## Acceptance criteria
+
+- No candidate exists for repeated failure without resolution evidence.
+- Proposal execution cannot inherit unapproved credentials or isolation-owned
+  environment variables.
+- The live `SKILL.md` is byte-identical before and after propose/evaluate.
+- Overlapping task IDs, changed adapters, unknown verifier results, and any
+  regression fail closed.
+- Apply rejects a wrong digest or changed target.
+- Rollback restores the original bytes and refuses to overwrite a later edit.
+- The learner can explain why an eligible small task set supports one local
+  decision but not a universal performance claim.
+
+## Common failures
+
+- If harvest returns no candidate, confirm the evidence contains the same
+  failure family in at least two distinct sessions and a recorded resolution.
+- If proposal validation rejects the adapter program, regenerate the lab and
+  verify its configuration resolves to the reviewed executable by absolute
+  path.
+- If evaluation is disabled, set `CAIRN_EVAL=1` only for this disposable lab
+  and retain the explicit `--yes` confirmation.
+- If task validation reports overlap or a mutable revision, use the committed
+  exploration and confirmation fixtures from `course-09-skill` unchanged.
+- If apply rejects the confirmation, copy the full `proposal_digest` from the
+  reviewed proposal rather than an ID, prefix, or candidate-content digest.
+- If rollback reports a concurrent target change, stop and inspect that edit;
+  do not overwrite it by copying the backup manually.
+
+## Privacy and trust boundary
+
+Hindsight excerpts and skill content remain local until candidate approval.
+Approval permits those exact fields to enter the explicitly configured proposal
+adapter. Evaluation adapters receive isolated worktrees with baseline or
+candidate skill bytes, not the hindsight evidence. Candidate, proposal,
+evaluation, application, backup, and report artifacts remain sensitive local
+project state under `.agentfs/`.
+
+## Source material
+
+- [Validated skill improvement](../../skill-improvement.md)
+- [Evaluation and ablation](L16-evaluation.md)
+- [The agent boundary](L17-agent-boundary.md)
+- [Storage](../../storage.md#validated-skill-storage)
+- [Privacy and data flow](../../privacy-and-data-flow.md#validated-skill-improvement-flow)

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

@@ -0,0 +1,67 @@
+# L20 - Least-authority MCP tool profiles
+
+**Status:** Ready
+**Tested with:** Cairnkeep 2.9.0 and Node.js 22 or newer
+**Time:** 25 minutes
+
+## Outcome
+
+Classify every MCP tool as an observation or mutation, apply a read-only project
+profile, replace it with an exact allowlist, and prove that invalid authority is
+rejected before server startup.
+
+## Exercise
+
+Use a disposable directory so no real project policy changes:
+
+```bash
+lab=$(mktemp -d)
+cairn mcp-tools list --json >"$lab/catalog.json"
+cairn mcp-tools status --project "$lab" --json
+cairn mcp-tools set read-only --project "$lab"
+cairn mcp-tools status --project "$lab" --json >"$lab/read-only.json"
+test "$(stat -c '%a' "$lab/.ai/mcp-tools.json" 2>/dev/null || stat -f '%Lp' "$lab/.ai/mcp-tools.json")" = 600
+cairn mcp-tools set custom --tool memory_read --tool memory_search --project "$lab"
+cairn mcp-tools status --project "$lab" --json >"$lab/custom.json"
+```
+
+Inspect the catalog. Every entry must contain a title and four Boolean hints.
+The read-only profile must contain only tools whose `readOnlyHint` is true. The
+custom profile contains exactly the two named tools in canonical discovery
+order.
+
+Confirm environment precedence without changing the project file:
+
+```bash
+CAIRN_MCP_TOOL_PROFILE=full cairn mcp-tools status --project "$lab" --json
+```
+
+The source is `environment`; the project remains custom when the override is
+removed. A profile cannot enable a feature-gated tool, and a disabled capability
+still removes its tool. Restart the memory server after profile changes.
+
+## Common failures
+
+- `custom` without `--tool` is invalid because an empty accidental server is
+  more likely to be a configuration mistake than useful least authority.
+- Unknown names and a group/world-readable project config fail closed.
+- A running MCP session keeps its discovery snapshot until restarted.
+
+## Privacy and trust boundary
+
+Profiles do not read tool payloads or add telemetry. The digest identifies the
+allowlist, not the user's identity or the independent capability state. Client
+approval remains necessary for mutations even when a profile exposes them.
+
+## Recovery and acceptance
+
+```bash
+cairn mcp-tools reset --project "$lab"
+test ! -e "$lab/.ai/mcp-tools.json"
+rm -rf "$lab"
+```
+
+- Unknown custom tool names fail `set`, server startup, and `cairn doctor`.
+- Profile and capability digests are independent.
+- Conservative clients may execute read-only observations; mutations still
+  require their approval policy.

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

@@ -0,0 +1,79 @@
+# L21 - Immutable context packs and skill approval
+
+**Status:** Ready
+**Tested with:** Cairnkeep 2.9.0 and Node.js 22 or newer
+**Time:** 40 minutes
+
+## Outcome
+
+Build a local offline context pack, verify its immutable identity, pin it to a
+disposable project, and explain why document enablement and skill approval are
+different trust decisions.
+
+## Exercise
+
+```bash
+lab=$(mktemp -d)
+mkdir -p "$lab/pack" "$lab/project"
+printf '# Local guide\n\nSynthetic offline guidance.\n' >"$lab/pack/guide.md"
+export CAIRN_PACK_BASE_DIR="$lab/store"
+cairn pack init "$lab/pack" --id course-guide --version 1.0.0 \
+  --title "Course guide" --description "Synthetic local reference" \
+  --license Apache-2.0
+cairn pack lock "$lab/pack"
+cairn pack validate "$lab/pack"
+cairn pack install "$lab/pack" --json >"$lab/install.json"
+digest=$(node -e 'process.stdout.write(require(process.argv[1]).digest)' "$lab/install.json")
+cairn pack enable "$digest" --project "$lab/project"
+cairn pack show "$digest" --json
+cairn pack skills --project "$lab/project" --json
+```
+
+The local lifecycle makes no network request. The pack digest covers exact
+manifest and content bytes; `version` is a label, not identity. Objects remain
+under `$CAIRN_PACK_BASE_DIR` after disablement and ordinary uninstall.
+
+Add a file with `kind: skill`, refresh it with `cairn pack lock`, install the new
+digest, and enable it. `cairn pack skills` shows the skill but the MCP list/read
+surface does not expose it until:
+
+```bash
+cairn pack approve-skill NEW-PACK-DIGEST path/to/SKILL.md \
+  --confirm FILE-DIGEST --project "$lab/project"
+```
+
+Approval binds the project, pack, path, and file bytes. A later pack update
+invalidates it. Approval makes instructions readable only; it never executes or
+copies them into a harness.
+
+## Common failures
+
+- Adding a file after `init` requires declaring it in the manifest before
+  `lock`; undeclared content is rejected.
+- Git installation without `--ref`, a stale update confirmation, and removal of
+  an enabled digest all fail closed.
+- Enabling the pack does not expose a skill until its current file digest is
+  approved.
+
+## Privacy and trust boundary
+
+Local pack operations are offline. Configured semantic search can send enabled
+chunks and a query to the explicit embedding endpoint; failure falls back to
+substring search. A digest detects changed bytes but does not authenticate the
+publisher. Approved instructions remain untrusted readable context, not code.
+
+## Recovery and acceptance
+
+```bash
+cairn pack disable course-guide --project "$lab/project"
+cairn pack remove "$digest"
+unset CAIRN_PACK_BASE_DIR
+rm -rf "$lab"
+```
+
+- Traversal, symlinks, undeclared files, invalid UTF-8, and digest tampering fail
+  validation.
+- `update --check` never switches a project; apply requires the inspected digest.
+- `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.

package/docs/learning/tracks/evidence-and-evaluation.md

@@ -2,7 +2,7 @@
 
 **Audience:** maintainers and advanced practitioners evaluating optional layers
 **Prerequisite:** Practitioner track
-**Total time:** about 3.25 hours
+**Total time:** about 4 hours
 **Infrastructure:** local fixtures first; a live harness is operator-provided
 
 1. [L13 - Session evidence and hindsight](../lessons/L13-session-evidence.md)
@@ -10,11 +10,13 @@
 3. [L15 - Capability governance](../lessons/L15-capability-governance.md)
 4. [L16 - Evaluation and ablation](../lessons/L16-evaluation.md)
 5. [L17 - The agent boundary](../lessons/L17-agent-boundary.md)
+6. [L19 - Validated skill improvement](../lessons/L19-validated-skill-improvement.md)
 
 The track is complete when the learner can explain each consent boundary,
 inspect and manage every local evidence store, compare baseline and ablation
-reports without making unsupported claims, and distinguish current runtime
-features from the design-only meta-agent contract.
+reports without making unsupported claims, apply or roll back an exact eligible
+skill proposal, and distinguish that narrow runtime from the design-only
+general meta-agent contract.
 
 Hands-on spine: `course-05-evidence` through `course-07-evaluation` in the
 public [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/learning/tracks/operator.md

@@ -2,7 +2,7 @@
 
 **Audience:** advanced users and platform maintainers
 **Prerequisite:** Practitioner track; L13 before operating captured evidence
-**Total time:** about 4 hours
+**Total time:** about 5 hours
 
 1. [L09 - Domain knowledge with RAG](../lessons/L09-domain-knowledge.md)
 2. [L10 - Faster context exploration](../lessons/L10-context-exploration.md)
@@ -10,11 +10,13 @@
 4. [L12 - Managed overlays](../lessons/L12-managed-overlays.md)
 5. [L15 - Capability governance](../lessons/L15-capability-governance.md)
 6. [L16 - Evaluation and ablation](../lessons/L16-evaluation.md)
+7. [L20 - Least-authority MCP tool profiles](../lessons/L20-mcp-tool-profiles.md)
+8. [L21 - Immutable context packs and skill approval](../lessons/L21-context-packs.md)
 
 All modules are optional. The track is complete when the operator can add and
 remove each integration without breaking the standalone local workflow and can
 explain its storage, network, credential, and rollback boundaries.
 
 Hands-on spine: `course-04-operation`, `course-06-governance`, and
-`course-07-evaluation` in the public
+`course-07-evaluation`, and `course-10-trust-context` in the public
 [course labs](https://github.com/cairnkeep/cairnkeep-course-labs).

package/docs/learning/tracks/practitioner.md

@@ -6,10 +6,11 @@
 
 1. [L04 - Memory fundamentals](../lessons/L04-memory-fundamentals.md)
 2. [L05 - The daily workflow](../lessons/L05-daily-workflow.md)
-3. [L06 - Repository review and security](../lessons/L06-repository-quality.md)
-4. [L07 - Privacy and storage](../lessons/L07-privacy-and-storage.md)
-5. [L08 - Multiple machines](../lessons/L08-multiple-machines.md)
-6. [L13 - Session evidence and hindsight](../lessons/L13-session-evidence.md)
+3. [L18 - Local code graph](../lessons/L18-local-code-graph.md)
+4. [L06 - Repository review and security](../lessons/L06-repository-quality.md)
+5. [L07 - Privacy and storage](../lessons/L07-privacy-and-storage.md)
+6. [L08 - Multiple machines](../lessons/L08-multiple-machines.md)
+7. [L13 - Session evidence and hindsight](../lessons/L13-session-evidence.md)
 
 The track is complete when the learner can decide what should become memory,
 review derived knowledge, run governed repository checks, locate the store, and

package/docs/mcp-tool-profiles.md

@@ -0,0 +1,43 @@
+# MCP tool annotations and least-authority profiles
+
+Cairnkeep publishes a complete annotation contract for every MCP tool. Each
+tool has a stable title and explicit `readOnlyHint`, `destructiveHint`,
+`idempotentHint`, and `openWorldHint` values. Local observations are closed
+world. Tools that query configured services or delegated processes are open
+world. Any mutation that may replace or remove state is destructive; immutable
+artifact creation is additive.
+
+Use the profile CLI to reduce the tools visible to an MCP client:
+
+```bash
+cairn mcp-tools list
+cairn mcp-tools status --json
+cairn mcp-tools set read-only
+cairn mcp-tools set custom --tool memory_read --tool memory_search
+cairn mcp-tools reset
+```
+
+Project configuration is strict versioned JSON in `.ai/mcp-tools.json`, created
+only by `set` and written with mode `0600`. Do not hand-edit it. A process may
+override the project with `CAIRN_MCP_TOOL_PROFILE=full|read-only|custom`; custom
+process profiles also require a comma-separated `CAIRN_MCP_ALLOWED_TOOLS`.
+Precedence is process environment, project configuration, then `full`.
+
+`read-only` is derived from the central annotation catalog. `custom` is an
+exact allowlist. Unknown names fail server startup and `cairn doctor`. Profiles
+only remove authority: they cannot activate typed nodes, artifacts, context
+packs, HTTP exposure, or a disabled capability. Effective discovery is:
+
+```text
+available feature gates ∩ capability contract ∩ MCP tool profile
+```
+
+`status` includes a canonical profile digest. Evaluation reports record that
+same digest in their evidence provenance without changing the independent
+capability-configuration digest. Restart the memory server after changing an
+MCP profile.
+
+The default `full` profile preserves the same tool names, schemas, responses,
+feature gates, and ordering as an unconfigured server. The annotations help
+conservative clients distinguish observations from actions; they do not grant
+permission or replace the client's approval policy.

package/docs/operating.md

@@ -218,6 +218,13 @@ do not perform Graphify's optional semantic document extraction. Prefer exact
 function, class, or file names; broad natural-language graph queries are less
 precise. Cairnkeep does not install or update Graphify automatically.
 
+Graphify also maintains an incremental `graphify-out/` work directory at the
+repository root. It is separate from Cairnkeep's published
+`.planning/graphs/` view and can contain the same sensitive structural data.
+Keep both locations local. Before the first build in a Git repository, add
+`/graphify-out/` to the clone-local exclude file or the repository's ignore
+policy, and verify with `git status --short` after every build.
+
 ## Setup order (Kimi Code)
 
 Kimi Code can use the Cairnkeep memory MCP, generated project launcher, and one
@@ -897,6 +904,22 @@ See [storage](storage.md#evaluation-report-and-note-snapshot-storage) for local
 retention/removal and [privacy](privacy-and-data-flow.md#evaluation-adapter-and-report-flow)
 for the exact request, observation, environment, and persistence boundaries.
 
+### Validated skill improvement (opt-in)
+
+After hindsight-note distillation has recorded the same failure family in at
+least two sessions, `cairn skill harvest` creates a local candidate under
+`.agentfs/skills/`. Review its exact evidence with `show`, approve it explicitly,
+then use a private proposal adapter to generate a bounded edit list for one
+existing skill file. Proposal and evaluation do not modify the live target.
+
+Evaluation reuses the default-off evaluation coordinator and therefore requires
+`CAIRN_EVAL=1`, `--yes`, an explicit harness adapter, and two disjoint committed
+task sets. Only a complete, no-regression improvement in exploration opens the
+confirmation set. Only the same result on confirmation makes the proposal
+eligible for exact-digest application. See
+[Validated skill improvement](skill-improvement.md) for the command sequence,
+adapter contract, task constraints, and rollback procedure.
+
 ### Structured session trajectories (opt-in)
 
 Trajectory capture is disabled by default. To enable it for a launched Claude
@@ -1076,3 +1099,41 @@ truthy it launches exactly one separate `cairn notes distill --all-projects`
 process after the wiki scan and reports its bounded status. With the flag unset
 it performs no note work. Note failure does not replace wiki findings or change
 their actionable exit status; no credentials are embedded in rendered units.
+
+## Least-authority MCP profiles
+
+Inspect the annotation-derived catalog and then choose the smallest profile the
+client needs:
+
+```bash
+cairn mcp-tools list
+cairn mcp-tools set read-only --project .
+cairn mcp-tools set custom --tool memory_read --tool memory_search --project .
+cairn mcp-tools status --project . --json
+```
+
+Restart the memory server after `set` or `reset`. Environment overrides win over
+the mode-`0600` project file. A profile can only remove tools; feature and
+capability gates still apply. Invalid names make both startup and doctor fail.
+See [MCP tool profiles](mcp-tool-profiles.md).
+
+## Context packs (opt-in)
+
+Build and validate a local pack before installing it, then enable the immutable
+digest for exactly one project:
+
+```bash
+cairn pack init ./reference --id reference --version 1.0.0 \
+  --title Reference --description "Reviewed project context" --license Apache-2.0
+cairn pack lock ./reference
+cairn pack validate ./reference
+cairn pack install ./reference
+cairn pack enable PACK-DIGEST --project .
+CAIRN_CONTEXT_PACKS=1 cairn memory-server
+```
+
+Git sources additionally require `--ref`. Updates are a manual `--check`, then
+an `--apply --confirm CANDIDATE-DIGEST`. Use `cairn pack skills` and exact-digest
+approval before a bundled skill can be read through MCP. HTTP needs the separate
+`CAIRN_CONTEXT_PACK_HTTP=1` flag and all existing authentication/Host/CORS
+controls. See [Immutable context packs](context-packs.md).