@toolbaux/guardian 0.1.1 → 0.1.3

package/README.md

@@ -1,223 +1,195 @@
 # Guardian
 
-Architectural intelligence for codebases. One command turns your repo into compact, machine-readable context that AI coding tools can reason about without hallucinating.
+[![npm version](https://img.shields.io/npm/v/@toolbaux/guardian.svg)](https://www.npmjs.com/package/@toolbaux/guardian)
+[![license](https://img.shields.io/npm/l/@toolbaux/guardian.svg)](./LICENSE)
 
-## Quick Start
+Architectural intelligence for codebases. One command turns your repo into compact, machine-readable context that AI coding tools can reason about without hallucinating.
 
 ```bash
-# Initialize a project (creates .specs/, config, pre-commit hook, CLAUDE.md context)
+npm install -g @toolbaux/guardian
 guardian init
+```
 
-# Or run extraction manually
-guardian extract
-guardian generate --ai-context
+## The Problem
+
+AI coding tools hallucinate when they don't understand your architecture. They guess at imports, invent schemas that don't exist, and edit high-coupling files without understanding the blast radius.
+
+**Without Guardian** — Cursor generates this:
+
+```python
+from app.schemas import UpdateCaseRequest  # ← doesn't exist
+from app.models import User               # ← it's actually UserProfile
+from shared.utils import validate          # ← wrong module, it's in shared.policy
+```
+
+**With Guardian** — the AI reads your architecture context and generates:
+
+```python
+from shared.policy.persona import ChildProfile        # ✓ exact import path
+from service_conversation.engine import ConversationEngine  # ✓ correct module
+from shared.content.retriever import ContentRetriever  # ✓ verified by AST
+```
+
+Guardian extracts exact boundaries, coupling hotspots, model-to-endpoint relationships, page routes, and data flows from your source code using Tree-Sitter AST parsing. No LLM involved in extraction — deterministic, reproducible, fast.
+
+## How It Works
+
+```
+Developer writes code
+    ↓ (save)
+VSCode extension (5s debounce)
+    ↓
+guardian extract → .specs/
+guardian generate --ai-context → .specs/
+guardian context → CLAUDE.md (between markers)
+Status bar: "✓ Guardian: stable · 35 ep · 8 pg"
+    ↓ (git commit)
+Pre-commit hook: extract + context → auto-staged
+    ↓
+Claude Code / Cursor reads CLAUDE.md → fresh architecture context
 ```
 
 After `guardian init`, your project gets:
 - `.specs/` directory with architecture snapshots
-- `CLAUDE.md` with auto-injected architecture context (between `<!-- guardian:auto-context -->` markers)
-- Pre-commit hook that keeps context fresh on every commit
+- `CLAUDE.md` with auto-injected context (refreshed on every save and commit)
+- Pre-commit hook that keeps context fresh automatically
 - `guardian.config.json` with auto-detected backend/frontend roots
 
-## What Guardian Solves
-
-**Without Guardian:** AI invents fake schemas, imports wrong components, edits high-coupling files blindly, guesses at endpoint paths.
+## Claude Code / Cursor Integration
 
-**With Guardian:** AI gets a deterministic map of your repo — exact boundaries, coupling hotspots, model-to-endpoint relationships, page routes, and data flows — in ~3,000 tokens.
+Guardian auto-injects architecture context into `CLAUDE.md` so your AI tool reads it at session start:
 
-## Installation
+```markdown
+# my-project
 
-```bash
-# From source
-git clone <repo>
-cd guardian
-npm install && npm run build
-npm link   # makes `guardian` available globally
+<!-- guardian:auto-context -->
+## Codebase Map
+**Backend:** 16 schemas · 35 endpoints · 9 modules
+**Frontend:** 10 components · 8 pages
 
-# Or install from npm
-npm install -g @toolbaux/guardian
+### High-Coupling Files
+- shared/policy/__init__.py (score 1.00)
+- service-conversation/engine.py (score 0.40)
 
-# Initialize a project
-cd /path/to/your/project
-guardian init
+### Key Model → Endpoint Map
+- ChildProfile (1 endpoints) → POST /sessions/start
+- StartSessionResponse (1 endpoints) → POST /sessions/start
+<!-- /guardian:auto-context -->
 ```
 
-### VSCode Extension
+The block between markers is replaced on every save (VSCode extension) and every commit (pre-commit hook). Your manual content outside the markers is never touched.
 
-The extension adds a status bar indicator, background auto-extract on save, and command palette integration.
+## Key Commands
 
-**Install via symlink (development):**
 ```bash
-ln -sf /path/to/guardian/vscode-extension ~/.vscode/extensions/guardian-vscode
-# Reload VSCode: Cmd+Shift+P → "Reload Window"
-```
+# One-time setup — creates config, .specs/, pre-commit hook, CLAUDE.md
+guardian init
 
-**Install via .vsix (packaged):**
-```bash
-cd guardian/vscode-extension
-npx vsce package --allow-missing-repository
-# In VSCode: Cmd+Shift+P → "Extensions: Install from VSIX" → select the .vsix file
+# Extract architecture (run after major changes, or let the hook do it)
+guardian extract
+
+# Search your codebase by concept
+guardian search --query "session"
+
+# Compute architectural drift
+guardian drift
+
+# Generate HTML docs (open in browser, no server needed)
+guardian doc-html
 ```
 
-**What the extension provides:**
-- Status bar: `✓ Guardian: stable · 35 ep · 8 pg` — click to run drift check
-- Background extract on file save (5s debounce, code files only)
-- Auto-injects fresh context into CLAUDE.md on each save
-- Command palette: 8 commands (see below)
+## Framework Support
+
+**Frontend:** Expo Router, Next.js, React Router — auto-detected from `package.json`
+**Backend:** FastAPI, Django, Express, Spring Boot, Gin, ASP.NET Core
 
-**Extension settings:**
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `guardian.autoExtract` | `true` | Auto-run extract + context on file save |
-| `guardian.runOnSave` | `false` | Also run drift check on save (heavier) |
-| `guardian.backendRoot` | `"backend"` | Backend root relative to workspace |
-| `guardian.frontendRoot` | `"frontend"` | Frontend root relative to workspace |
-| `guardian.configPath` | `""` | Path to guardian.config.json |
-| `guardian.debounceMs` | `750` | Debounce for drift-on-save |
+All extraction uses Tree-Sitter AST parsing — deterministic, no LLM involved.
 
-## All Commands (18)
+## What Guardian Generates
 
-### Project Setup
+**Workflow sequence diagrams** — Mermaid diagrams for your most complex endpoints, showing the full call chain from client through handler to services and data stores.
+
+**System architecture diagram** — Full system view: frontend → backend services → data stores → external APIs, with actual endpoint paths per service.
+
+**Model role badges** — Each data model gets an inferred role: API Request, API Response, Configuration, Safety Policy, Entity Profile, Content Entity.
+
+**Subsystem diagrams with real names** — Backend modules show `ConversationEngine`, `ContentRetriever`, `SessionStateMachine` instead of generic file counts.
+
+---
+
+## Full Reference
+
+<details>
+<summary><strong>Installation</strong></summary>
 
 ```bash
-# Initialize project: config, .specs dir, pre-commit hook, CLAUDE.md
-guardian init
+# Install from npm
+npm install -g @toolbaux/guardian
 
-# Full extraction: architecture + UX snapshots + codebase intelligence + docs
-guardian extract
+# Or from source
+git clone https://github.com/idocoding/guardian
+cd guardian
+npm install && npm run build && npm link
+```
+
+</details>
 
-# AI context file only (compact ~3K token summary)
-guardian generate --ai-context
+<details>
+<summary><strong>All Commands (18)</strong></summary>
+
+### Project Setup
 
-# Build codebase-intelligence.json from existing snapshots
-guardian intel
+```bash
+guardian init                          # config, .specs dir, pre-commit hook, CLAUDE.md
+guardian extract                       # full architecture + UX snapshots + docs
+guardian generate --ai-context         # compact ~3K token AI context only
+guardian intel                         # build codebase-intelligence.json
 ```
 
 ### Search & Context
 
 ```bash
-# Search all artifacts by keyword (models, endpoints, components, modules, tasks)
-guardian search --query "session"
+guardian search --query "session"                  # search models, endpoints, components
 guardian search --query "auth" --types models,endpoints
-
-# Render focused AI context block (stdout or append to file)
-guardian context --focus "auth"
-guardian context --output CLAUDE.md          # injects between auto-context markers
-guardian context --focus "session" --output CLAUDE.md
-
-# Executive summary from existing snapshots
-guardian summary
+guardian context --focus "auth"                     # focused AI context block
+guardian context --output CLAUDE.md                 # inject between auto-context markers
+guardian summary                                   # executive summary
 ```
 
 ### Architectural Metrics
 
 ```bash
-# Compute drift metrics (D_t, K_t, delta, entropy, cycles)
-guardian drift
+guardian drift                         # compute D_t, K_t, delta, entropy, cycles
 guardian drift --baseline              # save baseline for future comparison
-
-# Verify drift stays within threshold (for CI gates)
-guardian verify-drift --baseline specs-out/machine/drift.baseline.json
-
-# Generate constraints JSON (duplicates, cycles, similar endpoints)
-guardian constraints
-
-# Structural complexity analysis for a feature area
-guardian analyze-depth --query "session"
-guardian analyze-depth --query "payment" --ci  # exit 1 on HIGH complexity
-
-# Diff between two snapshots
+guardian verify-drift --baseline drift.baseline.json  # CI gate
+guardian constraints                   # duplicates, cycles, similar endpoints
+guardian analyze-depth --query "session"            # structural complexity
+guardian analyze-depth --query "payment" --ci       # exit 1 on HIGH complexity
 guardian diff --baseline old.yaml --current new.yaml
 ```
 
 ### Documentation
 
 ```bash
-# LLM-powered product document (uses Ollama or Anthropic)
-guardian doc-generate
-guardian doc-generate --update-baseline    # freeze for discrepancy tracking
-
-# HTML Javadoc-style viewer (no server needed, open in browser)
-guardian doc-html
-
-# Discrepancy report: code vs baseline (JSON + Markdown)
-guardian discrepancy
+guardian doc-generate                  # LLM-powered product document
+guardian doc-generate --update-baseline
+guardian doc-html                      # HTML viewer (open in browser)
+guardian discrepancy                   # code vs baseline drift report
 ```
 
 ### Simulation & LLM Guardrails
 
 ```bash
-# Simulate drift impact of a patch before merging
 guardian simulate --patch changes.patch
-
-# LLM-guided code generation with drift guardrails
 guardian guard --task "add payment endpoint"
-guardian guard --task "refactor auth" --print-context  # print without calling LLM
-
-# Generate filtered context packet for implementing a single feature
+guardian guard --task "refactor auth" --print-context
 guardian feature-context --spec feature-specs/billing.yaml
 ```
 
-### VSCode Commands (Command Palette)
+</details>
 
-| Command | Description |
-|---------|-------------|
-| `Guardian: Initialize Project` | Run `guardian init` on workspace |
-| `Guardian: Generate AI Context` | Generate architecture-context.md |
-| `Guardian: Drift Check` | Compute drift metrics |
-| `Guardian: Generate Constraints` | Find duplicates, cycles, similar endpoints |
-| `Guardian: Copy Constraints Prompt` | Copy LLM guardrail prompt to clipboard |
-| `Guardian: Simulate Drift` | Simulate drift without a patch |
-| `Guardian: Guard Patch (Simulate)` | Pick a .patch file and simulate its impact |
-| `Guardian: Guarded Run` | Constraints + simulation in one step |
-
-## Output Structure
-
-```
-.specs/                              (or specs-out/)
-├── machine/
-│   ├── architecture-context.md      ← AI context (~3K tokens, injected into CLAUDE.md)
-│   ├── architecture.snapshot.yaml   ← full architecture snapshot
-│   ├── ux.snapshot.yaml             ← frontend components + pages
-│   ├── codebase-intelligence.json   ← unified registry for all downstream commands
-│   ├── structural-intelligence.json ← per-module complexity analysis
-│   ├── drift.heatmap.json           ← coupling scores per module
-│   ├── drift.report.json            ← drift metrics
-│   ├── constraints.json             ← duplicates, cycles, similar endpoints
-│   ├── discrepancies.json           ← code vs baseline diff
-│   └── docs/                        ← generated markdown docs
-│       ├── summary.md               ← product overview with quality signals
-│       ├── hld.md                   ← system diagrams, coupling heatmap, subsystems
-│       ├── integration.md           ← all API endpoints grouped by domain
-│       ├── data.md                  ← data models and schemas
-│       ├── ux.md                    ← pages, components, interaction maps
-│       ├── diff.md                  ← changelog between snapshots
-│       ├── runtime.md               ← Docker services, background tasks
-│       ├── infra.md                 ← manifests, scripts, Makefiles
-│       ├── tests.md                 ← behavioral test specs
-│       ├── stakeholder.md           ← one-page executive view
-│       └── index.md                 ← table of contents
-├── human/
-│   ├── product-document.md          ← LLM-powered comprehensive product doc
-│   ├── discrepancies.md             ← human-readable drift report
-│   ├── start-here.md                ← onboarding guide
-│   ├── system-overview.md           ← boundaries, risk zones
-│   ├── backend-overview.md          ← modules by layer
-│   ├── frontend-overview.md         ← page/component inventory
-│   ├── data-and-flows.md            ← models and cross-stack contracts
-│   ├── change-guide.md              ← what changed, what's risky
-│   └── docs/                        ← HTML viewer (open index.html in browser)
-│       ├── index.html               ← overview with product context from README
-│       ├── architecture.html        ← system diagram, workflow sequences, coupling
-│       ├── api-surface.html         ← all endpoints by domain
-│       ├── data-models.html         ← models with role badges
-│       ├── quality.html             ← patterns, duplicates, orphans
-│       ├── frontend.html            ← pages with component trees
-│       ├── tasks.html               ← background tasks
-│       └── discrepancies.html       ← code vs spec drift
-```
-
-## Configuration
+<details>
+<summary><strong>Configuration</strong></summary>
 
 `guardian.config.json` at project root (auto-created by `guardian init`):
 
@@ -240,83 +212,39 @@ guardian feature-context --spec feature-specs/billing.yaml
       "core": ["shared"],
       "top": ["service-conversation"],
       "isolated": ["service-auth", "service-content"]
-    },
-    "domains": {
-      "session": ["service-conversation", "shared"],
-      "auth": ["service-auth"]
     }
   },
   "llm": {
     "command": "ollama",
     "args": ["run", "llama3"]
-  },
-  "docs": {
-    "mode": "full"
-  },
-  "ignore": {
-    "directories": ["venv", "node_modules", "__pycache__"],
-    "paths": ["backend/alembic/versions"]
   }
 }
 ```
 
-## Claude Code Integration
-
-Guardian auto-injects architecture context into `CLAUDE.md` so Claude Code reads it at session start:
-
-```markdown
-# my-project
-
-## Guardian Architecture Context
+</details>
 
-<!-- guardian:auto-context -->
-## Codebase Map
-**Backend:** 16 schemas · 35 endpoints · 9 modules
-**Frontend:** 10 components · 8 pages
+<details>
+<summary><strong>Output Structure</strong></summary>
 
-### High-Coupling Files
-- shared/policy/__init__.py (score 1.00)
-- service-conversation/engine.py (score 0.40)
-...
-<!-- /guardian:auto-context -->
+```
+.specs/
+├── machine/
+│   ├── architecture-context.md      ← AI context (~3K tokens)
+│   ├── architecture.snapshot.yaml   ← full architecture snapshot
+│   ├── ux.snapshot.yaml             ← frontend components + pages
+│   ├── codebase-intelligence.json   ← unified registry
+│   ├── drift.report.json            ← drift metrics
+│   ├── constraints.json             ← duplicates, cycles
+│   └── docs/                        ← generated markdown docs
+├── human/
+│   ├── product-document.md          ← LLM-powered product doc
+│   └── docs/                        ← HTML viewer (open index.html)
 ```
 
-The block between `<!-- guardian:auto-context -->` markers is replaced on every save (via VSCode extension) and every commit (via pre-commit hook). Your manual content in CLAUDE.md outside the markers is never touched.
-
-## Key Architectural Outputs
-
-### Workflow Sequence Diagrams
-Auto-generated Mermaid sequence diagrams for your most complex endpoints, showing the full call chain from client through handler to services and data stores.
-
-### System Architecture Diagram
-Full system view: frontend → backend services → data stores → external APIs, with actual endpoint paths shown per service.
-
-### Service Communication Map
-Cross-service dependency flowchart showing which modules import from which, proxy patterns, and external API calls.
-
-### Model Role Badges
-Each data model gets an inferred role badge: API Request, API Response, Configuration, Safety Policy, Entity Profile, Content Entity, etc.
-
-### Subsystem Diagrams with Entity Names
-Backend module diagrams show actual class names (e.g., `ConversationEngine`, `ContentRetriever`, `SessionStateMachine`) instead of generic file counts.
-
-## Framework Support
-
-### Frontend Frameworks
-- **Expo Router** — auto-detected from `package.json`. Every `.tsx` in `app/` is a page (except `_layout`, `_error`). Route derived from filename.
-- **Next.js** — `page.tsx` convention in `app/` directory.
-- **React Router** — route definitions parsed from JSX `<Route>` elements and `createBrowserRouter()`.
-
-### Backend Frameworks
-- **Python**: FastAPI, Django, Pydantic, SQLAlchemy
-- **TypeScript/JavaScript**: Express, React, Next.js
-- **Java**: Spring Boot (`@RestController`, JPA)
-- **Go**: Gin routing, struct models
-- **C#**: ASP.NET Core HTTP endpoints, POCO schemas
-
-All extraction uses Tree-Sitter AST parsing — deterministic, no LLM involved.
+</details>
 
-## Key Metrics
+<details>
+<summary><strong>Key Metrics</strong></summary>
 
 | Metric | Meaning |
 |--------|---------|
@@ -324,26 +252,12 @@ All extraction uses Tree-Sitter AST parsing — deterministic, no LLM involved.
 | **K_t** | Architectural complexity |
 | **Delta** | Overall drift score |
 | **Coupling score** | Per-module dependency pressure (0-1) |
-| **Shape fingerprint** | Change = structural refactor. Same shape + different fingerprint = additive change |
+| **Shape fingerprint** | Change = structural refactor |
 
-## Automation Flow
+</details>
 
-```
-Developer writes code
-    ↓ (save)
-VSCode extension (5s debounce)
-    ↓
-guardian extract → .specs/
-guardian generate --ai-context → .specs/
-guardian context → CLAUDE.md (between markers)
-Status bar: "✓ Guardian: stable · 35 ep · 8 pg"
-    ↓ (git commit)
-Pre-commit hook: extract + context → auto-staged
-    ↓
-Claude Code reads CLAUDE.md → fresh architecture context
-```
-
-## GitHub Action
+<details>
+<summary><strong>GitHub Action</strong></summary>
 
 ```yaml
 - name: Install Guardian
@@ -358,13 +272,21 @@ Claude Code reads CLAUDE.md → fresh architecture context
 
 See [`.github/workflows/guardian.yml`](./.github/workflows/guardian.yml).
 
-## Development
+</details>
+
+<details>
+<summary><strong>Development</strong></summary>
 
 ```bash
 npm install
 npm run dev -- extract .          # run from source
 npm run build                     # compile to dist/
-npm run start -- extract .        # run compiled
 npm run typecheck                 # type check only
 npm test                          # run tests
 ```
+
+</details>
+
+---
+
+Built by [ToolBaux](https://github.com/idocoding). If Guardian helps you ship with confidence, [star the repo](https://github.com/idocoding/guardian).

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")
@@ -30,7 +31,7 @@ program
     .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("--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,7 +53,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("--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("--docs-mode <mode>", "Docs mode (lean|full)")
@@ -61,7 +62,7 @@ program
         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
@@ -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
@@ -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,11 +313,11 @@ 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,
     });
 });
@@ -326,7 +327,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("--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
     });

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),

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/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.");
     }
-    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,

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 });

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);

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

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/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/cache.js

@@ -1,9 +1,10 @@
 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";
 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/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"

package/package.json

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