agentboot 0.4.2 → 0.4.4

package/README.md

@@ -1,8 +1,8 @@
 # AgentBoot
 
-**Convention over configuration for agentic development teams.**
+**Bootstrap your agentic development teams.**
 
-AgentBoot is a build tool that compiles AI agent personas and distributes them across your organization's repositories. Define once, deploy everywhere. The Spring Boot of AI agent governance.
+AgentBoot is a build tool that compiles AI agent personas and distributes them across your organization's repositories. Define once, deploy everywhere. Convention over configuration for AI agent governance.
 
 ## The Problem
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentboot",
-  "version": "0.4.2",
-  "description": "Convention over configuration for agentic development teams. The Spring Boot of Claude Code governance.",
+  "version": "0.4.4",
+  "description": "Bootstrap your agentic development teams. Convention over configuration for AI agent governance.",
   "license": "Apache-2.0",
   "author": "Mike Saavedra <mike@agentboot.dev>",
   "homepage": "https://agentboot.dev",

package/scripts/cli.ts

@@ -12,7 +12,7 @@
  *   agentboot sync [--repos-file path] [--dry-run]
  *   agentboot install [--hub] [--connect] [--org name] [--path dir]
  *   agentboot add <type> <name>
- *   agentboot doctor [--format text|json]
+ *   agentboot doctor [--fix] [--dry-run] [--format text|json]
  *   agentboot status [--format text|json]
  *   agentboot lint [--persona name] [--severity level] [--format text|json]
  *   agentboot uninstall [--repo path] [--dry-run]
@@ -27,7 +27,7 @@ import path from "node:path";
 import fs from "node:fs";
 import chalk from "chalk";
 import { createHash } from "node:crypto";
-import { loadConfig, type MarketplaceManifest, type MarketplaceEntry } from "./lib/config.js";
+import { loadConfig, stripJsoncComments, type MarketplaceManifest, type MarketplaceEntry } from "./lib/config.js";
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -615,12 +615,12 @@ Add to \`agentboot.config.json\`:
 #   }
 
 INPUT=$(cat)
-EVENT_NAME=$(echo "$INPUT" | jq -r '.hook_event_name // empty')
+EVENT_NAME=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // empty')
 
 # TODO: Add your compliance logic here
 # Example: block a tool if a condition is met
 # if [ "$EVENT_NAME" = "PreToolUse" ]; then
-#   TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')
+#   TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty')
 #   if [ "$TOOL" = "Bash" ]; then
 #     echo '{"decision":"block","reason":"Bash tool is restricted by policy"}' >&2
 #     exit 2
@@ -682,19 +682,28 @@ program
   .command("doctor")
   .description("Check environment and diagnose configuration issues")
   .option("--format <fmt>", "output format: text, json", "text")
+  .option("--fix", "auto-fix issues that can be resolved automatically")
+  .option("--dry-run", "show what --fix would do without making changes")
   .action((opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const isJson = opts.format === "json";
+    const fixMode = opts.fix === true;
+    const dryRun = opts.dryRun === true;
+    if (dryRun && !fixMode && !isJson) {
+      console.log(chalk.yellow("Note: --dry-run has no effect without --fix\n"));
+    }
     if (!isJson) console.log(chalk.bold("\nAgentBoot — doctor\n"));
     const cwd = process.cwd();
-    let issues = 0;
+    let issuesFound = 0;
+    let issuesFixed = 0;
 
-    interface DoctorCheck { name: string; status: "ok" | "fail" | "warn"; message: string }
+    interface DoctorCheck { name: string; status: "ok" | "fail" | "warn"; message: string; fixable?: boolean; fixed?: boolean }
     const checks: DoctorCheck[] = [];
 
     function ok(msg: string) { checks.push({ name: msg, status: "ok", message: msg }); if (!isJson) console.log(`  ${chalk.green("✓")} ${msg}`); }
-    function fail(msg: string) { issues++; checks.push({ name: msg, status: "fail", message: msg }); if (!isJson) console.log(`  ${chalk.red("✗")} ${msg}`); }
-    function warn(msg: string) { checks.push({ name: msg, status: "warn", message: msg }); if (!isJson) console.log(`  ${chalk.yellow("⚠")} ${msg}`); }
+    function fail(msg: string, fixable = false) { issuesFound++; checks.push({ name: msg, status: "fail", message: msg, fixable }); if (!isJson) console.log(`  ${chalk.red("✗")} ${msg}${fixable && !fixMode ? chalk.gray(" (fixable with --fix)") : ""}`); }
+    function warn(msg: string, fixable = false) { checks.push({ name: msg, status: "warn", message: msg, fixable }); if (!isJson) console.log(`  ${chalk.yellow("⚠")} ${msg}${fixable && !fixMode ? chalk.gray(" (fixable with --fix)") : ""}`); }
+    function fixed(msg: string) { issuesFound++; issuesFixed++; checks.push({ name: msg, status: "ok", message: msg, fixed: true }); if (!isJson) console.log(`  ${chalk.green("✓")} ${msg} ${chalk.cyan(dryRun ? "(would fix)" : "(fixed)")}`); }
 
     // 1. Environment
     if (!isJson) console.log(chalk.cyan("Environment"));
@@ -725,36 +734,146 @@ program
         const config = loadConfig(configPath);
         ok(`Config parses successfully (org: ${config.org})`);
 
+        // Check for orgDisplayName
+        if (!config.orgDisplayName || config.orgDisplayName === config.org) {
+          warn(`orgDisplayName not set — compiled output will use "${config.org}" as the display name`);
+          if (!isJson) console.log(chalk.gray(`      Set it with: agentboot config orgDisplayName "Your Org Name"`));
+        }
+
+        // Helper: generate a minimal SKILL.md scaffold
+        function scaffoldSkillMd(name: string): string {
+          return [
+            "---",
+            `id: ${name}`,
+            `name: ${name}`,
+            "version: 0.1.0",
+            "---",
+            "",
+            `# ${name}`,
+            "",
+            "<!-- traits:start -->",
+            "<!-- traits:end -->",
+            "",
+            "TODO: Define this persona.",
+            "",
+          ].join("\n");
+        }
+
         // Check personas
         const enabledPersonas = config.personas?.enabled ?? [];
         const personasDir = path.join(cwd, "core", "personas");
         let personaIssues = 0;
+        let personasScaffolded = 0;
         for (const p of enabledPersonas) {
           const pDir = path.join(personasDir, p);
-          if (!fs.existsSync(pDir)) { personaIssues++; fail(`Persona not found: ${p}`); }
-          else if (!fs.existsSync(path.join(pDir, "SKILL.md"))) { personaIssues++; fail(`Missing SKILL.md: ${p}`); }
+          if (!fs.existsSync(pDir)) {
+            if (fixMode) {
+              if (!dryRun) {
+                fs.mkdirSync(pDir, { recursive: true });
+                fs.writeFileSync(path.join(pDir, "SKILL.md"), scaffoldSkillMd(p), "utf-8");
+                const personaConfig = { traits: config.traits?.enabled ?? [] };
+                fs.writeFileSync(path.join(pDir, "persona.config.json"), JSON.stringify(personaConfig, null, 2) + "\n", "utf-8");
+              }
+              personasScaffolded++;
+              fixed(`Scaffolded persona: ${p}`);
+            } else {
+              personaIssues++; fail(`Persona not found: ${p}`, true);
+            }
+          } else if (!fs.existsSync(path.join(pDir, "SKILL.md"))) {
+            if (fixMode) {
+              if (!dryRun) {
+                fs.writeFileSync(path.join(pDir, "SKILL.md"), scaffoldSkillMd(p), "utf-8");
+              }
+              personasScaffolded++;
+              fixed(`Created missing SKILL.md for: ${p}`);
+            } else {
+              personaIssues++; fail(`Missing SKILL.md: ${p}`, true);
+            }
+          }
+        }
+        if (personaIssues === 0 && personasScaffolded === 0) {
+          ok(`All ${enabledPersonas.length} enabled personas found`);
+        } else if (personaIssues === 0 && personasScaffolded > 0) {
+          ok(`All ${enabledPersonas.length} enabled personas found (${personasScaffolded} scaffolded)`);
         }
-        if (personaIssues === 0) ok(`All ${enabledPersonas.length} enabled personas found`);
 
         // Check traits
         const enabledTraits = config.traits?.enabled ?? [];
         const traitsDir = path.join(cwd, "core", "traits");
         let traitIssues = 0;
+        let traitsScaffolded = 0;
         for (const t of enabledTraits) {
-          if (!fs.existsSync(path.join(traitsDir, `${t}.md`))) { traitIssues++; fail(`Trait not found: ${t}`); }
+          if (!fs.existsSync(path.join(traitsDir, `${t}.md`))) {
+            if (fixMode) {
+              if (!dryRun) {
+                fs.mkdirSync(traitsDir, { recursive: true });
+                const traitContent = `# ${t}\n\nTODO: Define this trait.\n`;
+                fs.writeFileSync(path.join(traitsDir, `${t}.md`), traitContent, "utf-8");
+              }
+              traitsScaffolded++;
+              fixed(`Created missing trait: ${t}.md`);
+            } else {
+              traitIssues++; fail(`Trait not found: ${t}`, true);
+            }
+          }
+        }
+        if (traitIssues === 0 && traitsScaffolded === 0) {
+          ok(`All ${enabledTraits.length} enabled traits found`);
+        } else if (traitIssues === 0 && traitsScaffolded > 0) {
+          ok(`All ${enabledTraits.length} enabled traits found (${traitsScaffolded} scaffolded)`);
+        }
+
+        // Check core directories
+        const coreDirs = ["core/personas", "core/traits", "core/instructions", "core/gotchas"];
+        for (const dir of coreDirs) {
+          const fullDir = path.join(cwd, dir);
+          if (!fs.existsSync(fullDir)) {
+            if (fixMode) {
+              if (!dryRun) fs.mkdirSync(fullDir, { recursive: true });
+              fixed(`Created missing directory: ${dir}/`);
+            } else {
+              warn(`Missing directory: ${dir}/`, true);
+            }
+          }
         }
-        if (traitIssues === 0) ok(`All ${enabledTraits.length} enabled traits found`);
 
         // Check repos.json
         const reposPath = config.sync?.repos ?? "./repos.json";
         const fullReposPath = path.resolve(path.dirname(configPath), reposPath);
-        if (fs.existsSync(fullReposPath)) ok(`repos.json found`);
-        else warn(`repos.json not found at ${reposPath}`);
+        if (fs.existsSync(fullReposPath)) {
+          ok(`repos.json found`);
+        } else if (fixMode) {
+          if (!dryRun) fs.writeFileSync(fullReposPath, "[]\n", "utf-8");
+          fixed(`Created empty repos.json`);
+        } else {
+          warn(`repos.json not found at ${reposPath}`, true);
+        }
 
         // Check dist/
         const distPath = path.resolve(cwd, config.output?.distPath ?? "./dist");
-        if (fs.existsSync(distPath)) ok(`dist/ exists (built)`);
-        else warn(`dist/ not found — run \`agentboot build\``);
+        if (fs.existsSync(distPath)) {
+          ok(`dist/ exists (built)`);
+        } else if (fixMode) {
+          if (!isJson) console.log(`  ${chalk.cyan("→")} Building dist/...`);
+          if (!dryRun) {
+            const compileScript = path.join(SCRIPTS_DIR, "compile.ts");
+            const tsx = path.join(ROOT, "node_modules", ".bin", "tsx");
+            const buildResult = spawnSync(tsx, [compileScript], {
+              cwd,
+              encoding: "utf-8",
+              stdio: ["pipe", "pipe", "pipe"],
+            });
+            if (buildResult.status === 0) {
+              fixed(`Built dist/`);
+            } else {
+              fail(`Build failed: ${buildResult.stderr?.trim() ?? "unknown error"}`);
+            }
+          } else {
+            fixed(`Would run \`agentboot build\``);
+          }
+        } else {
+          warn(`dist/ not found — run \`agentboot build\``, true);
+        }
 
       } catch (e: unknown) {
         fail(`Config parse error: ${e instanceof Error ? e.message : String(e)}`);
@@ -766,16 +885,28 @@ program
 
     if (!isJson) console.log("");
 
+    const issuesRemaining = issuesFound - issuesFixed;
+
     if (isJson) {
-      console.log(JSON.stringify({ issues, checks }, null, 2));
-      process.exit(issues > 0 ? 1 : 0);
+      console.log(JSON.stringify({ issues: issuesRemaining, issuesFound, issuesFixed, checks }, null, 2));
+      process.exit(issuesRemaining > 0 ? 1 : 0);
     }
 
-    if (issues > 0) {
-      console.log(chalk.bold(chalk.red(`✗ ${issues} issue${issues !== 1 ? "s" : ""} found\n`)));
+    if (issuesRemaining > 0) {
+      const fixableCount = checks.filter(c => c.fixable && !c.fixed).length;
+      console.log(chalk.bold(chalk.red(`✗ ${issuesRemaining} issue${issuesRemaining !== 1 ? "s" : ""} found`)));
+      if (fixableCount > 0) {
+        console.log(chalk.gray(`  ${fixableCount} fixable — run \`agentboot doctor --fix\`\n`));
+      } else {
+        console.log("");
+      }
       process.exit(1);
     } else {
-      console.log(chalk.bold(chalk.green("✓ All checks passed\n")));
+      if (issuesFixed > 0) {
+        console.log(chalk.bold(chalk.green(`✓ All checks passed (${issuesFixed} issue${issuesFixed !== 1 ? "s" : ""} ${dryRun ? "would be " : ""}fixed)\n`)));
+      } else {
+        console.log(chalk.bold(chalk.green("✓ All checks passed\n")));
+      }
     }
   });
 
@@ -1264,9 +1395,9 @@ program
 
 program
   .command("config")
-  .description("View configuration (read-only)")
-  .argument("[key]", "config key (e.g., personas.enabled)")
-  .argument("[value]", "not yet supported")
+  .description("Read or write configuration values")
+  .argument("[key]", "config key (e.g., org, orgDisplayName, personas.enabled)")
+  .argument("[value]", "value to set (strings only — edit agentboot.config.json for complex values)")
   .action((key: string | undefined, value: string | undefined, _opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const cwd = process.cwd();
@@ -1303,10 +1434,61 @@ program
       process.exit(0);
     }
 
-    console.error(chalk.red(`Config writes are not yet supported. Edit agentboot.config.json directly.`));
-    console.error(chalk.gray(`  agentboot config ${key}   ← read a value`));
-    console.error(chalk.gray(`  agentboot config         ← show full config`));
-    process.exit(1);
+    // Write a config value
+    const raw = fs.readFileSync(configPath, "utf-8");
+
+    // Detect JSONC comments — writing back would destroy them
+    const stripped = stripJsoncComments(raw);
+    if (stripped !== raw) {
+      console.error(chalk.red("Config file contains comments (JSONC)."));
+      console.error(chalk.gray("  Writing would remove all comments. Edit the file directly:\n"));
+      console.error(chalk.gray(`    ${configPath}\n`));
+      process.exit(1);
+    }
+
+    let config: Record<string, unknown>;
+    try {
+      config = JSON.parse(stripped);
+    } catch {
+      console.error(chalk.red("Failed to parse config for writing."));
+      process.exit(1);
+    }
+
+    const keys = key.split(".");
+    let target: Record<string, unknown> = config;
+    for (let i = 0; i < keys.length - 1; i++) {
+      const k = keys[i]!;
+      if (target[k] === undefined) {
+        // Auto-create intermediate objects
+        target[k] = {};
+        target = target[k] as Record<string, unknown>;
+      } else if (typeof target[k] === "object" && !Array.isArray(target[k]) && target[k] !== null) {
+        target = target[k] as Record<string, unknown>;
+      } else {
+        console.error(chalk.red(`Cannot write to ${key}: "${k}" exists but is ${typeof target[k]}, not an object.`));
+        console.error(chalk.gray("  Edit agentboot.config.json directly.\n"));
+        process.exit(1);
+      }
+    }
+
+    const finalKey = keys[keys.length - 1]!;
+    const oldValue = target[finalKey];
+
+    // Guard against overwriting non-string values (arrays, objects, numbers, booleans)
+    if (oldValue !== undefined && typeof oldValue !== "string") {
+      console.error(chalk.red(`Cannot overwrite ${key}: existing value is ${typeof oldValue}, not a string.`));
+      console.error(chalk.gray("  Edit agentboot.config.json directly for non-string values.\n"));
+      process.exit(1);
+    }
+
+    target[finalKey] = value;
+
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    if (oldValue !== undefined) {
+      console.log(chalk.green(`  ${key}: ${JSON.stringify(oldValue)} → ${JSON.stringify(value)}`));
+    } else {
+      console.log(chalk.green(`  ${key}: ${JSON.stringify(value)} (added)`));
+    }
   });
 
 // ---- export (AB-40) -------------------------------------------------------

package/scripts/compile.ts

@@ -1043,10 +1043,15 @@ exit 0
   const includeDevId = config.telemetry?.includeDevId ?? false;
 
   let devIdBlock = "";
-  if (includeDevId === "hashed") {
+  if (includeDevId === "hashed" || includeDevId === "email") {
+    if (includeDevId === "email") {
+      log(chalk.yellow(`  ⚠ telemetry.includeDevId "email" now defaults to hashed for privacy.`));
+      log(chalk.yellow(`    Use "email-raw" to explicitly include raw emails (not recommended).`));
+    }
     devIdBlock = `DEV_ID=$(git config user.email 2>/dev/null | shasum -a 256 | cut -d' ' -f1)`;
-  } else if (includeDevId === "email") {
-    log(chalk.yellow(`  ⚠ telemetry.includeDevId is "email" — raw emails will be in telemetry logs. Consider "hashed" for privacy.`));
+  } else if (includeDevId === "email-raw") {
+    log(chalk.yellow(`  ⚠ telemetry.includeDevId is "email-raw" — raw emails will be in telemetry logs.`));
+    log(chalk.yellow(`    Consider "hashed" for privacy compliance (GDPR, data minimization).`));
     devIdBlock = `DEV_ID=$(git config user.email 2>/dev/null || echo "unknown")`;
   } else {
     devIdBlock = `DEV_ID=""`;

package/scripts/lib/config.ts

@@ -171,7 +171,7 @@ export interface TelemetryConfig {
   enabled?: boolean;
   /** How to identify developers in telemetry.
    *  false = no developer ID, "hashed" = SHA-256 of email, "email" = raw email. */
-  includeDevId?: false | "hashed" | "email";
+  includeDevId?: false | "hashed" | "email" | "email-raw";
   /** Path to NDJSON log file. Default: ~/.agentboot/telemetry.ndjson */
   logPath?: string;
   /** Never include raw prompt content in telemetry. Design invariant. */
@@ -396,10 +396,15 @@ export function loadConfig(configPath: string): AgentBootConfig {
     ["sync.repos", parsed.sync?.repos],
     ["output.distPath", parsed.output?.distPath],
     ["personas.customDir", parsed.personas?.customDir],
+    ["telemetry.logPath", parsed.telemetry?.logPath],
   ];
   for (const [fieldName, value] of pathFields) {
-    if (typeof value === "string" && value.includes("..")) {
-      throw new Error(`"${fieldName}" must not contain ".." path segments`);
+    if (typeof value === "string") {
+      // Check for .. path traversal (normalized for both separators)
+      const normalized = value.replace(/\\/g, "/");
+      if (normalized.split("/").includes("..")) {
+        throw new Error(`"${fieldName}" must not contain ".." path segments`);
+      }
     }
   }
 

package/scripts/lib/import.ts

@@ -917,7 +917,7 @@ function analyzeOverlap(
   return matches;
 }
 
-export { analyzeOverlap, normalizeContent, jaccardSimilarity };
+export { analyzeOverlap, normalizeContent, jaccardSimilarity, scanPath, applyPlan, buildClassificationPrompt, ALLOWED_CLASSIFICATION_DIRS };
 
 // ---------------------------------------------------------------------------
 // Hub finder

package/scripts/lib/install.ts

@@ -142,13 +142,21 @@ function detectGhAuthenticated(): boolean {
 }
 
 /**
- * Shallow scan sibling directories for agentboot.config.json or .claude/.
- * Returns list of found paths with their type.
+ * Scan nearby directories for agentboot.config.json or .claude/.
+ * Checks: the parent directory itself, then sibling directories.
+ * This supports both sibling layouts (hub next to spokes) and parent layouts
+ * (hub is the parent directory containing spoke repos).
  */
-function scanSiblings(cwd: string): Array<{ path: string; type: "hub" | "claude" }> {
+export function scanNearby(cwd: string): Array<{ path: string; type: "hub" | "claude" }> {
   const parent = path.dirname(cwd);
   const results: Array<{ path: string; type: "hub" | "claude" }> = [];
 
+  // Check parent directory itself (supports hub-as-parent layout)
+  if (fs.existsSync(path.join(parent, "agentboot.config.json"))) {
+    results.push({ path: parent, type: "hub" });
+  }
+
+  // Check sibling directories
   try {
     for (const entry of fs.readdirSync(parent)) {
       const siblingPath = path.join(parent, entry);
@@ -206,11 +214,11 @@ function searchGitHubOrg(org: string): string | null {
 // Scaffold helpers
 // ---------------------------------------------------------------------------
 
-export function scaffoldHub(targetDir: string, orgName: string): void {
+export function scaffoldHub(targetDir: string, orgSlug: string, orgDisplayName?: string): void {
   // agentboot.config.json
   const configContent = JSON.stringify({
-    org: orgName,
-    orgDisplayName: orgName,
+    org: orgSlug,
+    orgDisplayName: orgDisplayName ?? orgSlug,
     groups: {},
     personas: {
       enabled: ["code-reviewer", "security-reviewer", "test-generator", "test-data-expert"],
@@ -246,6 +254,11 @@ export function scaffoldHub(targetDir: string, orgName: string): void {
 
 function runBuild(hubDir: string): boolean {
   console.log(chalk.cyan("\n  Compiling personas..."));
+  console.log(chalk.gray(
+    "  This reads your traits and personas from core/, composes them, and\n" +
+    "  writes compiled output to dist/. The dist/ folder is what gets\n" +
+    "  deployed to your repos.\n"
+  ));
   const result = spawnSync("agentboot", ["build"], {
     cwd: hubDir,
     encoding: "utf-8",
@@ -253,10 +266,10 @@ function runBuild(hubDir: string): boolean {
   });
 
   if (result.status === 0) {
-    console.log(chalk.green("  Compiled successfully."));
+    console.log(chalk.green("  Build complete."));
     return true;
   } else {
-    console.log(chalk.yellow("  Build skipped — run `agentboot build` from the personas repo."));
+    console.log(chalk.yellow("  Build did not complete — you can run `agentboot build` later."));
     return false;
   }
 }
@@ -270,6 +283,150 @@ function runSync(hubDir: string): boolean {
   return result.status === 0;
 }
 
+// ---------------------------------------------------------------------------
+// Hub target validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate and potentially adjust the hub target directory.
+ *
+ * If the target directory exists and looks like it already has content (a git
+ * repo, source files, etc.), we don't want to scaffold hub files into it —
+ * that would pollute an existing project. Instead, offer to create a `personas`
+ * subdirectory.
+ */
+async function validateHubTarget(initialDir: string): Promise<string> {
+  let hubDir = initialDir;
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    // If the directory doesn't exist, it will be created fresh — no issue.
+    if (!fs.existsSync(hubDir)) {
+      fs.mkdirSync(hubDir, { recursive: true });
+      return hubDir;
+    }
+
+    // If it already has agentboot.config.json, it's already a hub — bail.
+    if (fs.existsSync(path.join(hubDir, "agentboot.config.json"))) {
+      console.log(chalk.yellow("\n  This directory already has agentboot.config.json."));
+      console.log(chalk.gray("  Run `agentboot doctor` to check your configuration.\n"));
+      throw new AgentBootError(0);
+    }
+
+    // Check if the directory has existing content that suggests it's not an
+    // empty directory intended for a new personas repo.
+    const entries = fs.readdirSync(hubDir).filter(e => !e.startsWith(".") || e === ".git");
+    const hasGit = fs.existsSync(path.join(hubDir, ".git"));
+    const hasPackageJson = fs.existsSync(path.join(hubDir, "package.json"));
+    const hasSrc = fs.existsSync(path.join(hubDir, "src"));
+
+    const hasExistingContent = entries.length > 0 && (hasGit || hasPackageJson || hasSrc);
+
+    if (!hasExistingContent) {
+      // Empty or near-empty directory — fine to use directly.
+      return hubDir;
+    }
+
+    // The directory has content. Warn and offer alternatives.
+    const dirName = path.basename(hubDir);
+    const personasPath = path.join(hubDir, "personas");
+
+    console.log(chalk.yellow(
+      `\n  "${dirName}" already has content (${entries.length} items).` +
+      `\n  Scaffolding here would mix persona source code with existing files.\n`
+    ));
+
+    const choice = await select({
+      message: "Where should the personas repo live?",
+      choices: [
+        { name: `Create ${personasPath} (recommended)`, value: "sub" },
+        { name: "Choose a different location", value: "custom" },
+        { name: `Use ${hubDir} anyway (not recommended)`, value: "here" },
+      ],
+    });
+
+    if (choice === "sub") {
+      if (!fs.existsSync(personasPath)) {
+        fs.mkdirSync(personasPath, { recursive: true });
+      }
+      return personasPath;
+    } else if (choice === "custom") {
+      const customPath = await input({
+        message: "Path for the personas repo:",
+        default: personasPath,
+      });
+      hubDir = path.resolve(customPath);
+      continue; // re-validate the new target
+    }
+
+    // "here" — user insists, proceed with original path
+    return hubDir;
+  }
+}
+
+/**
+ * Nudge toward the convention of naming the hub repo "personas".
+ *
+ * This is an educational moment, not a gate. The user can proceed with any
+ * name — but we explain why "personas" is the convention and what they gain
+ * by following it.
+ */
+async function nudgePersonasConvention(hubDir: string): Promise<string> {
+  const dirName = path.basename(hubDir);
+
+  // Already named "personas" — nothing to do.
+  if (dirName === "personas") return hubDir;
+
+  console.log(chalk.cyan(
+    `\n  Convention: name this repo "personas"\n\n`
+  ) + chalk.gray(
+    `  AgentBoot follows a convention-over-configuration philosophy. When every\n` +
+    `  org names their hub repo "personas", several things work automatically:\n\n` +
+    `    - \`agentboot install\` auto-discovers it by scanning for "personas" in\n` +
+    `      your GitHub org and sibling directories\n` +
+    `    - New team members know where to look without being told\n` +
+    `    - Docs, examples, and community answers all reference the same path\n` +
+    `    - \`gh repo clone <org>/personas\` works across every AgentBoot org\n\n` +
+    `  You chose "${dirName}" — that works fine. This is a recommendation,\n` +
+    `  not a requirement.\n`
+  ));
+
+  const choice = await select({
+    message: `Keep "${dirName}" or rename to "personas"?`,
+    choices: [
+      { name: `Rename to ${path.join(path.dirname(hubDir), "personas")} (recommended)`, value: "rename" },
+      { name: `Keep "${dirName}"`, value: "keep" },
+    ],
+  });
+
+  if (choice === "rename") {
+    const personasDir = path.join(path.dirname(hubDir), "personas");
+    if (fs.existsSync(personasDir)) {
+      console.log(chalk.yellow(`  ${personasDir} already exists. Keeping "${dirName}".`));
+      return hubDir;
+    }
+    // If the original dir was just created (empty), rename it.
+    // If it had content, we can't rename safely — keep it.
+    try {
+      const entries = fs.readdirSync(hubDir);
+      if (entries.length === 0) {
+        fs.rmdirSync(hubDir);
+        fs.mkdirSync(personasDir, { recursive: true });
+        return personasDir;
+      } else {
+        // Directory has content (from scaffold or prior step) — rename via fs.rename
+        fs.renameSync(hubDir, personasDir);
+        return personasDir;
+      }
+    } catch {
+      console.log(chalk.yellow(`  Could not rename. Keeping "${dirName}".`));
+      return hubDir;
+    }
+  }
+
+  return hubDir;
+}
+
 // ---------------------------------------------------------------------------
 // Path 1: Create a new personas repo (Architect)
 // ---------------------------------------------------------------------------
@@ -326,15 +483,18 @@ async function path1CreateHub(cwd: string, opts: InstallOptions, detection: Dete
     }
   }
 
-  // Create directory if needed
-  if (!fs.existsSync(hubDir)) {
-    fs.mkdirSync(hubDir, { recursive: true });
-  }
+  // Validate target directory — if it exists and has content, offer to create
+  // a personas subdirectory instead of scaffolding into an existing repo.
+  hubDir = await validateHubTarget(hubDir);
+
+  // Nudge toward the "personas" naming convention if the user chose a
+  // different name. This is educational, not enforced.
+  hubDir = await nudgePersonasConvention(hubDir);
 
-  // Step 1.2: Org detection
-  let orgName = opts.org ?? detection.gitOrg ?? null;
+  // Step 1.2: Org detection — slug (machine identifier) and display name (human label)
+  let orgSlug = opts.org ?? detection.gitOrg ?? null;
 
-  if (!orgName) {
+  if (!orgSlug) {
     // Try detecting from the hub dir's git remote
     try {
       const gitResult = spawnSync("git", ["remote", "get-url", "origin"], {
@@ -344,25 +504,39 @@ async function path1CreateHub(cwd: string, opts: InstallOptions, detection: Dete
       });
       if (gitResult.stdout) {
         const match = gitResult.stdout.trim().match(/[/:]([\w.-]+)\//);
-        if (match) orgName = match[1]!;
+        if (match) orgSlug = match[1]!;
       }
     } catch { /* no git */ }
   }
 
-  if (orgName) {
+  if (orgSlug) {
     const useDetected = await confirm({
-      message: `Use "${orgName}" as your org name?`,
+      message: `Use "${orgSlug}" as your org identifier?`,
       default: true,
     });
     if (!useDetected) {
-      orgName = await input({ message: "Org name:" });
+      orgSlug = await input({ message: "Org identifier (lowercase, used in package names and paths):" });
     }
   } else {
-    orgName = await input({
-      message: "Org name (GitHub org or username):",
+    orgSlug = await input({
+      message: "Org identifier (GitHub org, username, or slug — lowercase, no spaces):",
     });
   }
 
+  // Normalize slug: lowercase, replace spaces with hyphens
+  orgSlug = orgSlug.toLowerCase().replace(/\s+/g, "-");
+
+  // Derive a default display name from the slug
+  const defaultDisplayName = orgSlug
+    .split(/[-_]/)
+    .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+
+  const orgDisplayName = await input({
+    message: "Org display name (shown in compiled output):",
+    default: defaultDisplayName,
+  });
+
   // Step 1.3: Scan for existing content nearby (with permission)
   const shouldScan = await confirm({
     message: "Scan nearby directories for existing AI agent content?",
@@ -370,7 +544,7 @@ async function path1CreateHub(cwd: string, opts: InstallOptions, detection: Dete
   });
 
   if (shouldScan) {
-    const siblings = scanSiblings(hubDir !== cwd ? cwd : hubDir);
+    const siblings = scanNearby(hubDir !== cwd ? cwd : hubDir);
     const claudeSiblings = siblings.filter(s => s.type === "claude");
 
     if (claudeSiblings.length > 0) {
@@ -390,9 +564,9 @@ async function path1CreateHub(cwd: string, opts: InstallOptions, detection: Dete
   }
 
   // Step 1.4: Scaffold
-  console.log(chalk.bold(`\n  Creating personas repo for ${orgName}...\n`));
+  console.log(chalk.bold(`\n  Creating personas repo for ${orgDisplayName}...\n`));
 
-  scaffoldHub(hubDir, orgName);
+  scaffoldHub(hubDir, orgSlug, orgDisplayName);
 
   console.log(chalk.green("  Source code:"));
   console.log(chalk.gray("    core/personas/          4 personas (code-reviewer, security-reviewer, ...)"));
@@ -400,29 +574,72 @@ async function path1CreateHub(cwd: string, opts: InstallOptions, detection: Dete
   console.log(chalk.gray("    core/instructions/      2 always-on instruction sets"));
   console.log(chalk.gray("    core/gotchas/           (empty — add domain knowledge here)"));
   console.log(chalk.green("\n  Build configuration:"));
-  console.log(chalk.gray(`    agentboot.config.json   org: "${orgName}"`));
+  console.log(chalk.gray(`    agentboot.config.json   org: "${orgSlug}", displayName: "${orgDisplayName}"`));
   console.log(chalk.gray("    repos.json              (empty — register your repos here)"));
 
-  // Step 1.5: Auto-build
-  const hasNodeModules = fs.existsSync(path.join(hubDir, "node_modules"));
-  if (hasNodeModules) {
-    runBuild(hubDir);
+  // Step 1.5: Build
+  //
+  // AgentBoot is a build tool. The personas repo contains source code (traits,
+  // personas, instructions) that gets compiled into deployable output. This is
+  // like compiling TypeScript to JavaScript — the source is what you edit, the
+  // output is what gets deployed.
+  //
+  // If the user is running `agentboot install`, then agentboot is already
+  // available (globally or via npx). We can always attempt a build.
+
+  let buildSucceeded = false;
+  const shouldBuild = await confirm({
+    message: "Compile personas now? (builds the deployable output)",
+    default: true,
+  });
+
+  if (shouldBuild) {
+    buildSucceeded = runBuild(hubDir);
   } else {
-    console.log(chalk.gray("\n  Run `npm install && agentboot build` to compile personas."));
+    console.log(chalk.gray(
+      "\n  You can compile later by running:\n\n" +
+      `    cd ${hubDir}\n` +
+      "    agentboot build\n"
+    ));
   }
 
   // Step 1.6: Register first repo (optional)
+  //
+  // A "target repo" is any codebase where you want AI agent governance.
+  // Registering it adds it to repos.json — the list of repos that receive
+  // compiled personas when you run `agentboot sync`.
+  //
+  // The personas repo and target repos can be anywhere on your filesystem.
+  // They don't need to be siblings or in the same parent directory.
+
+  let registeredRepo = false;
+  let registeredRepoName = "";
+  let registeredRepoPath = "";
+
+  console.log(chalk.bold("\n  Register a target repo\n"));
+  console.log(chalk.gray(
+    "  A target repo is any codebase where you want AgentBoot personas deployed.\n" +
+    "  It can be anywhere on your filesystem — it does not need to be next to\n" +
+    "  this personas repo.\n"
+  ));
+
   const registerRepo = await confirm({
     message: "Register your first target repo now?",
     default: true,
   });
 
   if (registerRepo) {
-    const repoPathInput = await input(
-      detection.looksLikeCodeRepo
-        ? { message: "Path to a local repo:", default: cwd }
-        : { message: "Path to a local repo:" }
-    );
+    let promptOpts: { message: string; default?: string };
+    if (detection.looksLikeCodeRepo) {
+      promptOpts = {
+        message: `Path to target repo (absolute or relative):`,
+        default: cwd,
+      };
+    } else {
+      promptOpts = { message: "Path to target repo (absolute or relative):" };
+    }
+
+    const repoPathInput = await input(promptOpts);
     const repoPath = path.resolve(repoPathInput);
 
     if (!fs.existsSync(repoPath)) {
@@ -452,57 +669,127 @@ async function path1CreateHub(cwd: string, opts: InstallOptions, detection: Dete
       repos.push({ path: repoPath, label: repoName });
       fs.writeFileSync(reposJsonPath, JSON.stringify(repos, null, 2) + "\n", "utf-8");
       console.log(chalk.green(`\n  Added ${repoName} to repos.json.`));
+      registeredRepo = true;
+      registeredRepoName = repoName;
+      registeredRepoPath = repoPath;
 
       // Check for existing .claude/ content
       if (fs.existsSync(path.join(repoPath, ".claude"))) {
         console.log(chalk.gray(
-          `  This repo has existing .claude/ content. On first sync, it will be\n` +
-          `  archived to .claude/.agentboot-archive/. You can restore it with\n` +
-          `  agentboot uninstall.`
+          `\n  This repo has existing .claude/ content. On first sync, AgentBoot\n` +
+          `  will archive it to .claude/.agentboot-archive/ before deploying.\n` +
+          `  You can restore the original content anytime with: agentboot uninstall`
         ));
       }
 
-      // Offer to sync
-      if (!opts.noSync && hasNodeModules && fs.existsSync(path.join(hubDir, "dist"))) {
+      // Offer to sync — only if build succeeded (dist/ exists)
+      if (!opts.noSync && buildSucceeded && fs.existsSync(path.join(hubDir, "dist"))) {
+        console.log(chalk.gray(
+          `\n  Sync deploys the compiled personas to ${repoName}'s .claude/ directory.\n` +
+          `  This writes files locally — it does not commit or push. You review\n` +
+          `  the output before committing.`
+        ));
+
         const shouldSync = await confirm({
-          message: "Deploy personas to this repo now?",
+          message: `Deploy personas to ${repoName} now?`,
           default: true,
         });
 
         if (shouldSync) {
           console.log(chalk.cyan("\n  Syncing..."));
           if (runSync(hubDir)) {
-            console.log(chalk.green("\n  Personas deployed. Try: /review-code"));
+            console.log(chalk.green(`\n  Personas deployed to ${repoPath}/.claude/`));
+            console.log(chalk.gray(
+              `\n  To activate them, commit the .claude/ directory:\n\n` +
+              `    cd ${repoPath}\n` +
+              `    git add .claude/\n` +
+              `    git commit -m "chore: deploy AgentBoot personas"\n\n` +
+              `  Then open Claude Code in that repo and try: /review-code`
+            ));
           }
         }
+      } else if (!buildSucceeded) {
+        console.log(chalk.gray(
+          `\n  Repo registered. To deploy personas, build first:\n\n` +
+          `    cd ${hubDir}\n` +
+          `    agentboot build && agentboot sync`
+        ));
       }
     }
   }
 
-  // Step 1.7: Governance recommendations
-  console.log(chalk.bold("\n  Recommendations for your personas repo:\n"));
-  console.log(chalk.gray(
-    "    Branch protection:\n" +
-    "      Enable branch protection on 'main' with required PR reviews.\n" +
-    "      Persona changes should go through code review.\n"
-  ));
-  console.log(chalk.gray(
-    "    Contributing path:\n" +
-    "      Developers who use personas daily are your best contributors.\n" +
-    "      A low-friction PR workflow lets them improve the prompts they know best.\n"
-  ));
-  console.log(chalk.gray(
-    "    CI validation:\n" +
-    "      Add `agentboot validate --strict` to your CI pipeline.\n"
-  ));
+  // Step 1.7: Summary and next steps
+  //
+  // Context-aware: the summary reflects what actually happened during install,
+  // so the user knows exactly where they are and what to do next.
+
+  console.log(chalk.bold("\n  ─────────────────────────────────────────────"));
+  console.log(chalk.bold(`\n  ${chalk.green("✓")} AgentBoot setup complete\n`));
+
+  // What was created
+  console.log(chalk.cyan("  What was created:\n"));
+  console.log(chalk.gray(`    Personas repo:    ${hubDir}`));
+  console.log(chalk.gray(`    Config:           ${hubDir}/agentboot.config.json`));
+  console.log(chalk.gray(`    Org:              ${orgSlug} (${orgDisplayName})`));
+  if (buildSucceeded) {
+    console.log(chalk.gray(`    Compiled output:  ${hubDir}/dist/`));
+  }
+  if (registeredRepo) {
+    console.log(chalk.gray(`    Target repo:      ${registeredRepoPath} (${registeredRepoName})`));
+  }
+
+  // Remote status
+  let hubHasRemote = false;
+  try {
+    const remoteResult = spawnSync("git", ["remote", "get-url", "origin"], {
+      cwd: hubDir,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    hubHasRemote = remoteResult.status === 0 && !!remoteResult.stdout?.trim();
+  } catch { /* no git or no remote */ }
+
+  if (!hubHasRemote) {
+    console.log(chalk.gray("    Remote:           none (local only — fine for evaluation)"));
+  }
+
+  // Context-aware next steps
+  console.log(chalk.cyan("\n  What to do next:\n"));
+
+  let step = 1;
+
+  if (!buildSucceeded) {
+    console.log(chalk.gray(`    ${step}. Build personas:    cd ${hubDir} && agentboot build`));
+    step++;
+  }
+
+  if (!registeredRepo) {
+    console.log(chalk.gray(`    ${step}. Register a repo:   agentboot install (from your code repo)`));
+    console.log(chalk.gray(`       Or edit:            ${hubDir}/repos.json`));
+    step++;
+  } else if (buildSucceeded && !fs.existsSync(path.join(registeredRepoPath, ".claude", ".agentboot-manifest.json"))) {
+    console.log(chalk.gray(`    ${step}. Deploy personas:   cd ${hubDir} && agentboot sync`));
+    step++;
+  }
+
+  console.log(chalk.gray(`    ${step}. Try it out:        Open your repo in Claude Code and run /review-code`));
+  step++;
+  console.log(chalk.gray(`    ${step}. Customize:         Edit personas in ${hubDir}/core/personas/`));
+  step++;
+  console.log(chalk.gray(`    ${step}. Import existing:   agentboot import --path <dir>`));
+  step++;
+
+  if (!hubHasRemote) {
+    console.log(chalk.gray(`    ${step}. Push when ready:   gh repo create ${orgSlug}/personas --source . --private --push`));
+    step++;
+  }
 
-  // Step 1.8: Next steps
-  console.log(chalk.bold(`${chalk.green("✓")} Persona source code lives at: ${hubDir}\n`));
-  console.log(chalk.gray("  Next steps:"));
-  console.log(chalk.gray("    1. Review personas:    Browse core/personas/ and customize"));
-  console.log(chalk.gray("    2. Add more repos:     Edit repos.json or run `agentboot install` from a repo"));
-  console.log(chalk.gray("    3. Import existing:    agentboot import --path ~/work/"));
-  console.log(chalk.gray("    4. Set up CI:          agentboot validate --strict in your pipeline\n"));
+  // Governance — brief, not a wall
+  console.log(chalk.cyan("\n  Governance tips:\n"));
+  console.log(chalk.gray("    - Enable branch protection on main (persona changes deserve review)"));
+  console.log(chalk.gray("    - Add `agentboot validate --strict` to CI"));
+  console.log(chalk.gray("    - Encourage developers to contribute — they know the prompts best"));
+  console.log("");
 }
 
 // ---------------------------------------------------------------------------
@@ -517,7 +804,7 @@ async function path2ConnectToHub(cwd: string, opts: InstallOptions, detection: D
     console.log(chalk.gray("\n  Looking for your org's personas repo...\n"));
 
     // Check siblings
-    const siblings = scanSiblings(cwd);
+    const siblings = scanNearby(cwd);
     const hubSiblings = siblings.filter(s => s.type === "hub");
 
     if (hubSiblings.length === 1) {

package/scripts/sync.ts

@@ -595,15 +595,21 @@ function validateRepoEntry(entry: RepoEntry, config: AgentBootConfig): string[]
     );
   }
 
-  // Validate repo path safety
+  // Validate repo path safety — resolve symlinks to check the real target
   const resolvedPath = path.resolve(entry.path);
+  let realPath = resolvedPath;
+  try {
+    if (fs.existsSync(resolvedPath)) {
+      realPath = fs.realpathSync(resolvedPath);
+    }
+  } catch { /* permission denied or broken symlink — use resolved path */ }
   const dangerousPaths = ["/", "/etc", "/usr", "/var", "/tmp", "/home", "/root", "/bin", "/sbin", "/lib", "/opt"];
-  if (dangerousPaths.includes(resolvedPath)) {
+  if (dangerousPaths.includes(realPath)) {
     errors.push(
-      `[${label}] Repo path "${resolvedPath}" is a system directory — refusing to sync`
+      `[${label}] Repo path "${realPath}" resolves to a system directory — refusing to sync`
     );
   }
-  if (fs.existsSync(resolvedPath) && !fs.existsSync(path.join(resolvedPath, ".git"))) {
+  if (fs.existsSync(realPath) && !fs.existsSync(path.join(realPath, ".git"))) {
     // Warn but don't block — temp dirs in tests and some workflows don't have .git
     console.warn(
       chalk.yellow(`  ⚠ [${label}] Repo path "${resolvedPath}" has no .git directory — is this a git repo?`)

package/scripts/validate.ts

@@ -298,7 +298,7 @@ function checkSkillFrontmatter(config: AgentBootConfig, configDir: string): Chec
  * Detect regex patterns likely to cause catastrophic backtracking.
  * Rejects patterns with nested quantifiers like (a+)+, (a*)*b, etc.
  */
-function isUnsafeRegex(pattern: string): boolean {
+export function isUnsafeRegex(pattern: string): boolean {
   // Reject patterns longer than 200 chars
   if (pattern.length > 200) return true;
   // Reject nested quantifiers: (x+)+, (x*)+, (x+)*, (x{n,})+, etc.
@@ -308,7 +308,7 @@ function isUnsafeRegex(pattern: string): boolean {
   return false;
 }
 
-function buildSecretPatterns(config: AgentBootConfig): RegExp[] {
+export function buildSecretPatterns(config: AgentBootConfig): RegExp[] {
   const configPatterns: RegExp[] = [];
   for (const p of config.validation?.secretPatterns ?? []) {
     if (isUnsafeRegex(p)) {
@@ -438,7 +438,11 @@ async function main(): Promise<void> {
   }
 }
 
-main().catch((err: unknown) => {
-  console.error(chalk.red("Unexpected error:"), err);
-  process.exit(1);
-});
+// Only run main() when executed directly, not when imported for testing
+const isDirectRun = process.argv[1]?.includes("validate");
+if (isDirectRun) {
+  main().catch((err: unknown) => {
+    console.error(chalk.red("Unexpected error:"), err);
+    process.exit(1);
+  });
+}

package/website/src/pages/index.tsx

@@ -75,7 +75,7 @@ function Features() {
         />
         <Feature
           title="Convention Over Configuration"
-          description="Sensible defaults for everything. Edit one config file. The Spring Boot of AI agent governance."
+          description="Sensible defaults for everything. Edit one config file. Bootstrap your agentic development teams."
         />
       </div>
     </section>