holistic 0.5.5 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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.
+
+- Added **Granular Bootstrap Flags**: Users can now surgically enable setup items with `--yes-hooks`, `--yes-daemon`, `--yes-mcp`, `--yes-attr`, and `--yes-claude`.
+- Added `--portable` flag to `init` and `bootstrap` to explicitly toggle **Portable State (Privacy Mode)** during setup.
+- Refined **Bootstrap Pre-flight UX**: The pre-flight check now clearly differentiates between "Core Configuration" (covered by `--yes`) and "Optional/Explicit" items.
+- Fixed **Runtime Script Resolution**: Resolved a critical production bug where the CLI incorrectly searched for `.ts` files in built environments; now correctly resolves `.js` files when TypeScript stripping is unavailable.
+- Hardened **Read-Only Diagnostics**: Refactored `holistic doctor` and `getSetupStatus` to be strictly read-only, ensuring health checks never inadvertently modify Git hooks or repository state.
+- Improved **MCP Server Transparency**: Sanitized startup logging to prevent context leakage in system logs while maintaining full context availability via the `holistic_resume` tool.
+- Aligned **Claude Code Hook Detection**: Fixed a bug where `holistic doctor` misreported Claude hook status by incorrectly checking the filesystem instead of `settings.json`.
+
 ## 0.5.5 - 2026-04-10
 
 Major Security & Trust Hardening (M005) to eliminate silent automation and improve auditability.

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 🚀
 
@@ -178,12 +185,14 @@ Advanced overrides:
 ```bash
 holistic bootstrap --state-ref refs/holistic/state
 holistic bootstrap --state-branch holistic/state
+holistic bootstrap --portable
 ```
 
-If you want repo scaffolding without changing local desktop integrations or daemon startup on the current machine, use:
+If you want repo scaffolding without changing local desktop integrations or daemon startup on the current machine, you can use granular flags to be surgical:
 
 ```bash
-holistic bootstrap --install-daemon false --configure-mcp false
+# Only install Git hooks and managed attributes
+holistic bootstrap --yes-hooks --yes-attr
 ```
 
 **What to commit:**
@@ -208,7 +217,7 @@ One-time machine setup:
 
 - Run `holistic bootstrap`.
 - By default it scaffolds repo files, installs hooks, sets up daemon startup, and configures supported integrations such as Claude Desktop MCP on the current machine.
-- If you only want repo files and hooks, use `holistic bootstrap --install-daemon false --configure-mcp false`.
+- To be surgical about what is applied, use granular flags like `--yes-hooks`, `--yes-daemon`, or `--yes-mcp`.
 
 Normal use:
 
@@ -307,8 +316,10 @@ 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` to apply system changes. |
+| `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 |
@@ -411,17 +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:
-- **Explicit Consent**: `holistic bootstrap` will show you exactly what changes it wants to make to your machine (daemon installation, git hooks, Claude setup) and requires an explicit `--yes` to proceed.
-- **Privacy First**: Remote syncing is **disabled by default**. Set `"portableState": true` in `.holistic/config.json` only if you want to share memory across devices using a hidden git ref.
-- **Traceable Activity**: Background sync operations (PowerShell/Bash) are no longer silent. All activity is logged with timestamps and error details to `.holistic/system/sync.log`.
-- **Health Checks**: Use `holistic doctor` at any time to audit your machine-local setup and verify sync log health.
+- **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 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__/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;;;GAuEjB,CAAC"}

package/dist/__tests__/redact.test.js

@@ -0,0 +1,75 @@
+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 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":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;QACE,IAAI,EAAE,4CAA4C;QAClD,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG,0CAA0C,CAAC;YACzD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,sCAAsC,CAAC,CAAC;QACrE,CAAC;KACF;IACD;QACE,IAAI,EAAE,kCAAkC;QACxC,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG,iCAAiC,CAAC;YAChD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;QAC9D,CAAC;KACF;IACD;QACE,IAAI,EAAE,iCAAiC;QACvC,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG,4KAA4K,CAAC;YAC3L,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,+BAA+B,CAAC,CAAC;QAC9D,CAAC;KACF;IACD;QACE,IAAI,EAAE,oCAAoC;QAC1C,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG,gCAAgC,CAAC;YAC/C,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;QAC1D,CAAC;KACF;IACD;QACE,IAAI,EAAE,yCAAyC;QAC/C,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG,wCAAwC,CAAC;YACvD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,sCAAsC,CAAC,CAAC;QACrE,CAAC;KACF;IACD;QACE,IAAI,EAAE,6CAA6C;QACnD,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG;;;;;cAKN,CAAC;YACT,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC,CAAC;YACzD,MAAM,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAC;QACrD,CAAC;KACF;IACD;QACE,IAAI,EAAE,+CAA+C;QACrD,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG,sCAAsC,CAAC;YACrD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,0CAA0C,CAAC,CAAC;QACzE,CAAC;KACF;IACD;QACE,IAAI,EAAE,oCAAoC;QAC1C,GAAG,EAAE,GAAG,EAAE;YACR,MAAM,KAAK,GAAG,8CAA8C,CAAC;YAC7D,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;KACF;CACF,CAAC"}

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,CA4BvC;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAmFD,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 } from './core/setup.js';
 import { printSplash, printSplashError, renderSplash } from './core/splash.js';
 import { requestAutoSync } from './core/sync.js';
 import { runDaemonTick } from './daemon.js';
@@ -108,6 +108,12 @@ 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`);
+    }
+}
 function refreshHooksBeforeCommand(rootDir) {
     const hookResult = refreshHolisticHooks(rootDir);
     reportHookWarnings(hookResult.warnings);
@@ -135,7 +141,7 @@ function runtimeScript(name) {
     const runtimeDir = path.dirname(currentFile);
     const useStripTypes = extension === ".ts";
     return {
-        scriptPath: path.resolve(runtimeDir, `${name}${useStripTypes ? ".ts" : ".ts"}`),
+        scriptPath: path.resolve(runtimeDir, `${name}${useStripTypes ? ".ts" : ".js"}`),
         useStripTypes,
     };
 }
@@ -307,14 +313,17 @@ async function handleInit(rootDir, parsed) {
     const platformFlag = firstFlag(parsed.flags, "platform", process.platform);
     const platform = platformFlag === "windows" ? "win32" : platformFlag === "macos" ? "darwin" : platformFlag === "linux" ? "linux" : platformFlag;
     const intervalSeconds = Number.parseInt(firstFlag(parsed.flags, "interval", "30"), 10);
+    const portableState = firstFlag(parsed.flags, "portable") === "true" ? true : firstFlag(parsed.flags, "portable") === "false" ? false : undefined;
     const result = initializeHolistic(rootDir, {
-        installDaemon: firstFlag(parsed.flags, "install-daemon") === "true",
-        installGitHooks: firstFlag(parsed.flags, "install-hooks") === "true",
+        installDaemon: firstFlag(parsed.flags, "yes-daemon") === "true",
+        installGitHooks: firstFlag(parsed.flags, "yes-hooks") === "true",
+        installGitAttributes: firstFlag(parsed.flags, "yes-attr", "true") !== "false",
         platform: platform,
         intervalSeconds,
         remote: firstFlag(parsed.flags, "remote", "origin"),
         stateRef: firstFlag(parsed.flags, "state-ref"),
         stateBranch: firstFlag(parsed.flags, "state-branch"),
+        portableState,
     });
     reportHookWarnings(result.gitHookWarnings);
     const statusItems = [];
@@ -357,18 +366,33 @@ async function handleBootstrap(rootDir, parsed) {
         printSplash({
             message: "bootstrap pre-flight: pending actions",
         });
-        process.stdout.write("\nHolistic needs to make the following changes to your system:\n\n");
+        process.stdout.write("\nHolistic needs to make the following changes to your system (some outside this repo):\n\n");
         printSetupStatusTable(status);
-        process.stdout.write("\nRun with --yes to apply these changes.\n");
+        process.stdout.write("\nRun with --yes to apply the Core Configuration:\n");
+        process.stdout.write("  ✓ Git hooks, Background daemon, MCP config, Git attributes\n");
+        process.stdout.write("\nOptional / Explicit flags:\n");
+        process.stdout.write("  --yes-claude   Install Claude Code SessionStart hooks\n");
+        process.stdout.write("  --portable     Enable Portable State (remote-sync via git ref)\n");
+        process.stdout.write("\nGranular overrides:\n");
+        process.stdout.write("  --yes-hooks, --yes-daemon, --yes-mcp, --yes-attr\n");
         return 1;
     }
     printSplash({
         message: "bootstrapping holistic on this machine...",
     });
+    const installDaemon = firstFlag(parsed.flags, "yes-daemon") === "true" || (confirmed && firstFlag(parsed.flags, "install-daemon", "true") !== "false");
+    const installGitHooks = firstFlag(parsed.flags, "yes-hooks") === "true" || (confirmed && firstFlag(parsed.flags, "install-hooks", "true") !== "false");
+    const configureMcp = firstFlag(parsed.flags, "yes-mcp") === "true" || (confirmed && firstFlag(parsed.flags, "configure-mcp", "true") !== "false");
+    const installGitAttributes = firstFlag(parsed.flags, "yes-attr") === "true" || confirmed;
+    const installClaudeHooks = firstFlag(parsed.flags, "yes-claude") === "true";
+    const portableState = firstFlag(parsed.flags, "portable") === "true" ? true : firstFlag(parsed.flags, "portable") === "false" ? false : undefined;
     const result = bootstrapHolistic(rootDir, {
-        installDaemon: firstFlag(parsed.flags, "install-daemon", "true") !== "false",
-        installGitHooks: firstFlag(parsed.flags, "install-hooks", "true") !== "false",
-        configureMcp: firstFlag(parsed.flags, "configure-mcp", "true") !== "false",
+        installDaemon,
+        installGitHooks,
+        installGitAttributes,
+        installClaudeHooks,
+        configureMcp,
+        portableState,
         platform: platform,
         intervalSeconds,
         remote: firstFlag(parsed.flags, "remote", "origin"),
@@ -471,7 +495,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));
@@ -508,7 +532,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");
@@ -559,11 +582,17 @@ async function handleCheckpoint(rootDir, parsed) {
     return 0;
 }
 async function handleStartNew(rootDir, parsed) {
-    refreshHooksBeforeCommand(rootDir);
     const agent = asAgent(firstFlag(parsed.flags, "agent", "unknown"));
-    const goal = firstFlag(parsed.flags, "goal");
+    let goal = firstFlag(parsed.flags, "goal");
     const title = firstFlag(parsed.flags, "title");
     const plan = listFlag(parsed.flags, "plan");
+    if (!goal) {
+        goal = await ask("Current objective / goal");
+    }
+    if (!goal) {
+        process.stderr.write("Error: A goal is required to start a new session.\n");
+        return 1;
+    }
     const mutateResult = mutateState(rootDir, (state) => startNewSession(rootDir, state, agent, goal, plan, title));
     if (!mutateResult.success || !mutateResult.state) {
         process.stderr.write(`Error: Failed to start session: ${mutateResult.error}\n`);
@@ -573,7 +602,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");
@@ -734,7 +762,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;
@@ -806,7 +834,6 @@ async function handleSearch(rootDir, parsed) {
     return 0;
 }
 async function handleServe(rootDir) {
-    refreshHooksBeforeCommand(rootDir);
     printSplashError({
         message: "starting MCP server on stdio...",
     });
@@ -838,7 +865,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`);