paqad-ai 0.0.1 → 0.0.4

package/dist/cli/index.js

@@ -5,7 +5,7 @@ import { realpathSync } from "fs";
 import { pathToFileURL } from "url";
 
 // src/cli/program.ts
-import { Command as Command6 } from "commander";
+import { Command as Command7 } from "commander";
 
 // src/adapters/shared/base-adapter.ts
 import { readFile as readFile2 } from "fs/promises";
@@ -367,6 +367,8 @@ var AdapterFactory = class {
 // src/core/constants/paths.ts
 var PATHS = {
   AGENCY_DIR: ".agency",
+  AGENCY_CACHE_DIR: ".agency/cache",
+  AGENCY_SESSION_DIR: ".agency/session",
   PROJECT_PROFILE: ".agency/project-profile.yaml",
   DETECTION_REPORT: ".agency/detection-report.json",
   ONBOARDING_MANIFEST: ".agency/onboarding-manifest.json",
@@ -377,11 +379,16 @@ var PATHS = {
   CHANGED_FILES: ".agency/session/changed-files.json",
   CONTEXT_HIT_LOG: ".agency/session/context-hit-log.json",
   SKILL_CACHE_DIR: ".agency/cache/skill-results",
+  STACK_SNAPSHOT: ".agency/cache/stack-snapshot.json",
+  DOC_PROGRESS: ".agency/doc-progress.json",
+  DOC_RUN_SESSION: ".agency/session/doc-run.json",
   INDEXES_DIR: ".agency/indexes",
   DOCS_DIR: "docs",
   RULES_DIR: "docs/rules",
-  ARCHITECTURE_DIR: "docs/architecture",
-  DESIGN_SYSTEM_DIR: "docs/design-system",
+  INSTRUCTIONS_DIR: "docs/instructions",
+  ARCHITECTURE_DIR: "docs/instructions/architecture",
+  DESIGN_SYSTEM_DIR: "docs/instructions/design-system",
+  DESIGN_TOKENS_FILE: "docs/instructions/architecture/design-tokens.json",
   MODULES_DIR: "docs/modules",
   BENCHMARKS_DIR: "docs/benchmarks",
   TECH_DEBT_DIR: "docs/tech-debt",
@@ -618,12 +625,119 @@ var Detector = class {
   }
 };
 
-// src/health/checker.ts
-import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync4, statSync } from "fs";
-import { access } from "fs/promises";
-import { constants as fsConstants } from "fs";
-import { join as join6 } from "path";
-import YAML from "yaml";
+// src/design-tokens/defaults.ts
+var DEFAULT_DESIGN_TOKENS = {
+  color: {
+    primary: { $value: "#0F766E", $type: "color", $description: "Primary brand color." },
+    secondary: { $value: "#0F172A", $type: "color", $description: "Secondary brand color." },
+    accent: { $value: "#F59E0B", $type: "color", $description: "Accent color." },
+    surface: { $value: "#FFFFFF", $type: "color", $description: "Default surface color." },
+    text: {
+      default: { $value: "#0F172A", $type: "color", $description: "Default text color." },
+      muted: { $value: "#475569", $type: "color", $description: "Muted text color." }
+    },
+    semantic: {
+      success: { $value: "#16A34A", $type: "color" },
+      warning: { $value: "#EAB308", $type: "color" },
+      error: { $value: "#DC2626", $type: "color" },
+      info: { $value: "#2563EB", $type: "color" }
+    }
+  },
+  typography: {
+    fontFamily: {
+      body: { $value: "Inter, system-ui, sans-serif", $type: "fontFamily" },
+      display: { $value: "Satoshi, system-ui, sans-serif", $type: "fontFamily" },
+      mono: { $value: "JetBrains Mono, monospace", $type: "fontFamily" }
+    },
+    heading: {
+      h1: {
+        $value: {
+          fontFamily: "{typography.fontFamily.display.$value}",
+          fontSize: "3rem",
+          fontWeight: 700,
+          lineHeight: 1.1
+        },
+        $type: "typography"
+      },
+      h2: {
+        $value: {
+          fontFamily: "{typography.fontFamily.display.$value}",
+          fontSize: "2.25rem",
+          fontWeight: 600,
+          lineHeight: 1.2
+        },
+        $type: "typography"
+      },
+      body: {
+        $value: {
+          fontFamily: "{typography.fontFamily.body.$value}",
+          fontSize: "1rem",
+          fontWeight: 400,
+          lineHeight: 1.5
+        },
+        $type: "typography"
+      }
+    }
+  },
+  spacing: {
+    xs: { $value: "0.25rem", $type: "dimension" },
+    sm: { $value: "0.5rem", $type: "dimension" },
+    md: { $value: "1rem", $type: "dimension" },
+    lg: { $value: "1.5rem", $type: "dimension" },
+    xl: { $value: "2rem", $type: "dimension" }
+  },
+  radius: {
+    sm: { $value: "0.25rem", $type: "dimension" },
+    md: { $value: "0.5rem", $type: "dimension" },
+    lg: { $value: "1rem", $type: "dimension" },
+    full: { $value: "9999px", $type: "dimension" }
+  },
+  shadow: {
+    sm: {
+      $value: { color: "#0000001a", offsetX: "0px", offsetY: "1px", blur: "2px", spread: "0px" },
+      $type: "shadow"
+    },
+    md: {
+      $value: {
+        color: "#0000001a",
+        offsetX: "0px",
+        offsetY: "4px",
+        blur: "6px",
+        spread: "-1px"
+      },
+      $type: "shadow"
+    }
+  },
+  motion: {
+    duration: {
+      fast: { $value: "150ms", $type: "duration" },
+      normal: { $value: "300ms", $type: "duration" }
+    },
+    easing: {
+      emphasis: { $value: [0.2, 0, 0, 1], $type: "cubicBezier" }
+    }
+  },
+  components: {
+    button: {
+      radius: { $value: "{radius.md.$value}", $type: "dimension" },
+      paddingX: { $value: "{spacing.md.$value}", $type: "dimension" },
+      paddingY: { $value: "{spacing.sm.$value}", $type: "dimension" }
+    },
+    card: {
+      radius: { $value: "{radius.lg.$value}", $type: "dimension" },
+      shadow: { $value: "{shadow.md.$value}", $type: "shadow" }
+    }
+  },
+  accessibility: {
+    contrast: { $value: "WCAG 2.1 AA", $type: "string" },
+    focusRing: { $value: "2px solid {color.accent.$value}", $type: "string" },
+    reduceMotion: { $value: true, $type: "boolean" }
+  }
+};
+
+// src/design-tokens/service.ts
+import { mkdir, readFile as readFile3, writeFile } from "fs/promises";
+import { dirname as dirname2, join as join6 } from "path";
 
 // src/validators/validator.ts
 import Ajv from "ajv";
@@ -766,6 +880,117 @@ var detection_report_schema_default = {
   }
 };
 
+// src/validators/schemas/design-tokens.schema.json
+var design_tokens_schema_default = {
+  $id: "design-tokens",
+  type: "object",
+  additionalProperties: {
+    $ref: "#/$defs/node"
+  },
+  $defs: {
+    leaf: {
+      type: "object",
+      required: ["$value", "$type"],
+      properties: {
+        $value: {},
+        $type: { type: "string" },
+        $description: { type: "string" }
+      },
+      additionalProperties: true
+    },
+    group: {
+      type: "object",
+      minProperties: 1,
+      additionalProperties: {
+        $ref: "#/$defs/node"
+      }
+    },
+    node: {
+      anyOf: [{ $ref: "#/$defs/leaf" }, { $ref: "#/$defs/group" }]
+    }
+  }
+};
+
+// src/validators/schemas/doc-progress.schema.json
+var doc_progress_schema_default = {
+  $id: "doc-progress",
+  type: "object",
+  required: ["schema_version", "generated_by", "framework_version", "modules", "global"],
+  properties: {
+    schema_version: { const: "1" },
+    generated_by: { const: "paqad-ai" },
+    framework_version: { type: "string" },
+    modules: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: { $ref: "#/$defs/entry" }
+      }
+    },
+    global: {
+      type: "object",
+      additionalProperties: {
+        type: "object",
+        additionalProperties: { $ref: "#/$defs/entry" }
+      }
+    }
+  },
+  $defs: {
+    state: {
+      enum: ["not_started", "generating", "done", "failed"]
+    },
+    entry: {
+      type: "object",
+      required: [
+        "output_path",
+        "state",
+        "started_at",
+        "completed_at",
+        "source_files",
+        "source_hash",
+        "tokens_used",
+        "error"
+      ],
+      properties: {
+        output_path: { type: "string" },
+        state: { $ref: "#/$defs/state" },
+        started_at: { type: ["string", "null"] },
+        completed_at: { type: ["string", "null"] },
+        source_files: {
+          type: "array",
+          items: { type: "string" }
+        },
+        source_hash: { type: ["string", "null"] },
+        tokens_used: { type: ["number", "null"] },
+        error: { type: ["string", "null"] },
+        design_tokens: {
+          type: "object",
+          required: [
+            "extraction_state",
+            "total_tokens_found",
+            "placeholder_count",
+            "populated_count",
+            "placeholder_keys"
+          ],
+          properties: {
+            extraction_state: { $ref: "#/$defs/state" },
+            total_tokens_found: { type: "number" },
+            placeholder_count: { type: "number" },
+            populated_count: { type: "number" },
+            placeholder_keys: {
+              type: "array",
+              items: { type: "string" }
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  additionalProperties: false
+};
+
 // src/validators/schemas/error-catalog.schema.json
 var error_catalog_schema_default = {
   $id: "error-catalog",
@@ -1137,6 +1362,8 @@ var skill_frontmatter_schema_default = {
 var SCHEMAS = [
   project_profile_schema_default,
   detection_report_schema_default,
+  design_tokens_schema_default,
+  doc_progress_schema_default,
   onboarding_manifest_schema_default,
   handoff_artifact_schema_default,
   adversarial_review_report_schema_default,
@@ -1182,7 +1409,214 @@ var SchemaValidator = class {
   }
 };
 
+// src/design-tokens/service.ts
+var DesignTokenService = class {
+  constructor(validator = new SchemaValidator()) {
+    this.validator = validator;
+  }
+  async seed(projectRoot) {
+    const target = join6(projectRoot, PATHS.DESIGN_TOKENS_FILE);
+    await mkdir(dirname2(target), { recursive: true });
+    await writeFile(target, `${JSON.stringify(DEFAULT_DESIGN_TOKENS, null, 2)}
+`, {
+      flag: "wx"
+    }).catch((error) => {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+    });
+  }
+  async load(projectRoot) {
+    const target = join6(projectRoot, PATHS.DESIGN_TOKENS_FILE);
+    const raw = await readFile3(target, "utf8");
+    const parsed = JSON.parse(raw);
+    const validation = this.validator.validate("design-tokens", parsed);
+    if (!validation.valid) {
+      throw new Error(
+        `Invalid design token file: ${validation.errors.map((error) => error.message).join("; ")}`
+      );
+    }
+    return parsed;
+  }
+  async generateDocs(projectRoot) {
+    const tokens = await this.load(projectRoot);
+    const flattened = flattenTokens(tokens);
+    const sections = groupTokens(flattened);
+    return [
+      {
+        path: join6(PATHS.DESIGN_SYSTEM_DIR, "tokens.md"),
+        content: buildTokensMarkdown(flattened)
+      },
+      {
+        path: join6(PATHS.DESIGN_SYSTEM_DIR, "components.md"),
+        content: buildSectionMarkdown("Component Defaults", sections.components)
+      },
+      {
+        path: join6(PATHS.DESIGN_SYSTEM_DIR, "motion.md"),
+        content: buildSectionMarkdown("Motion", sections.motion)
+      },
+      {
+        path: join6(PATHS.DESIGN_SYSTEM_DIR, "accessibility.md"),
+        content: buildSectionMarkdown("Accessibility", sections.accessibility)
+      },
+      {
+        path: join6(PATHS.DESIGN_SYSTEM_DIR, "responsive.md"),
+        content: buildResponsiveMarkdown(sections.spacing)
+      },
+      {
+        path: join6(PATHS.DESIGN_SYSTEM_DIR, "patterns.md"),
+        content: buildPatternsMarkdown(flattened)
+      }
+    ];
+  }
+  async writeDocs(projectRoot) {
+    const docs = await this.generateDocs(projectRoot);
+    await Promise.all(
+      docs.map(async (artifact) => {
+        const target = join6(projectRoot, artifact.path);
+        await mkdir(dirname2(target), { recursive: true });
+        await writeFile(target, artifact.content);
+      })
+    );
+    return docs.map((artifact) => artifact.path);
+  }
+  async exportTheme(projectRoot, stack) {
+    const flattened = flattenTokens(await this.load(projectRoot));
+    const cssVariables = flattened.map((token) => `  --${token.key.replace(/\./g, "-")}: ${stringifyValue(token.value)};`).join("\n");
+    const tailwindEntries = flattened.map((token) => `    '${token.key.replace(/\./g, "-")}' : '${stringifyValue(token.value)}',`).join("\n");
+    const flutterEntries = flattened.filter((token) => token.type === "color").map(
+      (token) => `  static const String ${toIdentifier(token.key)} = '${stringifyValue(token.value)}';`
+    ).join("\n");
+    const artifacts = [
+      {
+        path: ".agency/theme/theme.css",
+        content: `:root {
+${cssVariables}
+}
+`
+      },
+      {
+        path: ".agency/theme/tailwind.theme.cjs",
+        content: `module.exports = {
+  theme: {
+    extend: {
+      colors: {
+${tailwindEntries}
+      },
+    },
+  },
+};
+`
+      }
+    ];
+    if (stack === "flutter") {
+      artifacts.push({
+        path: ".agency/theme/theme_tokens.dart",
+        content: `class ThemeTokens {
+${flutterEntries}
+}
+`
+      });
+    }
+    return artifacts;
+  }
+  async writeThemeExports(projectRoot, stack) {
+    const artifacts = await this.exportTheme(projectRoot, stack);
+    await Promise.all(
+      artifacts.map(async (artifact) => {
+        const target = join6(projectRoot, artifact.path);
+        await mkdir(dirname2(target), { recursive: true });
+        await writeFile(target, artifact.content);
+      })
+    );
+    return artifacts.map((artifact) => artifact.path);
+  }
+};
+function flattenTokens(node, pathSegments = [], tokens = []) {
+  for (const [key, value] of Object.entries(node)) {
+    const nextPath = [...pathSegments, key];
+    if (isTokenLeaf(value)) {
+      tokens.push({
+        key: nextPath.join("."),
+        type: value.$type,
+        value: value.$value,
+        description: value.$description
+      });
+      continue;
+    }
+    flattenTokens(value, nextPath, tokens);
+  }
+  return tokens.sort((left, right) => left.key.localeCompare(right.key));
+}
+function isTokenLeaf(value) {
+  return typeof value === "object" && value !== null && "$value" in value && "$type" in value && typeof value.$type === "string";
+}
+function groupTokens(tokens) {
+  return {
+    components: tokens.filter((token) => token.key.startsWith("components.")),
+    motion: tokens.filter((token) => token.key.startsWith("motion.")),
+    accessibility: tokens.filter((token) => token.key.startsWith("accessibility.")),
+    spacing: tokens.filter((token) => token.key.startsWith("spacing."))
+  };
+}
+function buildTokensMarkdown(tokens) {
+  const lines = ["# Design Tokens", "", "| Token | Type | Value |", "| --- | --- | --- |"];
+  for (const token of tokens) {
+    lines.push(`| \`${token.key}\` | \`${token.type}\` | \`${stringifyValue(token.value)}\` |`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function buildSectionMarkdown(title, tokens) {
+  const lines = [`# ${title}`, ""];
+  if (tokens.length === 0) {
+    lines.push("No tokens defined yet.", "");
+    return lines.join("\n");
+  }
+  for (const token of tokens) {
+    lines.push(`- \`${token.key}\`: \`${stringifyValue(token.value)}\``);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function buildResponsiveMarkdown(tokens) {
+  const lines = ["# Responsive Design", "", "## Spacing Scale", ""];
+  for (const token of tokens) {
+    lines.push(`- \`${token.key}\`: \`${stringifyValue(token.value)}\``);
+  }
+  lines.push("", "Use the spacing scale as the basis for layout density and breakpoints.", "");
+  return lines.join("\n");
+}
+function buildPatternsMarkdown(tokens) {
+  const highlighted = tokens.filter(
+    (token) => ["color.primary", "color.secondary", "typography.heading.h1", "components.button.radius"].some(
+      (prefix) => token.key.startsWith(prefix)
+    )
+  );
+  const lines = ["# Design Patterns", "", "## Framework Guidance", ""];
+  for (const token of highlighted) {
+    lines.push(`- Base pattern from \`${token.key}\`: \`${stringifyValue(token.value)}\``);
+  }
+  lines.push(
+    "",
+    "Keep generated UI aligned with these tokens before introducing new variants.",
+    ""
+  );
+  return lines.join("\n");
+}
+function stringifyValue(value) {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+function toIdentifier(value) {
+  return value.replace(/[^a-zA-Z0-9]+(.)/g, (_, character) => character.toUpperCase());
+}
+
 // src/health/checker.ts
+import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync4, statSync } from "fs";
+import { access } from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { join as join7 } from "path";
+import YAML from "yaml";
 var STALENESS_WINDOW_MS = 1e3 * 60 * 60 * 24 * 7;
 var HealthChecker = class {
   validator = new SchemaValidator();
@@ -1216,7 +1650,7 @@ var HealthChecker = class {
     };
   }
   readProfile(projectRoot) {
-    const path = join6(projectRoot, PATHS.PROJECT_PROFILE);
+    const path = join7(projectRoot, PATHS.PROJECT_PROFILE);
     if (!existsSync4(path)) {
       return null;
     }
@@ -1227,7 +1661,7 @@ var HealthChecker = class {
     }
   }
   detectModules(projectRoot) {
-    const modulesRoot = join6(projectRoot, "docs/modules");
+    const modulesRoot = join7(projectRoot, "docs/modules");
     if (!existsSync4(modulesRoot)) {
       return [];
     }
@@ -1241,7 +1675,7 @@ var HealthChecker = class {
       "scripts",
       "docs/modules/core"
     ];
-    const missing = required.filter((relative6) => !existsSync4(join6(projectRoot, relative6)));
+    const missing = required.filter((relative7) => !existsSync4(join7(projectRoot, relative7)));
     return missing.length === 0 ? pass("Framework artifacts exist", "Framework artifacts are present") : fail(
       "Framework artifacts exist",
       `Missing framework artifacts: ${missing.join(", ")}`,
@@ -1272,7 +1706,7 @@ var HealthChecker = class {
       "docs/modules/core/integration/contracts.md",
       "docs/modules/core/error-catalog.md"
     ];
-    const missing = required.filter((relative6) => !existsSync4(join6(projectRoot, relative6)));
+    const missing = required.filter((relative7) => !existsSync4(join7(projectRoot, relative7)));
     return missing.length === 0 ? pass("Docs scaffold exists", "Documentation scaffold is complete") : fail(
       "Docs scaffold exists",
       `Missing scaffold files: ${missing.join(", ")}`,
@@ -1281,9 +1715,9 @@ var HealthChecker = class {
   }
   checkIndexesCurrent(projectRoot) {
     const missing = REGISTRIES.filter(
-      (registry) => !existsSync4(join6(projectRoot, "docs", registry))
+      (registry) => !existsSync4(join7(projectRoot, "docs", registry))
     );
-    const statusPath = join6(projectRoot, ".agency/indexes/registry-status.json");
+    const statusPath = join7(projectRoot, ".agency/indexes/registry-status.json");
     if (missing.length > 0 || !existsSync4(statusPath)) {
       return fail(
         "Indexes are current",
@@ -1299,7 +1733,7 @@ var HealthChecker = class {
     const missing = [];
     const nonExecutable = [];
     for (const script of required) {
-      const path = join6(projectRoot, "scripts", script);
+      const path = join7(projectRoot, "scripts", script);
       if (!existsSync4(path)) {
         missing.push(script);
         continue;
@@ -1318,7 +1752,7 @@ var HealthChecker = class {
   }
   checkHooks(projectRoot) {
     const candidates = [".claude/settings.hooks.json", ".codex/hooks.json", ".gemini/hooks.json"];
-    return candidates.some((candidate) => existsSync4(join6(projectRoot, candidate))) ? pass("Hooks are active", "Hook registration files are present") : fail(
+    return candidates.some((candidate) => existsSync4(join7(projectRoot, candidate))) ? pass("Hooks are active", "Hook registration files are present") : fail(
       "Hooks are active",
       "No hook registration files were found",
       "Regenerate adapter hook configuration."
@@ -1326,7 +1760,7 @@ var HealthChecker = class {
   }
   checkAdapterConfig(projectRoot) {
     const configs = [PATHS.CLAUDE_MD, PATHS.AGENTS_MD, PATHS.GEMINI_MD];
-    const existing = configs.filter((config) => existsSync4(join6(projectRoot, config)));
+    const existing = configs.filter((config) => existsSync4(join7(projectRoot, config)));
     return existing.length > 0 ? pass("Adapter config is present", "Adapter config files are present") : fail(
       "Adapter config is present",
       "No adapter config files were found",
@@ -1356,7 +1790,7 @@ var HealthChecker = class {
     );
   }
   checkStableFrameworkPaths(projectRoot) {
-    const frameworkPath = join6(projectRoot, PATHS.FRAMEWORK_PATH);
+    const frameworkPath = join7(projectRoot, PATHS.FRAMEWORK_PATH);
     if (!existsSync4(frameworkPath)) {
       return fail(
         "Stable framework paths only",
@@ -1384,7 +1818,7 @@ var HealthChecker = class {
   }
   checkUiDocs(projectRoot, modules) {
     const missing = modules.filter(
-      (moduleName) => !existsSync4(join6(projectRoot, "docs/modules", moduleName, "ui/screens.md")) || !existsSync4(join6(projectRoot, "docs/modules", moduleName, "ui/components.md")) || !existsSync4(join6(projectRoot, "docs/modules", moduleName, "ui/states.md"))
+      (moduleName) => !existsSync4(join7(projectRoot, "docs/modules", moduleName, "ui/screens.md")) || !existsSync4(join7(projectRoot, "docs/modules", moduleName, "ui/components.md")) || !existsSync4(join7(projectRoot, "docs/modules", moduleName, "ui/states.md"))
     );
     return missing.length === 0 ? pass("UI docs present", "UI docs are present for all modules with UI docs") : fail(
       "UI docs present",
@@ -1394,7 +1828,7 @@ var HealthChecker = class {
   }
   checkApiDocs(projectRoot, modules) {
     const missing = modules.filter(
-      (moduleName) => !existsSync4(join6(projectRoot, "docs/modules", moduleName, "api/endpoints.md")) || !existsSync4(join6(projectRoot, "docs/modules", moduleName, "api/schemas.md")) || !existsSync4(join6(projectRoot, "docs/modules", moduleName, "api/error-codes.md"))
+      (moduleName) => !existsSync4(join7(projectRoot, "docs/modules", moduleName, "api/endpoints.md")) || !existsSync4(join7(projectRoot, "docs/modules", moduleName, "api/schemas.md")) || !existsSync4(join7(projectRoot, "docs/modules", moduleName, "api/error-codes.md"))
     );
     return missing.length === 0 ? pass("API docs present", "API docs are present for all modules with APIs") : fail(
       "API docs present",
@@ -1404,7 +1838,7 @@ var HealthChecker = class {
   }
   checkIntegrationDocs(projectRoot, modules) {
     const missing = modules.filter(
-      (moduleName) => !existsSync4(join6(projectRoot, "docs/modules", moduleName, "integration/events.md")) || !existsSync4(join6(projectRoot, "docs/modules", moduleName, "integration/contracts.md"))
+      (moduleName) => !existsSync4(join7(projectRoot, "docs/modules", moduleName, "integration/events.md")) || !existsSync4(join7(projectRoot, "docs/modules", moduleName, "integration/contracts.md"))
     );
     return missing.length === 0 ? pass("Integration docs present", "Integration docs are present for all modules") : fail(
       "Integration docs present",
@@ -1414,7 +1848,7 @@ var HealthChecker = class {
   }
   checkErrorCatalog(projectRoot, modules) {
     const missing = modules.filter(
-      (moduleName) => !existsSync4(join6(projectRoot, "docs/modules", moduleName, "error-catalog.md"))
+      (moduleName) => !existsSync4(join7(projectRoot, "docs/modules", moduleName, "error-catalog.md"))
     );
     return missing.length === 0 ? pass("Error catalog present", "Error catalogs are present for all modules") : fail(
       "Error catalog present",
@@ -1431,7 +1865,7 @@ var HealthChecker = class {
       );
     }
     const candidates = [".claude/settings.mcp.json", ".codex/mcp.json", ".gemini/mcp.json"];
-    const existing = candidates.filter((candidate) => existsSync4(join6(projectRoot, candidate)));
+    const existing = candidates.filter((candidate) => existsSync4(join7(projectRoot, candidate)));
     const expectedServers = getServersForStack(profile.routing.stack, profile.routing.capabilities).filter((server) => server.name !== "figma").map((server) => server.name);
     if (existing.length === 0) {
       return warn(
@@ -1443,7 +1877,7 @@ var HealthChecker = class {
     const configured = /* @__PURE__ */ new Set();
     for (const path of existing) {
       try {
-        const parsed = JSON.parse(readFileSync4(join6(projectRoot, path), "utf8"));
+        const parsed = JSON.parse(readFileSync4(join7(projectRoot, path), "utf8"));
         Object.keys(parsed.mcpServers ?? {}).forEach((server) => configured.add(server));
       } catch {
         continue;
@@ -1457,7 +1891,7 @@ var HealthChecker = class {
     );
   }
   checkSkillCache(projectRoot) {
-    const cacheDir = join6(projectRoot, PATHS.SKILL_CACHE_DIR);
+    const cacheDir = join7(projectRoot, PATHS.SKILL_CACHE_DIR);
     if (!existsSync4(cacheDir)) {
       return warn(
         "Skill cache healthy",
@@ -1467,7 +1901,7 @@ var HealthChecker = class {
     }
     const corrupt = readdirSync(cacheDir).filter((entry) => entry.endsWith(".json")).filter((entry) => {
       try {
-        JSON.parse(readFileSync4(join6(cacheDir, entry), "utf8"));
+        JSON.parse(readFileSync4(join7(cacheDir, entry), "utf8"));
         return false;
       } catch {
         return true;
@@ -1480,7 +1914,7 @@ var HealthChecker = class {
     );
   }
   checkContextHitRate(projectRoot, profile) {
-    const path = join6(projectRoot, PATHS.CONTEXT_HIT_LOG);
+    const path = join7(projectRoot, PATHS.CONTEXT_HIT_LOG);
     if (!existsSync4(path) || profile === null) {
       return pass("Context hit rate acceptable", "No recent context logs yet");
     }
@@ -1502,7 +1936,7 @@ var HealthChecker = class {
     }
   }
   buildEfficiencySummary(projectRoot, profile) {
-    const path = join6(projectRoot, PATHS.CONTEXT_HIT_LOG);
+    const path = join7(projectRoot, PATHS.CONTEXT_HIT_LOG);
     let contextHitRate = 1;
     if (existsSync4(path)) {
       try {
@@ -1514,7 +1948,7 @@ var HealthChecker = class {
     }
     return {
       context_hit_rate: contextHitRate,
-      skill_cache_hit_rate: existsSync4(join6(projectRoot, PATHS.SKILL_CACHE_DIR)) ? 1 : 0,
+      skill_cache_hit_rate: existsSync4(join7(projectRoot, PATHS.SKILL_CACHE_DIR)) ? 1 : 0,
       mcp_usage_rate: profile?.efficiency?.mcp_first ? 1 : 0
     };
   }
@@ -1543,7 +1977,7 @@ function isStale(timestampMs) {
 function walk(root) {
   const results = [];
   for (const entry of readdirSync(root, { withFileTypes: true })) {
-    const path = join6(root, entry.name);
+    const path = join7(root, entry.name);
     if (entry.isDirectory()) {
       results.push(...walk(path));
       continue;
@@ -1559,37 +1993,37 @@ import { mkdirSync as mkdirSync2 } from "fs";
 // src/onboarding/manifest-writer.ts
 import { mkdirSync, writeFileSync } from "fs";
 import { homedir } from "os";
-import { dirname as dirname2, join as join7 } from "path";
+import { dirname as dirname3, join as join8 } from "path";
 import YAML2 from "yaml";
 function writeProjectProfile(projectRoot, profile) {
-  const path = join7(projectRoot, PATHS.PROJECT_PROFILE);
-  mkdirSync(dirname2(path), { recursive: true });
+  const path = join8(projectRoot, PATHS.PROJECT_PROFILE);
+  mkdirSync(dirname3(path), { recursive: true });
   writeFileSync(path, YAML2.stringify(profile));
   return path;
 }
 function writeDetectionReport(projectRoot, report) {
-  const path = join7(projectRoot, PATHS.DETECTION_REPORT);
-  mkdirSync(dirname2(path), { recursive: true });
+  const path = join8(projectRoot, PATHS.DETECTION_REPORT);
+  mkdirSync(dirname3(path), { recursive: true });
   writeFileSync(path, JSON.stringify(report, null, 2));
   return path;
 }
 function writeFrameworkMetadata(projectRoot, version) {
-  mkdirSync(dirname2(join7(projectRoot, PATHS.FRAMEWORK_VERSION)), {
+  mkdirSync(dirname3(join8(projectRoot, PATHS.FRAMEWORK_VERSION)), {
     recursive: true
   });
-  writeFileSync(join7(projectRoot, PATHS.FRAMEWORK_VERSION), `${version}
+  writeFileSync(join8(projectRoot, PATHS.FRAMEWORK_VERSION), `${version}
 `);
-  writeFileSync(join7(projectRoot, PATHS.FRAMEWORK_PATH), `${resolveFrameworkInstallPath()}
+  writeFileSync(join8(projectRoot, PATHS.FRAMEWORK_PATH), `${resolveFrameworkInstallPath()}
 `);
 }
 function writeOnboardingManifest(projectRoot, manifest) {
-  const path = join7(projectRoot, PATHS.ONBOARDING_MANIFEST);
-  mkdirSync(dirname2(path), { recursive: true });
+  const path = join8(projectRoot, PATHS.ONBOARDING_MANIFEST);
+  mkdirSync(dirname3(path), { recursive: true });
   writeFileSync(path, JSON.stringify(manifest, null, 2));
   return path;
 }
 function resolveFrameworkInstallPath() {
-  return process.env.PAQAD_FRAMEWORK_HOME ?? join7(homedir(), ".paqad-ai/current");
+  return process.env.PAQAD_FRAMEWORK_HOME ?? join8(homedir(), ".paqad-ai/current");
 }
 
 // src/install/bootstrap.ts
@@ -1604,15 +2038,675 @@ function bootstrapFramework(projectRoot) {
   };
 }
 
+// src/introspection/cache.ts
+import { createHash } from "crypto";
+import { mkdir as mkdir2, readFile as readFile4, writeFile as writeFile2 } from "fs/promises";
+import { dirname as dirname4, join as join9 } from "path";
+var StackSnapshotCache = class {
+  async read(projectRoot) {
+    try {
+      const raw = await readFile4(join9(projectRoot, PATHS.STACK_SNAPSHOT), "utf8");
+      return JSON.parse(raw);
+    } catch {
+      return null;
+    }
+  }
+  async write(projectRoot, snapshot) {
+    const target = join9(projectRoot, PATHS.STACK_SNAPSHOT);
+    await mkdir2(dirname4(target), { recursive: true });
+    await writeFile2(target, `${JSON.stringify(snapshot, null, 2)}
+`);
+  }
+  async hashFiles(projectRoot, relativePaths) {
+    const hashes = {};
+    for (const relativePath of relativePaths) {
+      try {
+        const content = await readFile4(join9(projectRoot, relativePath), "utf8");
+        hashes[relativePath] = `sha256:${createHash("sha256").update(content).digest("hex")}`;
+      } catch {
+        continue;
+      }
+    }
+    return hashes;
+  }
+};
+
+// src/introspection/parsers/shared.ts
+import { readFile as readFile5 } from "fs/promises";
+import { join as join10 } from "path";
+async function readJsonFile2(projectRoot, relativePath) {
+  try {
+    return JSON.parse(await readFile5(join10(projectRoot, relativePath), "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function readTextFile(projectRoot, relativePath) {
+  try {
+    return await readFile5(join10(projectRoot, relativePath), "utf8");
+  } catch {
+    return null;
+  }
+}
+
+// src/introspection/parsers/composer.ts
+async function parseComposerProject(projectRoot) {
+  const composerJson = await readJsonFile2(projectRoot, "composer.json");
+  const composerLock = await readJsonFile2(projectRoot, "composer.lock");
+  if (composerJson === null) {
+    return null;
+  }
+  const lockedVersions = /* @__PURE__ */ new Map();
+  for (const pkg of composerLock?.packages ?? []) {
+    lockedVersions.set(pkg.name, pkg.version);
+  }
+  for (const pkg of composerLock?.["packages-dev"] ?? []) {
+    lockedVersions.set(pkg.name, pkg.version);
+  }
+  return {
+    toolchain: {
+      ecosystem: "php",
+      package_manager: "composer",
+      lockfile: "composer.lock"
+    },
+    packages: [
+      ...Object.entries(composerJson.require ?? {}).map(([name, version_constraint]) => ({
+        name,
+        version_constraint,
+        locked_version: lockedVersions.get(name) ?? version_constraint,
+        ecosystem: "php",
+        is_dev: false
+      })),
+      ...Object.entries(composerJson["require-dev"] ?? {}).map(([name, version_constraint]) => ({
+        name,
+        version_constraint,
+        locked_version: lockedVersions.get(name) ?? version_constraint,
+        ecosystem: "php",
+        is_dev: true
+      }))
+    ].sort((left, right) => left.name.localeCompare(right.name))
+  };
+}
+
+// src/introspection/parsers/dart.ts
+import YAML3 from "yaml";
+async function parseDartProject(projectRoot) {
+  const pubspecText = await readTextFile(projectRoot, "pubspec.yaml");
+  if (pubspecText === null) {
+    return null;
+  }
+  const pubspec = YAML3.parse(pubspecText);
+  const pubspecLockText = await readTextFile(projectRoot, "pubspec.lock");
+  const pubspecLock = pubspecLockText ? YAML3.parse(pubspecLockText) : null;
+  const lockedVersions = /* @__PURE__ */ new Map();
+  for (const [name, value] of Object.entries(pubspecLock?.packages ?? {})) {
+    if (value.version) {
+      lockedVersions.set(name, value.version);
+    }
+  }
+  return {
+    toolchain: {
+      ecosystem: "dart",
+      package_manager: "pub",
+      lockfile: "pubspec.lock"
+    },
+    packages: [
+      ...buildPackages(pubspec.dependencies ?? {}, lockedVersions, false),
+      ...buildPackages(pubspec.dev_dependencies ?? {}, lockedVersions, true)
+    ].sort((left, right) => left.name.localeCompare(right.name))
+  };
+}
+function buildPackages(dependencies, lockedVersions, is_dev) {
+  return Object.entries(dependencies).map(([name, value]) => {
+    const version_constraint = typeof value === "string" ? value : value.sdk !== void 0 ? `sdk:${value.sdk}` : "unknown";
+    return {
+      name,
+      version_constraint,
+      locked_version: lockedVersions.get(name) ?? version_constraint,
+      ecosystem: "dart",
+      is_dev
+    };
+  });
+}
+
+// src/introspection/parsers/npm.ts
+async function parseNpmProject(projectRoot) {
+  const packageJson = await readJsonFile2(projectRoot, "package.json");
+  const packageLock = await readJsonFile2(projectRoot, "package-lock.json");
+  if (packageJson === null) {
+    return null;
+  }
+  const lockedVersions = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(packageLock?.packages ?? {})) {
+    if (!key.startsWith("node_modules/") || value.version === void 0) {
+      continue;
+    }
+    lockedVersions.set(key.replace(/^node_modules\//, ""), value.version);
+  }
+  return {
+    toolchain: {
+      ecosystem: "node",
+      package_manager: "npm",
+      lockfile: "package-lock.json"
+    },
+    packages: buildNodePackages(packageJson, lockedVersions)
+  };
+}
+function buildNodePackages(packageJson, lockedVersions) {
+  const runtime = Object.entries(packageJson.dependencies ?? {}).map(
+    ([name, version_constraint]) => ({
+      name,
+      version_constraint,
+      locked_version: lockedVersions.get(name) ?? version_constraint,
+      ecosystem: "node",
+      is_dev: false
+    })
+  );
+  const dev = Object.entries(packageJson.devDependencies ?? {}).map(
+    ([name, version_constraint]) => ({
+      name,
+      version_constraint,
+      locked_version: lockedVersions.get(name) ?? version_constraint,
+      ecosystem: "node",
+      is_dev: true
+    })
+  );
+  return [...runtime, ...dev].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+// src/introspection/parsers/pnpm.ts
+import YAML4 from "yaml";
+async function parsePnpmProject(projectRoot) {
+  const packageJson = await readJsonFile2(projectRoot, "package.json");
+  const lockfile = await readTextFile(projectRoot, "pnpm-lock.yaml");
+  if (packageJson === null) {
+    return null;
+  }
+  const parsedLock = lockfile ? YAML4.parse(lockfile) : null;
+  const lockedVersions = /* @__PURE__ */ new Map();
+  for (const [key, value] of Object.entries(parsedLock?.packages ?? {})) {
+    const match = key.match(/^\/?(@?[^@/]+(?:\/[^@/]+)?)@/);
+    if (match?.[1] && value.version) {
+      lockedVersions.set(match[1], value.version);
+    }
+  }
+  return {
+    toolchain: {
+      ecosystem: "node",
+      package_manager: "pnpm",
+      lockfile: "pnpm-lock.yaml"
+    },
+    packages: buildNodePackages2(packageJson, lockedVersions)
+  };
+}
+function buildNodePackages2(packageJson, lockedVersions) {
+  const runtime = Object.entries(packageJson.dependencies ?? {}).map(
+    ([name, version_constraint]) => ({
+      name,
+      version_constraint,
+      locked_version: lockedVersions.get(name) ?? version_constraint,
+      ecosystem: "node",
+      is_dev: false
+    })
+  );
+  const dev = Object.entries(packageJson.devDependencies ?? {}).map(
+    ([name, version_constraint]) => ({
+      name,
+      version_constraint,
+      locked_version: lockedVersions.get(name) ?? version_constraint,
+      ecosystem: "node",
+      is_dev: true
+    })
+  );
+  return [...runtime, ...dev].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+// src/introspection/stack-introspector.ts
+var StackIntrospector = class {
+  cache = new StackSnapshotCache();
+  async snapshot(projectRoot) {
+    const currentHashes = await this.cache.hashFiles(projectRoot, [
+      "package.json",
+      "pnpm-lock.yaml",
+      "package-lock.json",
+      "composer.json",
+      "composer.lock",
+      "pubspec.yaml",
+      "pubspec.lock"
+    ]);
+    const cached = await this.cache.read(projectRoot);
+    if (cached !== null && JSON.stringify(cached.source_hashes) === JSON.stringify(currentHashes)) {
+      return cached;
+    }
+    const results = await Promise.all([
+      parsePnpmProject(projectRoot),
+      parseNpmProject(projectRoot),
+      parseComposerProject(projectRoot),
+      parseDartProject(projectRoot)
+    ]);
+    const toolchains = results.flatMap((result) => result ? [result.toolchain] : []);
+    const packages = results.flatMap((result) => result ? result.packages : []);
+    const snapshot = {
+      generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+      source_hashes: currentHashes,
+      toolchains,
+      packages
+    };
+    await this.cache.write(projectRoot, snapshot);
+    return snapshot;
+  }
+};
+
+// src/document/pipeline.ts
+import { mkdir as mkdir4, readdir as readdir2, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname6, join as join14, relative } from "path";
+
+// src/onboarding/registry-generator.ts
+import { readdir } from "fs/promises";
+import { join as join11 } from "path";
+async function generateInitialRegistries(projectRoot) {
+  const modules = await discoverModules(projectRoot);
+  return [
+    {
+      path: ".agency/indexes/registry-status.json",
+      content: JSON.stringify(
+        {
+          generated: true,
+          modules,
+          generated_at: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        null,
+        2
+      ),
+      autoUpdate: true
+    },
+    {
+      path: ".agency/cache/skill-results/.gitkeep",
+      content: "",
+      autoUpdate: true
+    },
+    {
+      path: PATHS.GLOSSARY,
+      content: "# Glossary\n\n",
+      autoUpdate: true
+    },
+    ...REGISTRIES.map((registry) => ({
+      path: join11("docs", registry),
+      content: registry === "module-registry.md" ? buildModuleRegistry(modules) : `# ${registry}
+
+`,
+      autoUpdate: true
+    }))
+  ];
+}
+async function discoverModules(projectRoot) {
+  const candidates = [
+    join11(projectRoot, "docs/modules"),
+    join11(projectRoot, "app"),
+    join11(projectRoot, "lib")
+  ];
+  const modules = /* @__PURE__ */ new Set(["core"]);
+  for (const root of candidates) {
+    try {
+      const entries = await readdir(root, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) {
+          continue;
+        }
+        const name = entry.name;
+        if (name !== "" && !name.startsWith(".")) {
+          modules.add(name);
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return Array.from(modules).sort();
+}
+function buildModuleRegistry(modules) {
+  return ["# module-registry.md", "", ...modules.map((module) => `- ${module}`), ""].join("\n");
+}
+
+// src/document/progress-tracker.ts
+import { mkdir as mkdir3, readFile as readFile6, rm, writeFile as writeFile3 } from "fs/promises";
+import { dirname as dirname5, join as join12 } from "path";
+var DocumentProgressTracker = class {
+  constructor(validator = new SchemaValidator()) {
+    this.validator = validator;
+  }
+  async load(projectRoot) {
+    try {
+      const parsed = JSON.parse(
+        await readFile6(join12(projectRoot, PATHS.DOC_PROGRESS), "utf8")
+      );
+      const validation = this.validator.validate("doc-progress", parsed);
+      if (!validation.valid) {
+        throw new Error(validation.errors.map((error) => error.message).join("; "));
+      }
+      return parsed;
+    } catch {
+      return this.createEmpty();
+    }
+  }
+  async save(projectRoot, progress) {
+    const target = join12(projectRoot, PATHS.DOC_PROGRESS);
+    await mkdir3(dirname5(target), { recursive: true });
+    await writeFile3(target, `${JSON.stringify(progress, null, 2)}
+`);
+  }
+  async resetGeneratingEntries(projectRoot, progress) {
+    const entries = collectEntries(progress);
+    await Promise.all(
+      entries.map(async (entry) => {
+        if (entry.state !== "generating") {
+          return;
+        }
+        entry.state = "not_started";
+        entry.started_at = null;
+        entry.completed_at = null;
+        entry.error = null;
+        await rm(join12(projectRoot, entry.output_path), { force: true });
+      })
+    );
+  }
+  createEntry(output_path, source_files) {
+    return {
+      output_path,
+      state: "not_started",
+      started_at: null,
+      completed_at: null,
+      source_files,
+      source_hash: null,
+      tokens_used: null,
+      error: null
+    };
+  }
+  createEmpty() {
+    return {
+      schema_version: "1",
+      generated_by: "paqad-ai",
+      framework_version: VERSION,
+      modules: {},
+      global: {}
+    };
+  }
+};
+function collectEntries(progress) {
+  return [
+    ...Object.values(progress.modules).flatMap((group) => Object.values(group)),
+    ...Object.values(progress.global).flatMap((group) => Object.values(group))
+  ];
+}
+
+// src/document/staleness.ts
+import { createHash as createHash2 } from "crypto";
+import { readFile as readFile7 } from "fs/promises";
+import { join as join13 } from "path";
+async function hashSourceFiles(projectRoot, sourceFiles) {
+  const hash = createHash2("sha1");
+  for (const relativePath of sourceFiles) {
+    try {
+      hash.update(await readFile7(join13(projectRoot, relativePath), "utf8"));
+    } catch {
+      hash.update(`missing:${relativePath}`);
+    }
+  }
+  return `sha1:${hash.digest("hex").slice(0, 7)}`;
+}
+
+// src/document/pipeline.ts
+var DocumentPipeline = class {
+  tracker = new DocumentProgressTracker();
+  async run(options) {
+    const progress = await this.tracker.load(options.projectRoot);
+    await this.tracker.resetGeneratingEntries(options.projectRoot, progress);
+    const stackSnapshot = options.refreshStack === true || options.scope === "full" ? await new StackIntrospector().snapshot(options.projectRoot) : null;
+    if (options.refreshTokens === true || options.scope === "ui" || options.scope === "full") {
+      await new DesignTokenService().writeDocs(options.projectRoot);
+    }
+    const sourceFiles = await gatherSourceFiles(options.projectRoot);
+    const modules = await discoverModules(options.projectRoot);
+    const generated = [];
+    const skipped = [];
+    if (shouldGenerateModuleDocs(options.scope)) {
+      for (const moduleName of modules) {
+        progress.modules[moduleName] ??= {};
+        const businessPath = join14(PATHS.MODULES_DIR, moduleName, "business.md");
+        const technicalPath = join14(PATHS.MODULES_DIR, moduleName, "technical.md");
+        progress.modules[moduleName].business ??= this.tracker.createEntry(
+          businessPath,
+          sourceFiles
+        );
+        progress.modules[moduleName].technical ??= this.tracker.createEntry(
+          technicalPath,
+          sourceFiles
+        );
+        if (shouldGenerateBusinessDoc(options.scope)) {
+          await processEntry({
+            projectRoot: options.projectRoot,
+            entry: progress.modules[moduleName].business,
+            content: buildBusinessDoc(moduleName, sourceFiles),
+            generated,
+            skipped,
+            dryRun: options.dryRun === true
+          });
+        }
+        if (shouldGenerateTechnicalDoc(options.scope)) {
+          await processEntry({
+            projectRoot: options.projectRoot,
+            entry: progress.modules[moduleName].technical,
+            content: buildTechnicalDoc(moduleName, sourceFiles, stackSnapshot),
+            generated,
+            skipped,
+            dryRun: options.dryRun === true
+          });
+        }
+      }
+    }
+    progress.global.designSystem ??= {};
+    progress.global.designSystem.tokens ??= this.tracker.createEntry(
+      join14(PATHS.DESIGN_SYSTEM_DIR, "tokens.md"),
+      [PATHS.DESIGN_TOKENS_FILE]
+    );
+    progress.global.architecture ??= {};
+    progress.global.architecture.overview ??= this.tracker.createEntry(
+      join14(PATHS.ARCHITECTURE_DIR, "overview.md"),
+      sourceFiles
+    );
+    if (shouldGenerateArchitectureDocs(options.scope)) {
+      await processEntry({
+        projectRoot: options.projectRoot,
+        entry: progress.global.architecture.overview,
+        content: buildArchitectureOverview(modules, stackSnapshot),
+        generated,
+        skipped,
+        dryRun: options.dryRun === true
+      });
+    }
+    const handoverPath = join14(".agency/handover", "product-summary.md");
+    if (!options.dryRun && shouldGenerateHandover(options.scope)) {
+      await mkdir4(dirname6(join14(options.projectRoot, handoverPath)), { recursive: true });
+      await writeFile4(
+        join14(options.projectRoot, handoverPath),
+        buildHandoverSummary(modules, generated, stackSnapshot)
+      );
+      generated.push(handoverPath);
+    }
+    await this.tracker.save(options.projectRoot, progress);
+    return {
+      generated,
+      skipped,
+      progress_path: PATHS.DOC_PROGRESS,
+      handover_path: handoverPath,
+      stack_snapshot: stackSnapshot
+    };
+  }
+};
+function shouldGenerateModuleDocs(scope) {
+  return scope === "full" || scope === "ui" || scope === "api" || scope === "database";
+}
+function shouldGenerateBusinessDoc(scope) {
+  return scope === "full" || scope === "ui";
+}
+function shouldGenerateTechnicalDoc(scope) {
+  return scope === "full" || scope === "ui" || scope === "api" || scope === "database";
+}
+function shouldGenerateArchitectureDocs(scope) {
+  return scope === "full" || scope === "architecture";
+}
+function shouldGenerateHandover(scope) {
+  return scope === "full";
+}
+async function processEntry(input) {
+  const currentHash = await hashSourceFiles(input.projectRoot, input.entry.source_files);
+  if (input.entry.state === "done" && input.entry.source_hash === currentHash) {
+    input.skipped.push(input.entry.output_path);
+    return;
+  }
+  input.entry.state = "generating";
+  input.entry.started_at = (/* @__PURE__ */ new Date()).toISOString();
+  input.entry.error = null;
+  if (!input.dryRun) {
+    await mkdir4(dirname6(join14(input.projectRoot, input.entry.output_path)), { recursive: true });
+    await writeFile4(join14(input.projectRoot, input.entry.output_path), input.content);
+    input.generated.push(input.entry.output_path);
+  }
+  input.entry.state = "done";
+  input.entry.completed_at = (/* @__PURE__ */ new Date()).toISOString();
+  input.entry.source_hash = currentHash;
+  input.entry.tokens_used = Math.max(32, Math.round(input.content.length / 4));
+  if (input.entry.output_path.endsWith("tokens.md")) {
+    input.entry.design_tokens = {
+      extraction_state: "done",
+      total_tokens_found: (input.content.match(/`/g) ?? []).length / 2,
+      placeholder_count: (input.content.match(/\{[^}]+\}/g) ?? []).length,
+      populated_count: Math.max(0, input.content.split("\n").length - 4),
+      placeholder_keys: Array.from(
+        new Set((input.content.match(/\{[^}]+\}/g) ?? []).map((item) => item.slice(1, -1)))
+      ).slice(0, 10)
+    };
+  }
+}
+async function gatherSourceFiles(projectRoot) {
+  const roots = ["src", "app", "lib", "routes", "resources", "config"];
+  const results = /* @__PURE__ */ new Set();
+  for (const root of roots) {
+    try {
+      for (const file of await walk2(join14(projectRoot, root))) {
+        results.add(relative(projectRoot, file));
+      }
+    } catch {
+      continue;
+    }
+  }
+  if (results.size === 0) {
+    results.add("package.json");
+  }
+  return Array.from(results).sort();
+}
+async function walk2(root) {
+  const entries = await readdir2(root, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const target = join14(root, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walk2(target));
+      continue;
+    }
+    files.push(target);
+  }
+  return files;
+}
+function buildBusinessDoc(moduleName, sourceFiles) {
+  return [
+    `# ${titleize(moduleName)} Business`,
+    "",
+    "## Overview",
+    "",
+    `${titleize(moduleName)} is documented from the current codebase snapshot.`,
+    "",
+    "## User Flows",
+    "",
+    ...sourceFiles.slice(0, 5).map((file, index) => `${index + 1}. Flow signal from \`${file}\`.`),
+    "",
+    "## Business Rules",
+    "",
+    "- Preserve the documented behaviors inferred from the current implementation.",
+    ""
+  ].join("\n");
+}
+function buildTechnicalDoc(moduleName, sourceFiles, stackSnapshot) {
+  const packageLines = stackSnapshot?.packages.slice(0, 6).map((pkg) => `- \`${pkg.name}\` @ \`${pkg.locked_version}\``) ?? ["- No snapshot available."];
+  return [
+    `# ${titleize(moduleName)} Technical`,
+    "",
+    "## Module Boundaries",
+    "",
+    ...sourceFiles.slice(0, 8).map((file) => `- \`${file}\``),
+    "",
+    "## Dependencies",
+    "",
+    ...packageLines,
+    "",
+    "## Testing Entry Points",
+    "",
+    `- Update module coverage under \`tests/\` for ${moduleName}.`,
+    ""
+  ].join("\n");
+}
+function buildArchitectureOverview(modules, stackSnapshot) {
+  return [
+    "# Architecture Overview",
+    "",
+    "## Modules",
+    "",
+    ...modules.map((moduleName) => `- ${moduleName}`),
+    "",
+    "## Toolchains",
+    "",
+    ...stackSnapshot?.toolchains.map(
+      (toolchain) => `- ${toolchain.ecosystem}: ${toolchain.package_manager} (${toolchain.lockfile})`
+    ) ?? ["- No toolchain snapshot available."],
+    ""
+  ].join("\n");
+}
+function buildHandoverSummary(modules, generated, stackSnapshot) {
+  return [
+    "# Product Summary",
+    "",
+    `Generated documentation for ${modules.length} module(s).`,
+    "",
+    `Artifacts written: ${generated.length}.`,
+    "",
+    `Package snapshot entries: ${stackSnapshot?.packages.length ?? 0}.`,
+    ""
+  ].join("\n");
+}
+function titleize(value) {
+  return value.replace(/[-_]/g, " ").replace(/\b\w/g, (character) => character.toUpperCase());
+}
+
+// src/document/command.ts
+async function runDocumentCommand(options) {
+  return new DocumentPipeline().run({
+    projectRoot: options.projectRoot,
+    scope: options.scope,
+    dryRun: options.dryRun,
+    refreshStack: options.refreshStack ?? options.scope === "full",
+    refreshTokens: options.refreshTokens ?? (options.scope === "ui" || options.scope === "full")
+  });
+}
+
 // src/onboarding/file-writer.ts
 import { chmodSync, existsSync as existsSync5, mkdirSync as mkdirSync3, writeFileSync as writeFileSync2 } from "fs";
-import { dirname as dirname3, join as join8 } from "path";
+import { dirname as dirname7, join as join15 } from "path";
 function writeGeneratedFiles(projectRoot, files) {
   const written = [];
   const skipped = [];
   for (const file of files) {
-    const target = join8(projectRoot, file.path);
-    mkdirSync3(dirname3(target), { recursive: true });
+    const target = join15(projectRoot, file.path);
+    mkdirSync3(dirname7(target), { recursive: true });
     if (!file.autoUpdate && existsSync5(target)) {
       skipped.push(file.path);
       continue;
@@ -1628,7 +2722,7 @@ function writeGeneratedFiles(projectRoot, files) {
 
 // src/resolver/resolver.ts
 import fg from "fast-glob";
-import { basename as basename2, extname, relative as relative2 } from "pathe";
+import { basename as basename2, extname, relative as relative3 } from "pathe";
 
 // src/resolver/artifact-types.ts
 var ARTIFACT_TYPES = [
@@ -1666,14 +2760,14 @@ var ARTIFACT_OUTPUT_KEYS = {
 };
 
 // src/resolver/inheritance.ts
-import { join as join10, relative } from "pathe";
+import { join as join17, relative as relative2 } from "pathe";
 
 // src/resolver/capability-resolver.ts
-import { join as join9 } from "pathe";
+import { join as join16 } from "pathe";
 function resolveCapabilityDirectories(runtimeRoot, domain, stack, capabilities, artifactType) {
   const directoryName = resolveCapabilityArtifactDirectory(artifactType);
   return capabilities.map(
-    (capability) => join9(
+    (capability) => join16(
       runtimeRoot,
       "domains",
       domain,
@@ -1690,9 +2784,9 @@ function resolveCapabilityArtifactDirectory(artifactType) {
     case "mcp-configs":
       return "mcp";
     case "patterns":
-      return join9("benchmarks", "patterns");
+      return join16("benchmarks", "patterns");
     case "anti-patterns":
-      return join9("benchmarks", "anti-patterns");
+      return join16("benchmarks", "anti-patterns");
     default:
       return artifactType;
   }
@@ -1703,48 +2797,48 @@ function getInheritanceDirectories(runtimeRoot, routing, artifactType) {
   if (artifactType === "hooks") {
     return [
       {
-        path: join10(runtimeRoot, "hooks"),
+        path: join17(runtimeRoot, "hooks"),
         level: 0,
-        source: relative(runtimeRoot, join10(runtimeRoot, "hooks"))
+        source: relative2(runtimeRoot, join17(runtimeRoot, "hooks"))
       }
     ];
   }
   if (artifactType === "templates") {
     return [
       {
-        path: join10(runtimeRoot, "templates"),
+        path: join17(runtimeRoot, "templates"),
         level: 0,
-        source: relative(runtimeRoot, join10(runtimeRoot, "templates"))
+        source: relative2(runtimeRoot, join17(runtimeRoot, "templates"))
       }
     ];
   }
-  const basePath = join10(runtimeRoot, "domains");
+  const basePath = join17(runtimeRoot, "domains");
   const directoryName = resolveArtifactDirectoryName(artifactType);
   const directories = [
     {
-      path: join10(basePath, "_shared", directoryName),
+      path: join17(basePath, "_shared", directoryName),
       level: 0,
-      source: relative(runtimeRoot, join10(basePath, "_shared", directoryName))
+      source: relative2(runtimeRoot, join17(basePath, "_shared", directoryName))
     },
     {
-      path: join10(basePath, routing.domain, directoryName),
+      path: join17(basePath, routing.domain, directoryName),
       level: 1,
-      source: relative(runtimeRoot, join10(basePath, routing.domain, directoryName))
+      source: relative2(runtimeRoot, join17(basePath, routing.domain, directoryName))
     },
     {
-      path: join10(basePath, routing.domain, "stacks", "_shared", directoryName),
+      path: join17(basePath, routing.domain, "stacks", "_shared", directoryName),
       level: 2,
-      source: relative(
+      source: relative2(
         runtimeRoot,
-        join10(basePath, routing.domain, "stacks", "_shared", directoryName)
+        join17(basePath, routing.domain, "stacks", "_shared", directoryName)
       )
     },
     {
-      path: join10(basePath, routing.domain, "stacks", routing.stack, directoryName),
+      path: join17(basePath, routing.domain, "stacks", routing.stack, directoryName),
       level: 2,
-      source: relative(
+      source: relative2(
         runtimeRoot,
-        join10(basePath, routing.domain, "stacks", routing.stack, directoryName)
+        join17(basePath, routing.domain, "stacks", routing.stack, directoryName)
       )
     }
   ];
@@ -1757,7 +2851,7 @@ function getInheritanceDirectories(runtimeRoot, routing, artifactType) {
   ).map((path) => ({
     path,
     level: 3,
-    source: relative(runtimeRoot, path)
+    source: relative2(runtimeRoot, path)
   }));
   return [...directories, ...capabilityDirectories];
 }
@@ -1766,9 +2860,9 @@ function resolveArtifactDirectoryName(artifactType) {
     case "mcp-configs":
       return "mcp";
     case "patterns":
-      return join10("benchmarks", "patterns");
+      return join17("benchmarks", "patterns");
     case "anti-patterns":
-      return join10("benchmarks", "anti-patterns");
+      return join17("benchmarks", "anti-patterns");
     default:
       return artifactType;
   }
@@ -1832,13 +2926,13 @@ var Resolver = class {
         const artifact = {
           path: file,
           level: directory.level,
-          source: relative2(this.runtimeRoot, file)
+          source: relative3(this.runtimeRoot, file)
         };
         if (COLLISION_MAP[artifactType] === "additive-merge") {
           entries.push(artifact);
           continue;
         }
-        overrides.set(relative2(directory.path, file), artifact);
+        overrides.set(relative3(directory.path, file), artifact);
       }
     }
     const resolved = COLLISION_MAP[artifactType] === "additive-merge" ? entries : Array.from(overrides.values());
@@ -1864,8 +2958,8 @@ function getRulePriority(filePath) {
 
 // src/scripts/generator.ts
 import { chmodSync as chmodSync2 } from "fs";
-import { mkdir, writeFile } from "fs/promises";
-import { dirname as dirname4, join as join11 } from "path";
+import { mkdir as mkdir5, writeFile as writeFile5 } from "fs/promises";
+import { dirname as dirname8, join as join18 } from "path";
 
 // src/templates/context-builders/runner-scripts.ts
 function buildRunnerScriptContext(input) {
@@ -1874,7 +2968,7 @@ function buildRunnerScriptContext(input) {
 
 // src/templates/registry.ts
 import fg2 from "fast-glob";
-import { basename as basename3, relative as relative3 } from "pathe";
+import { basename as basename3, relative as relative4 } from "pathe";
 var TemplateRegistry = class {
   constructor(templatesRoot) {
     this.templatesRoot = templatesRoot;
@@ -1888,7 +2982,7 @@ var TemplateRegistry = class {
     return files.sort().map((path) => ({
       name: basename3(path),
       path,
-      relativePath: relative3(this.templatesRoot, path)
+      relativePath: relative4(this.templatesRoot, path)
     }));
   }
 };
@@ -1897,11 +2991,11 @@ var TemplateRegistry = class {
 var RunnerScriptGenerator = class {
   engine = new TemplateEngine();
   async generate(profile) {
-    const registry = new TemplateRegistry(join11(getRuntimeTemplatesRoot(), "runner-scripts"));
+    const registry = new TemplateRegistry(join18(getRuntimeTemplatesRoot(), "runner-scripts"));
     const templates = await registry.discover();
     return Promise.all(
       templates.map(async (template) => ({
-        path: join11("scripts", template.relativePath.replace(/\.hbs$/, "")),
+        path: join18("scripts", template.relativePath.replace(/\.hbs$/, "")),
         content: await this.engine.render(template.path, buildScriptContext(profile)),
         autoUpdate: true,
         executable: true
@@ -1912,9 +3006,9 @@ var RunnerScriptGenerator = class {
     const generated = await this.generate(profile);
     const written = [];
     for (const file of generated) {
-      const target = join11(projectRoot, file.path);
-      await mkdir(dirname4(target), { recursive: true });
-      await writeFile(target, file.content);
+      const target = join18(projectRoot, file.path);
+      await mkdir5(dirname8(target), { recursive: true });
+      await writeFile5(target, file.content);
       chmodSync2(target, 493);
       written.push(file.path);
     }
@@ -1944,83 +3038,16 @@ async function resolveSelections(detection, overrides) {
   };
 }
 
-// src/onboarding/registry-generator.ts
-import { readdir } from "fs/promises";
-import { join as join12 } from "path";
-async function generateInitialRegistries(projectRoot) {
-  const modules = await discoverModules(projectRoot);
-  return [
-    {
-      path: ".agency/indexes/registry-status.json",
-      content: JSON.stringify(
-        {
-          generated: true,
-          modules,
-          generated_at: (/* @__PURE__ */ new Date()).toISOString()
-        },
-        null,
-        2
-      ),
-      autoUpdate: true
-    },
-    {
-      path: ".agency/cache/skill-results/.gitkeep",
-      content: "",
-      autoUpdate: true
-    },
-    {
-      path: PATHS.GLOSSARY,
-      content: "# Glossary\n\n",
-      autoUpdate: true
-    },
-    ...REGISTRIES.map((registry) => ({
-      path: join12("docs", registry),
-      content: registry === "module-registry.md" ? buildModuleRegistry(modules) : `# ${registry}
-
-`,
-      autoUpdate: true
-    }))
-  ];
-}
-async function discoverModules(projectRoot) {
-  const candidates = [
-    join12(projectRoot, "docs/modules"),
-    join12(projectRoot, "app"),
-    join12(projectRoot, "lib")
-  ];
-  const modules = /* @__PURE__ */ new Set(["core"]);
-  for (const root of candidates) {
-    try {
-      const entries = await readdir(root, { withFileTypes: true });
-      for (const entry of entries) {
-        if (!entry.isDirectory()) {
-          continue;
-        }
-        const name = entry.name;
-        if (name !== "" && !name.startsWith(".")) {
-          modules.add(name);
-        }
-      }
-    } catch {
-      continue;
-    }
-  }
-  return Array.from(modules).sort();
-}
-function buildModuleRegistry(modules) {
-  return ["# module-registry.md", "", ...modules.map((module) => `- ${module}`), ""].join("\n");
-}
-
 // src/onboarding/reference-generator.ts
-import { readFile as readFile3 } from "fs/promises";
-import { join as join13, relative as relative4 } from "path";
+import { readFile as readFile8 } from "fs/promises";
+import { join as join19, relative as relative5 } from "path";
 import fg3 from "fast-glob";
 async function generateReferenceGuides(runtimeRoot, routing) {
   const stack = routing.stack;
   if (routing.domain !== "coding" || stack !== "laravel" && stack !== "flutter") {
     return [];
   }
-  const referencesRoot = join13(runtimeRoot, "domains", "coding", "stacks", stack, "references");
+  const referencesRoot = join19(runtimeRoot, "domains", "coding", "stacks", stack, "references");
   const entries = await fg3(["tools/*.md", "tools-catalog.md"], {
     cwd: referencesRoot,
     onlyFiles: true,
@@ -2028,8 +3055,8 @@ async function generateReferenceGuides(runtimeRoot, routing) {
   });
   return Promise.all(
     entries.sort().map(async (entry) => ({
-      path: toProjectReferencePath(stack, relative4(referencesRoot, entry)),
-      content: await readFile3(entry, "utf8"),
+      path: toProjectReferencePath(stack, relative5(referencesRoot, entry)),
+      content: await readFile8(entry, "utf8"),
       autoUpdate: false
     }))
   );
@@ -2037,19 +3064,19 @@ async function generateReferenceGuides(runtimeRoot, routing) {
 function toProjectReferencePath(stack, relativePath) {
   const normalized = relativePath.replaceAll("\\", "/");
   if (normalized === "tools-catalog.md") {
-    return join13("docs/tools", stack, "README.md");
+    return join19("docs/tools", stack, "README.md");
   }
-  return join13("docs/tools", stack, normalized.replace(/^tools\//, ""));
+  return join19("docs/tools", stack, normalized.replace(/^tools\//, ""));
 }
 
 // src/onboarding/rule-generator.ts
-import { readFile as readFile4 } from "fs/promises";
-import { join as join14 } from "path";
+import { readFile as readFile9 } from "fs/promises";
+import { join as join20 } from "path";
 async function generateProjectRules(rules) {
   return Promise.all(
     rules.map(async (rule) => ({
       path: toProjectRulePath(rule.source),
-      content: await readFile4(rule.path, "utf8"),
+      content: await readFile9(rule.path, "utf8"),
       autoUpdate: false
     }))
   );
@@ -2058,19 +3085,14 @@ function toProjectRulePath(source) {
   const normalized = source.replace(/^domains\//, "");
   const [prefix, suffix] = normalized.split("/rules/");
   if (prefix === void 0 || suffix === void 0) {
-    return join14("docs/rules", normalized);
+    return join20("docs/rules", normalized);
   }
   const target = suffix.endsWith("/guide.md") ? suffix.replace("/guide.md", ".md") : suffix;
-  return join14("docs/rules", prefix, target);
+  return join20("docs/rules", prefix, target);
 }
 
 // src/onboarding/scaffold-generator.ts
-import { join as join15 } from "path";
-
-// src/templates/context-builders/design-system.ts
-function buildDesignSystemContext(projectName) {
-  return { projectName };
-}
+import { join as join21 } from "path";
 
 // src/templates/context-builders/module-scaffold.ts
 function buildModuleScaffoldContext(moduleName) {
@@ -2082,6 +3104,8 @@ function buildModuleScaffoldContext(moduleName) {
 
 // src/onboarding/scaffold-generator.ts
 var MODULE_TEMPLATE_TARGETS = [
+  ["business.md.hbs", "business.md"],
+  ["technical.md.hbs", "technical.md"],
   ["summary.md.hbs", "index/summary.md"],
   ["schema.md.hbs", "database/schema.md"],
   ["indexes.md.hbs", "database/indexes.md"],
@@ -2102,40 +3126,29 @@ async function generateDocumentationScaffold(moduleNames = ["core"]) {
   for (const moduleName of Array.from(new Set(moduleNames)).sort()) {
     files.push(...await generateModuleScaffold(moduleName));
   }
-  const engine = new TemplateEngine();
-  for (const [templateName, target] of DESIGN_SYSTEM_TEMPLATE_TARGETS) {
-    files.push({
-      path: target,
-      content: await engine.render(
-        join15(getRuntimeTemplatesRoot(), "design-system", templateName),
-        buildDesignSystemContext("Paqad")
-      ),
-      autoUpdate: true
-    });
-  }
   files.push(
     {
-      path: join15(PATHS.ARCHITECTURE_DIR, "overview.md"),
+      path: join21(PATHS.ARCHITECTURE_DIR, "overview.md"),
       content: "# Architecture Overview\n\n",
       autoUpdate: true
     },
     {
-      path: join15(PATHS.ARCHITECTURE_DIR, "decisions.md"),
+      path: join21(PATHS.ARCHITECTURE_DIR, "decisions.md"),
       content: "# Architecture Decisions\n\n",
       autoUpdate: true
     },
     {
-      path: join15(PATHS.ARCHITECTURE_DIR, "patterns.md"),
+      path: join21(PATHS.ARCHITECTURE_DIR, "patterns.md"),
       content: "# Architecture Patterns\n\n",
       autoUpdate: true
     },
     {
-      path: join15(PATHS.BENCHMARKS_DIR, "index.md"),
+      path: join21(PATHS.BENCHMARKS_DIR, "index.md"),
       content: "# Benchmarks\n\n",
       autoUpdate: true
     },
     {
-      path: join15(PATHS.TECH_DEBT_DIR, "index.md"),
+      path: join21(PATHS.TECH_DEBT_DIR, "index.md"),
       content: "# Technical Debt\n\n",
       autoUpdate: true
     }
@@ -2156,9 +3169,9 @@ async function generateModuleScaffold(moduleName) {
   const files = [];
   for (const [templateName, relativeTarget] of MODULE_TEMPLATE_TARGETS) {
     files.push({
-      path: join15(PATHS.MODULES_DIR, moduleName, relativeTarget),
+      path: join21(PATHS.MODULES_DIR, moduleName, relativeTarget),
       content: await engine.render(
-        join15(getRuntimeTemplatesRoot(), "module-scaffold", templateName),
+        join21(getRuntimeTemplatesRoot(), "module-scaffold", templateName),
         context
       ),
       autoUpdate: false
@@ -2166,14 +3179,6 @@ async function generateModuleScaffold(moduleName) {
   }
   return files;
 }
-var DESIGN_SYSTEM_TEMPLATE_TARGETS = [
-  ["tokens.md.hbs", "docs/design-system/tokens.md"],
-  ["components.md.hbs", "docs/design-system/components.md"],
-  ["motion.md.hbs", "docs/design-system/motion.md"],
-  ["accessibility.md.hbs", "docs/design-system/accessibility.md"],
-  ["responsive.md.hbs", "docs/design-system/responsive.md"],
-  ["patterns.md.hbs", "docs/design-system/patterns.md"]
-];
 
 // src/onboarding/orchestrator.ts
 var OnboardingOrchestrator = class {
@@ -2215,6 +3220,10 @@ var OnboardingOrchestrator = class {
     generatedFiles.push(...await generateInitialRegistries(options.projectRoot));
     generatedFiles.push(...await new RunnerScriptGenerator().generate(profile));
     const writeResult = writeGeneratedFiles(options.projectRoot, generatedFiles);
+    const designTokens = new DesignTokenService();
+    await designTokens.seed(options.projectRoot);
+    await designTokens.writeDocs(options.projectRoot);
+    await designTokens.writeThemeExports(options.projectRoot, selections.stack);
     writeProjectProfile(options.projectRoot, profile);
     writeDetectionReport(options.projectRoot, detection);
     writeFrameworkMetadata(options.projectRoot, VERSION);
@@ -2302,8 +3311,8 @@ function buildProjectProfile(selections, overrides) {
 }
 
 // src/pipeline/lane-runner.ts
-import { mkdir as mkdir2, writeFile as writeFile2 } from "fs/promises";
-import { dirname as dirname5, join as join16 } from "path";
+import { mkdir as mkdir6, writeFile as writeFile6 } from "fs/promises";
+import { dirname as dirname9, join as join22 } from "path";
 
 // src/pipeline/phases/shared.ts
 function createPassResult(phase, summary, context) {
@@ -2459,29 +3468,29 @@ var DEFAULT_PHASES = {
 };
 
 // src/skills/cache-manager.ts
-import { createHash } from "crypto";
-import { mkdir as mkdir3, readFile as readFile5, readdir as readdir2, rm, stat, writeFile as writeFile3 } from "fs/promises";
-import { join as join17 } from "path";
+import { createHash as createHash3 } from "crypto";
+import { mkdir as mkdir7, readFile as readFile10, readdir as readdir3, rm as rm2, stat, writeFile as writeFile7 } from "fs/promises";
+import { join as join23 } from "path";
 import fg4 from "fast-glob";
 
 // src/skills/frontmatter-parser.ts
-import YAML3 from "yaml";
+import YAML5 from "yaml";
 
 // src/skills/loader.ts
-import { readFile as readFile6 } from "fs/promises";
+import { readFile as readFile11 } from "fs/promises";
 
 // src/update/updater.ts
 import { chmodSync as chmodSync3, existsSync as existsSync6, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync3 } from "fs";
-import { mkdtemp, readdir as readdir3, readFile as readFile7, rm as rm2 } from "fs/promises";
+import { mkdtemp, readdir as readdir4, readFile as readFile12, rm as rm3 } from "fs/promises";
 import { tmpdir } from "os";
-import { dirname as dirname6, join as join18, relative as relative5 } from "path";
-import YAML4 from "yaml";
+import { dirname as dirname10, join as join24, relative as relative6 } from "path";
+import YAML6 from "yaml";
 var FrameworkUpdater = class {
   constructor(options = {}) {
     this.options = options;
   }
   async run(projectRoot) {
-    const previousVersion = readText(join18(projectRoot, PATHS.FRAMEWORK_VERSION));
+    const previousVersion = readText(join24(projectRoot, PATHS.FRAMEWORK_VERSION));
     const manifest = readManifest(projectRoot);
     const artifactPolicy = new Map(
       manifest?.generated_artifacts.map((artifact) => [artifact.path, artifact.auto_update]) ?? []
@@ -2491,7 +3500,7 @@ var FrameworkUpdater = class {
     const skipped = [];
     const newScripts = [];
     for (const candidate of candidates) {
-      const target = join18(projectRoot, candidate.path);
+      const target = join24(projectRoot, candidate.path);
       const existed = existsSync6(target);
       const autoUpdate = artifactPolicy.get(candidate.path) ?? candidate.autoUpdate;
       if (existed && autoUpdate === false) {
@@ -2502,7 +3511,7 @@ var FrameworkUpdater = class {
         });
         continue;
       }
-      mkdirSync4(dirname6(target), { recursive: true });
+      mkdirSync4(dirname10(target), { recursive: true });
       writeFileSync3(target, candidate.content);
       if (candidate.executable === true) {
         chmodSync3(target, 493);
@@ -2512,8 +3521,8 @@ var FrameworkUpdater = class {
         newScripts.push(candidate.path);
       }
     }
-    mkdirSync4(dirname6(join18(projectRoot, PATHS.FRAMEWORK_VERSION)), { recursive: true });
-    writeFileSync3(join18(projectRoot, PATHS.FRAMEWORK_VERSION), `${VERSION}
+    mkdirSync4(dirname10(join24(projectRoot, PATHS.FRAMEWORK_VERSION)), { recursive: true });
+    writeFileSync3(join24(projectRoot, PATHS.FRAMEWORK_VERSION), `${VERSION}
 `);
     return {
       previous_version: previousVersion,
@@ -2533,7 +3542,7 @@ var FrameworkUpdater = class {
     if (profile === null) {
       throw new Error("Cannot update framework-managed artifacts without a project profile");
     }
-    const tempRoot = await mkdtemp(join18(tmpdir(), "paqad-ai-update-"));
+    const tempRoot = await mkdtemp(join24(tmpdir(), "paqad-ai-update-"));
     try {
       const result = await new OnboardingOrchestrator().run({
         projectRoot: tempRoot,
@@ -2543,23 +3552,23 @@ var FrameworkUpdater = class {
       const files = await collectFiles(tempRoot, result.generated_files);
       return files;
     } finally {
-      await rm2(tempRoot, { recursive: true, force: true });
+      await rm3(tempRoot, { recursive: true, force: true });
     }
   }
 };
 function readManifest(projectRoot) {
-  const path = join18(projectRoot, PATHS.ONBOARDING_MANIFEST);
+  const path = join24(projectRoot, PATHS.ONBOARDING_MANIFEST);
   if (!existsSync6(path)) {
     return null;
   }
   return JSON.parse(readFileSync5(path, "utf8"));
 }
 function readProfile(projectRoot) {
-  const path = join18(projectRoot, PATHS.PROJECT_PROFILE);
+  const path = join24(projectRoot, PATHS.PROJECT_PROFILE);
   if (!existsSync6(path)) {
     return null;
   }
-  return YAML4.parse(readFileSync5(path, "utf8"));
+  return YAML6.parse(readFileSync5(path, "utf8"));
 }
 function readText(path) {
   if (!existsSync6(path)) {
@@ -2568,42 +3577,52 @@ function readText(path) {
   return readFileSync5(path, "utf8").trim();
 }
 async function collectFiles(root, generated) {
-  const paths = generated.length > 0 ? generated : await walk2(root);
+  const paths = generated.length > 0 ? generated : await walk3(root);
   return Promise.all(
     paths.map(async (file) => ({
       path: file,
-      content: await readFile7(join18(root, file), "utf8"),
+      content: await readFile12(join24(root, file), "utf8"),
       autoUpdate: true,
       executable: file.startsWith("scripts/")
     }))
   );
 }
-async function walk2(root, current = root) {
-  const entries = await readdir3(current, { withFileTypes: true });
+async function walk3(root, current = root) {
+  const entries = await readdir4(current, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const absolute = join18(current, entry.name);
+    const absolute = join24(current, entry.name);
     if (entry.isDirectory()) {
-      files.push(...await walk2(root, absolute));
+      files.push(...await walk3(root, absolute));
       continue;
     }
-    files.push(relative5(root, absolute));
+    files.push(relative6(root, absolute));
   }
   return files.sort();
 }
 
 // src/verification/gates/documentation-freshness.ts
 import { existsSync as existsSync7 } from "fs";
-import { join as join19 } from "path";
+import { join as join25 } from "path";
 var STALENESS_WINDOW_MS2 = 1e3 * 60 * 60 * 24 * 7;
 
 // src/index.ts
-var VERSION = "0.0.1";
+var VERSION = "0.0.4";
 
-// src/cli/commands/doctor.ts
+// src/cli/commands/document.ts
 import { Command } from "commander";
+function createDocumentCommand() {
+  return new Command("document").description("Generate project documentation from the current codebase").option("--project-root <path>", "Project root", process.cwd()).option("--scope <scope>", "Scope to generate", "full").option("--dry-run", "Preview without writing files").option("--resume", "Resume from the existing progress tracker").option("--refresh-stack", "Refresh stack introspection before generation").option("--refresh-tokens", "Refresh design-system docs before generation").action(
+    async (options) => {
+      await runDocumentCommand(options);
+    }
+  );
+}
+
+// src/cli/commands/doctor.ts
+import { Command as Command2 } from "commander";
 function createDoctorCommand() {
-  return new Command("doctor").description("Check framework health and suggest fixes").option("--project-root <path>", "Project root", process.cwd()).action(async (options) => {
+  return new Command2("doctor").description("Check framework health and suggest fixes").option("--project-root <path>", "Project root", process.cwd()).action(async (options) => {
     const report = await new HealthChecker().run(options.projectRoot);
     console.log(JSON.stringify(report, null, 2));
     process.exitCode = report.overall_status === "fail" ? 1 : 0;
@@ -2611,18 +3630,18 @@ function createDoctorCommand() {
 }
 
 // src/cli/commands/install.ts
-import { Command as Command2 } from "commander";
+import { Command as Command3 } from "commander";
 function createInstallCommand() {
-  return new Command2("install").description("Bootstrap the framework into the current project").option("--project-root <path>", "Project root", process.cwd()).action((options) => {
+  return new Command3("install").description("Bootstrap the framework into the current project").option("--project-root <path>", "Project root", process.cwd()).action((options) => {
     const result = bootstrapFramework(options.projectRoot);
     console.log(JSON.stringify(result, null, 2));
   });
 }
 
 // src/cli/commands/onboard.ts
-import { Command as Command3 } from "commander";
+import { Command as Command4 } from "commander";
 function createOnboardCommand() {
-  return new Command3("onboard").description("Full project onboarding").option("--project-root <path>", "Project root", process.cwd()).option("--domain <domain>", "Force the target domain").option("--stack <stack>", "Force the target stack").option("--capability <capability...>", "Add one or more capabilities").action(
+  return new Command4("onboard").description("Full project onboarding").option("--project-root <path>", "Project root", process.cwd()).option("--domain <domain>", "Force the target domain").option("--stack <stack>", "Force the target stack").option("--capability <capability...>", "Add one or more capabilities").action(
     async (options) => {
       const orchestrator = new OnboardingOrchestrator();
       await orchestrator.run({
@@ -2638,16 +3657,24 @@ function createOnboardCommand() {
 }
 
 // src/cli/commands/refresh.ts
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 function createRefreshCommand() {
-  return new Command4("refresh").description("Refresh indexes and registries").action(() => {
+  return new Command5("refresh").description("Refresh derived framework artifacts").option("--project-root <path>", "Project root", process.cwd()).option("--design-system", "Refresh design-system markdown from design tokens").option("--stack", "Refresh the cached stack snapshot").action(async (options) => {
+    const shouldRefreshDesignSystem = options.designSystem ?? true;
+    const shouldRefreshStack = options.stack ?? true;
+    if (shouldRefreshDesignSystem) {
+      await new DesignTokenService().writeDocs(options.projectRoot);
+    }
+    if (shouldRefreshStack) {
+      await new StackIntrospector().snapshot(options.projectRoot);
+    }
   });
 }
 
 // src/cli/commands/update.ts
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 function createUpdateCommand() {
-  return new Command5("update").description("Update framework-managed artifacts").option("--project-root <path>", "Project root", process.cwd()).action(async (options) => {
+  return new Command6("update").description("Update framework-managed artifacts").option("--project-root <path>", "Project root", process.cwd()).action(async (options) => {
     const report = await new FrameworkUpdater().run(options.projectRoot);
     console.log(JSON.stringify(report, null, 2));
   });
@@ -2655,10 +3682,11 @@ function createUpdateCommand() {
 
 // src/cli/program.ts
 function createProgram() {
-  const program = new Command6();
+  const program = new Command7();
   program.name("paqad-ai").description("AI Agency Framework for software agencies").version(VERSION).showSuggestionAfterError(true);
   program.addCommand(createInstallCommand());
   program.addCommand(createDoctorCommand());
+  program.addCommand(createDocumentCommand());
   program.addCommand(createOnboardCommand());
   program.addCommand(createRefreshCommand());
   program.addCommand(createUpdateCommand());