@cairnkeep/cli 1.1.1 → 1.1.3

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable user-facing changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## [1.1.3] - 2026-07-14
+
+### Fixed
+
+- Allow the standard `$schema` self-reference in strict overlay manifests and
+  verify that the shipped example uses only declared top-level properties.
+
+## [1.1.2] - 2026-07-14
+
+### Added
+
+- Define a provider-neutral managed-distribution contract for private overlays.
+- Ship a versioned overlay manifest schema and local-first example.
+- Document wrapper commands, profile locks, data-routing diagnostics, private
+  registry delivery, package hygiene, fleet migration, and rollback practices.
+
 ## [1.1.1] - 2026-07-14
 
 ### Fixed

package/README.md

@@ -186,6 +186,7 @@ enabling them.
 
 - **Optional document RAG** (`domain_knowledge_*` via AnythingLLM) — [docs/domain-knowledge.md](docs/domain-knowledge.md)
 - **Building a private overlay** (wrap cairnkeep for your org/provider) — [docs/building-an-overlay.md](docs/building-an-overlay.md)
+- **Managed overlay distributions** (wrapper CLI, policy lock, private registry, rollback) — [docs/overlay-distributions.md](docs/overlay-distributions.md)
 - **Full operating guide** — [docs/operating.md](docs/operating.md)
 - **Memory storage and deployment** — [docs/storage.md](docs/storage.md)
 - **Privacy and data flow** — [docs/privacy-and-data-flow.md](docs/privacy-and-data-flow.md)

package/docs/building-an-overlay.md

@@ -6,6 +6,11 @@ credentials, and no organization-specific launchers. Everything specific to
 launchers, policy — belongs in a small private **overlay** that wraps cairnkeep.
 This guide shows the pattern.
 
+For multi-machine or organization-wide use, package the overlay as a managed
+distribution that owns the enrolled machine's `cairn` command. See
+[Managed Cairnkeep distributions](overlay-distributions.md) for the command,
+manifest, profile-lock, private-registry, and rollback contract.
+
 ## Principles
 
 1. **Consume, don't fork.** Treat cairnkeep as an upstream dependency: install it
@@ -122,3 +127,7 @@ secret storage, not generated project files.
 - [ ] Operating layer scoped as intended (global vs `--live-root`)
 - [ ] Optional integrations wired only where wanted
 - [ ] A single documented command takes a fresh machine to a working setup
+- [ ] Managed machines resolve `cairn` to the overlay distribution, not raw core
+- [ ] `cairn config explain` reports memory and RAG destinations without secrets
+- [ ] A project profile lock prevents silent cross-overlay reconfiguration
+- [ ] Private packages reject public-registry publication and exclude runtime data

package/docs/overlay-distributions.md

@@ -0,0 +1,97 @@
+# Managed Cairnkeep distributions
+
+A private overlay becomes significantly easier to operate when it is treated as
+a **distribution** rather than a directory of configuration fragments. The
+distribution owns the `cairn` command on enrolled machines while consuming the
+public `@cairnkeep/cli` package as an exact dependency.
+
+This keeps Cairnkeep neutral and upgradeable. The distribution owns environment
+policy, data routing, launchers, private integrations, and delivery through an
+approved package registry. It should not patch or fork the core implementation.
+
+## Command contract
+
+An overlay package can expose its own `cairn` binary and delegate to its pinned
+core dependency:
+
+- `cairn bootstrap <project>` runs core bootstrap and then applies the overlay.
+- `cairn doctor` runs core diagnostics plus overlay policy checks.
+- `cairn config explain` reports effective storage and service destinations
+  without printing credentials.
+- `cairn overlay info` reports distribution and core versions separately.
+- `cairn core <command>` explicitly bypasses overlay behavior for diagnosis.
+- Other commands, especially `memory-server`, delegate to the pinned core with
+  the validated machine and project environment loaded.
+
+Do not replace core source files. A small wrapper preserves the upstream command
+surface while making managed bootstrap the default users reasonably expect.
+
+## Distribution manifest
+
+Store non-secret capabilities and data-routing policy in
+`cairnkeep.overlay.json`. The reference schema is
+[`schemas/cairnkeep-overlay.schema.json`](../schemas/cairnkeep-overlay.schema.json),
+with a complete example in
+[`examples/overlay-distribution`](../examples/overlay-distribution/cairnkeep.overlay.json).
+
+The distribution version and core version are independent. Pin the core exactly
+and test every distribution release against it.
+
+After a successful bootstrap, write an untracked project profile lock containing
+the distribution identity, versions, and non-secret policy. Refuse a different
+overlay identity before making changes. A stale lock should make `doctor` fail
+with an instruction to rerun managed bootstrap.
+
+## Configuration and secrets
+
+Use two explicit configuration layers:
+
+1. A mode-0600 machine profile in the user's configuration directory.
+2. An optional untracked, mode-0600 project override in `.ai/.env`.
+
+Validate both files before sourcing them: reject symlinks, permissive modes, and
+tracked project files. The manifest and project lock must never contain tokens,
+cookies, private keys, or credential-bearing URLs.
+
+`cairn config explain` should answer these questions directly:
+
+- Is memory local or remote?
+- Which transport is used?
+- Which directory or endpoint receives memory?
+- Is document RAG disabled, local, or remote?
+- Which configuration files selected those values?
+
+## Private package delivery
+
+A distribution can be an ordinary scoped npm package with:
+
+- `@cairnkeep/cli` as an exact dependency;
+- a `bin.cairn` entry for the wrapper;
+- `publishConfig.access` set to `restricted`;
+- an explicit guard that rejects the public npm registry;
+- registry credentials supplied by a user credential helper or protected CI
+  variables, never by repository files.
+
+Support installation from a private registry, a reviewed tarball, and a local
+checkout. Avoid `postinstall` enrollment: installing a package must not silently
+replace machine policy. Provide an explicit enrollment command with a retained
+rollback target.
+
+## Release and fleet safety
+
+Every release should verify:
+
+- fresh managed bootstrap and idempotent reruns;
+- core delegation and the explicit core escape hatch;
+- profile mismatch rejection before mutation;
+- storage and RAG policy enforcement;
+- secret and runtime-artifact exclusion from the package;
+- package installation from the produced tarball;
+- checksums, an SBOM, and an immutable version;
+- pre-upgrade and post-upgrade `doctor` results;
+- rollback to the previous command or package version.
+
+For a fleet migration, update the machine operating layer once, reapply managed
+bootstrap to projects without altering tracked Git status, and validate every
+profile lock. Storage migrations require their own backup, integrity, canary,
+and rollback procedure; changing an overlay version alone must not move data.

package/examples/overlay-distribution/cairnkeep.overlay.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "../../schemas/cairnkeep-overlay.schema.json",
+  "schemaVersion": 1,
+  "id": "team-managed",
+  "name": "Example managed Cairnkeep distribution",
+  "version": "1.0.0",
+  "core": {
+    "package": "@cairnkeep/cli",
+    "version": "1.1.3"
+  },
+  "policy": {
+    "memory": {
+      "transport": "stdio",
+      "storage": "local",
+      "baseDir": "${HOME}/.cairnkeep"
+    },
+    "rag": {"mode": "disabled"},
+    "gitProvider": "none"
+  },
+  "bootstrap": {
+    "defaultMode": "untracked",
+    "launcher": ".ai/start-managed-agent.sh",
+    "profileLock": ".ai/cairnkeep-profile.json"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "A durable, harness-agnostic memory + context layer for coding agents (Claude Code, OpenCode).",
   "license": "Apache-2.0",
   "type": "module",
@@ -17,6 +17,8 @@
     "claude/",
     "opencode/",
     "examples/anythingllm/",
+    "examples/overlay-distribution/",
+    "schemas/",
     "docs/",
     "CHANGELOG.md",
     "CONTRIBUTING.md",

package/schemas/cairnkeep-overlay.schema.json

@@ -0,0 +1,80 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/cairnkeep-overlay.schema.json",
+  "title": "Cairnkeep distribution profile",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "name", "version", "core", "policy", "bootstrap"],
+  "properties": {
+    "$schema": {"type": "string", "format": "uri-reference"},
+    "schemaVersion": {"const": 1},
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{1,63}$"},
+    "name": {"type": "string", "minLength": 1, "maxLength": 120},
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$"
+    },
+    "core": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package", "version"],
+      "properties": {
+        "package": {"const": "@cairnkeep/cli"},
+        "version": {
+          "type": "string",
+          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$"
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["memory", "rag", "gitProvider"],
+      "properties": {
+        "memory": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["transport", "storage"],
+          "properties": {
+            "transport": {"enum": ["stdio", "http"]},
+            "storage": {"enum": ["local", "remote"]},
+            "baseDir": {"type": "string", "minLength": 1},
+            "endpoint": {"type": "string", "format": "uri"}
+          },
+          "allOf": [
+            {
+              "if": {"properties": {"storage": {"const": "local"}}},
+              "then": {"required": ["baseDir"]}
+            },
+            {
+              "if": {"properties": {"storage": {"const": "remote"}}},
+              "then": {"required": ["endpoint"]}
+            }
+          ]
+        },
+        "rag": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["mode"],
+          "properties": {
+            "mode": {"enum": ["disabled", "local", "remote"]},
+            "baseUrl": {"type": "string", "format": "uri"}
+          },
+          "if": {"properties": {"mode": {"enum": ["local", "remote"]}}},
+          "then": {"required": ["baseUrl"]}
+        },
+        "gitProvider": {"type": "string", "minLength": 1}
+      }
+    },
+    "bootstrap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["defaultMode", "launcher", "profileLock"],
+      "properties": {
+        "defaultMode": {"enum": ["tracked", "untracked"]},
+        "launcher": {"type": "string", "minLength": 1},
+        "profileLock": {"type": "string", "minLength": 1}
+      }
+    }
+  }
+}

package/scripts/test-overlay-schema.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+
+node --input-type=module - "$ROOT" <<'NODE'
+import fs from "node:fs";
+import path from "node:path";
+
+const root = process.argv[2];
+const schema = JSON.parse(fs.readFileSync(path.join(root, "schemas/cairnkeep-overlay.schema.json"), "utf8"));
+const example = JSON.parse(fs.readFileSync(path.join(root, "examples/overlay-distribution/cairnkeep.overlay.json"), "utf8"));
+
+if (schema.$schema !== "https://json-schema.org/draft/2020-12/schema") throw new Error("unexpected schema draft");
+if (schema.properties.schemaVersion.const !== 1) throw new Error("unexpected schema version");
+for (const field of schema.required) {
+  if (!(field in example)) throw new Error(`example missing required field: ${field}`);
+}
+for (const field of Object.keys(example)) {
+  if (!(field in schema.properties)) throw new Error(`example uses undeclared field: ${field}`);
+}
+if (example.core.package !== "@cairnkeep/cli") throw new Error("example must consume the public core");
+if (example.policy.memory.storage !== "local") throw new Error("example must remain local-first");
+if (example.policy.memory.transport !== "stdio") throw new Error("example must remain local-first");
+NODE
+
+pack_manifest=$(mktemp)
+trap 'rm -f "$pack_manifest"' EXIT
+npm --prefix "$ROOT" pack --dry-run --json --ignore-scripts > "$pack_manifest"
+node --input-type=module - "$pack_manifest" <<'NODE'
+import fs from "node:fs";
+
+const manifest = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+const files = new Set(manifest[0].files.map((item) => item.path));
+for (const required of [
+  "schemas/cairnkeep-overlay.schema.json",
+  "examples/overlay-distribution/cairnkeep.overlay.json",
+  "docs/overlay-distributions.md",
+]) {
+  if (!files.has(required)) throw new Error(`npm package missing ${required}`);
+}
+NODE
+
+echo "overlay schema checks passed"