@sbains2/lifeos 0.2.0 → 0.2.2

package/bin/lifeos.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { run } from '../src/index.js';
 import { runDoctorCommand } from '../src/commands/doctor.js';
+import { runBrainCommand } from '../src/commands/brain.js';
 
 // Parse argv: optional subcommand + positional target dir + flags
 // Usage:
@@ -24,10 +25,24 @@ Wizard options:
                 defaults everywhere. Target install time: < 60 seconds.
 
 Doctor options:
+  --fix         Apply deterministic fixes (mkdir folders, copy missing
+                council files, generate writing_style stub, generate
+                .env.example with help URLs). Never touches secrets or
+                shell rc. Re-runs doctor after to show before/after.
   --json        Emit machine-readable JSON (for CI / scripting)
   --quiet       Suppress ✓ lines, only show warnings and errors
   --strict      Exit code 1 even on warnings (default: warnings are 0)
 
+Brain options:
+  --dry-run     Show what would run without invoking graphify
+  --json        Emit machine-readable JSON (for CI / scripting)
+
+Note on brain: lifeos brain shells out to graphify (https://github.com/
+safishamsi/graphify), an OSS knowledge-graph tool. Install once with
+"pip install graphifyy && graphify install". Code parsing is 100% local;
+semantic extraction uses your existing AI-assistant session (no separate
+API key, no incremental cost).
+
 Arguments:
   target-dir    Directory to scaffold into / verify (default: current working dir)
 
@@ -53,11 +68,19 @@ async function main() {
       json: flags.has('--json'),
       quiet: flags.has('--quiet'),
       strict: flags.has('--strict'),
+      fix: flags.has('--fix'),
+    });
+    process.exit(exitCode);
+  }
+  if (subcommand === 'brain') {
+    const exitCode = await runBrainCommand(targetDir, {
+      dryRun: flags.has('--dry-run'),
+      json: flags.has('--json'),
     });
     process.exit(exitCode);
   }
-  if (subcommand === 'brain' || subcommand === 'migrate') {
-    console.error(`\nNot yet implemented: \`lifeos ${subcommand}\`. See docs/COMMANDS.md for the design.`);
+  if (subcommand === 'migrate') {
+    console.error(`\nNot yet implemented: \`lifeos migrate\`. See docs/COMMANDS.md for the design.`);
     process.exit(2);
   }
   // Default: run the wizard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sbains2/lifeos",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Scaffold a personal LifeOS — life-quadrant folders, a council of AI agent voices, and curated MCP wiring. Generates a working lifeos.config.json + .claude/agents/council/ in 2-4 minutes (or <60s with --minimal). BETA — early seed release.",
   "type": "module",
   "bin": {

package/src/brain.js

@@ -0,0 +1,129 @@
+/**
+ * `lifeos brain` — thin wrapper around graphify (https://github.com/safishamsi/graphify).
+ *
+ * Why graphify (decision rationale):
+ * - Open-source, MIT-licensed
+ * - Runs entirely on the user's machine: code parsing is 100% local via tree-sitter
+ *   AST + NetworkX + Leiden clustering
+ * - For semantic content (docs, images, PDFs), uses the user's EXISTING AI-assistant
+ *   session — Claude Code, Cursor, Codex, etc. — via credentials they've already
+ *   configured. No separate API key, no incremental cost beyond their existing
+ *   subscription.
+ * - Cost to LifeOS project: $0 (we don't host or proxy anything)
+ * - Cost to friends installing LifeOS: $0 incremental (their Claude Code subscription
+ *   is already paying for any LLM calls graphify makes)
+ *
+ * This module is a thin shell-out wrapper. It does not re-implement graphify;
+ * it just invokes it with the right paths from lifeos.config.json.
+ */
+
+import { execSync, spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join, isAbsolute } from 'node:path';
+
+/**
+ * Check if graphify is installed and available in PATH.
+ * Pure side-effect-free check. Returns boolean.
+ */
+export function isGraphifyInstalled() {
+  try {
+    execSync('command -v graphify', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Determine what `lifeos brain` would do for a given scaffold, without executing.
+ * Returns { ok, paths, cwd, outputHint } on success or { ok: false, error } on failure.
+ */
+export function planBrainRun(targetDir) {
+  const configPath = join(targetDir, 'lifeos.config.json');
+  if (!existsSync(configPath)) {
+    return { ok: false, error: `lifeos.config.json not found at ${configPath}` };
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return { ok: false, error: `lifeos.config.json parse failed: ${err.message}` };
+  }
+
+  // Prefer brain.graphify.paths (explicit config); fall back to active quadrant paths
+  const configuredPaths = config.brain?.graphify?.paths;
+  const activeQuadrantPaths = (config.quadrants ?? []).filter((q) => q.active).map((q) => q.path);
+  const paths = configuredPaths && configuredPaths.length > 0 ? configuredPaths : activeQuadrantPaths;
+
+  if (paths.length === 0) {
+    return {
+      ok: false,
+      error:
+        'No paths to index. Add at least one active quadrant to lifeos.config.json or set brain.graphify.paths explicitly.',
+    };
+  }
+
+  // Resolve relative paths against targetDir for display + check existence (warn, not error)
+  const resolvedPaths = paths.map((p) => (isAbsolute(p) ? p : join(targetDir, p)));
+  const missingPaths = resolvedPaths.filter((p) => !existsSync(p));
+
+  return {
+    ok: true,
+    paths,
+    resolvedPaths,
+    missingPaths,
+    cwd: targetDir,
+    outputHint: config.brain?.graphify?.output ?? './graphify-out',
+  };
+}
+
+/**
+ * Invoke graphify with the planned paths. Inherits stdio so the user sees graphify's
+ * own output stream. Returns { ok, exitCode, paths, outputDir } or { ok: false, error }.
+ *
+ * Does NOT auto-install graphify (too invasive — pip install requires user consent).
+ * If graphify is missing, returns ok:false with install instructions.
+ */
+export function runBrain(targetDir, options = {}) {
+  const { dryRun = false } = options;
+
+  const plan = planBrainRun(targetDir);
+  if (!plan.ok) return plan;
+
+  if (!isGraphifyInstalled()) {
+    return {
+      ok: false,
+      error: 'graphify not installed',
+      installCommand: 'pip install graphifyy && graphify install',
+      installUrl: 'https://github.com/safishamsi/graphify',
+    };
+  }
+
+  if (dryRun) {
+    return {
+      ok: true,
+      dryRun: true,
+      command: 'graphify',
+      args: plan.paths,
+      cwd: plan.cwd,
+      outputDir: join(plan.cwd, 'graphify-out'),
+    };
+  }
+
+  // Shell out to graphify; let it write to its default `graphify-out/` in the
+  // working directory. We deliberately don't try to redirect output — graphify's
+  // CLI surface evolves and we don't want to fight it. Output location is
+  // surfaced to the user in our wrapper's "next steps" message.
+  const result = spawnSync('graphify', plan.paths, {
+    cwd: plan.cwd,
+    stdio: 'inherit',
+    encoding: 'utf8',
+  });
+
+  return {
+    ok: result.status === 0,
+    exitCode: result.status,
+    paths: plan.paths,
+    outputDir: join(plan.cwd, 'graphify-out'),
+  };
+}

package/src/commands/brain.js

@@ -0,0 +1,148 @@
+/**
+ * `lifeos brain` subcommand orchestrator.
+ *
+ * Thin wrapper around src/brain.js — handles flag parsing, output formatting,
+ * and exit codes. The actual graphify invocation is in brain.js.
+ *
+ * Flags:
+ *   --dry-run    Show what would run without invoking graphify
+ *                (does NOT require graphify to be installed — useful for previewing)
+ *   --json       Emit machine-readable JSON (for CI / scripting)
+ */
+
+import { runBrain, planBrainRun, isGraphifyInstalled } from '../brain.js';
+import { c } from '../utils/colors.js';
+
+export async function runBrainCommand(targetDir, options = {}) {
+  const { dryRun = false, json = false } = options;
+
+  // Step 1: plan first (no external deps — works without graphify)
+  const plan = planBrainRun(targetDir);
+  if (!plan.ok) {
+    if (json) {
+      console.log(JSON.stringify(plan, null, 2));
+    } else {
+      console.log('');
+      console.log(c.err(`✗ ${plan.error}`));
+      console.log('');
+    }
+    return 1;
+  }
+
+  // Step 2: if dry-run, print plan and exit (graphify install not required)
+  if (dryRun) {
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: true,
+            dryRun: true,
+            command: 'graphify',
+            args: plan.paths,
+            cwd: plan.cwd,
+            outputDir: `${plan.cwd}/graphify-out`,
+            graphifyInstalled: isGraphifyInstalled(),
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log('');
+      console.log(c.bold('lifeos brain --dry-run') + c.dim(' — would invoke:'));
+      console.log('');
+      console.log(`  ${c.cyan('cd')} ${plan.cwd}`);
+      console.log(`  ${c.cyan('graphify')} ${plan.paths.join(' ')}`);
+      console.log('');
+      console.log(c.dim(`  Output would land in: ${plan.cwd}/graphify-out/`));
+      if (plan.missingPaths && plan.missingPaths.length > 0) {
+        console.log('');
+        console.log(c.warn(`  ⚠ ${plan.missingPaths.length} path(s) don't exist — graphify may skip them:`));
+        for (const p of plan.missingPaths) {
+          console.log(c.dim(`     ${p}`));
+        }
+      }
+      if (!isGraphifyInstalled()) {
+        console.log('');
+        console.log(c.warn('  ⚠ graphify not installed yet — actual run would fail.'));
+        console.log(c.dim('     Install: pip install graphifyy && graphify install'));
+      }
+      console.log('');
+    }
+    return 0;
+  }
+
+  // Step 3: check graphify installed (only required for real execution)
+  if (!isGraphifyInstalled()) {
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: false,
+            error: 'graphify not installed',
+            installCommand: 'pip install graphifyy && graphify install',
+            installUrl: 'https://github.com/safishamsi/graphify',
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.log('');
+      console.log(c.bold('lifeos brain') + c.dim(' — knowledge graph via graphify'));
+      console.log('');
+      console.log(`  ${c.err('✗')} graphify not installed`);
+      console.log(c.dim(`     graphify is the OSS knowledge-graph builder LifeOS uses for the brain.`));
+      console.log(c.dim(`     It runs entirely on your machine — code parsing is 100% local`));
+      console.log(c.dim(`     (tree-sitter AST), and semantic extraction goes through your`));
+      console.log(c.dim(`     existing Claude Code / Cursor / Codex session (no separate API`));
+      console.log(c.dim(`     key, no incremental cost).`));
+      console.log('');
+      console.log(`     ${c.cyan('→ install:  ')}pip install graphifyy && graphify install`);
+      console.log(`     ${c.cyan('→ docs:     ')}https://github.com/safishamsi/graphify`);
+      console.log(`     ${c.cyan('→ preview:  ')}lifeos brain --dry-run ${targetDir}`);
+      console.log('');
+    }
+    return 1;
+  }
+
+  // Step 4: real invocation
+  console.log('');
+  console.log(c.bold('lifeos brain') + c.dim(` — indexing ${plan.paths.length} path(s) via graphify`));
+  console.log(c.dim(`  paths: ${plan.paths.join(', ')}`));
+  console.log(c.dim(`  cwd:   ${plan.cwd}`));
+  if (plan.missingPaths && plan.missingPaths.length > 0) {
+    console.log(c.warn(`  ⚠ ${plan.missingPaths.length} path(s) don't exist — graphify may skip them: ${plan.missingPaths.join(', ')}`));
+  }
+  console.log('');
+  console.log(c.dim('--- graphify output below ---'));
+  console.log('');
+
+  const result = runBrain(targetDir, { dryRun: false });
+
+  console.log('');
+  if (result.ok) {
+    if (json) {
+      console.log(JSON.stringify({ ok: true, paths: result.paths, outputDir: result.outputDir }, null, 2));
+    } else {
+      console.log(c.bold(c.ok('✓ brain built')));
+      console.log(c.dim(`  Output: ${result.outputDir}`));
+      console.log(c.dim(`  View graph:    open ${result.outputDir}/graph.html`));
+      console.log(c.dim(`  Read summary:  cat ${result.outputDir}/GRAPH_REPORT.md`));
+      console.log(c.dim(`  Query graph:   graphify query "your question"`));
+      console.log('');
+    }
+    return 0;
+  } else {
+    if (json) {
+      console.log(JSON.stringify({ ok: false, exitCode: result.exitCode }, null, 2));
+    } else {
+      console.log(c.err(`✗ graphify exited with code ${result.exitCode}`));
+      console.log(c.dim('  Check graphify output above for details. Common issues:'));
+      console.log(c.dim('    - Paths not readable / outside scope'));
+      console.log(c.dim('    - graphify install incomplete (run `graphify install` again)'));
+      console.log(c.dim('    - Underlying AI assistant session not configured'));
+    }
+    return result.exitCode || 1;
+  }
+}

package/src/commands/doctor.js

@@ -11,25 +11,79 @@
  */
 
 import { runDoctor } from '../doctor.js';
+import { applyDoctorFixes } from '../remedy.js';
 import { c } from '../utils/colors.js';
 
 export async function runDoctorCommand(targetDir, options = {}) {
-  const { json = false, quiet = false, strict = false } = options;
+  const { json = false, quiet = false, strict = false, fix = false } = options;
 
   const result = runDoctor(targetDir);
 
-  if (json) {
+  if (json && !fix) {
     console.log(JSON.stringify(result, null, 2));
-  } else {
+    if (result.summary.error > 0) return 1;
+    if (strict && result.summary.warn > 0) return 1;
+    return 0;
+  }
+
+  if (!fix) {
     printHumanReport(result, { quiet });
+    if (result.summary.error > 0) return 1;
+    if (strict && result.summary.warn > 0) return 1;
+    return 0;
+  }
+
+  // --fix mode: print initial state, apply remedies, re-run doctor, print final state
+  console.log('');
+  console.log(c.bold('lifeos doctor --fix') + c.dim(' — initial state'));
+  console.log('');
+  printSummaryLine(result.summary);
+
+  const remedy = applyDoctorFixes(targetDir);
+  console.log('');
+  console.log(c.bold('Applying deterministic fixes...'));
+  if (remedy.applied.length === 0) {
+    console.log(c.dim(`  ${c.dot} nothing to auto-fix (issues remaining need user input — see suggestions below)`));
+  } else {
+    for (const fix of remedy.applied) {
+      console.log(`  ${c.check} ${fix.id}: ${fix.message}`);
+    }
+  }
+  if (remedy.skipped.length > 0) {
+    console.log(c.dim(`  Skipped (need manual action):`));
+    for (const s of remedy.skipped) {
+      console.log(c.dim(`    ${c.dot} ${s.id}: ${s.reason}`));
+    }
+  }
+
+  // Re-run doctor to show new state
+  console.log('');
+  console.log(c.bold('Re-running doctor...'));
+  console.log('');
+  const after = runDoctor(targetDir);
+  printHumanReport(after, { quiet });
+
+  if (json) {
+    console.log('');
+    console.log(c.dim('--json + --fix combined: emitting after-state JSON'));
+    console.log(JSON.stringify(after, null, 2));
   }
 
-  // Exit code: 1 if any error; 1 if any warning AND strict mode; else 0
-  if (result.summary.error > 0) return 1;
-  if (strict && result.summary.warn > 0) return 1;
+  if (after.summary.error > 0) return 1;
+  if (strict && after.summary.warn > 0) return 1;
   return 0;
 }
 
+function printSummaryLine(summary) {
+  const { ok, warn, error } = summary;
+  const parts = [
+    `${c.ok(`${ok} ok`)}`,
+    warn > 0 ? c.warn(`${warn} warning${warn === 1 ? '' : 's'}`) : null,
+    error > 0 ? c.err(`${error} error${error === 1 ? '' : 's'}`) : null,
+  ].filter(Boolean);
+  console.log('  ' + parts.join(', '));
+}
+
 function printHumanReport(result, { quiet }) {
   console.log('');
   console.log(c.bold('lifeos doctor') + c.dim(' — checking your scaffold'));

package/src/doctor.js

@@ -253,7 +253,33 @@ export function runDoctor(targetDir) {
     }
   }
 
-  // Check 9: MCP runtimes available (npx / uvx / docker)
+  // Check 9: graphify installed (only if brain is enabled — graphify powers `lifeos brain`)
+  if (config.brain?.graphify?.enabled) {
+    let graphifyInstalled = false;
+    try {
+      execSync('command -v graphify', { stdio: 'ignore' });
+      graphifyInstalled = true;
+    } catch {
+      /* not installed */
+    }
+    if (graphifyInstalled) {
+      checks.push({
+        id: 'graphify_installed',
+        name: 'graphify installed (powers `lifeos brain`)',
+        status: 'ok',
+      });
+    } else {
+      checks.push({
+        id: 'graphify_installed',
+        name: 'graphify installed (powers `lifeos brain`)',
+        status: 'warn',
+        message: 'graphify CLI not in PATH — brain command will fail',
+        fix: 'Install (no API key needed; uses your existing Claude Code session):\n     pip install graphifyy && graphify install\n     docs: https://github.com/safishamsi/graphify',
+      });
+    }
+  }
+
+  // Check 10: MCP runtimes available (npx / uvx / docker)
   const wiredRuntimes = new Set();
   if (registry) {
     const byId = new Map(registry.servers.map((s) => [s.id, s]));

package/src/index.js

@@ -26,7 +26,7 @@ export async function run(targetDir, options = {}) {
   const { minimal = false } = options;
 
   console.log('');
-  console.log(c.bold('lifeos') + c.dim(' v0.2.0 — scaffold a personal LifeOS'));
+  console.log(c.bold('lifeos') + c.dim(' v0.2.2 — scaffold a personal LifeOS'));
   console.log(c.dim(`Target directory: ${targetDir}`));
   if (minimal) {
     console.log(c.dim('Mode: --minimal (speed-optimized; using template defaults for quadrants, council, MCPs)'));

package/src/remedy.js

@@ -0,0 +1,288 @@
+/**
+ * `lifeos doctor --fix` — deterministic remediation for an unhealthy scaffold.
+ *
+ * Trust posture:
+ * - NEVER touches user secrets (tokens, OAuth credentials)
+ * - NEVER edits the user's shell rc (~/.zshrc, ~/.bashrc)
+ * - NEVER overwrites existing files without backup
+ * - ONLY applies fixes for checks where the right action is unambiguous and
+ *   doesn't require user input
+ *
+ * What it can fix automatically:
+ * - Missing quadrant folders → mkdir -p (with placeholder README)
+ * - Missing council files → copy from bundled templates
+ * - Missing writing_style.md (when path is set in config) → create stub
+ * - Missing .env.example for required auth env vars → generate with help-URL
+ *   comments per env var. User sources it as .env.local after filling in
+ *   values.
+ *
+ * What it CANNOT fix automatically (must be user-driven):
+ * - Missing env var values (we'd need the secret)
+ * - Schema version mismatch (needs `lifeos migrate` — not yet implemented)
+ * - Empty brain index (needs `lifeos brain` — not yet implemented)
+ * - Missing MCP runtimes (npx / docker / uvx — user must install)
+ *
+ * Each fix returns { id, applied: boolean, action: string, message: string }.
+ * Caller decides how to render.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, copyFileSync, readFileSync } from 'node:fs';
+import { join, dirname, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadRegistry } from './templates-loader.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_COUNCIL = join(__dirname, '..', 'templates', 'council');
+
+/**
+ * Apply all deterministic fixes to a scaffold. Reads the same lifeos.config.json
+ * doctor reads. Returns { applied: [], skipped: [], summary }.
+ */
+export function applyDoctorFixes(targetDir, options = {}) {
+  const { allowWritingStyleStub = true, allowEnvExample = true } = options;
+
+  const configPath = join(targetDir, 'lifeos.config.json');
+  if (!existsSync(configPath)) {
+    return {
+      applied: [],
+      skipped: [{ id: 'config', reason: 'lifeos.config.json not found — nothing to remediate' }],
+      summary: { applied: 0, skipped: 1 },
+    };
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return {
+      applied: [],
+      skipped: [{ id: 'config', reason: `JSON parse failed: ${err.message} — fix manually first` }],
+      summary: { applied: 0, skipped: 1 },
+    };
+  }
+
+  const applied = [];
+  const skipped = [];
+
+  // Fix 1: missing quadrant folders
+  for (const q of config.quadrants ?? []) {
+    if (!q.active) continue;
+    const fullPath = isAbsolute(q.path) ? q.path : join(targetDir, q.path);
+    if (existsSync(fullPath)) continue;
+    try {
+      mkdirSync(fullPath, { recursive: true });
+      const readme = join(fullPath, 'README.md');
+      if (!existsSync(readme)) {
+        writeFileSync(readme, quadrantReadme(q), 'utf8');
+      }
+      applied.push({
+        id: `quadrant_folder:${q.id}`,
+        action: `mkdir`,
+        message: `Created ${q.path}/ + placeholder README`,
+      });
+    } catch (err) {
+      skipped.push({ id: `quadrant_folder:${q.id}`, reason: `mkdir failed: ${err.message}` });
+    }
+  }
+
+  // Fix 2: missing council files
+  const councilDir = join(targetDir, '.claude', 'agents', 'council');
+  for (const member of config.council ?? []) {
+    if (!member.system_prompt_path) continue;
+    const filename = member.system_prompt_path.split('/').pop();
+    const installedPath = join(councilDir, filename);
+    if (existsSync(installedPath)) continue;
+    const templatePath = join(TEMPLATES_COUNCIL, filename);
+    if (!existsSync(templatePath)) {
+      skipped.push({
+        id: `council_file:${member.id}`,
+        reason: `bundled template missing for ${filename} — file may be custom; not auto-fixable`,
+      });
+      continue;
+    }
+    try {
+      mkdirSync(councilDir, { recursive: true });
+      copyFileSync(templatePath, installedPath);
+      applied.push({
+        id: `council_file:${member.id}`,
+        action: 'copy',
+        message: `Copied ${filename} from bundled templates`,
+      });
+    } catch (err) {
+      skipped.push({ id: `council_file:${member.id}`, reason: `copy failed: ${err.message}` });
+    }
+  }
+
+  // Fix 3: writing_style.md stub if path is set + file missing
+  if (allowWritingStyleStub && config.writing_style_path) {
+    const stylePath = isAbsolute(config.writing_style_path)
+      ? config.writing_style_path
+      : join(targetDir, config.writing_style_path);
+    if (!existsSync(stylePath)) {
+      try {
+        mkdirSync(dirname(stylePath), { recursive: true });
+        writeFileSync(stylePath, writingStyleStub(), 'utf8');
+        applied.push({
+          id: 'writing_style',
+          action: 'stub',
+          message: `Wrote stub at ${config.writing_style_path} — replace with a real sample of your writing`,
+        });
+      } catch (err) {
+        skipped.push({ id: 'writing_style', reason: `write failed: ${err.message}` });
+      }
+    }
+  }
+
+  // Fix 4: .env.example for required env vars
+  if (allowEnvExample) {
+    let registry = null;
+    try {
+      registry = loadRegistry();
+    } catch {
+      /* skip env example if registry unavailable */
+    }
+    if (registry) {
+      const envEntries = collectEnvEntries(config, registry);
+      if (envEntries.length > 0) {
+        const envExamplePath = join(targetDir, '.env.example');
+        const wasExisting = existsSync(envExamplePath);
+        try {
+          // Don't overwrite if user already customized — just notify
+          if (wasExisting) {
+            skipped.push({
+              id: 'env_example',
+              reason: `.env.example already exists — not overwriting (review and merge manually if needed)`,
+            });
+          } else {
+            writeFileSync(envExamplePath, envExampleContent(envEntries), 'utf8');
+            applied.push({
+              id: 'env_example',
+              action: 'generate',
+              message: `Wrote .env.example with ${envEntries.length} env var stub(s) + help URLs. Copy to .env.local, fill in values, then \`source .env.local\` before launching Claude.`,
+            });
+          }
+        } catch (err) {
+          skipped.push({ id: 'env_example', reason: `write failed: ${err.message}` });
+        }
+      }
+    }
+  }
+
+  return {
+    applied,
+    skipped,
+    summary: { applied: applied.length, skipped: skipped.length },
+  };
+}
+
+/**
+ * Collect env var entries needed by wired MCPs.
+ * Returns [{ env_var, mcp_id, mcp_name, help_url, scope_hint }].
+ */
+function collectEnvEntries(config, registry) {
+  const byId = new Map(registry.servers.map((s) => [s.id, s]));
+  const entries = [];
+  const seen = new Set();
+  for (const m of config.mcp_servers ?? []) {
+    const entry = byId.get(m.id);
+    if (!entry?.auth?.env_var) continue;
+    if (seen.has(entry.auth.env_var)) continue;
+    seen.add(entry.auth.env_var);
+    entries.push({
+      env_var: entry.auth.env_var,
+      mcp_id: entry.id,
+      mcp_name: entry.name,
+      help_url: entry.auth.help_url,
+      scope_hint: entry.auth.scope_hint,
+    });
+  }
+  return entries;
+}
+
+function envExampleContent(entries) {
+  const lines = [
+    '# LifeOS — wired MCP environment variables',
+    '#',
+    '# Generated by `lifeos doctor --fix`. To use:',
+    '#   1. Copy this file to .env.local in the same directory',
+    '#   2. Fill in each value from the help URLs below',
+    '#   3. Source it before launching Claude Code:',
+    '#        source .env.local',
+    '#      or add a permanent `set -a; source .env.local; set +a` to your shell rc.',
+    '#',
+    '# Trust note: .env.local should be gitignored (LifeOS scaffold .gitignore covers this).',
+    '# LifeOS itself never reads any value in this file — it\'s yours, in your shell.',
+    '',
+  ];
+
+  for (const e of entries) {
+    lines.push(`# ${e.mcp_name}`);
+    if (e.help_url) lines.push(`# Get one: ${e.help_url}`);
+    if (e.scope_hint) {
+      const wrapped = wrapText(`# Scope: ${e.scope_hint}`, 100);
+      lines.push(...wrapped);
+    }
+    lines.push(`export ${e.env_var}=`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function wrapText(text, maxWidth) {
+  const lines = [];
+  const prefix = text.startsWith('#') ? '# ' : '';
+  const content = text.startsWith('#') ? text.slice(2) : text;
+  const words = content.split(/\s+/);
+  let current = '';
+  for (const word of words) {
+    if (current.length + word.length + 1 > maxWidth - prefix.length) {
+      if (current) lines.push(prefix + current);
+      current = word;
+    } else {
+      current = current ? `${current} ${word}` : word;
+    }
+  }
+  if (current) lines.push(prefix + current);
+  return lines;
+}
+
+function quadrantReadme(q) {
+  return `# ${q.name}
+
+${q.description ?? ''}
+
+This folder is the home of your **${q.id}** quadrant. The LifeOS council members assigned to it will read files here as context when convened.
+
+## Council members assigned
+
+${(q.council_member_ids ?? []).map((id) => `- \`${id}\``).join('\n') || '_none_'}
+
+## MCP servers wired
+
+${(q.mcp_server_ids ?? []).map((id) => `- \`${id}\``).join('\n') || '_none_'}
+
+## Priority
+
+\`${q.priority}\` — change in \`lifeos.config.json\` to adjust how much airtime this quadrant gets in cross-quadrant convenings.
+`;
+}
+
+function writingStyleStub() {
+  return `# Writing style
+
+> This file anchors your voice for council members that produce written output (Writing Critic, Editor, etc.).
+> Replace this placeholder with a real sample of your writing — an email, an essay paragraph, a Slack message you're proud of.
+> The council reads this verbatim and tries to match the register. Be specific.
+
+## Style notes
+
+- _Tone:_ [e.g., formal-analytical, conversational, direct, hedged]
+- _Sentence length preference:_ [e.g., short and punchy / long and layered]
+- _Vocabulary preferences:_ [e.g., academic, plain-spoken, jargon-heavy]
+- _Avoid:_ [e.g., overly casual contractions, filler phrases, marketing-speak]
+
+## Sample (replace this entire section with your own)
+
+[Paste 200-500 words of your own writing here. Anything you wrote and stand behind.]
+`;
+}