digital-brain 0.1.2 → 0.1.7

package/README.md

@@ -24,9 +24,9 @@ Digital Brain gives them a structured, local map of:
 npx digital-brain init
 ```
 
-The installer asks a short setup quiz: history window, primary focus, refresh cadence, always-on interval, active time window, outbound mode, and AI adapter setup.
+The installer asks a short setup quiz: setup mode, history window, primary focus, refresh cadence, always-on interval, active time window, outbound mode, and AI adapter setup.
 
-The quiz is mostly multiple choice. Press Enter to accept the default. If you skip the vault path, Digital Brain creates a new folder in the current directory:
+The quiz is mostly multiple choice. Pick with `A/B/C`, `1/2/3`, the exact value, or press Enter to accept the default. If you skip the vault path, Digital Brain creates a new folder in the current directory:
 
 ```text
 ./Digital Brain Vault
@@ -38,7 +38,7 @@ For a non-interactive setup:
 npx digital-brain init --yes
 ```
 
-For local always-on setup:
+Inside the quiz, choose `Auto mode` to use recommended always-on local refresh settings. You can also start there directly:
 
 ```bash
 npx digital-brain init --full-auto
@@ -46,6 +46,8 @@ npx digital-brain init --full-auto
 
 Full-auto means local repeated refreshes. It does not mean blind auto-send. WhatsApp sending still defaults to drafts or explicit confirmation, and the AI-disclosure guard stays enabled.
 
+`init` also runs a setup check. npm installs the package dependencies automatically, and Digital Brain does not require pip packages. If Python, WhatsApp for Mac, or optional Ollama setup is missing, the check prints the exact next step. See [docs/SETUP.md](docs/SETUP.md).
+
 For local development:
 
 ```bash
@@ -77,11 +79,22 @@ node ./bin/digital-brain.js init ./Digital Brain\ Vault
 ## Core Commands
 
 ```bash
-digital-brain init ./Digital Brain\ Vault
-digital-brain sync-whatsapp --vault ./Digital Brain\ Vault --days 30
-digital-brain extract --vault ./Digital Brain\ Vault --days 30
-digital-brain interpret --vault ./Digital Brain\ Vault --days 30
-digital-brain send-whatsapp --vault ./Digital Brain\ Vault --to "Name" --message "text"
+digital-brain init
+digital-brain run
+digital-brain doctor
+digital-brain send-whatsapp --to "Name" --message "text"
+```
+
+`init` remembers your vault globally, so `run` works from anywhere. `run` syncs WhatsApp, extracts relationships, and writes interpreted memory in one command.
+
+Use `digital-brain doctor` or `digital-brain tutorial` anytime to see dependency status and next steps.
+
+The lower-level commands still exist for debugging:
+
+```bash
+digital-brain sync-whatsapp
+digital-brain extract
+digital-brain interpret
 ```
 
 The sender drafts by default. Add `--yes` to actually send.

package/bin/digital-brain.js

@@ -5,7 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { fileURLToPath } from "node:url";
-import { copyDir, ensureDir, packageRoot, resolveVault } from "../lib/fs.js";
+import { copyDir, ensureDir, packageRoot, resolveVault, writeDefaultVault } from "../lib/fs.js";
 
 const root = packageRoot(import.meta.url);
 
@@ -19,7 +19,9 @@ async function main() {
   const args = parseArgs(argv);
 
   if (command === "init") await init(argv, args);
+  else if (command === "run" || command === "refresh") runRefresh(argv, args);
   else if (command === "doctor") doctor();
+  else if (command === "tutorial" || command === "setup-check") doctor({ tutorial: true });
   else if (command === "sync-whatsapp") runPython("digital_brain_whatsapp_mac_sync.py", argv);
   else if (command === "extract") runPython("digital_brain_relationship_extractor.py", argv);
   else if (command === "interpret") runPython("digital_brain_relationship_interpreter.py", argv);
@@ -31,6 +33,7 @@ async function init(argv, args) {
   const positional = argv.filter((arg) => !arg.startsWith("--"));
   const defaultVault = path.resolve(process.cwd(), "Digital Brain Vault");
   const fullAuto = toBoolean(args["full-auto"]);
+  let setupMode = fullAuto ? "full-auto" : "guided";
   let vault = positional[0] ? path.resolve(positional[0]) : args.yes ? defaultVault : "";
   let selfName = args["self-name"] || "";
   let connectAi = toBoolean(args["connect-ai"]);
@@ -46,39 +49,50 @@ async function init(argv, args) {
   if (!args.yes) {
     const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
     printSetupHeader(defaultVault);
-    vault ||= path.resolve(await ask(rl, "Vault path", defaultVault, "Enter creates this folder if it does not exist."));
-    selfName ||= await ask(rl, "Your name", "Me");
-    dataWindowDays = await askNumber(rl, "History to import", dataWindowDays, { suffix: "days", min: 1 });
+    vault ||= path.resolve(await ask(rl, "📁 Vault path", defaultVault, "Enter creates this folder if it does not exist."));
+    selfName ||= await ask(rl, "👤 Your name", "Me");
+    dataWindowDays = await askNumber(rl, "🕰️  History to import", dataWindowDays, { suffix: "days", min: 1 });
+    setupMode = await select(rl, "Setup mode", [
+      ["guided", "Guided", "Pick each setting yourself.", "🧭"],
+      ["full-auto", "Auto mode", "Use recommended always-on local refresh settings.", "⚡"],
+    ], setupMode);
     focus ||= await select(rl, "Primary focus", [
-      ["relationship-memory", "Relationship memory", "Map people, tone, and recurring patterns."],
-      ["reply-help", "Reply help", "Prioritize drafting guidance and typing-style matching."],
-      ["work-context", "Work context", "Prioritize collaborators, projects, and operational notes."],
+      ["relationship-memory", "Relationship memory", "Map people, tone, and recurring patterns.", "🧠"],
+      ["reply-help", "Reply help", "Prioritize drafting guidance and typing-style matching.", "💬"],
+      ["work-context", "Work context", "Prioritize collaborators, projects, and operational notes.", "💼"],
     ], "relationship-memory");
-    schedule = await select(rl, "Refresh cadence", [
-      ["manual", "Manual", "Only runs when you run a command."],
-      ["daily", "Daily", "Good for a low-maintenance personal vault."],
-      ["hourly", "Hourly", "Keeps memory warm without running constantly."],
-      ["every-30-min", "Every 30 minutes", "Useful for morning or work-window guidance."],
-      ["always-on", "Always-on local loop", "Runs repeatedly while your computer is awake."],
-    ], schedule);
+    if (setupMode === "full-auto") {
+      schedule = "always-on";
+      console.log("");
+      console.log("⚡ Auto mode selected: always-on local refresh, draft-first outbound, AI disclosure guard enabled.");
+    } else {
+      schedule = await select(rl, "Refresh cadence", [
+        ["manual", "Manual", "Only runs when you run a command.", "🖐️"],
+        ["daily", "Daily", "Good for a low-maintenance personal vault.", "🌅"],
+        ["hourly", "Hourly", "Keeps memory warm without running constantly.", "⏱️"],
+        ["every-30-min", "Every 30 minutes", "Useful for morning or work-window guidance.", "🔁"],
+        ["always-on", "Always-on local loop", "Runs repeatedly while your computer is awake.", "⚡"],
+      ], schedule);
+    }
     if (schedule === "always-on") {
-      refreshIntervalMinutes = await askNumber(rl, "Always-on pull interval", refreshIntervalMinutes, {
+      refreshIntervalMinutes = await askNumber(rl, "⏳ Always-on pull interval", refreshIntervalMinutes, {
         suffix: "minutes",
         min: 1,
       });
     }
-    activeWindow = await ask(rl, "Active window for frequent refreshes", activeWindow);
+    activeWindow = await ask(rl, "🪟 Active window for frequent refreshes", activeWindow);
     outboundMode = await select(rl, "WhatsApp outbound mode", [
-      ["disabled", "Disabled", "Never prepares WhatsApp sends."],
-      ["draft", "Draft only", "Prepares text and requires you to send it."],
-      ["send-with-confirmation", "Send with confirmation", "Can send only after explicit command confirmation."],
+      ["disabled", "Disabled", "Never prepares WhatsApp sends.", "🔒"],
+      ["draft", "Draft only", "Prepares text and requires you to send it.", "✍️"],
+      ["send-with-confirmation", "Send with confirmation", "Can send only after explicit command confirmation.", "✅"],
     ], outboundMode);
-    connectAi = await confirm(rl, "Add global AI pointers for Codex/Claude/Gemini?", true);
+    connectAi = await confirm(rl, "🔗 Add global AI pointers for Codex/Claude/Gemini?", true);
     responsibilityAccepted = await responsibilityGate(rl, { schedule, outboundMode });
     if (!responsibilityAccepted && (schedule === "always-on" || outboundMode === "send-with-confirmation")) {
       console.log("Full-auto/outbound confirmation was not accepted. Using manual refresh and draft-only outbound.");
       schedule = "manual";
       outboundMode = "draft";
+      setupMode = "guided";
     }
     rl.close();
   }
@@ -94,7 +108,7 @@ async function init(argv, args) {
     activeWindow,
     timezone,
     outboundMode,
-    setupMode: fullAuto ? "full-auto" : "guided",
+    setupMode,
     responsibilityAccepted,
     defaults: {
       enterUsesDefault: true,
@@ -109,6 +123,7 @@ async function init(argv, args) {
     },
   };
   writeConfig(vault, config);
+  writeDefaultVault(vault);
   writeRefreshScript(vault, config);
   writeWatchScript(vault, config);
 
@@ -120,43 +135,145 @@ async function init(argv, args) {
 
   console.log(`Digital Brain vault created: ${vault}`);
   console.log(`Config: ${path.join(vault, "digital-brain.config.json")}`);
+  console.log(`Default vault saved: ${vault}`);
   console.log(`Refresh script: ${path.join(vault, "Tools", "digital-brain-refresh.sh")}`);
   console.log(`Always-on script: ${path.join(vault, "Tools", "digital-brain-watch.sh")}`);
   console.log("Next:");
-  console.log(`  digital-brain sync-whatsapp --vault "${vault}" --days ${dataWindowDays}`);
-  console.log(`  digital-brain extract --vault "${vault}" --days ${dataWindowDays}`);
-  console.log(`  digital-brain interpret --vault "${vault}" --days ${dataWindowDays}`);
+  console.log("  digital-brain run");
   if (schedule === "always-on") console.log(`  "${path.join(vault, "Tools", "digital-brain-watch.sh")}"`);
+  printSetupCheck(vault, { tutorial: true });
 }
 
-function doctor() {
-  const checks = [
-    ["node", process.version],
-    ["python3", shell("python3", ["--version"])],
-    ["sqlite3", shell("sqlite3", ["--version"])],
-    ["ollama", shell("ollama", ["--version"], true)],
-  ];
-  for (const [name, value] of checks) {
-    console.log(`${name}: ${value || "not found"}`);
-  }
-  const macDb = path.join(os.homedir(), "Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite");
-  console.log(`WhatsApp Mac DB: ${fs.existsSync(macDb) ? macDb : "not found"}`);
+function doctor(options = {}) {
+  printSetupCheck(resolveVault(process.cwd()), options);
 }
 
 function runPython(script, argv) {
-  const resolved = withVault(argv);
-  const result = spawnSync("python3", [path.join(root, "scripts", script), ...resolved], { stdio: "inherit" });
+  const result = runPythonStep(script, withVault(argv));
   process.exit(result.status ?? 1);
 }
 
+function runRefresh(argv, args) {
+  const vault = getVaultFromArgs(argv);
+  const config = readVaultConfig(vault);
+  const days = String(args.days || args["data-window-days"] || config.dataWindowDays || 30);
+  const syncArgs = ["--vault", vault, "--days", days, "--markdown-mode", args["markdown-mode"] || "month"];
+  const extractArgs = ["--vault", vault, "--days", days];
+  const interpretArgs = ["--vault", vault, "--days", days];
+  if (args["min-messages"]) extractArgs.push("--min-messages", String(args["min-messages"]));
+  console.log(`Digital Brain refresh: ${vault}`);
+  for (const [label, script, stepArgs] of [
+    ["sync", "digital_brain_whatsapp_mac_sync.py", syncArgs],
+    ["extract", "digital_brain_relationship_extractor.py", extractArgs],
+    ["interpret", "digital_brain_relationship_interpreter.py", interpretArgs],
+  ]) {
+    if (toBoolean(args[`skip-${label}`])) {
+      console.log(`\n→ ${label} skipped`);
+      continue;
+    }
+    console.log(`\n→ ${label}`);
+    const result = runPythonStep(script, stepArgs);
+    if ((result.status ?? 1) !== 0) process.exit(result.status ?? 1);
+  }
+  console.log("\nDigital Brain refresh complete.");
+}
+
+function runPythonStep(script, argv) {
+  return spawnSync("python3", [path.join(root, "scripts", script), ...argv], { stdio: "inherit" });
+}
+
 function runNode(script, argv) {
-  const result = spawnSync(process.execPath, [path.join(root, script), ...argv], { stdio: "inherit" });
+  const result = spawnSync(process.execPath, [path.join(root, script), ...withVault(argv)], { stdio: "inherit" });
   process.exit(result.status ?? 1);
 }
 
 function withVault(argv) {
   if (argv.includes("--vault") || argv.some((arg) => arg.startsWith("--vault="))) return argv;
-  return ["--vault", resolveVault(process.cwd()), ...argv];
+  return ["--vault", getVaultFromArgs(argv), ...argv];
+}
+
+function getVaultFromArgs(argv) {
+  const args = parseArgs(argv);
+  if (args.vault) return path.resolve(String(args.vault));
+  return resolveVault(process.cwd());
+}
+
+function readVaultConfig(vault) {
+  const file = path.join(vault, "digital-brain.config.json");
+  if (!fs.existsSync(file)) {
+    console.error(`No Digital Brain vault found. Run "digital-brain init" first, or pass --vault <path>.`);
+    process.exit(1);
+  }
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function printSetupCheck(vault, options = {}) {
+  const pythonVersion = shell("python3", ["--version"], true);
+  const pythonSqlite = shell("python3", ["-c", "import sqlite3; print('ok')"], true);
+  const ollamaVersion = shell("ollama", ["--version"], true);
+  const macDb = path.join(os.homedir(), "Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite");
+  const checks = [
+    {
+      label: "Node",
+      ok: nodeMajor() >= 20,
+      value: process.version,
+      hint: "Install Node 20 or newer from https://nodejs.org.",
+    },
+    {
+      label: "Package dependencies",
+      ok: true,
+      value: "installed by npm",
+    },
+    {
+      label: "Python 3",
+      ok: Boolean(pythonVersion),
+      value: pythonVersion || "not found",
+      hint: "Install with: brew install python",
+    },
+    {
+      label: "Python sqlite3",
+      ok: pythonSqlite === "ok",
+      value: pythonSqlite === "ok" ? "available" : "not found",
+      hint: "Use a Python 3 build with sqlite3 support.",
+    },
+    {
+      label: "WhatsApp Mac database",
+      ok: fs.existsSync(macDb),
+      value: fs.existsSync(macDb) ? "found" : "not found yet",
+      hint: "Open WhatsApp for Mac and log in. If macOS blocks access, grant Terminal Full Disk Access.",
+    },
+    {
+      label: "Ollama",
+      ok: Boolean(ollamaVersion),
+      value: ollamaVersion || "optional",
+      hint: "Optional local LLM: brew install ollama",
+      optional: true,
+    },
+  ];
+
+  console.log("");
+  console.log("Setup check");
+  for (const check of checks) {
+    const icon = check.ok ? "✓" : check.optional ? "○" : "!";
+    console.log(`  ${icon} ${check.label}: ${check.value}`);
+    if (!check.ok && check.hint) console.log(`    ${check.hint}`);
+  }
+  if (fs.existsSync(path.join(vault, "digital-brain.config.json"))) {
+    console.log(`  ✓ Default vault: ${vault}`);
+  } else {
+    console.log("  ! Default vault: not set");
+    console.log("    Run: digital-brain init");
+  }
+
+  if (options.tutorial) {
+    console.log("");
+    console.log("How to use it");
+    console.log("  1. Open WhatsApp for Mac once and keep it logged in.");
+    console.log("  2. Run: digital-brain run");
+    console.log("  3. Ask your AI to use the generated vault notes for personal context.");
+    console.log("");
+    console.log("No pip install is needed. npm installs the package dependencies.");
+  }
 }
 
 function writeConfig(vault, config) {
@@ -173,9 +290,7 @@ set -euo pipefail
 VAULT="${vault.replace(/"/g, '\\"')}"
 DAYS="${days}"
 
-digital-brain sync-whatsapp --vault "$VAULT" --days "$DAYS" --markdown-mode month
-digital-brain extract --vault "$VAULT" --days "$DAYS"
-digital-brain interpret --vault "$VAULT" --days "$DAYS"
+digital-brain run --vault "$VAULT" --days "$DAYS" --markdown-mode month
 
 echo "Digital Brain refresh complete for $VAULT"
 `;
@@ -226,9 +341,11 @@ Use it as local personal context when the user asks about preferences, relations
 
 function printSetupHeader(defaultVault) {
   console.log("");
-  console.log("Digital Brain setup");
-  console.log("Press Enter to accept the shown default.");
-  console.log(`If you skip the vault path, Digital Brain creates: ${defaultVault}`);
+  console.log("╭────────────────────────────────────────╮");
+  console.log("│ 🧠 Digital Brain setup                 │");
+  console.log("╰────────────────────────────────────────╯");
+  console.log("Pick with A/B/C, 1/2/3, exact value, or press Enter for the default.");
+  console.log(`Skipping the vault path creates: ${defaultVault}`);
   console.log("");
 }
 
@@ -250,18 +367,22 @@ async function askNumber(rl, label, fallback, options = {}) {
 async function select(rl, label, options, fallback) {
   const defaultIndex = Math.max(0, options.findIndex(([value]) => value === fallback));
   console.log("");
-  console.log(`${label}:`);
-  options.forEach(([, title, description], index) => {
-    const marker = index === defaultIndex ? "default" : "";
-    console.log(`  ${index + 1}. ${title}${marker ? ` (${marker})` : ""}`);
+  console.log(`◇ ${label}`);
+  options.forEach(([, title, description, icon = "•"], index) => {
+    const marker = index === defaultIndex ? "  ← default" : "";
+    const letter = letterFor(index);
+    console.log(`  ${letter}) ${icon}  ${title}${marker}`);
     console.log(`     ${description}`);
   });
-  const answer = await rl.question(`Select [${defaultIndex + 1}]: `);
+  const answer = await rl.question(`Choose ${letterFor(defaultIndex)}/${defaultIndex + 1} [${letterFor(defaultIndex)}]: `);
   const trimmed = answer.trim();
   if (!trimmed) return options[defaultIndex][0];
+  const letterIndex = indexFromLetter(trimmed);
+  if (letterIndex >= 0 && letterIndex < options.length) return options[letterIndex][0];
   const selected = Number(trimmed);
   if (Number.isInteger(selected) && selected >= 1 && selected <= options.length) return options[selected - 1][0];
-  const exact = options.find(([value]) => value === trimmed);
+  const lower = trimmed.toLowerCase();
+  const exact = options.find(([value, title]) => value.toLowerCase() === lower || title.toLowerCase() === lower);
   return exact ? exact[0] : options[defaultIndex][0];
 }
 
@@ -276,13 +397,23 @@ async function responsibilityGate(rl, { schedule, outboundMode }) {
   const needsGate = schedule === "always-on" || outboundMode === "send-with-confirmation";
   if (!needsGate) return true;
   console.log("");
-  console.log("Responsibility check:");
+  console.log("⚠️  Responsibility check:");
   console.log("  Digital Brain may use local databases, WhatsApp Web, and black-box third-party app behavior.");
   console.log("  You are responsible for consent, privacy, message content, and any sends triggered from this machine.");
   console.log("  Enter does not approve this mode.");
   return confirm(rl, "I understand and want this mode enabled", false);
 }
 
+function letterFor(index) {
+  return String.fromCharCode(65 + index);
+}
+
+function indexFromLetter(value) {
+  const normalized = value.trim().toUpperCase();
+  if (!/^[A-Z]$/.test(normalized)) return -1;
+  return normalized.charCodeAt(0) - 65;
+}
+
 function shell(command, args, optional = false) {
   const result = spawnSync(command, args, { encoding: "utf8" });
   if (result.error && optional) return "";
@@ -290,6 +421,10 @@ function shell(command, args, optional = false) {
   return (result.stdout || result.stderr).trim().split("\n")[0];
 }
 
+function nodeMajor() {
+  return Number(process.version.replace(/^v/, "").split(".")[0]);
+}
+
 function parseArgs(argv) {
   const out = {};
   for (let i = 0; i < argv.length; i += 1) {
@@ -325,10 +460,12 @@ function help() {
 
 Usage:
   digital-brain init [vault]
+  digital-brain run
   digital-brain doctor
-  digital-brain sync-whatsapp --vault <path> --days 30
-  digital-brain extract --vault <path> --days 30
-  digital-brain interpret --vault <path> --days 30
-  digital-brain send-whatsapp --vault <path> --to "Name" --message "Text" [--yes]
+  digital-brain tutorial
+  digital-brain sync-whatsapp --days 30
+  digital-brain extract --days 30
+  digital-brain interpret --days 30
+  digital-brain send-whatsapp --to "Name" --message "Text" [--yes]
 `);
 }

package/docs/AUTOMATIONS.md

@@ -10,6 +10,14 @@ Tools/digital-brain-refresh.sh
 
 That script runs sync, extract, and interpret using the install-time config.
 
+After setup, the normal manual command is:
+
+```bash
+digital-brain run
+```
+
+`init` saves your default vault in `~/.digital-brain/config.json`, so `run` does not need a vault path.
+
 ## Configurable At Install
 
 `digital-brain init` asks:
@@ -17,6 +25,7 @@ That script runs sync, extract, and interpret using the install-time config.
 - vault path
 - your name
 - history window in days
+- setup mode: guided or auto mode
 - primary focus: relationship memory, reply help, work context
 - refresh cadence: manual, daily, hourly, every 30 minutes, or always-on
 - refresh interval in minutes for always-on mode, clamped to a minimum of 1
@@ -24,7 +33,7 @@ That script runs sync, extract, and interpret using the install-time config.
 - WhatsApp outbound mode
 - whether to add AI adapter pointers
 
-Most questions are multiple choice. Press Enter to use the displayed default.
+Most questions are multiple choice. Pick with `A/B/C`, `1/2/3`, the exact value, or press Enter to use the displayed default.
 
 Important defaults:
 
@@ -44,15 +53,15 @@ The answers are saved in:
 digital-brain.config.json
 ```
 
-## Full Auto
+## Auto Mode
 
-Use:
+Choose `Auto mode` during `digital-brain init`, or use:
 
 ```bash
 digital-brain init --full-auto
 ```
 
-Full-auto configures local always-on refreshes with a 5 minute default interval. It still uses the local watch script, so it only runs while the machine and runner are awake.
+Auto mode configures local always-on refreshes with a 5 minute default interval. It still uses the local watch script, so it only runs while the machine and runner are awake.
 
 During the guided quiz, always-on and send-with-confirmation require an explicit responsibility check. Pressing Enter does not approve that check. If it is skipped, Digital Brain falls back to manual refresh and draft-only outbound.
 
@@ -63,7 +72,7 @@ Use a Codex cron automation pointed at the generated vault.
 Prompt:
 
 ```text
-Run `Tools/digital-brain-refresh.sh`. Verify completion and report only counts plus output paths. Do not print private message contents.
+Run `digital-brain run`. Verify completion and report only counts plus output paths. Do not print private message contents.
 ```
 
 Example schedule ideas:

package/docs/SETUP.md

@@ -0,0 +1,46 @@
+# Setup
+
+Digital Brain is designed to install with one npm command:
+
+```bash
+npx digital-brain init
+```
+
+npm installs the Node dependencies. No pip install is needed; the Python scripts only use the standard library.
+
+## What Init Checks
+
+After the quiz, `init` runs a setup check for:
+
+- Node 20+
+- npm package dependencies
+- Python 3
+- Python sqlite3 support
+- WhatsApp for Mac local database access
+- optional Ollama
+
+Run the check again anytime:
+
+```bash
+digital-brain doctor
+```
+
+For a short usage guide:
+
+```bash
+digital-brain tutorial
+```
+
+## What Cannot Be Silently Installed
+
+Digital Brain does not silently install or configure system apps.
+
+- WhatsApp for Mac must be installed and logged in by the user.
+- macOS may require Full Disk Access for the terminal app.
+- Ollama is optional and only needed for local LLM workflows.
+
+Once setup passes, normal use is:
+
+```bash
+digital-brain run
+```

package/lib/fs.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -28,5 +29,31 @@ export function resolveVault(cwd) {
     if (parent === current) break;
     current = parent;
   }
+  const configured = readDefaultVault();
+  if (configured) return configured;
   return path.resolve(cwd);
 }
+
+export function globalConfigPath() {
+  return path.join(os.homedir(), ".digital-brain", "config.json");
+}
+
+export function readDefaultVault() {
+  const file = globalConfigPath();
+  if (!fs.existsSync(file)) return "";
+  try {
+    const config = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (config.defaultVault && fs.existsSync(path.join(config.defaultVault, "digital-brain.config.json"))) {
+      return config.defaultVault;
+    }
+  } catch {
+    return "";
+  }
+  return "";
+}
+
+export function writeDefaultVault(vault) {
+  const file = globalConfigPath();
+  ensureDir(path.dirname(file));
+  fs.writeFileSync(file, `${JSON.stringify({ defaultVault: vault }, null, 2)}\n`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "digital-brain",
-  "version": "0.1.2",
+  "version": "0.1.7",
   "description": "Your private digital imprint for AI assistants.",
   "type": "module",
   "bin": {