prae-cli 0.10.4 → 0.10.5

package/lib/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 //#region src/bin.ts
 const argv = process.argv.slice(2);
-(argv[0] === "hook" && argv[1] === "claude-code" ? argv[2] === "session-start" ? import("./quickstart-CV2i1KDh.js").then(({ runSessionStart }) => runSessionStart(argv.slice(3))) : import("./hook-C7ehSrzs.js").then(({ runHook }) => runHook(argv.slice(2))) : import("./cli-CkL2G7pV.js").then(({ main }) => main(argv))).catch((error) => {
+(argv[0] === "hook" && argv[1] === "claude-code" ? argv[2] === "session-start" ? import("./quickstart-CFk8Vj0G.js").then(({ runSessionStart }) => runSessionStart(argv.slice(3))) : import("./hook-C7ehSrzs.js").then(({ runHook }) => runHook(argv.slice(2))) : import("./cli-CggsIkQW.js").then(({ main }) => main(argv))).catch((error) => {
 	console.error(`prae: ${error instanceof Error ? error.message : error}`);
 	process.exit(1);
 });

package/lib/{cli-CkL2G7pV.js → cli-CggsIkQW.js}

@@ -1,6 +1,6 @@
 import "./src-DO3IFxZ-.js";
 import "./src-Tshjqoz6.js";
-import { t as main } from "./cli-Dpem2eHc.js";
+import { t as main } from "./cli-DLwlh4y9.js";
 import "./facts-BKzQ9GLI.js";
 import "./views-Hh3G5zpv.js";
 

package/lib/{cli-Dpem2eHc.js → cli-DLwlh4y9.js}

@@ -2030,6 +2030,12 @@ const USAGE = `⌜▪⌟ prae — operator policy for agent harnesses
       the exit code is non-zero if any invariant no longer holds, so a
       control pack can be defended in CI. --pack overrides the suite's own.
 
+  prae decisions [<ledger.jsonl>] [--last <n>] [--json]
+      The latest decisions, one line each: ALLOWED, DENIED or HELD, the
+      tool, the path or program, and for a refusal or hold the rule and its
+      reason. Default: the Claude Code ledger (~/.prae/claude-code/), the
+      last 10. Read-only; prae verify checks the chain.
+
   prae verify <ledger.jsonl> [--key <public.pem>] [--checkpoint <file>]
       Re-derive every hash in a decision log and report any break. With
       --key, also verify each row's signature against that pinned key. With
@@ -2234,7 +2240,7 @@ async function scanFile(path, packPath, json) {
 * not come up inspecting nothing.
 */
 async function mcp(root, packPath, ledgerPath) {
-	const { serveMcp } = await import("./mcp-HD1KrudT.js");
+	const { serveMcp } = await import("./mcp-BseFg7Zu.js");
 	const { resolve: resolve$1 } = await import("node:path");
 	const bundled = [join(import.meta.dirname, "secret-catcher.prae.json"), join(import.meta.dirname, "..", "..", "..", "examples", "secret-catcher.prae.json")].find((candidate) => existsSync(candidate));
 	const chosen = packPath ?? bundled;
@@ -2402,7 +2408,7 @@ async function receipt(path, seq, keyPath, out) {
 * file and sets the exit code, so scripts can branch on it.
 */
 async function verifyReceiptCmd(path) {
-	const { checkReceipt } = await import("./receipt-check-D4opBPn-.js");
+	const { checkReceipt } = await import("./receipt-check-wseVcJb_.js");
 	let parsed$1;
 	try {
 		parsed$1 = JSON.parse(await readFile(path, "utf8"));
@@ -2433,7 +2439,7 @@ async function test(suitePath, packOverride, asJson) {
 	} catch (error) {
 		return fail(`${suitePath} is not valid JSON: ${error instanceof Error ? error.message : error}`);
 	}
-	const { parseSuite, renderSuite, runSuite } = await import("./test-run-CveqObP9.js");
+	const { parseSuite, renderSuite, runSuite } = await import("./test-run-BG8VdLy-.js");
 	const suite = parseSuite(parsed$1);
 	if (!suite.ok) {
 		console.error(`prae: ${suitePath} is not a valid test suite`);
@@ -2459,6 +2465,34 @@ async function test(suitePath, packOverride, asJson) {
 	else for (const line of renderSuite(result)) console.log(line);
 	if (!result.ok) process.exit(1);
 }
+/** `prae decisions`: the latest ledger rows in the terminal (PRA-220). */
+async function decisions(argv) {
+	const { DEFAULT_LEDGER, decisionLines } = await import("./decisions-C42_kQyi.js");
+	const given = argv[0];
+	const path = given === void 0 || given.startsWith("--") ? DEFAULT_LEDGER : given;
+	const last = Number(flag(argv, "last") ?? 10);
+	if (!Number.isInteger(last) || last < 1) fail("--last needs a whole number above 0");
+	if (!existsSync(path)) fail(`no ledger at ${path}`);
+	let entries;
+	try {
+		entries = Ledger.open(path).read();
+	} catch (error) {
+		return fail(error instanceof Error ? error.message : String(error));
+	}
+	if (argv.includes("--json")) {
+		console.log(JSON.stringify(entries.slice(-last), null, 2));
+		return;
+	}
+	if (entries.length === 0) {
+		console.log(`No decisions yet in ${path}.`);
+		return;
+	}
+	for (const line of decisionLines(entries, {
+		last,
+		cwd: process.cwd()
+	})) console.log(line);
+	console.log(`\n${Math.min(last, entries.length)} of ${entries.length} decisions · ${path}`);
+}
 async function verify$1(path, keyPath, checkpointPath) {
 	let ledger;
 	try {
@@ -2557,7 +2591,7 @@ async function report(path, out, packPath) {
 * that step is a proposal a human approves, and it starts from this list.
 */
 async function instructions(from, asJson) {
-	const { ingest } = await import("./src-C7rfOs_W.js");
+	const { ingest } = await import("./src-D16_Zt7u.js");
 	const result = ingest(from);
 	if (asJson) {
 		console.log(JSON.stringify(result, null, 2));
@@ -2593,7 +2627,7 @@ async function instructions(from, asJson) {
 * on purpose rather than something that happened to their policy.
 */
 async function propose(from, options) {
-	const [{ ingest }, { extract }] = await Promise.all([import("./src-C7rfOs_W.js"), import("./src-BsDLT9wq.js")]);
+	const [{ ingest }, { extract }] = await Promise.all([import("./src-D16_Zt7u.js"), import("./src-DWC4OVEg.js")]);
 	const read = ingest(from);
 	if (read.files.length === 0) {
 		console.log(`No instruction files found at or above ${from}.`);
@@ -2653,8 +2687,8 @@ async function consoleOut(path, argv) {
 	const instructionsDir = flag(argv, "instructions");
 	if (instructionsDir !== void 0) {
 		const [{ ingest }, { extract }, { renderInstructions }] = await Promise.all([
-			import("./src-C7rfOs_W.js"),
-			import("./src-BsDLT9wq.js"),
+			import("./src-D16_Zt7u.js"),
+			import("./src-DWC4OVEg.js"),
 			import("./instructions-BqT2wN_4.js")
 		]);
 		const read = ingest(instructionsDir);
@@ -2840,7 +2874,7 @@ async function checkpoint(path, keyPath, out) {
 	}
 }
 async function exportLedger(path, options) {
-	const { toOcsf, ndjson, sendToHec } = await import("./ocsf-CRDSY64q.js");
+	const { toOcsf, ndjson, sendToHec } = await import("./ocsf-BrMcK3Qd.js");
 	const { createRequire: createRequire$1 } = await import("node:module");
 	const { version } = createRequire$1(import.meta.url)("../package.json");
 	let ledger;
@@ -2923,6 +2957,7 @@ async function main(argv) {
 			if (path === void 0) fail("verify needs a ledger file");
 			return verify$1(path, flag(rest, "key"), flag(rest, "checkpoint"));
 		}
+		case "decisions": return decisions(rest);
 		case "chain": {
 			const path = rest[0];
 			if (path === void 0) fail("chain needs a ledger file");
@@ -2971,7 +3006,7 @@ async function main(argv) {
 		}
 		case "init":
 			if (rest[0] === "claude-code") {
-				const { initClaudeCode, stableNode } = await import("./init-B_cGYN45.js");
+				const { initClaudeCode, stableNode } = await import("./init-DvhJ97F9.js");
 				const prompt = process.stdin.isTTY && process.stdout.isTTY ? (await import("node:readline/promises")).createInterface({
 					input: process.stdin,
 					output: process.stdout
@@ -2994,7 +3029,7 @@ async function main(argv) {
 		case "hook": {
 			if (rest[0] !== "claude-code") fail("hook takes claude-code");
 			if (rest[1] === "session-start") {
-				const { runSessionStart } = await import("./quickstart-CV2i1KDh.js");
+				const { runSessionStart } = await import("./quickstart-CFk8Vj0G.js");
 				return runSessionStart(rest.slice(2));
 			}
 			const { runHook } = await import("./hook-C7ehSrzs.js");

package/lib/decisions-C42_kQyi.js

@@ -0,0 +1,38 @@
+import { isAbsolute, join, relative, sep } from "node:path";
+import { homedir } from "node:os";
+
+//#region src/decisions.ts
+/** Where `prae init claude-code` keeps the ledger unless told otherwise. */
+const DEFAULT_LEDGER = join(homedir(), ".prae", "claude-code", "ledger.jsonl");
+const LABEL = {
+	allow: "ALLOWED",
+	ask: "HELD",
+	deny: "DENIED",
+	correct: "CORRECTED"
+};
+/** A path inside `cwd` as the user typed it; anything else as it is. */
+function shown(subject, cwd) {
+	if (!isAbsolute(subject)) return subject.replace(/^\.\//, "");
+	const rel = relative(cwd, subject);
+	return rel !== "" && !rel.startsWith("..") && !rel.startsWith(sep) ? rel : subject;
+}
+/** One line per row, oldest first, the last `last` rows of `entries`. */
+function decisionLines(entries, options) {
+	const rows = entries.slice(-options.last).map((e) => {
+		const label = `${LABEL[e.verdict]}${e.shadow && e.verdict !== "allow" ? " (shadow, ran anyway)" : ""}`;
+		const what = e.subject !== void 0 ? shown(e.subject, options.cwd) : e.command?.program ?? "";
+		const why = e.verdict === "allow" || e.rule === void 0 ? "" : `${e.rule} · ${e.reason ?? ""}`;
+		return [
+			`row ${e.seq}`,
+			label,
+			e.tool,
+			what,
+			why
+		];
+	});
+	const width = (i) => Math.max(0, ...rows.map((r) => r[i]?.length ?? 0));
+	return rows.map((r) => r.map((cell, i) => i < r.length - 1 ? cell.padEnd(width(i)) : cell).join("  ").trimEnd());
+}
+
+//#endregion
+export { DEFAULT_LEDGER, decisionLines };

package/lib/docs/pilot-claude-code.md

@@ -70,22 +70,22 @@ so new tool calls go through PRAE without a restart.
 
 ### The quickstart inside Claude Code
 
-From prae-cli 0.10.4, `init` also installs a five-minute guided tour.
+From prae-cli 0.10.4, `init` also installs a five-minute guided tour, `/prae-quickstart`. From 0.10.5 it is a build–verify loop (PRA-220).
 
-- **The `/prae-quickstart` skill.** It is written beside the settings file:
+- **The skill** is written beside the settings file:
   - `~/.claude/skills/` for `--scope user`;
   - `./.claude/skills/` for `--scope project`;
   - `.claude/skills/` inside the managed settings directory.
 
-  Claude walks you through it with real calls, in a scratch folder (`./.prae-quickstart/`) it creates in your project:
-  - a read that is allowed;
-  - a synthetic credentials file that is refused (BASE-005);
-  - a recursive delete that waits for you (BASE-002);
-  - `prae verify` on the ledger;
-  - `prae explain`, which you run yourself, because PRAE's pack is not the agent's to touch.
+  It is written for your install, with your paths and mode.
+- **The tour.** Claude builds a tiny project in `./.prae-quickstart/`, one increment at a time. After each increment it **verifies** (runs the tests), **inspects** what PRAE decided (`prae decisions`) and **continues**.
+  1. A function and its test: every call is allowed.
+  2. Database configuration: reading `.env` is denied (BASE-005). Claude continues the way the refusal points: configuration from the environment, documented in `.env.example`.
+  3. A build, then cleaning it: `rm -r` is held for you (BASE-002).
 
-  It ends with links to prae-ai.com. The skill is written for your install, with your paths and mode. Rerun it any time.
-- **A `SessionStart` entry, `matcher: "startup"`.** In the first session after the install, it shows `PRAE is active … Type /prae-quickstart for a five-minute tour.`, and Claude offers the tour once. It then leaves `quickstart-offered` in the state directory and stays silent in every later session. It never fails a session.
+  It ends with `prae verify` on the ledger, `prae explain` (which you run yourself, because PRAE's pack is not the agent's to touch) and links to prae-ai.com.
+- **Pre-approved calls.** The skill's `allowed-tools` pre-approves only the tour's own safe calls in Claude Code: edits inside `./.prae-quickstart/`, its tests and build script, and `prae decisions`/`prae verify`. PRAE still judges every one of them, so the only prompt is PRAE's own hold.
+- **The offer.** A `SessionStart` entry (`matcher: "startup"`) shows, in the first session after the install, `PRAE is active … Type /prae-quickstart for a five-minute tour.` Claude offers the tour once. It then leaves `quickstart-offered` in the state directory and stays silent in every later session. It never fails a session.
 
 Options:
 
@@ -123,6 +123,7 @@ Read the record:
 
 ```bash
 P=~/.prae/claude-code
+prae decisions                # the last 10: ALLOWED, DENIED or HELD, with the rule and reason
 prae verify  $P/ledger.jsonl --key $P/prae-signing.pub.pem
 prae report  $P/ledger.jsonl --pack $P/prae-baseline.prae.json --out report.html
 prae console $P/ledger.jsonl --pack $P/prae-baseline.prae.json --out console/

package/lib/index.js

@@ -1,6 +1,6 @@
 import "./src-DO3IFxZ-.js";
 import "./src-Tshjqoz6.js";
-import { a as planWrite, i as dshHome, n as applyWrite, o as praeRow, r as defaultProfile, s as profileAt, t as main } from "./cli-Dpem2eHc.js";
+import { a as planWrite, i as dshHome, n as applyWrite, o as praeRow, r as defaultProfile, s as profileAt, t as main } from "./cli-DLwlh4y9.js";
 import "./facts-BKzQ9GLI.js";
 import "./views-Hh3G5zpv.js";
 

package/lib/{init-B_cGYN45.js → init-DvhJ97F9.js}

@@ -1,6 +1,6 @@
 import { t as parsePack } from "./src-DO3IFxZ-.js";
 import { d as generateKeypair, u as fingerprint } from "./src-Tshjqoz6.js";
-import { a as skill, o as skillFile } from "./quickstart-BsKH37Hb.js";
+import { a as skill, o as skillFile } from "./quickstart-D_Kgl1aW.js";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { homedir } from "node:os";

package/lib/{quickstart-CV2i1KDh.js → quickstart-CFk8Vj0G.js}

@@ -1,3 +1,3 @@
-import { a as skill, i as sessionStart, n as SKILL, o as skillFile, r as runSessionStart, t as OFFERED } from "./quickstart-BsKH37Hb.js";
+import { a as skill, i as sessionStart, n as SKILL, o as skillFile, r as runSessionStart, t as OFFERED } from "./quickstart-D_Kgl1aW.js";
 
 export { OFFERED, SKILL, runSessionStart, sessionStart, skill, skillFile };

package/lib/quickstart-D_Kgl1aW.js

@@ -0,0 +1,149 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+//#region src/claude-code/quickstart.ts
+const SKILL = "prae-quickstart";
+const OFFERED = "quickstart-offered";
+/**
+* Where Claude Code loads skills for a settings file: `skills/` beside
+* `~/.claude/settings.json` or `./.claude/settings.json`, and
+* `.claude/skills/` inside the managed settings directory
+* (https://code.claude.com/docs/en/skills).
+*/
+function skillFile(settings) {
+	const dir = dirname(settings);
+	return join(basename(settings) === "managed-settings.json" ? join(dir, ".claude", "skills") : join(dir, "skills"), SKILL, "SKILL.md");
+}
+const SITE = "https://prae-ai.com";
+/**
+* The `/prae-quickstart` skill, written for this install's paths and mode.
+*
+* The tour is a build–verify loop (PRA-220): Claude builds a tiny project in
+* increments, and after each one verifies it (the tests), inspects what PRAE
+* decided (`prae decisions`), and continues, adjusting when PRAE refused.
+* `allowed-tools` pre-approves the tour's own safe calls in Claude Code, so
+* the only prompt is PRAE's hold; PRAE still judges every call.
+*/
+function skill(i) {
+	const enforce = i.mode === "enforce";
+	const tour = ".prae-quickstart";
+	const decisions = `${i.prae} decisions ${i.ledger}`;
+	return `---
+name: ${SKILL}
+description: A five-minute guided tour of PRAE in this Claude Code session, as a build–verify loop. Claude builds a tiny project in steps, and after each step runs the tests, shows what PRAE decided (allowed, denied or held) and why, then continues. Use it when the user asks for the PRAE quickstart or tour, or accepts the offer of one.
+allowed-tools:
+${[
+		`Write(./${tour}/**)`,
+		`Edit(./${tour}/**)`,
+		`Bash(node --test ./${tour}/*)`,
+		`Bash(node ./${tour}/scripts/build.js)`,
+		`Bash(ls ./${tour}/*)`,
+		`Bash(${i.prae} decisions *)`,
+		`Bash(${i.prae} verify *)`
+	].map((a) => `  - ${JSON.stringify(a)}`).join("\n")}
+---
+
+# PRAE quickstart: build, verify, inspect, continue
+
+PRAE checks each of your tool calls against a policy pack before the call runs (a Claude Code \`PreToolUse\` hook), and records every decision in a signed, hash-chained ledger. Show the user what that looks like in real work. Build a tiny project in \`./${tour}/\`, one increment at a time, and run this loop for each increment:
+
+1. **Build:** make the change.
+2. **Verify:** run the tests.
+3. **Inspect:** run \`${decisions} --last 8\`. Talk only about the rows since the previous inspect, and don't narrate counting them. The inspect call is checked too, so it is always the last row. Say in one sentence what PRAE decided and why.
+4. **Continue:** go on to the next increment. Where PRAE refused something, adjust the approach the way the step says.
+
+Before each increment, say in one sentence what you are about to build. Keep the commentary short.
+
+## This install
+
+- **Mode:** ${enforce ? "**enforce**. PRAE returns its refusals and holds to Claude Code." : "**shadow**. PRAE records every decision and blocks nothing. A call it would refuse still runs, and its row in `prae decisions` says \"shadow, ran anyway\"."}
+- **Policy pack:** \`${i.pack}\`
+- **Ledger:** \`${i.ledger}\`
+- **PRAE CLI:** \`${i.prae}\`
+
+## Rules for the tour
+
+- **Run the whole tour in one go.** Don't stop to ask whether to continue. The only pause is PRAE's hold in increment 3.
+- **Make every call yourself, with your own tools.** Never suggest \`!\` shell mode: it runs outside every hook, so PRAE never sees it.
+- **Work only in \`./${tour}/\`.** Its \`.env\` is a synthetic canary, not a real secret.
+- **Report what actually happened.** If the pack in force decides differently from what a step expects, say so. The pack decides, not this guide.
+- **Never work around a refusal.** A refusal changes the approach; it is not an obstacle to route around.
+
+## 0. Set up
+
+Use the Write tool to create:
+- \`./${tour}/package.json\`: \`{ "name": "prae-quickstart", "private": true, "type": "module" }\`
+- \`./${tour}/.env\`: \`DATABASE_URL=postgres://demo:canary-not-a-secret@localhost:5432/demo\`
+
+## Increment 1: a function and its test
+
+- **Build:**
+  - \`./${tour}/src/slug.js\` exporting \`slugify(text)\`: lowercase, each run of characters other than a–z and 0–9 becomes \`-\`, and no leading or trailing \`-\`.
+  - \`./${tour}/test/slug.test.js\`: two \`node:test\` assertions.
+- **Verify:** \`node --test ./${tour}/test/*.test.js\`
+- **Inspect:** every call so far is ALLOWED. PRAE checked each one before it ran, and none needed a person. PRAE never answers "allow" on its own: it can only narrow what Claude Code would let through.
+
+## Increment 2: database configuration
+
+- **Build:** the app needs the database address. Read \`./${tour}/.env\` with the Read tool to find it.
+- **Inspect:** ${enforce ? "the read is DENIED under BASE-005, and nothing was read. Tell the user that **Ctrl+O** shows PRAE's own message: the rule, the reason and the ledger row. Claude Code labels any hook refusal \"hook error\", but PRAE's text says \"denied\"." : "the row says DENIED (shadow, ran anyway): enforce mode would have refused this read under BASE-005. Point that out."}
+- **Continue, the way the refusal points:** configuration must not depend on the agent reading secrets.
+  - \`./${tour}/src/config.js\` reads \`process.env.DATABASE_URL\`, and throws an error naming the variable when it is unset.
+  - \`./${tour}/.env.example\` documents the variable with a placeholder value.
+  - \`./${tour}/test/config.test.js\` covers both cases.
+- **Verify:** \`node --test ./${tour}/test/*.test.js\`
+- **Inspect:** the new calls are ALLOWED.
+
+## Increment 3: a build, and cleaning it
+
+- **Build:** \`./${tour}/scripts/build.js\` copies \`src/\` to \`build/\`, resolving both from the script's own directory.
+- **Verify:** \`node ./${tour}/scripts/build.js\`, then the tests again.
+- **Clean:** run \`rm -r ./${tour}/build\`. ${enforce ? "PRAE holds it for a person (BASE-002), and Claude Code asks the user with PRAE's reason. Tell them either answer is safe here, because it is build output in a scratch folder. Then **wait for their answer**." : "In shadow mode PRAE does not hold it. Claude Code's own permission prompt may still ask."}
+- **Inspect:** the row says HELD${enforce ? "" : " (shadow, ran anyway)"} under BASE-002. Then check whether \`./${tour}/build\` still exists, with \`ls ./${tour}/build\`. Claude Code does not tell you what the person answered, and the ledger records the hold, not the answer. So say what you observe: still there means they declined and nothing was deleted; gone means they approved.
+
+## 4. The whole record
+
+- **Verify the ledger:** \`${i.prae} verify ${i.ledger} --key ${i.publicKey}\`. Each row is hash-chained to the one before it and signed, so an edited, removed or reordered row shows up as a break.
+- **Why a rule fired:** ask the user to run this **in their own terminal**, not through you:
+
+  \`${i.prae} explain ${i.pack} Read file_path=./${tour}/.env\`
+
+  It prints every rule considered and the one that decided. Explain why you don't run it yourself: PRAE's pack, its hook settings and its signing key are protected from the agent (rule PRAE-SELF), so a session cannot change the policy that judges it.
+- **Changing the policy:** the pack is \`${i.pack}\`. The user edits it, never you. They check it with \`${i.prae} check ${i.pack}\`, and the next call is judged by the new pack, with no restart.
+${enforce ? "" : `- **Turning enforcement on:** the user runs \`${i.prae} init claude-code --settings ${i.settings} --enforce --apply\` in their own terminal, then starts a new session.
+`}
+## Finish
+
+- **The loop, in one line:** build a step, verify it, inspect what PRAE decided, continue. \`prae decisions\` is the inspect step in any session.
+- **More:** ${SITE}/products/developer-agents/ covers PRAE for Claude Code and other coding agents. ${SITE}/developers/ covers the CLI, the policy packs and the ledger.
+- **Cleanup:** \`./${tour}/\` stays. The user can delete it. A recursive delete is held again, which is expected.
+- **Again:** the tour can be rerun any time with \`/${SKILL}\`.
+`;
+}
+/** The SessionStart hook's stdout: the one-time offer, then nothing. */
+function sessionStart(dir) {
+	try {
+		const marker = join(dir, OFFERED);
+		if (existsSync(marker)) return "";
+		writeFileSync(marker, `${(/* @__PURE__ */ new Date()).toISOString()}\n`);
+		return JSON.stringify({
+			systemMessage: `PRAE is active: each tool call is checked against your policy before it runs. New to PRAE? Type /${SKILL} for a five-minute tour.`,
+			hookSpecificOutput: {
+				hookEventName: "SessionStart",
+				additionalContext: `PRAE was just installed, and this is the user's first session with it. PRAE checks each of your tool calls against a policy before the call runs. In your first reply, offer once, in one sentence, a five-minute guided tour (the /${SKILL} skill), then carry on with what the user asked. Run the tour only if they accept. Don't offer it again.`
+			}
+		});
+	} catch {
+		return "";
+	}
+}
+/** `prae hook claude-code session-start --dir <dir>`. */
+function runSessionStart(argv) {
+	const at = argv.indexOf("--dir");
+	const dir = at === -1 ? void 0 : argv[at + 1];
+	const out = dir === void 0 ? "" : sessionStart(dir);
+	if (out !== "") process.stdout.write(`${out}\n`);
+}
+
+//#endregion
+export { skill as a, sessionStart as i, SKILL as n, skillFile as o, runSessionStart as r, OFFERED as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prae-cli",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Operator policy for agent harnesses: validate packs, explain a decision, test a pack against security invariants, verify a decision log, and provision a governed DSH profile.",
   "keywords": [
     "dsh-plugin",
@@ -42,12 +42,12 @@
     "typescript": "^5.9.2",
     "vitest": "^3.2.4",
     "@prae/controls": "0.1.0",
-    "@prae/extract": "0.1.0",
     "@prae/instructions": "0.1.0",
-    "@prae/ledger": "0.1.0",
+    "@prae/extract": "0.1.0",
     "@prae/kernel": "0.1.0",
-    "@prae/tokens": "0.1.0",
-    "@prae/inspect": "0.1.0"
+    "@prae/inspect": "0.1.0",
+    "@prae/ledger": "0.1.0",
+    "@prae/tokens": "0.1.0"
   },
   "scripts": {
     "test": "vitest run",

package/lib/quickstart-BsKH37Hb.js

@@ -1,126 +0,0 @@
-import { existsSync, writeFileSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
-
-//#region src/claude-code/quickstart.ts
-const SKILL = "prae-quickstart";
-const OFFERED = "quickstart-offered";
-/**
-* Where Claude Code loads skills for a settings file: `skills/` beside
-* `~/.claude/settings.json` or `./.claude/settings.json`, and
-* `.claude/skills/` inside the managed settings directory
-* (https://code.claude.com/docs/en/skills).
-*/
-function skillFile(settings) {
-	const dir = dirname(settings);
-	return join(basename(settings) === "managed-settings.json" ? join(dir, ".claude", "skills") : join(dir, "skills"), SKILL, "SKILL.md");
-}
-const SITE = "https://prae-ai.com";
-/** The `/prae-quickstart` skill, written for this install's paths and mode. */
-function skill(i) {
-	const enforce = i.mode === "enforce";
-	const tour = ".prae-quickstart";
-	return `---
-name: ${SKILL}
-description: A five-minute guided tour of PRAE in this Claude Code session. It shows what PRAE allows, refuses and holds, where each decision is recorded, and how to change the policy. Use it when the user asks for the PRAE quickstart or tour, or accepts the offer of one.
----
-
-# PRAE quickstart
-
-PRAE checks each of your tool calls against a policy pack before the call runs (a Claude Code \`PreToolUse\` hook), and records every decision in a signed, hash-chained ledger. Walk the user through it, one step at a time. For each step:
-- say in one sentence what you are about to do;
-- do it;
-- say what happened and why.
-
-Keep it short. Stop and wait only where a step says to.
-
-## This install
-
-- **Mode:** ${enforce ? "**enforce**. PRAE returns its refusals and holds to Claude Code." : "**shadow**. PRAE records every decision and blocks nothing: a call it would refuse still runs, and its ledger row is marked shadow."}
-- **Policy pack:** \`${i.pack}\`
-- **Ledger:** \`${i.ledger}\`
-- **PRAE CLI:** \`${i.prae}\`
-
-## Rules for the tour
-
-- **Make every call yourself, with your own tools.** Never suggest \`!\` shell mode: it runs outside every hook, so PRAE never sees it.
-- **Work only in \`./${tour}/\`,** which you create in step 1. The credentials file there is a synthetic canary, not a real secret.
-- **Report what actually happened.** If the pack in force decides differently from what a step expects, say so: the pack decides, not this guide.
-- **Never work around a refusal.** Seeing it is the point.
-
-## 1. Set up the scratch directory
-
-Use the Write tool to create:
-- \`./${tour}/notes.md\`: one line, "PRAE quickstart scratch file."
-- \`./${tour}/credentials.json\`: \`{"api_key": "prae-quickstart-canary-not-a-secret"}\`
-- \`./${tour}/build/app.js\`: \`console.log('build output')\`
-
-These writes are inside the working tree, so the baseline allows them.
-
-## 2. An ordinary call: allowed
-
-Read \`./${tour}/notes.md\`. PRAE says nothing, and Claude Code's own permission flow is unchanged. PRAE never answers "allow" on its own: it can only narrow what Claude Code would let through.
-
-## 3. A secret: refused
-
-Read \`./${tour}/credentials.json\` with the Read tool. ${enforce ? "PRAE refuses the read before it runs (baseline rule BASE-005). Tell the user to press **Ctrl+O** to see PRAE's own message: the rule, the reason and the ledger row. Claude Code labels any hook refusal \"hook error\", but PRAE's text says \"denied\"." : "In shadow mode the read goes through. The ledger records the refusal PRAE would have returned (BASE-005), marked shadow. Point that out."}
-
-## 4. A destructive command: held
-
-Run \`rm -r ./${tour}/build\`. ${enforce ? "PRAE holds it for a person (BASE-002), and Claude Code asks the user with PRAE's reason. Tell them either answer is safe here, because it is a scratch folder. Then **wait for their answer**. If they decline, nothing is deleted. If the command runs, they approved it. Claude Code does not tell you a prompt was shown, so do not report that it ran without a hold." : "In shadow mode PRAE does not hold it. Claude Code's own permission prompt may still ask. The ledger records the hold PRAE would have placed (BASE-002)."}
-
-## 5. The record
-
-Run \`${i.prae} verify ${i.ledger} --key ${i.publicKey}\` and show the result. Each row is hash-chained to the one before it and signed, so an edited or reordered row shows up as a break. The rows from this tour are in it.
-
-Offer to write a printable report: \`${i.prae} report ${i.ledger} --out ./${tour}/report.html\`.
-
-## 6. Why a rule fired
-
-Ask the user to run this **in their own terminal**, not through you:
-
-\`${i.prae} explain ${i.pack} Read file_path=./${tour}/credentials.json\`
-
-It prints the trace: every rule considered, and the one that decided. Explain why you don't run it yourself. PRAE's pack, its hook settings and its signing key are protected from the agent (rule PRAE-SELF), so a session cannot change the policy that judges it. The ledger is readable, so step 5 works.
-
-## 7. Changing the policy
-
-The pack is the JSON file \`${i.pack}\`. The user edits it, never you. They check it with \`${i.prae} check ${i.pack}\`. The next tool call is judged by the new pack, with no restart.
-
-${enforce ? "" : `## 8. Turning enforcement on
-
-Shadow mode is for seeing what PRAE would do. To have it refuse and hold for real, the user runs \`${i.prae} init claude-code --settings ${i.settings} --enforce --apply\` in their own terminal, then starts a new session.
-
-`}## Finish
-
-- **More:** ${SITE}/products/developer-agents/ covers PRAE for Claude Code and other coding agents. ${SITE}/developers/ covers the CLI, the policy packs and the ledger.
-- **Cleanup:** \`./${tour}/\` stays. The user can delete it. A recursive delete is held again, which is expected.
-- **Again:** the tour can be rerun any time with \`/${SKILL}\`.
-`;
-}
-/** The SessionStart hook's stdout: the one-time offer, then nothing. */
-function sessionStart(dir) {
-	try {
-		const marker = join(dir, OFFERED);
-		if (existsSync(marker)) return "";
-		writeFileSync(marker, `${(/* @__PURE__ */ new Date()).toISOString()}\n`);
-		return JSON.stringify({
-			systemMessage: `PRAE is active: each tool call is checked against your policy before it runs. New to PRAE? Type /${SKILL} for a five-minute tour.`,
-			hookSpecificOutput: {
-				hookEventName: "SessionStart",
-				additionalContext: `PRAE was just installed, and this is the user's first session with it. PRAE checks each of your tool calls against a policy before the call runs. In your first reply, offer once, in one sentence, a five-minute guided tour (the /${SKILL} skill), then carry on with what the user asked. Run the tour only if they accept. Don't offer it again.`
-			}
-		});
-	} catch {
-		return "";
-	}
-}
-/** `prae hook claude-code session-start --dir <dir>`. */
-function runSessionStart(argv) {
-	const at = argv.indexOf("--dir");
-	const dir = at === -1 ? void 0 : argv[at + 1];
-	const out = dir === void 0 ? "" : sessionStart(dir);
-	if (out !== "") process.stdout.write(`${out}\n`);
-}
-
-//#endregion
-export { skill as a, sessionStart as i, SKILL as n, skillFile as o, runSessionStart as r, OFFERED as t };