@cairnkeep/cli 2.8.0 → 2.9.0

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/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/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

@@ -1099,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).

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

@@ -16,6 +16,9 @@ request unless the corresponding endpoint and credential are configured.
 | `domain_knowledge_sync` | Files selected by the sync configuration | `ANYTHINGLLM_BASE_URL` |
 | `route_check` | A health request, with no memory or prompt content | `CAIRN_ROUTE_ENDPOINT` |
 | `context_explore` | Repository path and query are passed to the configured local executable | `CAIRN_EXPLORE_BINARY`; any further data flow is controlled by that tool |
+| Local context-pack install/list/read/substring search | None | Verified immutable files and project pointers under `CAIRN_PACK_BASE_DIR` |
+| Embedding-ranked context-pack search | Enabled file chunks not already cached, plus the query | The explicitly configured embedding endpoint; failure falls back locally |
+| Authenticated HTTP context-pack retrieval | MCP requests and enabled document/approved-skill content | The explicit Cairnkeep HTTP server; requires separate pack HTTP consent |
 | Optional Graphify workflow | The repository path, exact query/symbol names, root `graphify-out/` work directory, and local `.planning/graphs/` publication are passed to or produced by the operator-installed `graphify` executable | Local Graphify subprocess with a minimal environment and no provider credentials; managed build uses code-only `update`, never semantic document extraction |
 | Remote HTTP memory | MCP requests and responses, including memory content | The explicitly registered Cairnkeep HTTP server |
 | Opt-in trajectory capture | None | Local `<project>/.agentfs/trajectory.db` only; no model or HTTP path exists |
@@ -512,3 +515,17 @@ provide tenant isolation or per-scope authorization.
 Before sharing diagnostics, remove credentials, private endpoints, database
 files, memory values, local paths, and project names. Report vulnerabilities
 through the private channel in [SECURITY.md](../SECURITY.md).
+
+## Context-pack trust boundary
+
+Pack validation proves that installed bytes match the manifest and immutable
+digest. It does not authenticate a publisher. Review the source, commit, license,
+and content before enabling a digest; signatures are not yet supported. Local
+directory installation, listing, reading, and substring search make no network
+request. Git installation/update contacts only the operator-supplied source and
+is never scheduled in the background.
+
+All enabled documents carry pack and file provenance in MCP results. Skill files
+are excluded until the current project approves the exact pack digest, path, and
+file digest. Updating the pack invalidates that approval. Approval only makes a
+skill readable; Cairnkeep never copies it into a harness or executes it.

package/docs/storage.md

@@ -21,6 +21,9 @@ registration, memory remains on that computer.
 | Opt-in session trajectories and capability callback state | `<harness project root>/.agentfs/trajectory.db` |
 | Opt-in local artifacts and compaction revisions | `<project root>/.agentfs/artifacts.db` |
 | Opt-in evaluation reports and note snapshots | `<project root>/.agentfs/eval/experiments/<experiment-id>/` |
+| Immutable context-pack objects and source records | `${CAIRN_PACK_BASE_DIR:-~/.cairnkeep/packs}/objects/` and `sources/` |
+| Digest-pinned context-pack project pointers and approvals | `${CAIRN_PACK_BASE_DIR:-~/.cairnkeep/packs}/projects/` |
+| Optional context-pack embedding cache | `${CAIRN_PACK_BASE_DIR:-~/.cairnkeep/packs}/cache/` (outside immutable objects) |
 | Opt-in derived hindsight notes | `${CAIRN_AGENTFS_BASE_DIR:-~/.cairnkeep}/notes/` |
 | Any named/global scope, such as `identity` or `work` | `${CAIRN_AGENTFS_BASE_DIR:-~/.cairnkeep}/<scope>.db` |
 
@@ -493,3 +496,17 @@ bearer_token_env_var = "CAIRN_MEMORY_HTTP_TOKEN"
 "X-Cairn-Scopes" = "identity,personal,project"
 "X-Cairn-AnythingLLM-Workspaces" = "engineering-patterns"
 ```
+
+## Context-pack storage
+
+Context-pack objects are content-addressed, immutable directories. Installation
+copies verified content through a temporary directory and atomically publishes
+the digest; a failed or concurrent install never changes project enablement.
+Project pointers are separate atomic mode-`0600` files keyed by canonical local
+project identity or a validated remote project ID. Updates retain old objects
+and switch only the named project after exact-digest confirmation.
+
+`cairn doctor` verifies objects, pointers, and interrupted-install remnants.
+It never chooses a pack version or grants a skill approval. `cairn pack remove`
+refuses any referenced digest. Ordinary uninstall retains this directory even
+when memory is removed; `--purge-packs` is the separate backup-first consent.

package/examples/eval/bundled-fake.json

@@ -1 +1 @@
-{"identifier":"cairn-offline-fake-v1","package_version":"2.8.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}
+{"identifier":"cairn-offline-fake-v1","package_version":"2.9.0","schema_version":1,"task_set_digest":"13e95379f35839593047ec34521a65a8fa3ab92bd3993bca9dc8bf5c4a9ff36f"}

package/mcp-memory-server/dist/context-pack-cli.js

@@ -0,0 +1,185 @@
+import { existsSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import { applyContextPackUpdate, approvePackSkill, contextPackBaseDirectory, disableContextPack, doctorContextPacks, enableContextPack, initializeContextPack, inspectContextPackUpdate, installContextPack, listInstalledContextPacks, listPackSkills, lockContextPack, readProjectPointer, removeContextPack, resolveInstalledPack, revokePackSkill, validateContextPack, } from "./context-pack.js";
+function usage() {
+    process.stderr.write(`Usage:
+  cairn pack init [DIRECTORY] [--id ID] [--version VERSION] [--title TITLE] [--description TEXT] [--license LICENSE]
+  cairn pack lock|validate [DIRECTORY]
+  cairn pack install SOURCE [--ref REF]
+  cairn pack list [--json]
+  cairn pack show SELECTOR [--json]
+  cairn pack remove SELECTOR
+  cairn pack enable|disable SELECTOR [--project PATH | --project-id ID]
+  cairn pack update SELECTOR --check [--project PATH | --project-id ID]
+  cairn pack update SELECTOR --apply --confirm DIGEST [--project PATH | --project-id ID]
+  cairn pack skills [--project PATH | --project-id ID] [--json]
+  cairn pack approve-skill SELECTOR PATH --confirm FILE_DIGEST [--project PATH | --project-id ID]
+  cairn pack revoke-skill SELECTOR PATH [--project PATH | --project-id ID]
+`);
+    process.exit(2);
+}
+function take(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--"))
+        usage();
+    args.splice(index, 2);
+    return value;
+}
+function flag(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return false;
+    args.splice(index, 1);
+    return true;
+}
+function projectOptions(args) {
+    const projectRoot = take(args, "--project");
+    const projectId = take(args, "--project-id");
+    if (projectRoot && projectId)
+        usage();
+    return projectId ? { projectId } : { projectRoot: projectRoot ?? process.cwd() };
+}
+function output(value, json, human) {
+    process.stdout.write(`${json ? JSON.stringify(value) : human ?? JSON.stringify(value, null, 2)}\n`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args.shift();
+    const json = flag(args, "--json");
+    if (command === "init") {
+        const directory = args[0] && !args[0].startsWith("--") ? args.shift() : process.cwd();
+        const manifest = await initializeContextPack(directory, {
+            id: take(args, "--id"), version: take(args, "--version"), title: take(args, "--title"),
+            description: take(args, "--description"), license: take(args, "--license"),
+        });
+        if (args.length)
+            usage();
+        output(manifest, json, `Initialized ${resolve(directory)}/context-pack.json`);
+        return;
+    }
+    if (command === "lock" || command === "validate") {
+        const directory = args.shift() ?? process.cwd();
+        if (args.length)
+            usage();
+        const result = command === "lock" ? await lockContextPack(directory) : await validateContextPack(directory);
+        output(result, json, command === "lock" ? `Locked ${resolve(directory)}/context-pack.json` : `Valid context pack: ${result.digest}`);
+        return;
+    }
+    if (command === "install") {
+        const source = args.shift();
+        if (!source)
+            usage();
+        const ref = take(args, "--ref");
+        if (args.length)
+            usage();
+        const result = await installContextPack(source, { ref });
+        output({ id: result.pack.manifest.id, version: result.pack.manifest.version, digest: result.pack.digest, source: result.source, existing: result.existing }, json, `${result.existing ? "Already installed" : "Installed"} ${result.pack.manifest.id}@${result.pack.manifest.version} ${result.pack.digest}`);
+        return;
+    }
+    if (command === "list") {
+        if (args.length)
+            usage();
+        const packs = await listInstalledContextPacks();
+        output({ schema_version: 1, packs }, json, packs.length ? packs.map((pack) => `${pack.id}@${pack.version}\t${pack.digest}`).join("\n") : "No context packs installed.");
+        return;
+    }
+    if (command === "show") {
+        const selector = args.shift();
+        if (!selector || args.length)
+            usage();
+        const pack = await resolveInstalledPack(selector);
+        output({ ...pack.manifest, digest: pack.digest, total_bytes: pack.total_bytes }, json);
+        return;
+    }
+    if (command === "remove") {
+        const selector = args.shift();
+        if (!selector || args.length)
+            usage();
+        const digest = await removeContextPack(selector);
+        output({ removed: true, digest }, json, `Removed context pack ${digest}.`);
+        return;
+    }
+    if (command === "enable" || command === "disable") {
+        const selector = args.shift();
+        if (!selector)
+            usage();
+        const project = projectOptions(args);
+        if (args.length)
+            usage();
+        const pointer = command === "enable" ? await enableContextPack(selector, project) : await disableContextPack(selector, project);
+        output(pointer, json, `${command === "enable" ? "Enabled" : "Disabled"} context pack ${selector}.`);
+        return;
+    }
+    if (command === "update") {
+        const selector = args.shift();
+        if (!selector)
+            usage();
+        const check = flag(args, "--check");
+        const apply = flag(args, "--apply");
+        const confirm = take(args, "--confirm");
+        const project = projectOptions(args);
+        if (args.length || check === apply || (apply && !confirm) || (check && confirm))
+            usage();
+        const result = check ? await inspectContextPackUpdate(selector, project) : await applyContextPackUpdate(selector, confirm, project);
+        output(result, json, check ? `${result.changed ? "Update available" : "Up to date"}: ${result.candidate_digest}` : `Applied context pack update ${result.candidate_digest}.`);
+        return;
+    }
+    if (command === "skills") {
+        const project = projectOptions(args);
+        if (args.length)
+            usage();
+        const skills = await listPackSkills(project);
+        output({ schema_version: 1, skills }, json, skills.length ? skills.map((row) => `${row.approved ? "approved" : "unapproved"}\t${row.pack_id}\t${row.path}\t${row.file_digest}`).join("\n") : "No context pack skills.");
+        return;
+    }
+    if (command === "approve-skill" || command === "revoke-skill") {
+        const selector = args.shift();
+        const path = args.shift();
+        if (!selector || !path)
+            usage();
+        const confirm = take(args, "--confirm");
+        const project = projectOptions(args);
+        if (args.length || (command === "approve-skill" && !confirm) || (command === "revoke-skill" && confirm))
+            usage();
+        const pointer = command === "approve-skill"
+            ? await approvePackSkill(selector, path, confirm, project)
+            : await revokePackSkill(selector, path, project);
+        output(pointer, json, `${command === "approve-skill" ? "Approved" : "Revoked"} ${path}.`);
+        return;
+    }
+    if (command === "doctor") {
+        if (args.length)
+            usage();
+        const result = await doctorContextPacks();
+        output(result, json, result.ok ? `Context packs healthy (${result.objects} objects, ${result.projects} projects).` : `Context pack problems: ${[...result.issues, ...result.temporary_remnants].join("; ")}`);
+        if (!result.ok)
+            process.exitCode = 1;
+        return;
+    }
+    if (command === "purge") {
+        if (!flag(args, "--yes") || args.length)
+            usage();
+        const base = contextPackBaseDirectory();
+        if (existsSync(base))
+            await rm(base, { recursive: true, force: true });
+        output({ purged: true, path: base }, json, `Purged context pack data at ${base}.`);
+        return;
+    }
+    if (command === "status") {
+        const project = projectOptions(args);
+        if (args.length)
+            usage();
+        const pointer = readProjectPointer(project);
+        output(pointer, json);
+        return;
+    }
+    usage();
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});