@cairnkeep/cli 2.15.3 → 2.16.0

package/docs/quickstart.md

@@ -7,18 +7,19 @@ the default store stays on this computer.
 ## Codex CLI
 
 Install Cairnkeep, then let guided setup initialize an empty project and write
-Codex's project-scoped MCP entry:
+Codex's project-scoped MCP entry. Select **Initialize a Git repository**,
+tick **Codex CLI** with Space, keep local memory, review the plan, and apply it:
 
 ```bash
 npm install --global @cairnkeep/cli
-cairn setup /path/to/project --git init --harness codex --memory local --yes
+cairn setup /path/to/project
 cd /path/to/project
 cairn doctor
 ./.ai/start-codex.sh
 ```
 
-Use `--git existing` instead when the target is already a Git work tree. On
-native Windows, launch with `.\.ai\start-codex.cmd`.
+The wizard recommends the existing repository mode when the target is already
+a Git work tree. On native Windows, launch with `.\.ai\start-codex.cmd`.
 
 Before the first session, review `.codex/config.toml` and accept Codex's project
 trust prompt. The generated entry runs `cairn memory-server` locally. Setup
@@ -53,6 +54,13 @@ cairn doctor
 Setup reports machine-level commands but never executes them. This keeps
 project scaffolding separate from harness-wide changes.
 
+For scripts, CI, or reproducible fleet setup, skip the selector and provide all
+choices explicitly:
+
+```bash
+cairn setup /path/to/project --git init --harness codex --memory local --yes
+```
+
 ## First memory cycle
 
 In a harness with Cairnkeep commands, remember one durable fact and recall it:
@@ -72,8 +80,9 @@ result should survive the restart.
 `.planning`, and `.agentfs` scaffold. It also reconciles Cairnkeep's delimited
 instruction block in `AGENTS.md` while preserving every surrounding user byte
 and file mode. The block tells compatible agents when to make one
-task-derived, project-scoped memory search, to verify maintained repository
-sources, and never to promote memory automatically. It initializes Git only
+task-derived, project-scoped memory search as their first tool or command, to
+verify maintained repository sources, and never to promote memory
+automatically. It initializes Git only
 with explicit
 `--git init`, preserves unrelated files, does not overwrite modified files it
 does not own, and records managed digests in private `.ai/cairnkeep.json`.

package/docs/releasing.md

@@ -10,37 +10,45 @@ from a workstation.
    `npm --prefix mcp-memory-server test`.
 3. Merge only after every required CI check passes.
 4. Publish a GitHub Release whose tag is exactly `v<package.json version>`.
-5. The `Publish release` workflow checks out that immutable tag, repeats the
-   tests, and publishes `@cairnkeep/cli` with npm provenance.
-6. The workflow uses the exact locked `@cyclonedx/cyclonedx-npm` development
-   dependency to generate a reproducible CycloneDX 1.6 SBOM from
-   `package-lock.json`. Generation includes schema validation and runs before
-   npm publication, so an invalid document blocks both publication and
-   attachment. The workflow attaches that SBOM, the npm tarball, and SHA-256
-   checksums to the GitHub Release.
-7. The workflow publishes versioned `linux/amd64` and `linux/arm64`
-   memory-server and workspace images to GHCR. It also updates `latest` for a
-   stable release or `next` for a prerelease.
-8. Verify both image digests, SBOM attestations, provenance attestations, and an
+5. After every platform and runtime job passes, CI builds one release candidate
+   keyed by the exact Git tree. It contains the npm tarball, reproducible
+   CycloneDX 1.6 SBOM, checksums, and a tree/version manifest. CI retains it for
+   30 days.
+6. The `Publish release` workflow checks out the immutable tag, resolves its
+   tree, and accepts a candidate only from a successful `CI` run for that exact
+   tree. It verifies the manifest and checksums instead of rebuilding or
+   repeating the complete test suite.
+7. After candidate verification, npm publication and the memory-server and
+   workspace container publications run in parallel. npm retains provenance;
+   the containers retain their per-image SBOM and provenance attestations.
+8. The workflow attaches the verified SBOM, npm tarball, and SHA-256 checksums
+   to the GitHub Release. It publishes versioned `linux/amd64` and
+   `linux/arm64` images to GHCR and updates `latest` for a stable release or
+   `next` for a prerelease.
+9. Verify both image digests, SBOM attestations, provenance attestations, and an
    anonymous pull before announcing the release.
 
 Stable versions must use a stable GitHub Release and publish to npm's `latest`
 tag. SemVer prerelease versions must use a GitHub prerelease and publish to
 `next`. A mismatch fails before publication.
 
-The workflow is safe to rerun: it skips `npm publish` and each versioned OCI
-image when that exact version is already present. It regenerates release
-artifacts, retries attestations against the resolved image digests, and moves
+The workflow is safe to rerun: it re-verifies the same CI candidate, skips
+`npm publish` and each versioned OCI image when that exact version is already
+present, retries attestations against the resolved image digests, and moves
 only the `latest` or `next` channel tag. A versioned image tag is never rebuilt
-or moved.
+or moved. If the tree-addressed candidate has expired, rerun CI for the exact
+release commit before retrying publication; the workflow never substitutes a
+different version or tree.
 
 ## Repository configuration
 
 The repository must provide an `NPM_TOKEN` Actions secret authorized to publish
 `@cairnkeep/cli`. Keep that credential out of local files and rotate it according
-to the npm account's security policy. The workflow grants `contents: write`,
-`packages: write`, `attestations: write`, and `id-token: write`; the last two
-are required for registry-backed build provenance.
+to the npm account's security policy. The workflow grants `actions: read`,
+`contents: write`, `packages: write`, `attestations: write`, and
+`id-token: write`. Read access resolves the successful tree-addressed CI
+artifact; the last two permissions are required for registry-backed build
+provenance.
 
 GitHub creates each new GHCR package as private. After the first container
 release, a package administrator must change both `cairnkeep` and

package/examples/eval/bundled-fake.json

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

package/mcp-memory-server/dist/playbook-cli.js

@@ -245,11 +245,18 @@ async function main() {
         process.stdout.write(usage());
         return;
     }
-    if (["check", "record"].includes(command) && raw.length === 1 && ["--help", "-h"].includes(raw[0])) {
-        if (command === "check")
-            process.stdout.write(checkUsage());
-        else
-            process.stdout.write(recordUsage());
+    if (command === "check" && raw.some((value) => ["--help", "-h"].includes(value))) {
+        const helpArguments = raw.filter((value) => !["--help", "-h"].includes(value));
+        if (raw.length !== helpArguments.length + 1
+            || helpArguments.length > 1
+            || (helpArguments.length === 1 && !["start", "check", "finish"].includes(helpArguments[0]))) {
+            throw new Error("check help accepts at most one event: start, check, or finish.");
+        }
+        process.stdout.write(checkUsage());
+        return;
+    }
+    if (command === "record" && raw.length === 1 && ["--help", "-h"].includes(raw[0])) {
+        process.stdout.write(recordUsage());
         return;
     }
     const parsed = parse(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.15.3",
+  "version": "2.16.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",

package/scripts/cairn-cli.mjs

@@ -37,6 +37,7 @@ export const USAGE = `cairn — Cairnkeep CLI
 
 Usage:
   cairn bootstrap [--untracked] [path]
+  cairn setup [PATH]  # interactive Git, harness, memory, and confirmation selectors
   cairn setup PATH --git init|existing|none --harness LIST --memory local|none [--policy PATH] --yes [--json]
   cairn memory-server
   cairn sync [--check|--apply] [--live-root DIR]

package/scripts/setup.mjs

@@ -21,8 +21,9 @@ import {
   resolveSetupChoices,
 } from "./setup-core.mjs";
 import { reconcileSetupPlan } from "./setup-reconcile.mjs";
-import { HARNESS_IDS, machineSyncCommand, requiredHarnessAssetPaths } from "./harness-registry.mjs";
+import { HARNESS_IDS, HARNESS_REGISTRY, machineSyncCommand, requiredHarnessAssetPaths } from "./harness-registry.mjs";
 import { reconcilePlaybookInstructions } from "./playbook-instructions.mjs";
+import { selectManyPrompt, selectOnePrompt, supportsTerminalPrompts } from "./terminal-prompts.mjs";
 
 const HARNESSES = HARNESS_IDS;
 const GIT_MODES = Object.freeze(["init", "existing", "none"]);
@@ -70,11 +71,36 @@ function parseInteractiveHarnesses(value) {
 }
 
 export async function promptSetupChoices(parsed, streams) {
-  const terminal = typeof streams.question === "function"
-    ? { question: streams.question, close: streams.closePrompt ?? (() => {}) }
-    : createInterface({ input: streams.input, output: streams.output });
+  let linePrompt = null;
+  let externallyClosed = false;
+  const question = typeof streams.question === "function"
+    ? streams.question
+    : async (message) => {
+      linePrompt ??= createInterface({ input: streams.input, output: streams.output });
+      return linePrompt.question(message);
+    };
+  const closeLinePrompt = () => {
+    if (linePrompt) linePrompt.close();
+    linePrompt = null;
+    if (!externallyClosed) {
+      streams.closePrompt?.();
+      externallyClosed = true;
+    }
+  };
+  const structured = Boolean(streams.selectOne && streams.selectMany)
+    || supportsTerminalPrompts(streams.input, streams.output);
+  const selectOne = streams.selectOne ?? ((options) => selectOnePrompt({
+    ...options,
+    input: streams.input,
+    output: streams.output,
+  }));
+  const selectMany = streams.selectMany ?? ((options) => selectManyPrompt({
+    ...options,
+    input: streams.input,
+    output: streams.output,
+  }));
   try {
-    const target = parsed.target ?? (await terminal.question("Target path: ")).trim();
+    const target = parsed.target ?? (await question("Target path: ")).trim();
     if (!target) throw operational("interactive-input", "A setup target path is required.");
     const preflight = classifySetupTarget(target);
     const gitQuestion = preflight.targetState === "missing" || preflight.targetState === "empty"
@@ -82,12 +108,63 @@ export async function promptSetupChoices(parsed, streams) {
       : preflight.repository === "work-tree"
         ? "Git mode (existing recommended; choices: init, existing, none): "
         : "Git mode (init requires explicit choice for existing non-Git target; choices: init, existing, none): ";
-    const git = parsed.git ?? (await terminal.question(gitQuestion)).trim();
-    const harnesses = parsed.harnesses ?? parseInteractiveHarnesses(await terminal.question(`Harnesses (${HARNESSES.join(", ")}): `));
-    const memory = parsed.memory ?? (await terminal.question("Memory mode (local, none): ")).trim();
-    return { target, git, harnesses, memory, preflight, terminal };
+    if (structured) closeLinePrompt();
+    const gitChoices = preflight.gitExecutable === "missing"
+      ? [{ value: "none", label: "Continue without Git", hint: "Git executable not found; repository features will be limited" }]
+      : preflight.repository === "work-tree"
+        ? [
+          { value: "existing", label: "Use the existing Git repository", hint: "recommended" },
+          { value: "none", label: "Continue without Git integration", hint: "limited" },
+        ]
+        : [
+          { value: "init", label: "Initialize a Git repository", hint: preflight.targetState === "non-empty" ? "review the existing directory first" : "recommended" },
+          { value: "none", label: "Continue without Git integration", hint: "limited" },
+        ];
+    const git = parsed.git ?? (structured
+      ? await selectOne({ message: "Git integration", choices: gitChoices, initialValue: gitChoices[0].value })
+      : (await question(gitQuestion)).trim());
+    const harnesses = parsed.harnesses ?? (structured
+      ? await selectMany({
+        message: "Coding harnesses",
+        choices: HARNESS_REGISTRY.map(({ id, title }) => ({ value: id, label: `${title} (${id})` })),
+      })
+      : parseInteractiveHarnesses(await question(`Harnesses (${HARNESSES.join(", ")}): `)));
+    const memory = parsed.memory ?? (structured
+      ? await selectOne({
+        message: "Memory mode",
+        choices: [
+          { value: "local", label: "Local Cairnkeep memory", hint: "recommended" },
+          { value: "none", label: "No memory server" },
+        ],
+        initialValue: "local",
+      })
+      : (await question("Memory mode (local, none): ")).trim());
+    return {
+      target,
+      git,
+      harnesses,
+      memory,
+      preflight,
+      terminal: {
+        question,
+        close: closeLinePrompt,
+        confirm: structured
+          ? async () => (await selectOne({
+            message: "Apply this setup plan?",
+            choices: [
+              { value: "no", label: "No, cancel" },
+              { value: "yes", label: "Yes, apply the plan" },
+            ],
+            initialValue: "no",
+          })) === "yes"
+          : async () => {
+            const answer = (await question("Apply this setup plan? [y/N] ")).trim().toLowerCase();
+            return answer === "y" || answer === "yes";
+          },
+      },
+    };
   } catch (error) {
-    terminal.close();
+    closeLinePrompt();
     throw error;
   }
 }
@@ -167,7 +244,7 @@ function initializeGit(target) {
 }
 
 async function executeSetup(args, options) {
-  const isTTY = options.isTTY ?? Boolean(options.input.isTTY);
+  const isTTY = options.isTTY ?? Boolean(options.input.isTTY && options.output.isTTY);
   const parsed = parseSetupArgs(args, { isTTY });
   const policy = parsed.policyPath ? readSetupPolicy(parsed.policyPath) : null;
 
@@ -196,9 +273,9 @@ async function executeSetup(args, options) {
 
   if (interactive && !parsed.confirmed) {
     renderPlan(plan, options.output);
-    const answer = (await interactive.terminal.question("Apply this setup plan? [y/N] ")).trim().toLowerCase();
+    const accepted = await interactive.terminal.confirm();
     interactive.terminal.close();
-    if (answer !== "y" && answer !== "yes") {
+    if (!accepted) {
       writeLine(options.output, "Setup cancelled; no files were changed.");
       return null;
     }
@@ -221,6 +298,8 @@ export async function runSetup(args, options = {}) {
     augmentPlan: options.augmentPlan,
     question: options.question,
     closePrompt: options.closePrompt,
+    selectOne: options.selectOne,
+    selectMany: options.selectMany,
   };
   try {
     const result = await executeSetup(args, streams);

package/scripts/terminal-prompts.mjs

@@ -0,0 +1,172 @@
+import { emitKeypressEvents } from "node:readline";
+
+function promptError(message, status = 1) {
+  const error = new Error(message);
+  error.name = "TerminalPromptError";
+  error.status = status;
+  return error;
+}
+
+function normalizedChoices(choices) {
+  if (!Array.isArray(choices) || choices.length === 0) throw promptError("A terminal prompt requires at least one choice.");
+  const normalized = choices.map((choice) => Object.freeze({
+    value: String(choice.value),
+    label: String(choice.label),
+    hint: choice.hint ? String(choice.hint) : "",
+  }));
+  if (new Set(normalized.map(({ value }) => value)).size !== normalized.length) {
+    throw promptError("Terminal prompt choices must have unique values.");
+  }
+  return Object.freeze(normalized);
+}
+
+export function supportsTerminalPrompts(input, output, env = process.env) {
+  return Boolean(
+    input?.isTTY
+      && output?.isTTY
+      && typeof input.setRawMode === "function"
+      && env.TERM !== "dumb",
+  );
+}
+
+async function runKeypressPrompt({ input, output, draw, accept }) {
+  emitKeypressEvents(input);
+  const wasRaw = Boolean(input.isRaw);
+  const wasPaused = typeof input.isPaused === "function" ? input.isPaused() : false;
+  let renderedLines = 0;
+  let settled = false;
+  let keypressHandler = null;
+  let rawChanged = false;
+  let resumed = false;
+  let cursorHidden = false;
+
+  const render = () => {
+    const lines = draw();
+    if (renderedLines > 0) output.write(`\x1b[${renderedLines}A\r\x1b[0J`);
+    output.write(`${lines.join("\n")}\n`);
+    renderedLines = lines.length;
+  };
+
+  const clear = () => {
+    if (renderedLines > 0) output.write(`\x1b[${renderedLines}A\r\x1b[0J`);
+    renderedLines = 0;
+  };
+
+  try {
+    if (!wasRaw) {
+      input.setRawMode(true);
+      rawChanged = true;
+    }
+    if (wasPaused && typeof input.resume === "function") {
+      input.resume();
+      resumed = true;
+    }
+    output.write("\x1b[?25l");
+    cursorHidden = true;
+    render();
+    return await new Promise((resolve, reject) => {
+      const finish = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        input.removeListener("keypress", onKeypress);
+        callback(value);
+      };
+      const onKeypress = (text, key = {}) => {
+        try {
+          if ((key.ctrl && key.name === "c") || key.name === "escape") {
+            finish(reject, promptError("Setup cancelled.", 130));
+            return;
+          }
+          const result = accept(text, key);
+          if (result?.done) finish(resolve, result.value);
+          else render();
+        } catch (error) {
+          finish(reject, error);
+        }
+      };
+      keypressHandler = onKeypress;
+      input.on("keypress", onKeypress);
+    });
+  } finally {
+    if (keypressHandler) input.removeListener("keypress", keypressHandler);
+    clear();
+    if (cursorHidden) output.write("\x1b[?25h");
+    if (rawChanged) input.setRawMode(false);
+    if (resumed && typeof input.pause === "function") input.pause();
+  }
+}
+
+function movement(key, cursor, length) {
+  if (key.name === "up" || key.name === "k") return (cursor - 1 + length) % length;
+  if (key.name === "down" || key.name === "j") return (cursor + 1) % length;
+  if (key.name === "home") return 0;
+  if (key.name === "end") return length - 1;
+  return cursor;
+}
+
+export async function selectOnePrompt({ message, choices, initialValue, input, output }) {
+  const options = normalizedChoices(choices);
+  let cursor = Math.max(0, options.findIndex(({ value }) => value === initialValue));
+  const selected = await runKeypressPrompt({
+    input,
+    output,
+    draw: () => [
+      `? ${message} (Up/Down to move, Enter to select)`,
+      ...options.map((choice, index) => `${index === cursor ? ">" : " "} ${choice.label}${choice.hint ? ` - ${choice.hint}` : ""}`),
+    ],
+    accept: (text, key) => {
+      cursor = movement(key, cursor, options.length);
+      if (key.name === "return" || key.name === "enter") return { done: true, value: options[cursor].value };
+      const number = Number.parseInt(text, 10);
+      if (Number.isInteger(number) && number >= 1 && number <= options.length) {
+        cursor = number - 1;
+        return { done: true, value: options[cursor].value };
+      }
+      return null;
+    },
+  });
+  const label = options.find(({ value }) => value === selected)?.label ?? selected;
+  output.write(`> ${message}: ${label}\n`);
+  return selected;
+}
+
+export async function selectManyPrompt({ message, choices, selectedValues = [], input, output, minimum = 1 }) {
+  const options = normalizedChoices(choices);
+  const allowed = new Set(options.map(({ value }) => value));
+  const selected = new Set(selectedValues.filter((value) => allowed.has(value)));
+  let cursor = 0;
+  let validation = "";
+  const values = await runKeypressPrompt({
+    input,
+    output,
+    draw: () => [
+      `? ${message} (Up/Down to move, Space to toggle, A to toggle all, Enter to continue)`,
+      ...options.map((choice, index) => `${index === cursor ? ">" : " "} [${selected.has(choice.value) ? "x" : " "}] ${choice.label}${choice.hint ? ` - ${choice.hint}` : ""}`),
+      validation,
+    ],
+    accept: (text, key) => {
+      cursor = movement(key, cursor, options.length);
+      if (key.name === "space" || text === " ") {
+        const value = options[cursor].value;
+        if (selected.has(value)) selected.delete(value);
+        else selected.add(value);
+        validation = "";
+      } else if (text?.toLowerCase() === "a") {
+        if (selected.size === options.length) selected.clear();
+        else for (const { value } of options) selected.add(value);
+        validation = "";
+      } else if (key.name === "return" || key.name === "enter") {
+        if (selected.size < minimum) {
+          validation = `  Select at least ${minimum} option${minimum === 1 ? "" : "s"}.`;
+          output.write("\x07");
+        } else {
+          return { done: true, value: options.filter(({ value }) => selected.has(value)).map(({ value }) => value) };
+        }
+      }
+      return null;
+    },
+  });
+  const labels = options.filter(({ value }) => values.includes(value)).map(({ label }) => label);
+  output.write(`> ${message}: ${labels.join(", ")}\n`);
+  return values;
+}

package/scripts/test-cli-dispatch.sh

@@ -29,6 +29,10 @@ env -u CAIRN_NOTE_DISTILLATION "$cairn" notes --help >/dev/null 2>&1 || fail "ca
 "$cairn" evidence --help | grep -q "cairn evidence list" || fail "cairn evidence dispatch"
 "$cairn" playbook --help | grep -q "cairn playbook list" || fail "cairn playbook dispatch"
 "$cairn" playbook check --help | grep -q "check start|check|finish" || fail "cairn playbook check help"
+"$cairn" playbook check start --help | grep -q "trivial|standard|complex" || fail "cairn playbook event help"
+if "$cairn" playbook check start finish --help >/dev/null 2>&1; then
+  fail "playbook check help should reject multiple events"
+fi
 "$cairn" playbook record --help >"$tmp/playbook-record-help" || fail "cairn playbook record help"
 grep -qF -- '--event start|check|finish' "$tmp/playbook-record-help" || fail "playbook record help missing events"
 grep -qF -- '--outcome completed|skipped|failed' "$tmp/playbook-record-help" || fail "playbook record help missing outcomes"

package/scripts/test-docs-navigation.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "$0")/.." && pwd)
+cd "$ROOT"
+
+fail() {
+  echo "FATAL: $*" >&2
+  exit 1
+}
+
+require_term() {
+  local file="$1" term="$2"
+  grep -qF "$term" "$file" || fail "$file is missing required navigation term: $term"
+}
+
+check_local_links() {
+  local file="$1" base target resolved
+  base=$(dirname "$file")
+  while IFS= read -r target; do
+    case "$target" in
+      http://*|https://*|mailto:*|'#'*|'') continue ;;
+    esac
+    target=${target%%#*}
+    resolved="$base/$target"
+    [[ -e "$resolved" ]] || fail "$file links to missing local target: $target"
+  done < <(grep -oE '\]\([^)]+' "$file" | sed 's/^](//' || true)
+}
+
+readme_lines=$(wc -l < README.md | tr -d ' ')
+[[ "$readme_lines" -le 140 ]] || fail "README.md must remain a lean landing page (found $readme_lines lines; limit 140)"
+
+require_term README.md '## For coding agents'
+require_term README.md 'docs/README.md'
+require_term README.md 'docs/agents.md'
+require_term README.md 'docs/quickstart.md'
+require_term README.md 'docs/learning/README.md'
+
+if grep -qE '\b(CAIRN_|MCP_HTTP_)' README.md; then
+  fail 'README.md contains detailed environment configuration; keep it in versioned focused docs'
+fi
+
+for guide in \
+  quickstart.md agents.md operating.md harness-compatibility.md \
+  mcp-tool-profiles.md context-packs.md storage.md privacy-and-data-flow.md \
+  work-evidence.md native-windows.md containers.md ecosystem.md \
+  learning/README.md; do
+  require_term docs/README.md "$guide"
+done
+
+for term in \
+  'memory_search' 'locator' 'memory_write' 'cairn playbook check start' \
+  'cairn playbook check finish' 'cairn mcp-tools set read-only' \
+  'cannot enable a disabled feature' 'not evidence'; do
+  require_term docs/agents.md "$term"
+done
+
+check_local_links README.md
+check_local_links docs/README.md
+check_local_links docs/agents.md
+check_local_links docs/ecosystem.md
+
+echo "PASS: lean README, agent contract, documentation index, and local navigation"

package/scripts/test-learning-docs.sh

@@ -154,7 +154,7 @@ for phrase in \
   '--enforce' \
   'cairn playbook record' \
   'cairn playbook record --help' \
-  'before repository inventory or search' \
+  'as the first tool or command' \
   'unauthenticated' \
   'does not run'; do
   grep -qF -- "$phrase" "$l25" || {

package/scripts/test-package-install.sh

@@ -51,7 +51,7 @@ bootstrap_output=$(cairn bootstrap "$tmp/project")
 [[ -f "$tmp/project/.ai/playbooks.json" ]] || fail "bootstrap did not install the playbook policy"
 grep -qF '<!-- cairnkeep:playbook:v1:start -->' "$tmp/project/AGENTS.md" || fail "bootstrap did not install playbook agent guidance"
 grep -qF 'derive one short query from the task' "$tmp/project/AGENTS.md" || fail "bootstrap did not install generic memory retrieval guidance"
-grep -qF 'before running repository inventory or search' "$tmp/project/AGENTS.md" || fail "bootstrap did not install retrieval ordering guidance"
+grep -qF 'make this retrieval the first tool or command' "$tmp/project/AGENTS.md" || fail "bootstrap did not install retrieval ordering guidance"
 grep -qF 'cairn playbook record --help' "$tmp/project/AGENTS.md" || fail "bootstrap did not install actionable receipt guidance"
 grep -qF 'Treat returned memory as a locator, not authority.' "$tmp/project/AGENTS.md" || fail "bootstrap did not install memory provenance guidance"
 

package/scripts/test-phase17-artifact-lifecycle.sh

@@ -244,7 +244,7 @@ check_uninstall_bytes() {
 
 check_docs_contract() {
   local public_doc
-  for public_doc in "$ROOT/README.md" "$ROOT/docs/operating.md"; do
+  for public_doc in "$ROOT/docs/operating.md"; do
     require_term "$public_doc" 'CAIRN_COMPACTION_CAPTURE' "$(basename "$public_doc") compaction flag"
     require_term "$public_doc" 'CAIRN_ARTIFACT_STORE' "$(basename "$public_doc") artifact-store flag"
     require_term "$public_doc" 'CAIRN_ARTIFACT_HTTP' "$(basename "$public_doc") artifact HTTP flag"

package/scripts/test-playbook-instructions.sh

@@ -14,13 +14,15 @@ grep -qF 'Keep this line.' "$project/AGENTS.md"
 [[ $(grep -cF '<!-- cairnkeep:playbook:v1:start -->' "$project/AGENTS.md") -eq 1 ]]
 grep -qF 'derive one short query from the task' "$project/AGENTS.md"
 grep -qF 'search `scope: project` once' "$project/AGENTS.md"
-grep -qF 'before running repository inventory or search' "$project/AGENTS.md"
-grep -qF '`rg --files`, `find`, `tree`' "$project/AGENTS.md"
+grep -qF 'make this retrieval the first tool or command' "$project/AGENTS.md"
+grep -qF '`pwd`, `ls`, `rg --files`, `find`' "$project/AGENTS.md"
 grep -qF "do not inspect" "$project/AGENTS.md"
 grep -qF 'Treat returned memory as a locator, not authority.' "$project/AGENTS.md"
 grep -qF 'Do not write, supersede, or approve durable memory' "$project/AGENTS.md"
 grep -qF 'cairn playbook record --policy POLICY_DIGEST --decision DECISION_DIGEST' "$project/AGENTS.md"
 grep -qF 'cairn playbook record --help' "$project/AGENTS.md"
+grep -qF -- '--complexity trivial|standard|complex --familiarity known|mixed|unfamiliar' "$project/AGENTS.md"
+grep -qF -- '--risk low|normal|high|security' "$project/AGENTS.md"
 [[ $(stat -c '%a' "$project/AGENTS.md") == 640 ]]
 before=$(sha256sum "$project/AGENTS.md" | cut -d' ' -f1)
 node "$ROOT/scripts/playbook-instructions.mjs" "$project" >/dev/null