@toolbaux/guardian 0.1.2 → 0.1.4

package/README.md

@@ -105,6 +105,39 @@ guardian doc-html
 
 All extraction uses Tree-Sitter AST parsing — deterministic, no LLM involved.
 
+## LLM Usage — Opt-In Only
+
+> **Important:** Guardian's core commands (`extract`, `generate`, `context`, `drift`, `search`, `init`) **never call an LLM**. All extraction is deterministic AST parsing — no API keys needed, no background AI calls, no cost.
+
+Two commands **optionally** use an LLM, and **only when you explicitly configure it**:
+
+| Command | What the LLM does | Runs automatically? |
+|---------|-------------------|-------------------|
+| `guardian doc-generate` | Adds narrative summaries to product docs | **No** — manual command only |
+| `guardian guard --task "..."` | Generates a code patch from a task description | **No** — manual command only |
+
+**If you never set API keys, no LLM is ever called.** These commands degrade gracefully — `doc-generate` produces docs without narrative sections, and `guard` prints context instead of generating patches.
+
+### Configuring LLM (optional)
+
+```bash
+# Option 1: Cloud LLM (OpenAI-compatible endpoint)
+export GUARDIAN_LLM_ENDPOINT="https://api.openai.com/v1"
+export GUARDIAN_LLM_API_KEY="sk-..."
+export GUARDIAN_LLM_MODEL="gpt-4o"         # optional, defaults to gpt-4o
+
+# Option 2: Local Ollama (no API key needed, auto-detected)
+# Just have Ollama running on localhost:11434
+export GUARDIAN_OLLAMA_HOST="http://localhost:11434"  # optional, this is the default
+export GUARDIAN_OLLAMA_MODEL="llama3.2"                # optional, this is the default
+
+# Option 3: Shell command (for guardian guard)
+# Set in guardian.config.json:
+# { "llm": { "command": "ollama", "args": ["run", "llama3"] } }
+```
+
+**No pre-commit hook, VSCode extension, or automated workflow ever triggers LLM calls.** The hook only runs `extract` + `context` (pure AST).
+
 ## What Guardian Generates
 
 **Workflow sequence diagrams** — Mermaid diagrams for your most complex endpoints, showing the full call chain from client through handler to services and data stores.

package/dist/cli.js

@@ -18,6 +18,7 @@ import { runDocGenerate } from "./commands/doc-generate.js";
 import { runDiscrepancy } from "./commands/discrepancy.js";
 import { runDocHtml } from "./commands/doc-html.js";
 import { runInit } from "./commands/init.js";
+import { DEFAULT_SPECS_DIR } from "./config.js";
 const program = new Command();
 program
     .name("guardian")
@@ -29,8 +30,8 @@ program
     .argument("[projectRoot]", "Repo or project root", process.cwd())
     .option("--backend-root <path>", "Path to backend root")
     .option("--frontend-root <path>", "Path to frontend root")
-    .option("--config <path>", "Path to specguard.config.json")
-    .option("--output <path>", "Output directory", "specs-out")
+    .option("--config <path>", "Path to guardian.config.json")
+    .option("--output <path>", "Output directory", DEFAULT_SPECS_DIR)
     .option("--focus <text>", "Focus the generated AI context on a feature area")
     .option("--max-lines <count>", "Maximum lines for the generated context")
     .option("--ai-context", "Generate architecture-context.md for AI tools", false)
@@ -52,16 +53,16 @@ program
     .argument("[projectRoot]", "Repo or project root", process.cwd())
     .option("--backend-root <path>", "Path to backend root")
     .option("--frontend-root <path>", "Path to frontend root")
-    .option("--output <path>", "Output directory", "specs-out")
+    .option("--output <path>", "Output directory", DEFAULT_SPECS_DIR)
     .option("--include-file-graph", "Include file-level dependency graph", false)
-    .option("--config <path>", "Path to specguard.config.json")
+    .option("--config <path>", "Path to guardian.config.json")
     .option("--docs-mode <mode>", "Docs mode (lean|full)")
     .action(async (projectRoot, options) => {
     await runExtract({
         projectRoot,
         backendRoot: options.backendRoot,
         frontendRoot: options.frontendRoot,
-        output: options.output ?? "specs-out",
+        output: options.output ?? DEFAULT_SPECS_DIR,
         includeFileGraph: options.includeFileGraph ?? false,
         configPath: options.config,
         docsMode: options.docsMode
@@ -89,7 +90,7 @@ program
     .option("--output <path>", "Output report path", "specs-out/machine/drift.report.json")
     .option("--baseline [path]", "Write baseline drift file")
     .option("--history [path]", "Append drift history entry")
-    .option("--config <path>", "Path to specguard.config.json")
+    .option("--config <path>", "Path to guardian.config.json")
     .action(async (projectRoot, options) => {
     await runDrift({
         projectRoot,
@@ -107,7 +108,7 @@ program
     .argument("[projectRoot]", "Repo or project root", process.cwd())
     .option("--backend-root <path>", "Path to backend root")
     .option("--frontend-root <path>", "Path to frontend root")
-    .option("--config <path>", "Path to specguard.config.json")
+    .option("--config <path>", "Path to guardian.config.json")
     .option("--baseline <path>", "Path to baseline payload")
     .option("--strict-threshold <val>", "Maximum allowed delta shift (default 0.15)")
     .action(async (projectRoot, options) => {
@@ -127,7 +128,7 @@ program
     .option("--backend-root <path>", "Path to backend root")
     .option("--frontend-root <path>", "Path to frontend root")
     .option("--output <path>", "Output constraints path", "specs-out/machine/constraints.json")
-    .option("--config <path>", "Path to specguard.config.json")
+    .option("--config <path>", "Path to guardian.config.json")
     .action(async (projectRoot, options) => {
     await runConstraints({
         projectRoot,
@@ -148,7 +149,7 @@ program
     .option("--baseline-summary <path>", "Baseline architecture summary path")
     .option("--patch <path>", "Patch file to apply for simulation")
     .option("--mode <mode>", "Simulation mode (soft|hard)")
-    .option("--config <path>", "Path to specguard.config.json")
+    .option("--config <path>", "Path to guardian.config.json")
     .action(async (projectRoot, options) => {
     await runSimulate({
         projectRoot,
@@ -175,7 +176,7 @@ program
     .option("--mode <mode>", "Simulation mode (soft|hard)")
     .option("--llm-command <cmd>", "Override LLM command from config")
     .option("--print-context", "Print an IDE-ready context block instead of calling an LLM", false)
-    .option("--config <path>", "Path to specguard.config.json")
+    .option("--config <path>", "Path to guardian.config.json")
     .action(async (projectRoot, options) => {
     await runGuard({
         projectRoot,
@@ -194,24 +195,24 @@ program
 program
     .command("summary")
     .description("Generate a plain-language project summary from existing snapshots")
-    .option("--input <path>", "Snapshot output directory", "specs-out")
+    .option("--input <path>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .option("--output <path>", "Summary output path")
     .action(async (options) => {
     await runSummary({
-        input: options.input ?? "specs-out",
+        input: options.input ?? DEFAULT_SPECS_DIR,
         output: options.output
     });
 });
 program
     .command("search")
     .description("Search existing snapshots for models, endpoints, components, modules, and tasks")
-    .option("--input <path>", "Snapshot output directory", "specs-out")
+    .option("--input <path>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .requiredOption("--query <text>", "Search query")
     .option("--output <path>", "Write search results to a file")
     .option("--types <items>", "Comma-separated filters: models,endpoints,components,modules,tasks")
     .action(async (options) => {
     await runSearch({
-        input: options.input ?? "specs-out",
+        input: options.input ?? DEFAULT_SPECS_DIR,
         query: options.query,
         output: options.output,
         types: options.types ? [options.types] : undefined
@@ -220,13 +221,13 @@ program
 program
     .command("context")
     .description("Render an AI-ready context block from existing snapshots")
-    .option("--input <path>", "Snapshot output directory", "specs-out")
+    .option("--input <path>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .option("--output <path>", "Append the context block to a file")
     .option("--focus <text>", "Focus the context on a feature area")
     .option("--max-lines <count>", "Maximum number of lines to include")
     .action(async (options) => {
     await runContext({
-        input: options.input ?? "specs-out",
+        input: options.input ?? DEFAULT_SPECS_DIR,
         output: options.output,
         focus: options.focus,
         maxLines: options.maxLines
@@ -239,7 +240,7 @@ program
     .requiredOption("--query <text>", "Feature or area to analyze (e.g. 'stripe', 'auth')")
     .option("--backend-root <path>", "Path to backend root")
     .option("--frontend-root <path>", "Path to frontend root")
-    .option("--config <path>", "Path to specguard.config.json")
+    .option("--config <path>", "Path to guardian.config.json")
     .option("--output <path>", "Write report to a file instead of stdout")
     .option("--format <fmt>", "Output format: yaml or json (default: yaml)")
     .option("--ci", "Exit with code 1 when HIGH complexity is detected with strong confidence", false)
@@ -258,7 +259,7 @@ program
 program
     .command("intel")
     .description("Build codebase-intelligence.json from existing snapshots")
-    .option("--specs <dir>", "Snapshot output directory", "specs-out")
+    .option("--specs <dir>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .option("--output <path>", "Output path for codebase-intelligence.json")
     .action(async (options) => {
     await runIntel({
@@ -270,7 +271,7 @@ program
     .command("feature-context")
     .description("Generate a filtered context packet for implementing a single feature")
     .requiredOption("--spec <file>", "Path to feature spec YAML")
-    .option("--specs <dir>", "Snapshot output directory", "specs-out")
+    .option("--specs <dir>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .option("--output <path>", "Output path for feature context JSON")
     .action(async (options) => {
     await runFeatureContext({
@@ -282,7 +283,7 @@ program
 program
     .command("doc-generate")
     .description("Generate a human-readable product document from codebase intelligence")
-    .option("--specs <dir>", "Snapshot output directory", "specs-out")
+    .option("--specs <dir>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .option("--feature-specs <dir>", "Directory of feature spec YAML files")
     .option("--output <path>", "Output path for product-document.md")
     .option("--update-baseline", "Freeze current state as new baseline for discrepancy tracking", false)
@@ -297,7 +298,7 @@ program
 program
     .command("discrepancy")
     .description("Diff current codebase intelligence against a committed baseline")
-    .option("--specs <dir>", "Snapshot output directory", "specs-out")
+    .option("--specs <dir>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .option("--feature-specs <dir>", "Directory of feature spec YAML files")
     .option("--output <path>", "Output path (used when --format is json or md)")
     .option("--format <fmt>", "Output format: json, md, or both (default: both)", "both")
@@ -312,21 +313,21 @@ program
 program
     .command("doc-html")
     .description("Generate a self-contained Javadoc-style HTML viewer from codebase intelligence")
-    .option("--specs <dir>", "Snapshot output directory", "specs-out")
+    .option("--specs <dir>", "Snapshot output directory", DEFAULT_SPECS_DIR)
     .option("--output <path>", "Output path for index.html")
     .action(async (options) => {
     await runDocHtml({
-        specs: options.specs ?? "specs-out",
+        specs: options.specs ?? DEFAULT_SPECS_DIR,
         output: options.output,
     });
 });
 program
     .command("init")
-    .description("Initialize specguard for a project (config, .specs dir, pre-commit hook, CLAUDE.md)")
+    .description("Initialize guardian for a project (config, .specs dir, pre-commit hook, CLAUDE.md)")
     .argument("[projectRoot]", "Repo or project root", process.cwd())
     .option("--backend-root <path>", "Path to backend root")
     .option("--frontend-root <path>", "Path to frontend root")
-    .option("--output <path>", "Output directory", ".specs")
+    .option("--output <path>", "Output directory", DEFAULT_SPECS_DIR)
     .option("--skip-hook", "Skip pre-commit hook installation", false)
     .action(async (projectRoot, options) => {
     await runInit({

package/dist/commands/analyze-depth.js

@@ -3,12 +3,13 @@ import fs from "node:fs/promises";
 import yaml from "js-yaml";
 import { buildSnapshots } from "../extract/index.js";
 import { analyzeDepth } from "../extract/analyzers/depth.js";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 export async function runAnalyzeDepth(options) {
     const { architecture } = await buildSnapshots({
         projectRoot: options.projectRoot,
         backendRoot: options.backendRoot,
         frontendRoot: options.frontendRoot,
-        output: options.output ?? "specs-out",
+        output: options.output ?? DEFAULT_SPECS_DIR,
         includeFileGraph: true,
         configPath: options.configPath
     });
@@ -35,7 +36,7 @@ export async function runAnalyzeDepth(options) {
     if (options.ci &&
         report.classification.compressible === "NON_COMPRESSIBLE" &&
         report.confidence.value >= report.guardrails.enforce_if_confidence_above) {
-        console.error(`\n[SpecGuard] CI FAIL: "${options.query}" classified as HIGH complexity (confidence ${report.confidence.value.toFixed(2)}).\n` +
+        console.error(`\n[Guardian] CI FAIL: "${options.query}" classified as HIGH complexity (confidence ${report.confidence.value.toFixed(2)}).\n` +
             `Recommended pattern: ${report.recommendation.primary.pattern}\n` +
             `Avoid: ${report.recommendation.avoid.join(", ")}`);
         process.exit(1);

package/dist/commands/context.js

@@ -4,8 +4,9 @@ import yaml from "js-yaml";
 import { loadArchitectureDiff, loadHeatmap } from "../extract/compress.js";
 import { renderContextBlock } from "../extract/context-block.js";
 import { resolveMachineInputDir } from "../output-layout.js";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 export async function runContext(options) {
-    const inputDir = await resolveMachineInputDir(options.input || "specs-out");
+    const inputDir = await resolveMachineInputDir(options.input || DEFAULT_SPECS_DIR);
     const { architecture, ux } = await loadSnapshots(inputDir);
     const [diff, heatmap] = await Promise.all([
         loadArchitectureDiff(inputDir),
@@ -41,7 +42,7 @@ async function loadSnapshots(inputDir) {
     }
     catch (error) {
         if (error.code === "ENOENT") {
-            throw new Error(`Could not find snapshots in ${inputDir}. Run \`specguard extract\` first.`);
+            throw new Error(`Could not find snapshots in ${inputDir}. Run \`guardian extract\` first.`);
         }
         throw error;
     }

package/dist/commands/discrepancy.js

@@ -1,5 +1,5 @@
 /**
- * `specguard discrepancy` — diff current codebase intelligence against a baseline.
+ * `guardian discrepancy` — diff current codebase intelligence against a baseline.
  *
  * Reads:
  *   - specs-out/machine/codebase-intelligence.json
@@ -22,7 +22,7 @@ export async function runDiscrepancy(options) {
     // Load codebase intelligence
     const intelPath = path.join(layout.machineDir, "codebase-intelligence.json");
     const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
-        throw new Error(`Could not load codebase-intelligence.json from ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+        throw new Error(`Could not load codebase-intelligence.json from ${intelPath}. Run \`guardian intel --specs ${options.specs}\` first.`);
     });
     const baselinePath = path.join(layout.machineDir, "product-document.baseline.json");
     const featureSpecsDir = options.featureSpecs ? path.resolve(options.featureSpecs) : null;

package/dist/commands/doc-generate.js

@@ -1,5 +1,5 @@
 /**
- * `specguard doc-generate` — generate a human-readable, self-updating product document.
+ * `guardian doc-generate` — generate a human-readable, self-updating product document.
  *
  * Reads:
  *   - specs-out/machine/codebase-intelligence.json
@@ -12,8 +12,8 @@
  *   - specs-out/machine/product-document.baseline.json (if --update-baseline)
  *
  * LLM env vars (optional — all deterministic sections write regardless):
- *   SPECGUARD_LLM_ENDPOINT, SPECGUARD_LLM_API_KEY, SPECGUARD_LLM_MODEL
- *   SPECGUARD_OLLAMA_HOST, SPECGUARD_OLLAMA_MODEL
+ *   GUARDIAN_LLM_ENDPOINT, GUARDIAN_LLM_API_KEY, GUARDIAN_LLM_MODEL
+ *   GUARDIAN_OLLAMA_HOST, GUARDIAN_OLLAMA_MODEL
  */
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -32,7 +32,7 @@ export async function runDocGenerate(options) {
     const llmConfig = await loadLlmConfig();
     if (!llmConfig) {
         console.log("none (deterministic only)");
-        console.log("  Tip: set SPECGUARD_LLM_ENDPOINT + SPECGUARD_LLM_API_KEY, or run Ollama locally, to add narrative summaries.");
+        console.log("  Tip: set GUARDIAN_LLM_ENDPOINT + GUARDIAN_LLM_API_KEY, or run Ollama locally, to add narrative summaries.");
     }
     else if (llmConfig.provider === "ollama") {
         console.log(`Ollama (${llmConfig.model} at ${llmConfig.endpoint.replace("/api/chat", "")})`);
@@ -46,7 +46,7 @@ export async function runDocGenerate(options) {
     process.stdout.write("Loading codebase intelligence... ");
     const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
         console.log("failed");
-        throw new Error(`Could not load ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+        throw new Error(`Could not load ${intelPath}. Run \`guardian intel --specs ${options.specs}\` first.`);
     });
     console.log(`${intel.meta.counts.endpoints} endpoints, ${intel.meta.counts.models} models, ` +
         `${intel.meta.counts.enums} enums, ${intel.meta.counts.tasks} tasks`);
@@ -158,6 +158,6 @@ export async function runDocGenerate(options) {
     // ── Done ──────────────────────────────────────────────────────────────────
     if (discrepancies.summary.total_issues > 0) {
         const critical = discrepancies.summary.has_critical ? " (critical changes detected)" : "";
-        console.log(`  ⚠ ${discrepancies.summary.total_issues} discrepancy(s) found${critical}. Run \`specguard discrepancy\` for details.`);
+        console.log(`  ⚠ ${discrepancies.summary.total_issues} discrepancy(s) found${critical}. Run \`guardian discrepancy\` for details.`);
     }
 }

package/dist/commands/doc-html.js

@@ -1,5 +1,5 @@
 /**
- * `specguard doc-html` — generate a self-contained Javadoc-style HTML viewer.
+ * `guardian doc-html` — generate a self-contained Javadoc-style HTML viewer.
  *
  * Same data pipeline as `doc-generate` but outputs a single index.html with:
  *   - Fixed sidebar navigation (collapsible, searchable)
@@ -23,7 +23,7 @@ export async function runDocHtml(options) {
     process.stdout.write("Loading codebase intelligence... ");
     const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
         console.log("failed");
-        throw new Error(`Could not load ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+        throw new Error(`Could not load ${intelPath}. Run \`guardian intel --specs ${options.specs}\` first.`);
     });
     console.log(`${intel.meta.counts.endpoints} endpoints, ${intel.meta.counts.models} models`);
     // ── Feature arcs (optional) ───────────────────────────────────────────────

package/dist/commands/drift.js

@@ -62,7 +62,7 @@ export async function runDrift(options) {
         await fs.appendFile(resolvedHistory, `${JSON.stringify(entry)}\n`);
         console.log(`Appended history ${resolvedHistory}`);
     }
-    console.log("SpecGuard Drift Report");
+    console.log("Guardian Drift Report");
     console.log(`Status: ${drift.status}`);
     console.log(`D_t: ${drift.D_t.toFixed(4)}`);
     console.log(`K_t: ${drift.K_t.toFixed(4)}`);

package/dist/commands/extract.js

@@ -1,6 +1,9 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { extractProject } from "../extract/index.js";
 import { runIntel } from "./intel.js";
+import { runGenerate } from "./generate.js";
+import { runContext } from "./context.js";
 export async function runExtract(options) {
     const { architecturePath, uxPath } = await extractProject(options);
     console.log(`Wrote ${architecturePath}`);
@@ -13,4 +16,26 @@ export async function runExtract(options) {
     catch {
         // Non-fatal — intel build failure should not break extract
     }
+    // Auto-generate AI context + inject into CLAUDE.md
+    const projectRoot = path.resolve(options.projectRoot || process.cwd());
+    try {
+        await runGenerate({
+            projectRoot,
+            backendRoot: options.backendRoot,
+            frontendRoot: options.frontendRoot,
+            output: specsDir,
+            aiContext: true,
+        });
+        const claudeMdPath = path.join(projectRoot, "CLAUDE.md");
+        try {
+            await fs.stat(claudeMdPath);
+            await runContext({ input: specsDir, output: claudeMdPath });
+        }
+        catch {
+            // No CLAUDE.md — skip context injection
+        }
+    }
+    catch {
+        // Non-fatal — context generation failure should not break extract
+    }
 }

package/dist/commands/feature-context.js

@@ -1,5 +1,5 @@
 /**
- * `specguard feature-context` — generate a filtered, self-contained context packet
+ * `guardian feature-context` — generate a filtered, self-contained context packet
  * for implementing a single feature.
  *
  * Analogous to `chapter-context` in the book workflow: given a feature spec YAML,
@@ -26,7 +26,7 @@ export async function runFeatureContext(options) {
     // Load codebase intelligence
     const intelPath = path.join(layout.machineDir, "codebase-intelligence.json");
     const intel = await loadCodebaseIntelligence(intelPath).catch(() => {
-        throw new Error(`Could not load codebase-intelligence.json from ${intelPath}. Run \`specguard intel --specs ${options.specs}\` first.`);
+        throw new Error(`Could not load codebase-intelligence.json from ${intelPath}. Run \`guardian intel --specs ${options.specs}\` first.`);
     });
     // Build filtered context
     const context = buildFeatureContext(spec, intel);

package/dist/commands/generate.js

@@ -3,12 +3,13 @@ import path from "node:path";
 import { buildSnapshots } from "../extract/index.js";
 import { renderContextBlock } from "../extract/context-block.js";
 import { getOutputLayout } from "../output-layout.js";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 import { analyzeDepth } from "../extract/analyzers/depth.js";
 export async function runGenerate(options) {
     if (!options.aiContext) {
-        throw new Error("`specguard generate` currently supports `--ai-context` only.");
+        throw new Error("`guardian generate` currently supports `--ai-context` only.");
     }
-    const outputRoot = path.resolve(options.output ?? "specs-out");
+    const outputRoot = path.resolve(options.output ?? DEFAULT_SPECS_DIR);
     const layout = getOutputLayout(outputRoot);
     const { architecture, ux } = await buildSnapshots({
         projectRoot: options.projectRoot,
@@ -18,7 +19,7 @@ export async function runGenerate(options) {
         includeFileGraph: true,
         configPath: options.configPath
     });
-    // Load persisted Structural Intelligence reports emitted by `specguard extract`
+    // Load persisted Structural Intelligence reports emitted by `guardian extract`
     const siReports = await loadStructuralIntelligenceReports(layout.machineDir);
     // If a --focus query is provided, prepend a real-time SI report for that query
     if (options.focus) {

package/dist/commands/guard.js

@@ -6,6 +6,7 @@ import { runSimulate } from "./simulate.js";
 import { buildSnapshots } from "../extract/index.js";
 import { renderContextBlock } from "../extract/context-block.js";
 import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 export async function runGuard(options) {
     const resolved = await resolveProjectPaths({
         projectRoot: options.projectRoot,
@@ -30,7 +31,7 @@ export async function runGuard(options) {
             projectRoot: resolved.workspaceRoot,
             backendRoot: resolved.backendRoot,
             frontendRoot: resolved.frontendRoot,
-            output: "specs-out",
+            output: DEFAULT_SPECS_DIR,
             includeFileGraph: true,
             configPath: options.configPath
         });

package/dist/commands/init.js

@@ -12,6 +12,7 @@
  */
 import fs from "node:fs/promises";
 import path from "node:path";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 const DEFAULT_CONFIG = {
     project: {
         backendRoot: "./backend",
@@ -47,7 +48,7 @@ exit 0
 `;
 export async function runInit(options) {
     const root = path.resolve(options.projectRoot || process.cwd());
-    const specsDir = path.join(root, options.output || ".specs");
+    const specsDir = path.join(root, options.output || DEFAULT_SPECS_DIR);
     console.log(`Initializing Guardian in ${root}\n`);
     // 1. Create .specs/ directory
     await fs.mkdir(path.join(specsDir, "machine", "docs"), { recursive: true });
@@ -145,7 +146,7 @@ export async function runInit(options) {
         const content = [
             `# ${projectName}`,
             "",
-            "## SpecGuard Architecture Context",
+            "## Guardian Architecture Context",
             "",
             "<!-- guardian:auto-context -->",
             "<!-- This block is auto-updated by guardian. Do not edit manually. -->",
@@ -181,7 +182,7 @@ export async function runInit(options) {
             input: specsDir,
             output: claudeMdPath,
         });
-        console.log("\n✓ SpecGuard initialized. Architecture context is in CLAUDE.md and .specs/");
+        console.log("\n✓ Guardian initialized. Architecture context is in CLAUDE.md and .specs/");
         console.log("  Pre-commit hook will keep it fresh on every commit.");
     }
     catch (err) {

package/dist/commands/intel.js

@@ -1,10 +1,10 @@
 /**
- * `specguard intel` — build codebase-intelligence.json from existing snapshots.
+ * `guardian intel` — build codebase-intelligence.json from existing snapshots.
  *
  * Reads:  specs-out/machine/architecture.snapshot.yaml + ux.snapshot.yaml
  * Writes: specs-out/machine/codebase-intelligence.json
  *
- * Also auto-runs at the end of `specguard extract`.
+ * Also auto-runs at the end of `guardian extract`.
  */
 import path from "node:path";
 import { writeCodebaseIntelligence } from "../extract/codebase-intel.js";

package/dist/commands/search.js

@@ -3,8 +3,9 @@ import path from "node:path";
 import yaml from "js-yaml";
 import { loadHeatmap } from "../extract/compress.js";
 import { resolveMachineInputDir } from "../output-layout.js";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 export async function runSearch(options) {
-    const inputDir = await resolveMachineInputDir(options.input || "specs-out");
+    const inputDir = await resolveMachineInputDir(options.input || DEFAULT_SPECS_DIR);
     const { architecture, ux } = await loadSnapshots(inputDir);
     const heatmap = await loadHeatmap(inputDir);
     const types = normalizeTypes(options.types);
@@ -38,7 +39,7 @@ async function loadSnapshots(inputDir) {
     }
     catch (error) {
         if (error.code === "ENOENT") {
-            throw new Error(`Could not find snapshots in ${inputDir}. Run \`specguard extract\` first.`);
+            throw new Error(`Could not find snapshots in ${inputDir}. Run \`guardian extract\` first.`);
         }
         throw error;
     }

package/dist/commands/simulate.js

@@ -6,6 +6,7 @@ import { spawn } from "node:child_process";
 import yaml from "js-yaml";
 import { buildSnapshots } from "../extract/index.js";
 import { buildArchitectureSummary, loadArchitectureSummary } from "../extract/compress.js";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 import { createIgnoreMatcher } from "../extract/ignore.js";
 import { logResolvedProjectPaths, resolveProjectPaths } from "../project-discovery.js";
 export async function runSimulate(options) {
@@ -106,7 +107,7 @@ async function resolveBaselineSummaryPath(params) {
     if (params.override) {
         candidates.push(params.override);
     }
-    candidates.push(path.join(params.projectRoot, "specs-out", "machine", "architecture.summary.json"));
+    candidates.push(path.join(params.projectRoot, DEFAULT_SPECS_DIR, "machine", "architecture.summary.json"));
     for (const candidate of candidates) {
         const resolved = path.isAbsolute(candidate)
             ? candidate
@@ -241,7 +242,7 @@ function buildSuggestions(reasons) {
     return Array.from(suggestions);
 }
 async function createTempCopy(sourceRoot, config) {
-    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "specguard-sim-"));
+    const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), "guardian-sim-"));
     const ignore = createIgnoreMatcher(config, sourceRoot);
     await fs.cp(sourceRoot, tempRoot, {
         recursive: true,

package/dist/commands/summary.js

@@ -4,8 +4,9 @@ import yaml from "js-yaml";
 import { renderExecutiveSummary } from "../extract/docs.js";
 import { loadArchitectureSummary, loadArchitectureDiff, loadHeatmap } from "../extract/compress.js";
 import { resolveMachineInputDir } from "../output-layout.js";
+import { DEFAULT_SPECS_DIR } from "../config.js";
 export async function runSummary(options) {
-    const inputDir = await resolveMachineInputDir(options.input || "specs-out");
+    const inputDir = await resolveMachineInputDir(options.input || DEFAULT_SPECS_DIR);
     const architecturePath = path.join(inputDir, "architecture.snapshot.yaml");
     const uxPath = path.join(inputDir, "ux.snapshot.yaml");
     const [architectureRaw, uxRaw] = await Promise.all([

package/dist/commands/verify-drift.js

@@ -31,7 +31,7 @@ export async function runVerifyDrift(options) {
     }
     const threshold = options.strictThreshold ? parseFloat(options.strictThreshold) : 0.15;
     console.log("=========================================");
-    console.log("SpecGuard Drift Verification");
+    console.log("Guardian Drift Verification");
     console.log("=========================================\n");
     console.log(`Current Status: ${drift.status}`);
     console.log(`Current Delta:  ${drift.delta.toFixed(4)}`);

package/dist/config.js

@@ -1,5 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+/** Single source of truth for the default specs output directory */
+export const DEFAULT_SPECS_DIR = ".specs";
 const DEFAULT_CONFIG = {
     project: {
         root: "",
@@ -29,8 +31,13 @@ const DEFAULT_CONFIG = {
             "log",
             "tmp",
             "cache",
-            "specs-out",
-            "ghost-out"
+            ".specs",
+            "ghost-out",
+            "ios",
+            "android",
+            ".expo",
+            ".turbo",
+            "web-build"
         ],
         paths: []
     },
@@ -77,6 +84,9 @@ const DEFAULT_CONFIG = {
         timeoutMs: 120000,
         promptTemplate: ""
     },
+    output: {
+        specsDir: DEFAULT_SPECS_DIR
+    },
     docs: {
         mode: "lean",
         internalDir: "internal"
@@ -338,6 +348,9 @@ function mergeConfig(base, override) {
             timeoutMs: override.llm?.timeoutMs ?? base.llm?.timeoutMs ?? 120000,
             promptTemplate: override.llm?.promptTemplate ?? base.llm?.promptTemplate ?? ""
         },
+        output: {
+            specsDir: override.output?.specsDir ?? base.output?.specsDir ?? DEFAULT_SPECS_DIR
+        },
         docs: {
             mode: override.docs?.mode ?? base.docs?.mode ?? "lean",
             internalDir: override.docs?.internalDir ?? base.docs?.internalDir ?? "internal"

package/dist/extract/analyzers/backend.js

@@ -1041,7 +1041,7 @@ function emptyPythonFileResult() {
         endpointModelUsage: []
     };
 }
-export async function analyzeBackend(backendRoot, config) {
+export async function analyzeBackend(backendRoot, config, workspaceRoot) {
     const root = path.resolve(backendRoot);
     const baseRoot = path.dirname(root);
     const ignore = createIgnoreMatcher(config, baseRoot);
@@ -1111,8 +1111,9 @@ export async function analyzeBackend(backendRoot, config) {
     }
     codeFiles.sort((a, b) => a.localeCompare(b));
     const knownFiles = new Set(codeFiles);
+    const cacheRoot = workspaceRoot ? path.resolve(workspaceRoot) : baseRoot;
     const { cachePath, cache } = await loadBackendExtractionCache({
-        projectRoot: baseRoot,
+        projectRoot: cacheRoot,
         config
     });
     const activeAbsoluteFiles = new Set(codeFiles.map((file) => path.join(baseRoot, file)));

package/dist/extract/cache.js

@@ -1,9 +1,10 @@
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-const BACKEND_CACHE_VERSION = "specguard-backend-cache-v4";
+import { DEFAULT_SPECS_DIR } from "../config.js";
+const BACKEND_CACHE_VERSION = "guardian-backend-cache-v4";
 export async function loadBackendExtractionCache(params) {
-    const cachePath = path.join(params.projectRoot, "specs-out", ".cache", "file-hashes.json");
+    const cachePath = path.join(params.projectRoot, DEFAULT_SPECS_DIR, ".cache", "file-hashes.json");
     const configHash = hashObject(params.config);
     try {
         const raw = await fs.readFile(cachePath, "utf8");

package/dist/extract/docs-loader.js

@@ -1,5 +1,5 @@
 /**
- * Docs Loader — loads and parses sections from existing specguard doc files.
+ * Docs Loader — loads and parses sections from existing guardian doc files.
  *
  * Reads from specs-out/machine/docs/:
  *   hld.md         → systemDiagram, couplingHeatmap, backendSubsystems, apiDomainMap

package/dist/extract/docs.js

@@ -189,7 +189,7 @@ function renderIndex(architecture, ux, options) {
     const internalFiles = options.internalFiles ?? [];
     const internalDir = options.internalDir ?? "internal";
     return [
-        section("SpecGuard Overview"),
+        section("Guardian Overview"),
         `Project: **${architecture.project.name}**\n\n`,
         renderTable(["Metric", "Count", "Notes"], [
             ["Modules", String(architecture.modules.length), "Backend modules"],
@@ -211,7 +211,7 @@ function renderIndex(architecture, ux, options) {
 }
 function renderHumanRootReadme(architecture) {
     return [
-        "# SpecGuard Output",
+        "# Guardian Output",
         "",
         `Project: **${architecture.project.name}**`,
         "",
@@ -381,7 +381,7 @@ function renderHumanDataAndFlows(architecture, ux) {
         [
             "unverified",
             String(architecture.cross_stack_contracts.length - verified.length),
-            "SpecGuard could not confidently infer enough fields yet"
+            "Guardian could not confidently infer enough fields yet"
         ]
     ]));
     lines.push("Next: [Change Guide](./change-guide.md)\n");
@@ -472,7 +472,7 @@ export function renderExecutiveSummary(architecture, ux, meta) {
     summaryLines.push(section("Product Summary"));
     summaryLines.push(`Project: **${architecture.project.name}**\n\n`);
     summaryLines.push(`Snapshot date: **${formatTimestamp(generatedAt)}**\n\n`);
-    summaryLines.push("SpecGuard produces living, machine‑verified documentation for your codebase so teams can align on architecture, detect drift, and share an accurate system spec without manual doc maintenance.\n\n");
+    summaryLines.push("Guardian produces living, machine‑verified documentation for your codebase so teams can align on architecture, detect drift, and share an accurate system spec without manual doc maintenance.\n\n");
     summaryLines.push("## Vision\n\n");
     summaryLines.push("Enable teams to treat architecture as a first‑class, continuously verifiable product artifact—" +
         "not a static diagram or an outdated wiki.\n\n");
@@ -2087,7 +2087,7 @@ function renderDiff(architecture, meta) {
     const lines = [];
     lines.push(section("Snapshot Changelog"));
     if (!meta?.diff) {
-        lines.push("*No previous summary available. Run SpecGuard twice to generate a diff.*\n\n");
+        lines.push("*No previous summary available. Run Guardian twice to generate a diff.*\n\n");
         return lines.join("");
     }
     lines.push(`Structural change: **${meta.diff.structural_change ? "yes" : "no"}**  \n` +
@@ -2166,7 +2166,7 @@ function renderIntegrationGuide(snapshot) {
         const mismatchedCount = verifiedContracts.filter((contract) => contract.status === "mismatched").length;
         const unverifiedCount = snapshot.cross_stack_contracts.length - verifiedContracts.length;
         lines.push(`Verified: ${verifiedContracts.length} contracts (${mismatchedCount} mismatched). Unverified: ${unverifiedCount}.`);
-        lines.push(" Run `specguard extract --include-file-graph` for richer caller inference.\n\n");
+        lines.push(" Run `guardian extract --include-file-graph` for richer caller inference.\n\n");
         if (verifiedContracts.length === 0) {
             lines.push("*No verified frontend/backend contracts detected yet.*\n\n");
         }
@@ -2251,7 +2251,8 @@ export async function writeDocs(outputRoot, architecture, ux, options) {
         { name: "data.md", content: renderData(architecture, "lean") },
         { name: "tests.md", content: renderTests(architecture) }
     ];
-    const fullFiles = [
+    // Internal-only files: richer versions of lean files + files that only exist in full mode
+    const fullOnlyFiles = [
         { name: "index.md", content: renderIndex(architecture, ux, { docsFiles: FULL_INDEX_FILES }) },
         {
             name: "summary.md",
@@ -2273,27 +2274,10 @@ export async function writeDocs(outputRoot, architecture, ux, options) {
             })
         },
         { name: "architecture.md", content: renderArchitecture(architecture, { summary, diff, heatmap }) },
-        { name: "ux.md", content: renderUx(ux) },
         { name: "data.md", content: renderData(architecture, "full") },
         { name: "data_dictionary.md", content: renderDataDictionary(architecture) },
-        { name: "integration.md", content: renderIntegrationGuide(architecture) },
-        {
-            name: "diff.md",
-            content: renderDiff(architecture, {
-                summary,
-                diff,
-                previous: options?.previous?.architecture ?? null
-            })
-        },
         { name: "test_coverage.md", content: renderTestCoverage(architecture) },
-        { name: "runtime.md", content: renderRuntime(architecture) },
-        { name: "infra.md", content: renderInfra(architecture) },
-        {
-            name: "hld.md",
-            content: renderHld(architecture, ux, driftHistory, { summary, diff, heatmap })
-        },
         { name: "lld.md", content: renderLld(architecture, ux, "full") },
-        { name: "tests.md", content: renderTests(architecture) }
     ];
     const written = [];
     await fs.writeFile(path.join(layout.rootDir, "README.md"), renderHumanRootReadme(architecture));
@@ -2306,7 +2290,7 @@ export async function writeDocs(outputRoot, architecture, ux, options) {
     if (docsMode === "full") {
         const internalDir = layout.machineInternalDir;
         await fs.mkdir(internalDir, { recursive: true });
-        for (const file of fullFiles) {
+        for (const file of fullOnlyFiles) {
             const target = path.join(internalDir, file.name);
             await fs.writeFile(target, file.content);
             written.push(target);

package/dist/extract/html-doc.js

@@ -374,7 +374,7 @@ function renderQualityPage(intel, docs) {
     // Quality signals
     parts.push(`<section id="quality-signals"><h2>Quality Signals</h2>${docs.qualitySignals
         ? renderMd(docs.qualitySignals)
-        : `<p class="muted">Run <code>specguard extract</code> to populate quality signals.</p>`}</section>`);
+        : `<p class="muted">Run <code>guardian extract</code> to populate quality signals.</p>`}</section>`);
     // Pattern registry
     const active = intel.pattern_registry.patterns.filter((p) => p.occurrences > 0);
     const rows = active.map((p) => {

package/dist/extract/index.js

@@ -28,7 +28,7 @@ export async function buildSnapshots(options) {
     const reportedFrontendRoot = formatOutputPath(resolvedFrontendRoot);
     const reportedWorkspaceRoot = formatOutputPath(workspaceRoot);
     const config = resolvedProject.config;
-    const backend = await analyzeBackend(resolvedBackendRoot, config);
+    const backend = await analyzeBackend(resolvedBackendRoot, config, workspaceRoot);
     const frontend = await analyzeFrontend(resolvedFrontendRoot, config);
     const projectRoot = workspaceRoot;
     const runtime = await analyzeRuntime(workspaceRoot, config);

package/dist/extract/llm-client.js

@@ -2,16 +2,16 @@
  * LLM Client — thin HTTP client for LLM-powered doc generation.
  *
  * Resolution order:
- *   1. Configured LLM  — SPECGUARD_LLM_ENDPOINT + SPECGUARD_LLM_API_KEY both set
- *   2. Ollama fallback — SPECGUARD_LLM_ENDPOINT/KEY not set, Ollama reachable at localhost
+ *   1. Configured LLM  — GUARDIAN_LLM_ENDPOINT + GUARDIAN_LLM_API_KEY both set
+ *   2. Ollama fallback — GUARDIAN_LLM_ENDPOINT/KEY not set, Ollama reachable at localhost
  *   3. None            — returns null from loadLlmConfig(), callers write placeholder text
  *
  * Env vars:
- *   SPECGUARD_LLM_ENDPOINT   — full URL e.g. https://api.anthropic.com/v1/messages
- *   SPECGUARD_LLM_API_KEY    — API key (not required for Ollama)
- *   SPECGUARD_LLM_MODEL      — model ID (optional)
- *   SPECGUARD_OLLAMA_HOST    — Ollama base URL (default: http://localhost:11434)
- *   SPECGUARD_OLLAMA_MODEL   — Ollama model (default: llama3.2)
+ *   GUARDIAN_LLM_ENDPOINT   — full URL e.g. https://api.anthropic.com/v1/messages
+ *   GUARDIAN_LLM_API_KEY    — API key (not required for Ollama)
+ *   GUARDIAN_LLM_MODEL      — model ID (optional)
+ *   GUARDIAN_OLLAMA_HOST    — Ollama base URL (default: http://localhost:11434)
+ *   GUARDIAN_OLLAMA_MODEL   — Ollama model (default: llama3.2)
  *
  * Wire formats (auto-detected from endpoint URL):
  *   anthropic  — POST /v1/messages        { model, max_tokens, system, messages }
@@ -28,21 +28,21 @@ const DEFAULT_MAX_TOKENS = 2048;
  * Load LLM config from environment variables.
  *
  * Resolution order:
- *   1. SPECGUARD_LLM_ENDPOINT + SPECGUARD_LLM_API_KEY → configured cloud/local LLM
- *   2. Ollama reachable at SPECGUARD_OLLAMA_HOST (or localhost:11434) → Ollama fallback
+ *   1. GUARDIAN_LLM_ENDPOINT + GUARDIAN_LLM_API_KEY → configured cloud/local LLM
+ *   2. Ollama reachable at GUARDIAN_OLLAMA_HOST (or localhost:11434) → Ollama fallback
  *   3. null → no LLM available
  */
 export async function loadLlmConfig() {
     // Priority 1: explicit endpoint + key
-    const endpoint = process.env["SPECGUARD_LLM_ENDPOINT"];
-    const apiKey = process.env["SPECGUARD_LLM_API_KEY"];
+    const endpoint = process.env["GUARDIAN_LLM_ENDPOINT"];
+    const apiKey = process.env["GUARDIAN_LLM_API_KEY"];
     if (endpoint && apiKey) {
-        const model = process.env["SPECGUARD_LLM_MODEL"] ?? DEFAULT_CLOUD_MODEL;
+        const model = process.env["GUARDIAN_LLM_MODEL"] ?? DEFAULT_CLOUD_MODEL;
         return { endpoint, apiKey, model, provider: detectProvider(endpoint) };
     }
     // Priority 2: Ollama fallback
-    const ollamaHost = process.env["SPECGUARD_OLLAMA_HOST"] ?? DEFAULT_OLLAMA_HOST;
-    const ollamaModel = process.env["SPECGUARD_OLLAMA_MODEL"] ?? DEFAULT_OLLAMA_MODEL;
+    const ollamaHost = process.env["GUARDIAN_OLLAMA_HOST"] ?? DEFAULT_OLLAMA_HOST;
+    const ollamaModel = process.env["GUARDIAN_OLLAMA_MODEL"] ?? DEFAULT_OLLAMA_MODEL;
     if (await isOllamaReachable(ollamaHost)) {
         return {
             endpoint: `${ollamaHost}/api/chat`,
@@ -58,11 +58,11 @@ export async function loadLlmConfig() {
  * Use when async is not possible, or when you want to skip Ollama discovery.
  */
 export function loadLlmConfigSync() {
-    const endpoint = process.env["SPECGUARD_LLM_ENDPOINT"];
-    const apiKey = process.env["SPECGUARD_LLM_API_KEY"];
+    const endpoint = process.env["GUARDIAN_LLM_ENDPOINT"];
+    const apiKey = process.env["GUARDIAN_LLM_API_KEY"];
     if (!endpoint || !apiKey)
         return null;
-    const model = process.env["SPECGUARD_LLM_MODEL"] ?? DEFAULT_CLOUD_MODEL;
+    const model = process.env["GUARDIAN_LLM_MODEL"] ?? DEFAULT_CLOUD_MODEL;
     return { endpoint, apiKey, model, provider: detectProvider(endpoint) };
 }
 /**

package/dist/output-layout.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import fs from "node:fs/promises";
+import { DEFAULT_SPECS_DIR } from "./config.js";
 export function getOutputLayout(outputRoot, internalDir = "internal") {
     const rootDir = path.resolve(outputRoot);
     const machineDir = path.join(rootDir, "machine");
@@ -12,7 +13,7 @@ export function getOutputLayout(outputRoot, internalDir = "internal") {
     };
 }
 export async function resolveMachineInputDir(input) {
-    const resolved = path.resolve(input || "specs-out");
+    const resolved = path.resolve(input || DEFAULT_SPECS_DIR);
     const directSnapshot = await hasMachineSnapshots(resolved);
     if (directSnapshot) {
         return resolved;

package/dist/project-discovery.js

@@ -1,6 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
-import { loadSpecGuardConfig } from "./config.js";
+import { DEFAULT_SPECS_DIR, loadSpecGuardConfig } from "./config.js";
 const IGNORE_DIRS = new Set([
     ".git",
     "node_modules",
@@ -11,7 +11,7 @@ const IGNORE_DIRS = new Set([
     "__pycache__",
     ".venv",
     "venv",
-    "specs-out",
+    DEFAULT_SPECS_DIR,
     ".pytest_cache",
     ".mypy_cache",
     ".turbo"
@@ -62,7 +62,7 @@ export async function resolveProjectPaths(options) {
     };
 }
 export function logResolvedProjectPaths(resolved) {
-    console.log(`SpecGuard roots (${resolved.resolutionSource}): workspace=${resolved.workspaceRoot} backend=${resolved.backendRoot} frontend=${resolved.frontendRoot}`);
+    console.log(`Guardian roots (${resolved.resolutionSource}): workspace=${resolved.workspaceRoot} backend=${resolved.backendRoot} frontend=${resolved.frontendRoot}`);
 }
 async function chooseBackendRoot(workspaceRoot) {
     const candidates = await discoverBackendCandidates(workspaceRoot);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolbaux/guardian",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Architectural intelligence for codebases. Verify that AI-generated code matches your architectural intent.",
   "keywords": [