@texturehq/edges 1.7.2 → 1.7.4

package/scripts/generate-edges-docs.js

@@ -0,0 +1,1004 @@
+// generate-edges-docs.js
+// Unified AI Context Generator for @texturehq/edges
+//
+// Consolidates and enhances:
+// - generate-components-manifest.js
+// - generate-utilities-manifest.js
+//
+// Generates:
+// - Component, utility, and hook manifests
+// - docs/ai/edges/ markdown documentation
+// - .agent-fragments/edges.md (for merging with other fragments)
+// - .cursor/rules/edges-components.mdc
+// - Distributable context files for consuming apps
+
+import { execSync } from "child_process";
+import fs from "fs";
+import path from "path";
+
+const ROOT = process.cwd();
+const SRC_DIR = path.join(ROOT, "src");
+const DIST_DIR = path.join(ROOT, "dist");
+const MONO_ROOT = path.join(ROOT, "../..");
+const DOCS_AI_EDGES = path.join(MONO_ROOT, "docs/ai/edges");
+
+const PACKAGE_JSON_PATH = path.join(ROOT, "package.json");
+const PACKAGE_VERSION = JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, "utf8")).version;
+
+// ============================================================================
+// UTILITIES
+// ============================================================================
+
+function read(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFile(filePath, content) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, content, "utf8");
+  console.log(`✓ Generated: ${filePath}`);
+}
+
+// ============================================================================
+// COMPONENT MANIFEST GENERATION
+// ============================================================================
+
+function extractExportsFromIndex(indexContent) {
+  const re = /export\s+\{\s*([A-Za-z0-9_,\s]+)\s*\}\s+from\s+"\.\/components\/([A-Za-z0-9_/.-]+)"/g;
+  const results = [];
+  let m;
+  while ((m = re.exec(indexContent))) {
+    const exported = m[1]
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const rel = m[2];
+    for (const name of exported) {
+      results.push({ name, relPath: rel });
+    }
+  }
+  return results;
+}
+
+function findComponentFile(relPath) {
+  const base = path.join(SRC_DIR, "components", relPath);
+  const componentName = relPath.split("/").pop();
+  const candidates = [
+    path.join(base, `${componentName}.tsx`),
+    path.join(base, `${componentName}.ts`),
+    path.join(base, `index.tsx`),
+    path.join(base, `index.ts`),
+  ];
+  for (const f of candidates) {
+    if (fs.existsSync(f)) return f;
+  }
+  return null;
+}
+
+function findStorybookFile(relPath) {
+  const base = path.join(SRC_DIR, "components", relPath);
+  const componentName = relPath.split("/").pop();
+  const candidates = [path.join(base, `${componentName}.stories.tsx`), path.join(base, `${componentName}.stories.ts`)];
+  for (const f of candidates) {
+    if (fs.existsSync(f)) return f;
+  }
+  return null;
+}
+
+function extractStorybookCategory(storyContent) {
+  // Extract: title: "Form Controls/Button"
+  const titleMatch = storyContent.match(/title:\s*["']([^"']+)["']/);
+  if (titleMatch) {
+    const fullTitle = titleMatch[1];
+    const parts = fullTitle.split("/");
+    if (parts.length > 1) {
+      return parts[0]; // "Form Controls"
+    }
+  }
+  return null;
+}
+
+function extractRelatedComponents(storyContent) {
+  // Find other component imports in the story file
+  const importMatch = storyContent.match(/import\s*\{([^}]+)\}\s*from\s*["']\.\.\/(\w+)["']/g);
+  const related = new Set();
+  if (importMatch) {
+    for (const imp of importMatch) {
+      const m = imp.match(/import\s*\{([^}]+)\}/);
+      if (m) {
+        const imports = m[1].split(",").map((s) => s.trim());
+        for (const name of imports) {
+          if (/^[A-Z]/.test(name)) {
+            related.add(name);
+          }
+        }
+      }
+    }
+  }
+  return Array.from(related);
+}
+
+function getJsdocAbove(content, idx) {
+  const upTo = content.slice(0, idx);
+  const start = upTo.lastIndexOf("/**");
+  const end = upTo.lastIndexOf("*/");
+  if (start !== -1 && end !== -1 && end > start) {
+    const block = upTo.slice(start + 3, end).trim();
+    return block
+      .split("\n")
+      .map((l) => l.replace(/^\s*\*\s?/, "").trim())
+      .join(" ")
+      .trim();
+  }
+  return "";
+}
+
+function extractProps(content, componentName) {
+  const ifaceRe = new RegExp(
+    `export\\s+interface\\s+${componentName}Props\\s*(?:extends\\s+[^{]+)?\\{([\\s\\S]*?)\\}`,
+    "m",
+  );
+  let m = ifaceRe.exec(content);
+  if (!m) {
+    const anyIfaceRe = /export\s+interface\s+([A-Za-z0-9_]+Props)\s*(?:extends\s+[^{]+)?\{([\s\S]*?)\}/m;
+    m = anyIfaceRe.exec(content);
+  }
+  if (!m) {
+    const typeRe = new RegExp(`export\\s+type\\s+${componentName}Props\\s*=\\s*(?:[^{&]+&\s*)?([\\s\\S]*?)\\}`, "m");
+    m = typeRe.exec(content);
+  }
+  const props = [];
+  if (m) {
+    const body = m[2] || m[1] || "";
+    // Parse props more carefully to handle nested types
+    let currentProp = "";
+    let braceDepth = 0;
+    const lines = body.split("\n");
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith("//")) continue;
+
+      // Count braces to track nested objects
+      for (const char of trimmed) {
+        if (char === "{") braceDepth++;
+        if (char === "}") braceDepth--;
+      }
+
+      currentProp += (currentProp ? " " : "") + trimmed;
+
+      // If we're at depth 0 and the line ends with semicolon or we're complete, process the prop
+      if (braceDepth === 0 && (trimmed.endsWith(";") || trimmed.endsWith(","))) {
+        const pm = /^(readonly\s+)?([A-Za-z0-9_]+)\??:\s*(.+?)[;,]?\s*$/.exec(currentProp.trim());
+        if (pm) {
+          const name = pm[2];
+          let type = pm[3].trim();
+          // Clean up type - remove trailing semicolon/comma
+          type = type.replace(/[;,]\s*$/, "");
+          // Simplify very long nested types for readability
+          if (type.includes("{") && type.length > 100) {
+            // For nested object types, show simplified version
+            type = type.substring(0, 80) + "...}";
+          }
+          props.push({ name, type });
+        }
+        currentProp = "";
+        braceDepth = 0;
+      }
+    }
+  }
+  return props;
+}
+
+function generateComponentsManifest() {
+  console.log("\n📦 Generating components manifest...");
+
+  const indexPath = path.join(SRC_DIR, "index.ts");
+  const indexContent = read(indexPath);
+  const exports = extractExportsFromIndex(indexContent);
+
+  const components = [];
+  const categories = {};
+
+  for (const { name, relPath } of exports) {
+    if (!/^[A-Z]/.test(name)) continue;
+
+    const componentFile = findComponentFile(relPath);
+    if (!componentFile) continue;
+    const content = read(componentFile);
+
+    // Extract description from JSDoc
+    let idx = -1;
+    let description = "";
+    const patterns = [
+      `export function ${name}`,
+      `export const ${name}:`,
+      `export const ${name} =`,
+      `export class ${name}`,
+      new RegExp(`export\\s+const\\s+${name}\\s*[:=]`),
+      new RegExp(`export\\s+function\\s+${name}\\s*[(<]`),
+    ];
+
+    for (const pattern of patterns) {
+      if (typeof pattern === "string") {
+        idx = content.indexOf(pattern);
+      } else {
+        const match = content.search(pattern);
+        if (match !== -1) idx = match;
+      }
+      if (idx !== -1) break;
+    }
+
+    if (idx !== -1) {
+      description = getJsdocAbove(content, idx);
+    }
+
+    // Extract props
+    const props = extractProps(content, name);
+
+    // Extract Storybook metadata
+    const storyFile = findStorybookFile(relPath);
+    let category = "Uncategorized";
+    let relatedComponents = [];
+
+    if (storyFile) {
+      const storyContent = read(storyFile);
+      const storyCategory = extractStorybookCategory(storyContent);
+      if (storyCategory) category = storyCategory;
+      relatedComponents = extractRelatedComponents(storyContent);
+    }
+
+    const component = {
+      name,
+      category,
+      description,
+      importRoot: "@texturehq/edges",
+      importPath: `@texturehq/edges/components/${name}`,
+      props,
+      relatedComponents,
+      storybookPath: category + "/" + name,
+    };
+
+    components.push(component);
+
+    // Organize by category
+    if (!categories[category]) {
+      categories[category] = [];
+    }
+    categories[category].push(name);
+  }
+
+  // Sort components by name
+  components.sort((a, b) => a.name.localeCompare(b.name));
+
+  // Sort category arrays
+  for (const cat in categories) {
+    categories[cat].sort();
+  }
+
+  const manifest = {
+    version: PACKAGE_VERSION,
+    generatedAt: new Date().toISOString(),
+    components: components,
+    categories: categories,
+  };
+
+  ensureDir(DIST_DIR);
+  writeFile(path.join(DIST_DIR, "components.manifest.json"), JSON.stringify(manifest, null, 2));
+
+  console.log(`  Found ${components.length} components in ${Object.keys(categories).length} categories`);
+  return manifest;
+}
+
+// ============================================================================
+// UTILITIES & HOOKS MANIFEST GENERATION
+// ============================================================================
+
+function extractJSDoc(content, functionName) {
+  const patterns = [
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+(?:async\\s+)?function\\s+${functionName}\\b`, "s"),
+    new RegExp(`\\/\\*\\*([^*]|\\*(?!\\/))*\\*\\/\\s*export\\s+const\\s+${functionName}\\s*=`, "s"),
+  ];
+
+  for (const pattern of patterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const jsdocMatch = match[0].match(/\/\*\*([\s\S]*?)\*\//);
+      if (jsdocMatch) {
+        const cleaned = jsdocMatch[1]
+          .split("\n")
+          .map((line) => line.replace(/^\s*\*\s?/, "").trim())
+          .filter((line) => line && !line.startsWith("@"))
+          .join(" ")
+          .trim();
+        return cleaned;
+      }
+    }
+  }
+  return "";
+}
+
+function extractExportsFromFile(filePath) {
+  const content = read(filePath);
+  if (!content) return [];
+
+  const utilities = [];
+
+  // Match export function declarations
+  const functionPattern = /export\s+(?:async\s+)?function\s+(\w+)/g;
+  let match;
+  while ((match = functionPattern.exec(content))) {
+    const name = match[1];
+    utilities.push({
+      name,
+      type: "function",
+      description: extractJSDoc(content, name),
+    });
+  }
+
+  // Match export const arrow functions and constants
+  const constPattern = /export\s+const\s+(\w+)\s*(?::\s*[^=]+)?\s*=/g;
+  while ((match = constPattern.exec(content))) {
+    const name = match[1];
+    const afterMatch = content.slice(match.index + match[0].length, match.index + match[0].length + 50);
+    const isFunction = afterMatch.includes("=>") || afterMatch.includes("function");
+
+    utilities.push({
+      name,
+      type: isFunction ? "function" : "constant",
+      description: extractJSDoc(content, name),
+    });
+  }
+
+  return utilities;
+}
+
+function scanDirectory(dir, category) {
+  const utilities = [];
+
+  if (!fs.existsSync(dir)) return utilities;
+
+  const files = fs.readdirSync(dir);
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    const stat = fs.statSync(filePath);
+
+    if (stat.isDirectory() && file !== "__tests__" && file !== "tests") {
+      utilities.push(...scanDirectory(filePath, `${category}/${file}`));
+    } else if ((file.endsWith(".ts") || file.endsWith(".tsx")) && !file.endsWith(".d.ts")) {
+      if (file.includes(".test.") || file.includes(".spec.") || file.includes(".stories.")) {
+        continue;
+      }
+
+      const funcs = extractExportsFromFile(filePath);
+      for (const func of funcs) {
+        utilities.push({
+          ...func,
+          category,
+          file: path.relative(SRC_DIR, filePath),
+        });
+      }
+    }
+  }
+
+  return utilities;
+}
+
+function generateUtilitiesManifest() {
+  console.log("\n🔧 Generating utilities manifest...");
+
+  const manifest = {
+    version: PACKAGE_VERSION,
+    generatedAt: new Date().toISOString(),
+    categories: {},
+  };
+
+  // Scan hooks directory
+  const hooksDir = path.join(SRC_DIR, "hooks");
+  const hooks = scanDirectory(hooksDir, "hooks");
+  if (hooks.length > 0) {
+    manifest.categories.hooks = {
+      description:
+        "React hooks for common functionality like breakpoints, debouncing, local storage, and media queries",
+      utilities: hooks.sort((a, b) => a.name.localeCompare(b.name)),
+    };
+  }
+
+  // Scan formatting utilities
+  const formattingDir = path.join(SRC_DIR, "utils/formatting");
+  const formatting = scanDirectory(formattingDir, "formatting");
+  if (formatting.length > 0) {
+    manifest.categories.formatting = {
+      description:
+        "Comprehensive formatting utilities for text, numbers, dates, currency, energy, temperature, distance, and more",
+      utilities: formatting.sort((a, b) => a.name.localeCompare(b.name)),
+    };
+  }
+
+  // Chart utilities
+  const chartsDir = path.join(SRC_DIR, "utils/charts");
+  const charts = scanDirectory(chartsDir, "charts");
+  const chartExportUtils = extractExportsFromFile(path.join(SRC_DIR, "utils/chartExport.ts"));
+  const chartUtils = extractExportsFromFile(path.join(SRC_DIR, "utils/charts.ts"));
+  const allChartUtils = [
+    ...charts,
+    ...chartExportUtils.map((f) => ({ ...f, category: "charts", file: "utils/chartExport.ts" })),
+    ...chartUtils.map((f) => ({ ...f, category: "charts", file: "utils/charts.ts" })),
+  ];
+
+  if (allChartUtils.length > 0) {
+    manifest.categories.charts = {
+      description: "Chart utilities for data visualization, scaling, and export functionality",
+      utilities: allChartUtils.sort((a, b) => a.name.localeCompare(b.name)),
+    };
+  }
+
+  // Color utilities
+  const colorUtils = extractExportsFromFile(path.join(SRC_DIR, "utils/colors.ts"));
+  if (colorUtils.length > 0) {
+    manifest.categories.colors = {
+      description:
+        "Color management utilities for theme-aware color resolution, contrast calculation, and palette generation",
+      utilities: colorUtils
+        .map((f) => ({ ...f, category: "colors", file: "utils/colors.ts" }))
+        .sort((a, b) => a.name.localeCompare(b.name)),
+    };
+  }
+
+  const totalUtilities = Object.values(manifest.categories).reduce((sum, cat) => sum + cat.utilities.length, 0);
+
+  ensureDir(DIST_DIR);
+  writeFile(path.join(DIST_DIR, "utilities.manifest.json"), JSON.stringify(manifest, null, 2));
+
+  console.log(`  Found ${totalUtilities} utilities in ${Object.keys(manifest.categories).length} categories`);
+  return manifest;
+}
+
+// ============================================================================
+// THEME PARSING
+// ============================================================================
+
+function parseThemeColors() {
+  console.log("\n🎨 Parsing theme colors...");
+
+  const distThemePath = path.join(DIST_DIR, "theme.css");
+  const sources = [];
+
+  if (fs.existsSync(distThemePath)) {
+    sources.push(distThemePath);
+  } else {
+    const generatedDir = path.join(SRC_DIR, "generated");
+    const fallbackFiles = [
+      path.join(generatedDir, "tailwind-tokens-light.css"),
+      path.join(generatedDir, "tailwind-tokens-dark.css"),
+      path.join(generatedDir, "viz-runtime.css"),
+    ];
+
+    for (const file of fallbackFiles) {
+      if (fs.existsSync(file)) {
+        sources.push(file);
+      }
+    }
+
+    if (sources.length > 0) {
+      console.log("  ℹ️  Using generated token CSS as fallback (dist/theme.css missing)");
+    }
+  }
+
+  if (sources.length === 0) {
+    console.log("  ⚠️  No theme CSS sources found, skipping color extraction");
+    return {};
+  }
+
+  const colorVars = {};
+  const seen = new Set();
+  const colorRegex = /--color-([a-zA-Z0-9-]+):\s*([^;]+);/g;
+
+  for (const source of sources) {
+    const themeContent = read(source);
+    let match;
+
+    while ((match = colorRegex.exec(themeContent))) {
+      const varName = match[1];
+      const value = match[2].trim();
+
+      if (!seen.has(varName)) {
+        seen.add(varName);
+        colorVars[varName] = value;
+      }
+    }
+  }
+
+  console.log(`  Found ${Object.keys(colorVars).length} color variables`);
+  return colorVars;
+}
+
+// ============================================================================
+// MARKDOWN DOCUMENTATION GENERATION
+// ============================================================================
+
+function generateComponentsReference(componentsManifest) {
+  console.log("\n📝 Generating components reference...");
+
+  const { components, categories } = componentsManifest;
+
+  let content = `# Edges Components Reference
+
+> **Auto-generated** - Do not edit manually. Run \`node scripts/generate-edges-docs.js\` to regenerate.
+
+This document provides a complete reference of all ${components.length} components in the @texturehq/edges design system, organized by functional category.
+
+## Quick Navigation
+
+`;
+
+  // Table of contents by category
+  const sortedCategories = Object.keys(categories).sort();
+  for (const category of sortedCategories) {
+    const count = categories[category].length;
+    content += `- [${category}](#${category.toLowerCase().replace(/\s+/g, "-")}) (${count} component${count > 1 ? "s" : ""})\n`;
+  }
+
+  content += `\n---\n\n`;
+
+  // Generate content by category
+  for (const category of sortedCategories) {
+    content += `## ${category}\n\n`;
+
+    const categoryComponents = components.filter((c) => c.category === category);
+    categoryComponents.sort((a, b) => a.name.localeCompare(b.name));
+
+    for (const component of categoryComponents) {
+      content += `### ${component.name}\n\n`;
+
+      if (component.description) {
+        content += `${component.description}\n\n`;
+      }
+
+      content += `**Import:**\n\n`;
+      content += `\`\`\`typescript\n`;
+      content += `import { ${component.name} } from "${component.importRoot}";\n`;
+      content += `// or\n`;
+      content += `import { ${component.name} } from "${component.importPath}";\n`;
+      content += `\`\`\`\n\n`;
+
+      if (component.props && component.props.length > 0) {
+        content += `**Props:**\n\n`;
+        content += `| Prop | Type |\n`;
+        content += `|------|------|\n`;
+        for (const prop of component.props) {
+          content += `| \`${prop.name}\` | \`${prop.type}\` |\n`;
+        }
+        content += `\n`;
+      }
+
+      if (component.relatedComponents && component.relatedComponents.length > 0) {
+        content += `**Related:** ${component.relatedComponents.join(", ")}\n\n`;
+      }
+
+      if (component.storybookPath) {
+        content += `**Storybook:** \`${component.storybookPath}\`\n\n`;
+      }
+
+      content += `---\n\n`;
+    }
+  }
+
+  writeFile(path.join(DOCS_AI_EDGES, "components-reference.md"), content);
+}
+
+function generateHooksReference(utilitiesManifest) {
+  console.log("\n🪝 Generating hooks reference...");
+
+  const hooksCategory = utilitiesManifest.categories.hooks;
+  if (!hooksCategory) {
+    console.log("  No hooks found");
+    return;
+  }
+
+  const hooks = hooksCategory.utilities;
+
+  let content = `# Edges Hooks Reference
+
+> **Auto-generated** - Do not edit manually. Run \`node scripts/generate-edges-docs.js\` to regenerate.
+
+This document provides a complete reference of all ${hooks.length} React hooks in the @texturehq/edges design system.
+
+${hooksCategory.description}
+
+## Available Hooks
+
+`;
+
+  for (const hook of hooks) {
+    content += `### ${hook.name}\n\n`;
+
+    if (hook.description) {
+      content += `${hook.description}\n\n`;
+    }
+
+    content += `**Import:**\n\n`;
+    content += `\`\`\`typescript\n`;
+    content += `import { ${hook.name} } from "@texturehq/edges";\n`;
+    content += `\`\`\`\n\n`;
+
+    content += `**Source:** \`src/${hook.file}\`\n\n`;
+    content += `---\n\n`;
+  }
+
+  writeFile(path.join(DOCS_AI_EDGES, "hooks-reference.md"), content);
+}
+
+function generateUtilitiesReference(utilitiesManifest) {
+  console.log("\n🛠️  Generating utilities reference...");
+
+  const categories = Object.keys(utilitiesManifest.categories).filter((c) => c !== "hooks");
+  if (categories.length === 0) {
+    console.log("  No utilities found");
+    return;
+  }
+
+  let content = `# Edges Utilities Reference
+
+> **Auto-generated** - Do not edit manually. Run \`node scripts/generate-edges-docs.js\` to regenerate.
+
+This document provides a complete reference of all utility functions in the @texturehq/edges design system.
+
+## Categories
+
+`;
+
+  for (const category of categories) {
+    const cat = utilitiesManifest.categories[category];
+    content += `- [${category}](#${category}) (${cat.utilities.length} utilities)\n`;
+  }
+
+  content += `\n---\n\n`;
+
+  for (const category of categories) {
+    const cat = utilitiesManifest.categories[category];
+    content += `## ${category}\n\n`;
+    content += `${cat.description}\n\n`;
+
+    for (const util of cat.utilities) {
+      content += `### ${util.name}\n\n`;
+
+      if (util.description) {
+        content += `${util.description}\n\n`;
+      }
+
+      content += `**Type:** ${util.type}\n\n`;
+      content += `**Import:**\n\n`;
+      content += `\`\`\`typescript\n`;
+      content += `import { ${util.name} } from "@texturehq/edges";\n`;
+      content += `\`\`\`\n\n`;
+
+      content += `**Source:** \`src/${util.file}\`\n\n`;
+      content += `---\n\n`;
+    }
+  }
+
+  writeFile(path.join(DOCS_AI_EDGES, "utilities-reference.md"), content);
+}
+
+function generateThemeSystemDoc(colorVars) {
+  console.log("\n🎨 Generating theme system documentation...");
+
+  let content = `# Edges Theme System
+
+> **Auto-generated** - Do not edit manually. Run \`node scripts/generate-edges-docs.js\` to regenerate.
+
+## Overview
+
+The @texturehq/edges design system uses Tailwind 4 with CSS variables. All design tokens are defined as CSS variables and automatically become available as Tailwind utility classes.
+
+## Setup
+
+\`\`\`css
+@import "@texturehq/edges/theme.css";
+\`\`\`
+
+## How It Works
+
+CSS variables automatically become Tailwind classes:
+- \`--color-brand-primary\` → \`bg-brand-primary\`, \`text-brand-primary\`, \`border-brand-primary\`
+- \`--spacing-md\` → \`p-md\`, \`m-md\`, \`gap-md\`
+- \`--text-lg\` → \`text-lg\`
+- \`--radius-lg\` → \`rounded-lg\`
+
+## Color System
+
+The theme includes ${Object.keys(colorVars).length} color variables organized by purpose:
+
+### Brand Colors
+- \`brand-primary\` - Primary brand color
+- \`brand-light\` - Light brand variant
+- \`brand-dark\` - Dark brand variant
+
+### Text Colors
+- \`text-body\` - Body text
+- \`text-heading\` - Heading text
+- \`text-muted\` - Muted/secondary text
+- \`text-caption\` - Caption/helper text
+- \`text-on-primary\` - Text on primary backgrounds
+
+### Background Colors
+- \`background-body\` - Main page background
+- \`background-surface\` - Card/surface background
+- \`background-muted\` - Muted background
+- \`background-subtle\` - Subtle background
+
+### Border Colors
+- \`border-default\` - Default border
+- \`border-focus\` - Focused border
+- \`border-muted\` - Muted border
+- \`border-subtle\` - Subtle border
+
+### Action Colors
+- \`action-primary\` - Primary actions
+- \`action-secondary\` - Secondary actions
+- \`action-destructive\` - Destructive actions
+
+### Feedback Colors
+- \`feedback-success\` - Success state
+- \`feedback-error\` - Error state
+- \`feedback-warning\` - Warning state
+- \`feedback-info\` - Info state
+
+## Usage Guidelines
+
+**✅ Good - Use semantic classes:**
+\`\`\`tsx
+<div className="bg-brand-primary text-text-on-primary p-md rounded-lg shadow-md">
+  <h2 className="text-text-heading text-lg font-medium">Title</h2>
+  <p className="text-text-body text-base">Content</p>
+</div>
+\`\`\`
+
+**❌ Avoid - Arbitrary values:**
+\`\`\`tsx
+<div className="bg-[#444ae1] text-[#ffffff] p-[1rem] rounded-[0.5rem]">
+  <h2 className="text-[#111827] text-[1.125rem] font-[500]">Title</h2>
+  <p className="text-[#333333] text-[1rem]">Content</p>
+</div>
+\`\`\`
+
+## Spacing Scale
+
+- \`xs\`, \`sm\`, \`md\`, \`lg\`, \`xl\`, \`2xl\`, \`3xl\`, \`4xl\`
+
+## Typography Scale
+
+- \`xs\`, \`sm\`, \`base\`, \`lg\`, \`xl\`, \`2xl\`, \`3xl\`, \`4xl\`
+
+## Border Radius Scale
+
+- \`xs\`, \`sm\`, \`md\`, \`lg\`, \`xl\`, \`2xl\`, \`3xl\`, \`4xl\`
+
+## Dark Mode
+
+All colors automatically adapt to dark mode when the \`.theme-dark\` class is present on a parent element.
+
+## Available Variables
+
+The theme includes:
+- Complete color system (${Object.keys(colorVars).length} color variables)
+- Spacing scale
+- Typography scale  
+- Border radius scale
+- Shadow system
+- Animation definitions
+- Form control specifications
+`;
+
+  writeFile(path.join(DOCS_AI_EDGES, "theme-system.md"), content);
+}
+
+function generateEdgesReadme(componentsManifest, utilitiesManifest) {
+  console.log("\n📄 Generating edges README...");
+
+  const componentCount = componentsManifest.components.length;
+  const categoryCount = Object.keys(componentsManifest.categories).length;
+  const hookCount = utilitiesManifest.categories.hooks?.utilities.length || 0;
+
+  let utilityCount = 0;
+  for (const cat in utilitiesManifest.categories) {
+    if (cat !== "hooks") {
+      utilityCount += utilitiesManifest.categories[cat].utilities.length;
+    }
+  }
+
+  let content = `# Edges Design System - AI Context
+
+> **Auto-generated** - Do not edit manually. Run \`node scripts/generate-edges-docs.js\` to regenerate.
+
+👋 **AI Agents: Start here!**
+
+Complete documentation for the @texturehq/edges design system.
+
+## What's Inside
+
+- **${componentCount} Components** across ${categoryCount} categories
+- **${hookCount} React Hooks** for common functionality
+- **${utilityCount} Utility Functions** for formatting, charts, colors, and more
+- **Complete Theme System** with Tailwind 4 + CSS variables
+
+## Quick Links
+
+### Component Library
+- [Components Reference](components-reference.md) - All ${componentCount} components organized by category
+- [Component Categories](#component-categories) - Quick navigation by function
+
+### Utilities & Hooks
+- [Hooks Reference](hooks-reference.md) - All ${hookCount} React hooks
+- [Utilities Reference](utilities-reference.md) - All ${utilityCount} utility functions
+
+### Design System
+- [Theme System](theme-system.md) - Colors, spacing, typography with Tailwind 4
+- [Patterns](patterns.md) - Common UI patterns and best practices
+
+## Component Categories
+
+`;
+
+  const sortedCategories = Object.keys(componentsManifest.categories).sort();
+  for (const category of sortedCategories) {
+    const components = componentsManifest.categories[category];
+    content += `### ${category}\n\n`;
+    content += `${components.join(", ")}\n\n`;
+  }
+
+  content += `## Installation
+
+\`\`\`bash
+yarn add @texturehq/edges
+\`\`\`
+
+## Setup
+
+\`\`\`css
+@import "@texturehq/edges/theme.css";
+\`\`\`
+
+\`\`\`typescript
+import { Button, TextField, DataTable } from "@texturehq/edges";
+\`\`\`
+
+## For Dashboard Development
+
+When building UI in \`apps/dashboard\`, reference:
+- **Components**: \`docs/ai/edges/components-reference.md\`
+- **Hooks**: \`docs/ai/edges/hooks-reference.md\`
+- **Utilities**: \`docs/ai/edges/utilities-reference.md\`
+- **Theme**: \`docs/ai/edges/theme-system.md\`
+- **Patterns**: \`docs/ai/edges/patterns.md\`
+
+---
+
+**Package Version:** ${componentsManifest.version}  
+**Generated:** ${new Date().toISOString()}
+`;
+
+  writeFile(path.join(DOCS_AI_EDGES, "README.md"), content);
+}
+
+// ============================================================================
+// AGENT INSTRUCTION FRAGMENT
+// ============================================================================
+
+function generateEdgesFragment(componentsManifest, utilitiesManifest) {
+  console.log("\n📄 Generating edges fragment...");
+
+  const componentCount = componentsManifest.components.length;
+  const hookCount = utilitiesManifest.categories.hooks?.utilities.length || 0;
+
+  let utilityCount = 0;
+  for (const cat in utilitiesManifest.categories) {
+    if (cat !== "hooks") {
+      utilityCount += utilitiesManifest.categories[cat].utilities.length;
+    }
+  }
+
+  const content = `<!-- priority: 20 -->
+## Edges Design System Context
+
+The @texturehq/edges design system provides ${componentCount} React components, ${hookCount} hooks, and ${utilityCount} utility functions.
+
+**Complete component documentation is in**: \`docs/ai/edges/\`
+
+### Quick Start
+
+1. Read \`docs/ai/edges/README.md\` for an overview and component categories
+2. Reference \`docs/ai/edges/components-reference.md\` for detailed component API
+3. Review \`docs/ai/edges/patterns.md\` for common UI patterns and best practices
+4. Check \`docs/ai/edges/theme-system.md\` for Tailwind 4 color tokens and styling
+
+### Additional Resources
+
+- Hooks: \`docs/ai/edges/hooks-reference.md\`
+- Utilities: \`docs/ai/edges/utilities-reference.md\`
+
+### For Dashboard Development
+
+**UI (Edges)**:
+- All components, hooks, and utilities from \`@texturehq/edges\`
+- Use semantic Tailwind classes from theme (see theme-system.md)
+- Follow patterns from \`docs/ai/edges/patterns.md\`
+
+### Common Patterns
+
+**Import**: \`import { Button, TextField } from "@texturehq/edges"\`  
+**Styling**: Use semantic classes like \`bg-brand-primary\`, \`text-text-body\`  
+**Forms**: Wrap in \`<Form>\`, use validation with \`errorMessage\`  
+**Loading**: Show \`<Skeleton>\` during data fetching  
+**Responsive**: Use \`useBreakpoint()\` hook or responsive grid cols
+`;
+
+  const fragmentsDir = path.join(MONO_ROOT, ".agent-fragments");
+  ensureDir(fragmentsDir);
+  writeFile(path.join(fragmentsDir, "edges.md"), content);
+}
+
+// ============================================================================
+// MAIN
+// ============================================================================
+
+async function main() {
+  console.log("🚀 Generating Edges AI Context...\n");
+
+  // Ensure output directories exist
+  ensureDir(DOCS_AI_EDGES);
+  ensureDir(DIST_DIR);
+
+  // Generate manifests
+  const componentsManifest = generateComponentsManifest();
+  const utilitiesManifest = generateUtilitiesManifest();
+
+  // Parse theme
+  const colorVars = parseThemeColors();
+
+  // Generate markdown documentation
+  generateComponentsReference(componentsManifest);
+  generateHooksReference(utilitiesManifest);
+  generateUtilitiesReference(utilitiesManifest);
+  generateThemeSystemDoc(colorVars);
+  generateEdgesReadme(componentsManifest, utilitiesManifest);
+
+  // Generate agent instruction fragment
+  generateEdgesFragment(componentsManifest, utilitiesManifest);
+
+  // Merge all agent instruction fragments
+  console.log("\n🔀 Merging agent instruction fragments...");
+  try {
+    execSync("ts-node scripts/merge-agent-instructions.ts", {
+      cwd: MONO_ROOT,
+      stdio: "inherit",
+    });
+  } catch (err) {
+    console.log("⚠️  Note: Could not merge agent instructions (merge script may not be available yet)");
+  }
+
+  console.log("\n✅ Edges AI context generation complete!");
+  console.log("\nGenerated files:");
+  console.log("  - dist/components.manifest.json");
+  console.log("  - dist/utilities.manifest.json");
+  console.log("  - docs/ai/edges/README.md");
+  console.log("  - docs/ai/edges/components-reference.md");
+  console.log("  - docs/ai/edges/hooks-reference.md");
+  console.log("  - docs/ai/edges/utilities-reference.md");
+  console.log("  - docs/ai/edges/theme-system.md");
+  console.log("  - .agent-fragments/edges.md");
+  console.log("  - .claude/instructions.md (merged)");
+  console.log("  - .codex/instructions.md (merged)");
+  console.log("  - .github/copilot-instructions.md (merged)");
+}
+
+main().catch((err) => {
+  console.error("❌ Failed to generate AI context:", err);
+  process.exit(1);
+});