holistic 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.6.1 - 2026-04-12
+
+Trust & Privacy Hardening (M006). This release implements a "Consent-First" read-only architecture, strengthens privacy boundaries for portable state, and introduces configurable MCP logging and enhanced secret redaction.
+
+- Implemented **Read-Only Command Policy**: Routine commands (`status`, `resume`, `diff`, `search`) are now strictly non-mutating. They will surface health warnings for outdated hooks but will never fix them silently.
+- Hardened **Privacy Mode Enforcement**: When `portableState` is disabled (Privacy Mode), generated shell scripts and Git hooks now exit early to prevent any accidental remote state synchronization.
+- Added **MCP Logging Privacy**: Introduced `mcpLogging` configuration (`off` | `minimal` | `default`). Defaults to `minimal` to prevent session objectives and titles from leaking into system logs.
+- Expanded **Secret Redaction**: significantly strengthened the redaction engine to identify and scrub JWT tokens, Bearer tokens, AWS keys, and PEM private key blocks.
+- Added **Redaction Quality Tests**: Integrated 8 new unit tests to verify that sensitive patterns are correctly scrubbed while preserving normal text.
+- Added **SECURITY.md**: Published a comprehensive technical disclosure of Holistic's trust model, data residency guarantees, and safety architecture.
+
 ## 0.6.0 - 2026-04-11
 
 Comprehensive Reliability & UX Refinement (M005). This release finalizes the security hardening milestone, introduces granular bootstrap controls, and adds support for explicit portable-state management.

package/README.md

@@ -17,35 +17,35 @@ Shared memory for AI agents, built into your repo.
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/node-%3E%3D24-339933.svg)](./package.json)
 
-### One command. Every agent. Zero re-explaining. ✨
+### One command. Every agent. Zero re-explaining. ✨  
+No context loss. No fragile handoffs.
 
 Holistic gives your AI agents shared memory inside the repo itself. When you switch from Claude to Codex to Gemini, the next agent can see what happened last time, what not to break, and what should happen next.
 
-
 ---
 
+## Why trust Holistic? 🔒
 
-### Why trust this?
+Holistic is designed to be **safe to install, inspectable, and predictable**.
 
-- 🔐 No known security vulnerabilities
-- 🧪 60+ automated tests covering core flows
+- 🔐 **Security-first design** — local-first, no telemetry, no external services  
+- 🧭 **Consent-first model** — system changes only happen via `bootstrap` or `repair`  
+- 👀 **Read-only by default** — routine commands never silently modify your repo or machine  
+- 🔍 **Fully transparent** — readable scripts, visible hooks, no hidden behavior  
+- 🛡️ **Privacy mode by default** — no remote sync unless explicitly enabled  
+- 🧪 60+ automated tests covering core flows  
 - 🛠️ Actively maintained (frequent releases)
-- 🔍 Transparent local setup (see `SECURITY.md`)
-
-> Early beta, but built to be safe, inspectable, and predictable.
 
+> See [SECURITY.md](./SECURITY.md) for full technical details.
 
 ---
 
-
 ## Get started in 30 seconds ⚡
 
 Open your project repo in PowerShell, Terminal, Command Prompt, or whatever shell you normally use.
 
 Requires Node.js 24+.
 
-Run these two commands:
-
 ```bash
 npm install -g holistic
 holistic bootstrap --yes
@@ -61,26 +61,22 @@ That is enough to get the basic Holistic workflow working.
 
 If you want the fuller install and setup details, jump to [Quick start](#quick-start-).
 
-
 ---
 
-
 ## The problem 😵
 
 If you use more than one AI coding assistant, the workflow usually falls apart:
 
-- 🔁 You re-explain the project every session.
-- 🐞 Bugs come back because the next agent does not know what was already fixed.
-- 🧠 Progress gets lost when context windows end.
-- 💥 Agents undo each other because there is no durable handoff.
-- 🌫️ It is hard to tell what is actually done.
+- 🔁 You re-explain the project every session  
+- 🐞 Bugs come back because the next agent does not know what was already fixed  
+- 🧠 Progress gets lost when context windows end  
+- 💥 Agents undo each other because there is no durable handoff  
+- 🌫️ It is hard to tell what is actually done  
 
 Holistic fixes that by making the repo the source of truth.
 
-
 ---
 
-
 ## What it feels like with HOLISTIC 🌿
 
 Run one setup command on a machine:
@@ -91,19 +87,15 @@ holistic bootstrap
 
 Then daily use is mostly:
 
-1. Open the repo in Codex, Claude, or another supported app.
-2. Start a fresh session.
-3. Ask the agent to read `AGENTS.md` and `HOLISTIC.md`.
-4. Let Holistic carry continuity through checkpoints, handoffs, and repo memory.
+1. Open the repo in Codex, Claude, or another supported app  
+2. Start a fresh session  
+3. Ask the agent to read `AGENTS.md` and `HOLISTIC.md`  
+4. Let Holistic carry continuity through checkpoints, handoffs, and repo memory  
 
 Most days, you do not need to keep a terminal process open or manually re-brief the agent.
 
-`holistic bootstrap` is a machine setup command, not just a repo setup command. By default it can install local startup helpers and configure Claude Desktop MCP on that machine.
-
-
 ---
 
-
 ## How it works 🧭
 
 ```text
@@ -122,9 +114,24 @@ Holistic checkpoints and handoffs keep repo memory current
 The next agent picks up without a long re-explanation
 ```
 
-
 ---
 
+## 🔒 Security & Trust Model
+
+Holistic is designed to be **transparent, audit-safe, and consent-first**.
+
+- **Read-Only by Default** — routine commands warn instead of mutating  
+- **Explicit Consent** — system changes require `bootstrap` or `repair`  
+- **Granular Control** — apply only what you want (`--yes-*` flags)  
+- **Privacy Mode** — sync disabled by default with enforced guards  
+- **MCP Logging Controls** — configurable visibility  
+- **Redaction** — JWTs, tokens, AWS keys, and PEM blocks scrubbed  
+- **Traceable Activity** — logs written locally  
+- **Git-native behavior** — respects `.gitignore`  
+
+For full details, see [SECURITY.md](./SECURITY.md).
+
+---
 
 ## Quick start 🚀
 
@@ -309,19 +316,21 @@ The portable repo memory (config, state, context, sessions) is meant to be commi
 
 ## Commands
 
+| Command | Description |
+| :--- | :--- |
 | `holistic init` | Base repo setup and scaffolding |
 | `holistic bootstrap` | One-step machine setup. Required `--yes` for Core Setup, or granular `--yes-*` flags. |
-| `holistic doctor` | Runs health checks on machine setup and sync logs |
-| `holistic repair` | Regenerates `.holistic/system/` helpers |
-| `holistic resume / start --agent <name>` | Loads project recap and prints state |
+| `holistic doctor` | Health checks and configuration diagnostics **(Read-only)** |
+| `holistic repair` | Regenerates `.holistic/system/` local helpers |
+| `holistic resume / start` | Loads project recap and prints state **(Read-only)** |
 | `holistic start-new` | Starts a fresh session |
-| `holistic checkpoint --reason "..."` | Saves progress and context |
-| `holistic handoff` | Ends a session with a handoff message |
-| `holistic status` | Shows current state and recent sync activity |
-| `holistic diff --from <id> --to <id>` | Compares two sessions |
-| `holistic search --id <session-id>` | Finds and reactivates an archived session |
-| `holistic serve` | Runs the thin MCP server |
-| `holistic watch` | Foreground daemon mode for automatic checkpoints |
+| `holistic checkpoint` | Saves progress and context **(Stateful)** |
+| `holistic handoff` | Ends a session with a handoff message **(Stateful)** |
+| `holistic status` | Shows current state and sync activity **(Read-only)** |
+| `holistic diff` | Compares two session IDs **(Read-only)** |
+| `holistic search` | Finds and retrieves session state **(Read-only)** |
+| `holistic serve` | Runs the thin MCP server **(Read-only)** |
+| `holistic watch` | Foreground daemon; automatically creates checkpoints **(Mutating)** |
 
 ### Slash command helper text (agent-facing)
 
@@ -413,18 +422,17 @@ For support and troubleshooting, see [SUPPORT.md](./SUPPORT.md).
 ---
 
 
-## Security, Privacy, and Trust 🔒
-
 Holistic is designed to be **transparent, audit-safe, and consent-first**. It is a shared memory layer that stays in your repo, not a cloud service that watches your screen.
 
 ### Trust Architecture:
-- **Granular Consent**: `holistic bootstrap` now uses a "Consent-First" model. It displays a summary of system-modifying actions and requires an explicit `--yes` for the Core Setup (hooks, daemon, MCP, attributes).
+- **Read-Only by Default**: Routine commands (`status`, `resume`, `diff`) are strictly non-mutating. They will only **warn** you if git hooks are missing or outdated, rather than fixing them silently.
+- **Granular Consent**: `holistic bootstrap` uses a "Consent-First" model. It displays a summary of system-modifying actions and requires an explicit `--yes` for the Core Setup (hooks, daemon, MCP, attributes).
 - **Surgical Control**: Use granular flags (`--yes-hooks`, `--yes-daemon`, `--yes-mcp`, `--yes-attr`, `--yes-claude`) to apply only the specific integrations you want.
-- **Privacy Mode vs. Portable Mode**: Holistic defaults to **Privacy Mode** (local-only state). To enable cross-device sync, use the `--portable` flag or set `"portableState": true` in the repo config.
-- **Read-Only Diagnostics**: The `holistic doctor` command and bootstrap pre-flight checks are strictly non-mutating. They audit your environment without making unexpected changes.
+- **Privacy Mode Enforcement**: When `portableState` is disabled (the default), all generated sync scripts and git hooks contain early-exit guards to prevent any accidental remote traffic.
+- **MCP Logging Privacy**: Control what Holistic reports to your agent UI. Set `mcpLogging` to `"off"`, `"minimal"` (default), or `"default"` in `.holistic/config.json`.
+- **Advanced Redaction**: Holistic automatically scrubs JWTs, Bearer tokens, AWS keys, and PEM blocks from all generated session metadata to prevent context leakage.
 - **Traceable Activity**: Background sync operations (PowerShell/Bash) are visible and logged with timestamps to `.holistic/system/sync.log`.
 - **Git-Native Snapshotting**: The repo snapshot logic uses native `git ls-files`, ensuring that your `.gitignore` rules are perfectly respected and performance stays $O(\text{repo size})$.
-- **Zero Shell Injection**: Internal commit logic has been stripped of shell wrappers to eliminate command injection risks.
 
 ### What it does:
 - Writes session state into `.holistic/` inside your repo (committed files you control)

package/dist/__tests__/privacy-artifacts.test.d.ts

@@ -0,0 +1,5 @@
+export declare const tests: {
+    name: string;
+    run: () => void;
+}[];
+//# sourceMappingURL=privacy-artifacts.test.d.ts.map

package/dist/__tests__/privacy-artifacts.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privacy-artifacts.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/privacy-artifacts.test.ts"],"names":[],"mappings":"AAiBA,eAAO,MAAM,KAAK;;;GA2EjB,CAAC"}

package/dist/__tests__/privacy-artifacts.test.js

@@ -0,0 +1,75 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execFileSync } from "node:child_process";
+import { initializeHolistic } from '../core/setup.js';
+import { getRuntimePaths } from '../core/state.js';
+function makeTempRepo() {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), "holistic-privacy-test-"));
+    execFileSync("git", ["init"], { cwd: root });
+    execFileSync("git", ["config", "user.name", "Test User"], { cwd: root });
+    execFileSync("git", ["config", "user.email", "test@example.com"], { cwd: root });
+    return root;
+}
+export const tests = [
+    {
+        name: "generated artifacts contain privacy guards when portableState is off",
+        run: () => {
+            const rootDir = makeTempRepo();
+            try {
+                initializeHolistic(rootDir, {
+                    portableState: false,
+                    installGitHooks: true,
+                    platform: "win32"
+                });
+                const paths = getRuntimePaths(rootDir);
+                const prePush = fs.readFileSync(path.join(rootDir, ".git", "hooks", "pre-push"), "utf8");
+                assert.match(prePush, /exit 0  # Portable state disabled \(Privacy Mode\)/);
+                const syncPs1 = fs.readFileSync(path.join(rootDir, ".holistic", "system", "sync-state.ps1"), "utf8");
+                assert.match(syncPs1, /Write-Host 'Holistic sync skipped: portableState is disabled \(Privacy Mode\).'/);
+                assert.match(syncPs1, /exit 0/);
+                const restorePs1 = fs.readFileSync(path.join(rootDir, ".holistic", "system", "restore-state.ps1"), "utf8");
+                assert.match(restorePs1, /Write-Host 'Holistic restore skipped: portableState is disabled \(Privacy Mode\).'/);
+                assert.match(restorePs1, /exit 0/);
+                initializeHolistic(rootDir, {
+                    portableState: false,
+                    installGitHooks: true,
+                    platform: "linux"
+                });
+                const syncSh = fs.readFileSync(path.join(rootDir, ".holistic", "system", "sync-state.sh"), "utf8");
+                assert.match(syncSh, /echo 'Holistic sync skipped: portableState is disabled \(Privacy Mode\).'/);
+                assert.match(syncSh, /exit 0/);
+                const restoreSh = fs.readFileSync(path.join(rootDir, ".holistic", "system", "restore-state.sh"), "utf8");
+                assert.match(restoreSh, /echo 'Holistic restore skipped: portableState is disabled \(Privacy Mode\).'/);
+                assert.match(restoreSh, /exit 0/);
+            }
+            finally {
+                fs.rmSync(rootDir, { recursive: true, force: true });
+            }
+        }
+    },
+    {
+        name: "generated artifacts do NOT contain privacy guards when portableState is on",
+        run: () => {
+            const rootDir = makeTempRepo();
+            try {
+                initializeHolistic(rootDir, {
+                    portableState: true,
+                    installGitHooks: true,
+                    platform: "linux"
+                });
+                const prePush = fs.readFileSync(path.join(rootDir, ".git", "hooks", "pre-push"), "utf8");
+                assert.doesNotMatch(prePush, /Privacy Mode/);
+                const syncSh = fs.readFileSync(path.join(rootDir, ".holistic", "system", "sync-state.sh"), "utf8");
+                assert.doesNotMatch(syncSh, /Privacy Mode/);
+                const restoreSh = fs.readFileSync(path.join(rootDir, ".holistic", "system", "restore-state.sh"), "utf8");
+                assert.doesNotMatch(restoreSh, /Privacy Mode/);
+            }
+            finally {
+                fs.rmSync(rootDir, { recursive: true, force: true });
+            }
+        }
+    }
+];
+//# sourceMappingURL=privacy-artifacts.test.js.map

package/dist/__tests__/privacy-artifacts.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"privacy-artifacts.test.js","sourceRoot":"","sources":["../../src/__tests__/privacy-artifacts.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/redact.test.d.ts

@@ -0,0 +1,5 @@
+export declare const tests: {
+    name: string;
+    run: () => void;
+}[];
+//# sourceMappingURL=redact.test.d.ts.map

package/dist/__tests__/redact.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/redact.test.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,KAAK;;;GAuFjB,CAAC"}

package/dist/__tests__/redact.test.js

@@ -0,0 +1,91 @@
+import assert from "node:assert";
+import { sanitizeText } from '../core/redact.js';
+export const tests = [
+    {
+        name: "sanitizeText redacts OpenAI-style sk- keys",
+        run: () => {
+            const input = "Use key sk-Abc123Abc123Abc123 for access";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "Use key [REDACTED_SECRET] for access");
+        },
+    },
+    {
+        name: "sanitizeText redacts GitHub PATs",
+        run: () => {
+            const input = "My token is ghp_foobarbazqux123";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "My token is [REDACTED_SECRET]");
+        },
+    },
+    {
+        name: "sanitizeText redacts JWT tokens",
+        run: () => {
+            const input = "Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoyNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "Authorization: [REDACTED_JWT]");
+        },
+    },
+    {
+        name: "sanitizeText redacts Bearer tokens",
+        run: () => {
+            const input = "Header: Bearer abc.123.def-456";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "Header: Bearer [REDACTED]");
+        },
+    },
+    {
+        name: "sanitizeText redacts AWS Access Key IDs",
+        run: () => {
+            const input = "AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "AWS_ACCESS_KEY_ID=[REDACTED_AWS_KEY]");
+        },
+    },
+    {
+        name: "sanitizeText redacts PEM Private Key blocks",
+        run: () => {
+            const input = `Here is the key:
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpQIBAAKCAQEA75v...
+...more...
+-----END RSA PRIVATE KEY-----
+Keep it safe.`;
+            const output = sanitizeText(input);
+            assert.ok(output.includes("[REDACTED_PEM_PRIVATE_KEY]"));
+            assert.ok(!output.includes("MIIEpQIBAAKCAQEA75v"));
+        },
+    },
+    {
+        name: "sanitizeText redacts assignment-style secrets",
+        run: () => {
+            const input = "password: mypassword123; secret=shhh";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "password: [REDACTED]; secret= [REDACTED]");
+        },
+    },
+    {
+        name: "sanitizeText redacts Azure keys",
+        run: () => {
+            const input = "azure_key = abc123def456ghi789jkl012mno345pqr";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "azure_key = [REDACTED]");
+        },
+    },
+    {
+        name: "sanitizeText redacts Stripe keys",
+        run: () => {
+            const input = "stripe_key: sk_test_51...abc";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, "stripe_key: [REDACTED]");
+        },
+    },
+    {
+        name: "sanitizeText preserves normal text",
+        run: () => {
+            const input = "The quick brown fox jumps over the lazy dog.";
+            const output = sanitizeText(input);
+            assert.strictEqual(output, input);
+        },
+    },
+];
+//# sourceMappingURL=redact.test.js.map

package/dist/__tests__/redact.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.test.js","sourceRoot":"","sources":["../../src/__tests__/redact.test.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAA4C,YAAY,EAAE,aAAa,EAAgB,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA2EvJ,wBAAgB,cAAc,IAAI,MAAM,CA4BvC;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AA4ED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAcnG;AAMD,wBAAgB,UAAU,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAoE1G;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CA8D1E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAA4C,YAAY,EAAE,aAAa,EAAgB,WAAW,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AA2EvJ,wBAAgB,cAAc,IAAI,MAAM,CA2BvC;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAoFD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,YAAY,GAAG,YAAY,CAcnG;AAMD,wBAAgB,UAAU,CAAC,WAAW,EAAE,aAAa,EAAE,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,WAAW,GAAG,MAAM,CAoE1G;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CA8D1E"}

package/dist/cli.js

@@ -6,7 +6,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { renderRepoLocalCliCommands } from './core/cli-fallback.js';
 import { captureRepoSnapshot, clearPendingCommit, commitPendingChanges, writePendingCommit } from './core/git.js';
 import { writeDerivedDocs } from './core/docs.js';
-import { bootstrapHolistic, getSetupStatus, initializeHolistic, refreshHolisticHooks, repairHolistic } from './core/setup.js';
+import { bootstrapHolistic, checkHolisticHooksStatus, getSetupStatus, initializeHolistic, refreshHolisticHooks, repairHolistic, validateRuntimeConfig } from './core/setup.js';
 import { printSplash, printSplashError, renderSplash } from './core/splash.js';
 import { requestAutoSync } from './core/sync.js';
 import { runDaemonTick } from './daemon.js';
@@ -71,30 +71,29 @@ function getVersion() {
 export function renderHelpText() {
     return `Holistic CLI v${getVersion()}
 
-Usage:
+Setup Commands:
   holistic init [--install-daemon] [--install-hooks] [--platform win32|darwin|linux] [--interval 30] [--remote origin] [--state-ref refs/holistic/state] [--state-branch holistic/state]
   holistic bootstrap [--platform win32|darwin|linux] [--interval 30] [--yes]
-  holistic doctor
   holistic repair [--platform win32|darwin|linux] [--refresh-hooks false] [--install-daemon true] [--configure-mcp true]
-  holistic start [--agent codex|claude|antigravity|gemini|copilot|cursor|goose|gsd|gsd2] [--continue] [--json]
-  holistic resume [--agent codex|claude|antigravity|gemini|copilot|cursor|goose|gsd|gsd2] [--continue] [--json]
-  holistic checkpoint --reason "<reason>" [--status "<status>"] [--plan "<step>"]... [--completion-kind natural-breakpoint|task-complete|slice-complete|milestone-complete] [--completion-source agent|system] [--completion-recorded-at <iso8601>]
-  holistic checkpoint --fixed "<bug>" [--fix-files "<file>"] [--fix-risk "<what reintroduces it>"]
-  holistic handoff [--draft] [--summary "<summary>"] [--next "<step>"]... [--commit]
-  holistic start-new [--goal "<goal>"] [--title "<title>"] [--plan "<step>"]...
-  holistic status
-  holistic diff --from "<session-id>" --to "<session-id>" [--format text|json]
-  holistic search --id "<session-id>" [--format text|json]
-  holistic serve
-  holistic watch [--agent codex|claude|antigravity|gemini|copilot|cursor|goose|gsd|gsd2] [--interval 60]
 
-Checkpoint examples:
-  holistic checkpoint --reason "tests passed" --status "Focused verification is green" --completion-kind natural-breakpoint --completion-source agent
-  holistic checkpoint --reason "feature complete" --status "Ready for handoff" --completion-kind task-complete --completion-source agent
+Read-Only & Diagnostic Commands:
+  holistic status       | View current repository health and sync status.
+  holistic doctor       | Run deep diagnostics and configuration validation.
+  holistic diff         | Compare session state between two points in time.
+  holistic search       | Find and retrieve session state by ID.
+  holistic resume       | Load the latest project recap and continue work.
+
+Stateful & Mutating Commands:
+  holistic checkpoint   | Capture current work progress (reason required).
+  holistic handoff      | Prepare a narrative handoff for the next session.
+  holistic start-new    | Initialize a new session with a fresh goal.
+  holistic watch        | Foreground daemon mode; may create checkpoints automatically.
 
-Use checkpoint at natural breakpoints like tests passed, bug fixed, feature complete, focus change, or before compaction. Use handoff as the final safety valve when the session is ending.
+Checkpoint examples:
+  holistic checkpoint --reason "tests passed" --status "Focused verification is green"
+  holistic checkpoint --reason "feature complete" --status "Ready for handoff"
 
-  'holistic start' is an alias for 'holistic resume'.
+Use checkpoint at natural breakpoints like tests passed, bug fixed, feature complete, or focus change. Use handoff as the final safety valve when the session is ending.
 `;
 }
 function printHelp() {
@@ -108,6 +107,13 @@ function reportHookWarnings(warnings) {
         process.stderr.write(`${warning}\n`);
     }
 }
+function warnIfHooksOutdated(rootDir) {
+    const result = checkHolisticHooksStatus(rootDir);
+    if (result.refreshed.length > 0) {
+        process.stderr.write(`\u26A0 Holistic hooks are outdated. Run 'holistic repair' to refresh them.\n`);
+        process.stderr.write(`  Hint: Keeping hooks current ensures session continuity and privacy guards are active.\n`);
+    }
+}
 function refreshHooksBeforeCommand(rootDir) {
     const hookResult = refreshHolisticHooks(rootDir);
     reportHookWarnings(hookResult.warnings);
@@ -427,13 +433,33 @@ async function handleDoctor(rootDir, parsed) {
     printSplash({
         message: "running holistic health check...",
     });
+    const paths = getRuntimePaths(rootDir);
     const status = getSetupStatus(rootDir);
     process.stdout.write("\nSystem Configuration:\n\n");
     printSetupStatusTable(status);
+    const findings = validateRuntimeConfig(paths);
+    if (findings.length > 0) {
+        process.stdout.write("\nConfiguration Diagnostics:\n\n");
+        for (const f of findings) {
+            const icon = f.level === "error" ? "✖" : f.level === "warn" ? "⚠" : "ℹ";
+            process.stdout.write(`${icon} ${f.field.padEnd(20)} | ${f.level.padEnd(10)} | ${f.message}\n`);
+        }
+        const errors = findings.filter(f => f.level === "error").length;
+        const warns = findings.filter(f => f.level === "warn").length;
+        if (errors > 0)
+            process.stdout.write("\n✖ config invalid\n");
+        else if (warns > 0)
+            process.stdout.write("\n⚠ config loaded with safe fallbacks\n");
+        else
+            process.stdout.write("\n✓ config valid\n");
+    }
+    else {
+        process.stdout.write("\n✓ config valid\n");
+    }
     process.stdout.write("\nSync Diagnostics:\n\n");
     process.stdout.write(renderSyncStatus(rootDir));
     const healthy = status.every(s => s.status === "ok");
-    if (healthy) {
+    if (healthy && findings.every(f => f.level !== "error")) {
         process.stdout.write("\n\u2713 Holistic is healthy and correctly configured on this machine.\n");
     }
     else {
@@ -489,7 +515,7 @@ Repo-local CLI: ${repairFallback}
     return 0;
 }
 async function handleResume(rootDir, parsed) {
-    refreshHooksBeforeCommand(rootDir);
+    warnIfHooksOutdated(rootDir);
     const agent = asAgent(firstFlag(parsed.flags, "agent", "unknown"));
     if (firstFlag(parsed.flags, "continue") === "true") {
         const mutateResult = mutateState(rootDir, (state) => continueFromLatest(rootDir, state, agent));
@@ -526,7 +552,6 @@ async function handleResume(rootDir, parsed) {
     return 0;
 }
 async function handleCheckpoint(rootDir, parsed) {
-    refreshHooksBeforeCommand(rootDir);
     const mutateResult = mutateState(rootDir, (state, paths) => {
         const regressions = listFlag(parsed.flags, "regression");
         const fixed = firstFlag(parsed.flags, "fixed");
@@ -577,7 +602,6 @@ async function handleCheckpoint(rootDir, parsed) {
     return 0;
 }
 async function handleStartNew(rootDir, parsed) {
-    refreshHooksBeforeCommand(rootDir);
     const agent = asAgent(firstFlag(parsed.flags, "agent", "unknown"));
     let goal = firstFlag(parsed.flags, "goal");
     const title = firstFlag(parsed.flags, "title");
@@ -598,7 +622,6 @@ async function handleStartNew(rootDir, parsed) {
     return 0;
 }
 async function handleHandoff(rootDir, parsed) {
-    refreshHooksBeforeCommand(rootDir);
     const { state, paths } = loadState(rootDir);
     if (!state.activeSession) {
         process.stderr.write("No active session to hand off.\n");
@@ -759,7 +782,7 @@ function renderSyncStatus(rootDir) {
     return lines.join("\n") + "\n";
 }
 async function handleStatus(rootDir) {
-    refreshHooksBeforeCommand(rootDir);
+    warnIfHooksOutdated(rootDir);
     const { state } = loadState(rootDir);
     process.stdout.write(renderStatus(rootDir, state));
     return 0;
@@ -831,7 +854,6 @@ async function handleSearch(rootDir, parsed) {
     return 0;
 }
 async function handleServe(rootDir) {
-    refreshHooksBeforeCommand(rootDir);
     printSplashError({
         message: "starting MCP server on stdio...",
     });
@@ -863,7 +885,6 @@ async function handleMarkCommit(rootDir, parsed) {
     return 0;
 }
 async function handleWatch(rootDir, parsed) {
-    refreshHooksBeforeCommand(rootDir);
     const intervalSeconds = Number.parseInt(firstFlag(parsed.flags, "interval", "60"), 10);
     const agent = asAgent(firstFlag(parsed.flags, "agent", "unknown"));
     process.stdout.write(`Watching repo every ${intervalSeconds}s for checkpoint-worthy changes.\n`);