@texturehq/edges 1.29.1 → 1.30.1

package/scripts/generate-edges-docs.js

@@ -1,1127 +0,0 @@
-// 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 escapeMarkdownTableCell(text) {
-  // Only escape backslashes since the text will be wrapped in backticks (inline code).
-  // Pipes and backticks don't need escaping inside inline code spans.
-  return text.replace(/\\/g, "\\\\");
-}
-
-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 = "";
-    // Use regex patterns with word boundaries to avoid substring matches
-    const patterns = [
-      new RegExp(`export\\s+function\\s+${name}\\s*[({<]`),
-      new RegExp(`export\\s+const\\s+${name}\\s*[:=]`),
-      new RegExp(`export\\s+class\\s+${name}\\s+`),
-    ];
-
-    for (const pattern of patterns) {
-      const match = content.search(pattern);
-      if (match !== -1) {
-        idx = match;
-        break;
-      }
-    }
-
-    if (idx !== -1) {
-      description = getJsdocAbove(content, idx);
-    }
-
-    // Extract props
-    const props = extractProps(content, name);
-    // Sort props alphabetically for deterministic output
-    props.sort((a, b) => a.name.localeCompare(b.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 removed to prevent unnecessary git churn
-    // Use version field to track which package version generated this
-    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 lines = jsdocMatch[1]
-          .split("\n")
-          .map((line) => line.replace(/^\s*\*\s?/, "").trim());
-
-        // Extract only the main description (before any @tags)
-        const descriptionLines = [];
-        for (const line of lines) {
-          if (line.startsWith("@")) {
-            break; // Stop at first @tag
-          }
-          if (line) {
-            descriptionLines.push(line);
-          }
-        }
-
-        return descriptionLines.join(" ").trim();
-      }
-    }
-  }
-  return "";
-}
-
-function extractExportsFromFile(filePath) {
-  const content = read(filePath);
-  if (!content) return [];
-
-  const utilities = [];
-
-  // Helper to check if a match is inside a comment
-  function isInComment(matchIndex) {
-    const beforeMatch = content.slice(0, matchIndex);
-
-    // Check if we're inside a JSDoc comment (/** ... */)
-    const lastJSDocStart = beforeMatch.lastIndexOf("/**");
-    const lastJSDocEnd = beforeMatch.lastIndexOf("*/");
-    if (lastJSDocStart > lastJSDocEnd) {
-      return true; // Inside JSDoc comment
-    }
-
-    // Check if we're inside a regular block comment (/* ... */)
-    const lastBlockStart = beforeMatch.lastIndexOf("/*");
-    const lastBlockEnd = beforeMatch.lastIndexOf("*/");
-    if (lastBlockStart > lastBlockEnd) {
-      // Make sure it's not a JSDoc opener (/**)
-      const blockOpener = beforeMatch.slice(lastBlockStart, lastBlockStart + 3);
-      if (blockOpener !== "/**") {
-        return true; // Inside regular block comment
-      }
-    }
-
-    // Check if we're on a line comment (//)
-    const lastNewline = beforeMatch.lastIndexOf("\n");
-    const lineStart = lastNewline === -1 ? 0 : lastNewline + 1;
-    const line = beforeMatch.slice(lineStart);
-    if (line.includes("//")) {
-      return true; // Inside line comment
-    }
-
-    return false;
-  }
-
-  // Match export function declarations
-  const functionPattern = /export\s+(?:async\s+)?function\s+(\w+)/g;
-  let match;
-  while ((match = functionPattern.exec(content))) {
-    if (!isInComment(match.index)) {
-      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))) {
-    if (!isInComment(match.index)) {
-      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 removed to prevent unnecessary git churn
-    // Use version field to track which package version generated this
-    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) {
-          const safeType = escapeMarkdownTableCell(prop.type);
-          content += `| \`${prop.name}\` | \`${safeType}\` |\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-brand\` - Brand-focused actions
-- \`action-secondary\` - Secondary actions
-- \`action-default\` - Default gray 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;
-  // Use version instead of timestamp to avoid git churn
-  const version = componentsManifest.version || PACKAGE_VERSION;
-
-  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
-- **Integrations** (Optional) like React Hook Form support
-
-## 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
-
-### Integrations (Optional)
-- [React Hook Form (RHF)](integrations-rhf.md) - Opt-in adapters and utilities for fast form building
-
-## 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";
-\`\`\`
-
-## Integrations
-
-React Hook Form integration is available as an optional subpath and tree-shakes when unused.
-
-\`\`\`bash
-yarn add react-hook-form @hookform/resolvers zod
-\`\`\`
-
-\`\`\`typescript
-import { RHFForm, RHFTextField } from "@texturehq/edges/rhf";
-\`\`\`
-
-## 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\`
- - **Integrations (Optional)**: \`docs/ai/edges/integrations-rhf.md\`
-
----
-
-**Package Version:** ${version}
-`;
-
-  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
-
-### Forms + RHF (Optional)
-
-- Import adapters from \`@texturehq/edges/rhf\`; install optional peers: \`react-hook-form @hookform/resolvers zod\`
-- Quickstart:
-  \`\`\`tsx
-  import { RHFForm, RHFTextField, SubmitButton, ErrorSummary } from "@texturehq/edges/rhf";
-  \`\`\`
-- Full guide: \`docs/ai/edges/integrations-rhf.md\`
-
-### 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);
-}
-
-// ============================================================================
-// INTEGRATIONS DOCS
-// ============================================================================
-
-function generateIntegrationsDocs() {
-  console.log("\n🔗 Generating integrations docs...");
-  const rhfReadmeSrc = path.join(SRC_DIR, "integrations", "rhf", "README.md");
-  const rhfDocDest = path.join(DOCS_AI_EDGES, "integrations-rhf.md");
-  const content = read(rhfReadmeSrc);
-  if (content) {
-    writeFile(rhfDocDest, content);
-  } else {
-    console.log("  ℹ️  RHF README not found, skipping integrations-rhf.md");
-  }
-}
-
-// ============================================================================
-// 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);
-  generateIntegrationsDocs();
-
-  // Generate agent instruction fragment
-  generateEdgesFragment(componentsManifest, utilitiesManifest);
-
-  // Merge all agent instruction fragments
-  console.log("\n🔀 Merging agent instruction fragments...");
-  try {
-    const output = execSync("ts-node scripts/merge-agent-instructions.ts", {
-      cwd: MONO_ROOT,
-      encoding: "utf8",
-      stdio: "pipe",
-    });
-    console.log(output);
-  } 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);
-});