@toolbaux/guardian 0.1.3 → 0.1.5

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

@@ -30,7 +30,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("--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")
@@ -55,7 +55,7 @@ program
     .option("--frontend-root <path>", "Path to frontend root")
     .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({
@@ -90,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,
@@ -108,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) => {
@@ -128,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,
@@ -149,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,
@@ -176,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,
@@ -240,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)
@@ -323,7 +323,7 @@ program
 });
 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")

package/dist/commands/analyze-depth.js

@@ -36,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

@@ -42,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/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

@@ -7,7 +7,7 @@ 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 ?? DEFAULT_SPECS_DIR);
     const layout = getOutputLayout(outputRoot);
@@ -19,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/init.js

@@ -146,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. -->",
@@ -182,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

@@ -39,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

@@ -242,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/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

@@ -7,6 +7,7 @@ const DEFAULT_CONFIG = {
         root: "",
         backendRoot: "",
         frontendRoot: "",
+        roots: [],
         discovery: {
             enabled: true
         },
@@ -137,6 +138,11 @@ function normalizeConfig(input, configDir) {
         project.root = resolveMaybe(project.root) ?? "";
         project.backendRoot = resolveMaybe(project.backendRoot) ?? "";
         project.frontendRoot = resolveMaybe(project.frontendRoot) ?? "";
+        if (Array.isArray(project.roots) && configDir) {
+            project.roots = project.roots
+                .filter((r) => typeof r === "string" && r.trim().length > 0)
+                .map(r => path.resolve(configDir, r));
+        }
         normalized.project = project;
     }
     if (input.python) {
@@ -271,6 +277,7 @@ function mergeConfig(base, override) {
             root: override.project?.root ?? base.project?.root ?? "",
             backendRoot: override.project?.backendRoot ?? base.project?.backendRoot ?? "",
             frontendRoot: override.project?.frontendRoot ?? base.project?.frontendRoot ?? "",
+            roots: mergeArrays(base.project?.roots, override.project?.roots),
             discovery: {
                 enabled: override.project?.discovery?.enabled ??
                     base.project?.discovery?.enabled ??

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

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { DEFAULT_SPECS_DIR } from "../config.js";
-const BACKEND_CACHE_VERSION = "specguard-backend-cache-v4";
+const BACKEND_CACHE_VERSION = "guardian-backend-cache-v4";
 export async function loadBackendExtractionCache(params) {
     const cachePath = path.join(params.projectRoot, DEFAULT_SPECS_DIR, ".cache", "file-hashes.json");
     const configHash = hashObject(params.config);

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,8 +28,20 @@ export async function buildSnapshots(options) {
     const reportedFrontendRoot = formatOutputPath(resolvedFrontendRoot);
     const reportedWorkspaceRoot = formatOutputPath(workspaceRoot);
     const config = resolvedProject.config;
-    const backend = await analyzeBackend(resolvedBackendRoot, config);
-    const frontend = await analyzeFrontend(resolvedFrontendRoot, config);
+    // Analyze all roots — run both analyzers on each root, then merge
+    const allRoots = resolvedProject.roots;
+    const backendResults = [];
+    const frontendResults = [];
+    for (const root of allRoots) {
+        const [be, fe] = await Promise.all([
+            analyzeBackend(root, config, workspaceRoot),
+            analyzeFrontend(root, config)
+        ]);
+        backendResults.push(be);
+        frontendResults.push(fe);
+    }
+    const backend = mergeBackendAnalyses(backendResults, allRoots, workspaceRoot);
+    const frontend = mergeFrontendAnalyses(frontendResults, allRoots, workspaceRoot);
     const projectRoot = workspaceRoot;
     const runtime = await analyzeRuntime(workspaceRoot, config);
     const projectName = deriveProjectName(resolvedBackendRoot);
@@ -82,6 +94,7 @@ export async function buildSnapshots(options) {
             workspace_root: reportedWorkspaceRoot,
             backend_root: reportedBackendRoot,
             frontend_root: reportedFrontendRoot,
+            roots: resolvedProject.roots.map(formatOutputPath),
             resolution_source: resolvedProject.resolutionSource,
             entrypoints: backend.entrypoints
         },
@@ -305,6 +318,97 @@ async function buildFunctionTestCoverage(params) {
         };
     });
 }
+function mergeBackendAnalyses(results, roots, workspaceRoot) {
+    if (results.length === 1)
+        return results[0];
+    // Prefix module IDs with root-relative path so they're globally unique
+    for (let i = 0; i < results.length; i++) {
+        const rootLabel = path.relative(workspaceRoot, roots[i]).replace(/\\/g, "/");
+        const idMap = new Map();
+        for (const mod of results[i].modules) {
+            const newId = `${rootLabel}/${mod.id}`;
+            idMap.set(mod.id, newId);
+            mod.id = newId;
+            mod.path = `${rootLabel}/${mod.path}`;
+        }
+        // Remap references in graph edges, endpoints, etc.
+        for (const edge of results[i].moduleGraph) {
+            edge.from = idMap.get(edge.from) ?? edge.from;
+            edge.to = idMap.get(edge.to) ?? edge.to;
+        }
+        for (const ep of results[i].endpoints) {
+            if (ep.module && idMap.has(ep.module)) {
+                ep.module = idMap.get(ep.module);
+            }
+        }
+        for (const cycle of results[i].circularDependencies) {
+            for (let j = 0; j < cycle.length; j++) {
+                cycle[j] = idMap.get(cycle[j]) ?? cycle[j];
+            }
+        }
+        results[i].orphanModules = results[i].orphanModules.map(m => idMap.get(m) ?? m);
+        const newUsage = {};
+        for (const [key, value] of Object.entries(results[i].moduleUsage)) {
+            newUsage[idMap.get(key) ?? key] = value;
+        }
+        results[i].moduleUsage = newUsage;
+    }
+    const moduleUsage = {};
+    for (const r of results) {
+        for (const [key, value] of Object.entries(r.moduleUsage)) {
+            moduleUsage[key] = (moduleUsage[key] ?? 0) + value;
+        }
+    }
+    // Merge testCoverage: combine arrays across all roots
+    const mergedCoverage = { ...results[0].testCoverage };
+    mergedCoverage.untested_source_files = [...mergedCoverage.untested_source_files];
+    mergedCoverage.test_files_missing_source = [...mergedCoverage.test_files_missing_source];
+    mergedCoverage.coverage_map = [...mergedCoverage.coverage_map];
+    for (let i = 1; i < results.length; i++) {
+        const tc = results[i].testCoverage;
+        mergedCoverage.untested_source_files.push(...tc.untested_source_files);
+        mergedCoverage.test_files_missing_source.push(...tc.test_files_missing_source);
+        mergedCoverage.coverage_map.push(...tc.coverage_map);
+    }
+    return {
+        modules: results.flatMap(r => r.modules),
+        moduleGraph: results.flatMap(r => r.moduleGraph),
+        fileGraph: results.flatMap(r => r.fileGraph),
+        endpoints: results.flatMap(r => r.endpoints),
+        dataModels: results.flatMap(r => r.dataModels),
+        enums: results.flatMap(r => r.enums),
+        constants: results.flatMap(r => r.constants),
+        endpointModelUsage: results.flatMap(r => r.endpointModelUsage),
+        tasks: results.flatMap(r => r.tasks),
+        circularDependencies: results.flatMap(r => r.circularDependencies),
+        orphanModules: results.flatMap(r => r.orphanModules),
+        orphanFiles: results.flatMap(r => r.orphanFiles),
+        moduleUsage,
+        unusedExports: results.flatMap(r => r.unusedExports),
+        unusedEndpoints: results.flatMap(r => r.unusedEndpoints),
+        entrypoints: results.flatMap(r => r.entrypoints),
+        duplicateFunctions: results.flatMap(r => r.duplicateFunctions),
+        similarFunctions: results.flatMap(r => r.similarFunctions),
+        testCoverage: mergedCoverage,
+        tests: results.flatMap(r => r.tests)
+    };
+}
+function mergeFrontendAnalyses(results, _roots, _workspaceRoot) {
+    if (results.length === 1)
+        return results[0];
+    return {
+        files: results.flatMap(r => r.files),
+        pages: results.flatMap(r => r.pages),
+        apiCalls: results.flatMap(r => r.apiCalls),
+        uxPages: results.flatMap(r => r.uxPages),
+        components: results.flatMap(r => r.components),
+        componentGraph: results.flatMap(r => r.componentGraph),
+        fileGraph: results.flatMap(r => r.fileGraph),
+        orphanFiles: results.flatMap(r => r.orphanFiles),
+        unusedExports: results.flatMap(r => r.unusedExports),
+        tests: results.flatMap(r => r.tests)
+    };
+}
 function findCommonRoot(paths) {
     if (paths.length === 0) {
         return process.cwd();

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/project-discovery.js

@@ -53,16 +53,22 @@ export async function resolveProjectPaths(options) {
         (await chooseBackendRoot(workspaceRoot));
     const frontendRoot = explicitFrontend ??
         (await chooseFrontendRoot(workspaceRoot));
+    // Build unified roots list: backendRoot + frontendRoot + any extra from config
+    const configRoots = (config.project?.roots ?? []).map(r => path.resolve(r));
+    const allRoots = [...new Set([backendRoot, frontendRoot, ...configRoots].filter(Boolean))];
     return {
         workspaceRoot,
         backendRoot,
         frontendRoot,
+        roots: allRoots,
         resolutionSource,
         config
     };
 }
 export function logResolvedProjectPaths(resolved) {
-    console.log(`SpecGuard roots (${resolved.resolutionSource}): workspace=${resolved.workspaceRoot} backend=${resolved.backendRoot} frontend=${resolved.frontendRoot}`);
+    const extra = resolved.roots.filter(r => r !== resolved.backendRoot && r !== resolved.frontendRoot);
+    const extraMsg = extra.length > 0 ? ` +${extra.length} roots` : "";
+    console.log(`Guardian roots (${resolved.resolutionSource}): workspace=${resolved.workspaceRoot} backend=${resolved.backendRoot} frontend=${resolved.frontendRoot}${extraMsg}`);
 }
 async function chooseBackendRoot(workspaceRoot) {
     const candidates = await discoverBackendCandidates(workspaceRoot);

package/package.json

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