@forge-ts/gen 0.5.0 → 0.6.0

package/dist/index.js

@@ -30,7 +30,6 @@ function pageSlug(pagePath) {
 }
 function buildDocsJson(context) {
   const { pages, projectName } = context;
-  const topLevel = [];
   const byPackage = /* @__PURE__ */ new Map();
   for (const page of pages) {
     const slug = pageSlug(page.path);
@@ -40,29 +39,56 @@ function buildDocsJson(context) {
       const list = byPackage.get(pkgName) ?? [];
       list.push(slug);
       byPackage.set(pkgName, list);
-    } else {
-      topLevel.push(slug);
     }
   }
-  const navigation = [];
-  if (topLevel.length > 0) {
-    navigation.push({ group: "Getting Started", pages: topLevel });
-  }
+  const tabs = [];
+  const docGroups = [];
+  docGroups.push({
+    group: "Getting Started",
+    pages: ["index", "getting-started"]
+  });
+  docGroups.push({
+    group: "Learn",
+    pages: ["concepts", "guides/index"]
+  });
+  docGroups.push({
+    group: "Reference",
+    pages: ["configuration", "changelog"]
+  });
+  docGroups.push({
+    group: "Community",
+    pages: ["faq", "contributing"]
+  });
+  tabs.push({ tab: "Documentation", groups: docGroups });
   if (byPackage.size > 0) {
-    const packageGroups = [];
+    const apiGroups = [];
     for (const [pkgName, slugs] of byPackage) {
-      packageGroups.push({ group: pkgName, pages: slugs });
+      const sorted = slugs.sort((a, b) => {
+        const order = (s) => {
+          if (s.endsWith("/index")) return 0;
+          if (s.includes("/api/index")) return 1;
+          if (s.includes("/api/functions")) return 2;
+          if (s.includes("/api/types")) return 3;
+          if (s.includes("/api/examples")) return 4;
+          return 5;
+        };
+        return order(a) - order(b);
+      });
+      apiGroups.push({ group: `@forge-ts/${pkgName}`, pages: sorted });
     }
-    navigation.push({
-      group: "Packages",
-      pages: packageGroups
-    });
+    tabs.push({ tab: "API Reference", groups: apiGroups });
   }
   return {
     name: projectName,
-    theme: "venus",
-    colors: { primary: "#0ea5e9" },
-    navigation
+    theme: "mint",
+    colors: { primary: "#0ea5e9", light: "#38bdf8", dark: "#0284c7" },
+    navigation: { tabs },
+    footer: {
+      socials: context.config.project.repository ? { github: context.config.project.repository } : {}
+    },
+    contextual: {
+      options: ["copy", "view", "chatgpt", "claude", "perplexity"]
+    }
   };
 }
 function addMintlifyFrontmatter(page) {
@@ -89,17 +115,39 @@ var mintlifyAdapter = {
       devDependencies: {},
       scripts: {},
       instructions: [
-        "Install Mintlify CLI: npm i -g mint",
-        "Preview locally: mint dev",
+        "Preview locally: npx @mintlify/cli dev",
         "Deploy: Push to GitHub and connect at mintlify.com"
       ]
     };
   },
   transformPages(pages, _context) {
-    return pages.map((page) => ({
-      path: page.path.replace(/\.md$/, ".mdx"),
-      content: addMintlifyFrontmatter(page)
-    }));
+    return pages.map((page) => {
+      let content = addMintlifyFrontmatter(page);
+      content = content.replace(/^# .+$/m, "").replace(/\n{3,}/g, "\n\n");
+      let insideFence = false;
+      content = content.split("\n").map((line) => {
+        if (insideFence) {
+          if (/^```\s*$/.test(line)) {
+            insideFence = false;
+          }
+          return line;
+        }
+        if (/^```\S/.test(line)) {
+          insideFence = true;
+          return line;
+        }
+        if (/^```\s*$/.test(line)) {
+          insideFence = true;
+          return "```typescript";
+        }
+        return line;
+      }).join("\n");
+      return {
+        path: page.path.replace(/\.md$/, ".mdx"),
+        content,
+        stub: page.stub
+      };
+    });
   },
   generateConfig(context) {
     const config = buildDocsJson(context);
@@ -111,10 +159,19 @@ var mintlifyAdapter = {
       }
     ];
   },
+  getDevCommand(outDir) {
+    return {
+      bin: "npx",
+      args: ["@mintlify/cli", "dev"],
+      cwd: outDir,
+      label: "Mintlify Dev Server",
+      url: "http://localhost:3000"
+    };
+  },
   async detectExisting(outDir) {
-    const { existsSync: existsSync2 } = await import("fs");
+    const { existsSync: existsSync3 } = await import("fs");
     const { join: join2 } = await import("path");
-    return existsSync2(join2(outDir, "docs.json"));
+    return existsSync3(join2(outDir, "docs.json"));
   }
 };
 registerAdapter(mintlifyAdapter);
@@ -282,7 +339,8 @@ var docusaurusAdapter = {
   transformPages(pages, _context) {
     return pages.map((page) => ({
       path: page.path.replace(/\.md$/, ".mdx"),
-      content: addDocusaurusFrontmatter(page)
+      content: addDocusaurusFrontmatter(page),
+      stub: page.stub
     }));
   },
   generateConfig(context) {
@@ -293,10 +351,19 @@ var docusaurusAdapter = {
       }
     ];
   },
+  getDevCommand(outDir) {
+    return {
+      bin: "npx",
+      args: ["docusaurus", "start"],
+      cwd: outDir,
+      label: "Docusaurus Dev Server",
+      url: "http://localhost:3000"
+    };
+  },
   async detectExisting(outDir) {
-    const { existsSync: existsSync2 } = await import("fs");
+    const { existsSync: existsSync3 } = await import("fs");
     const { join: join2 } = await import("path");
-    return existsSync2(join2(outDir, "sidebars.ts")) || existsSync2(join2(outDir, "docusaurus.config.ts")) || existsSync2(join2(outDir, "docusaurus.config.js"));
+    return existsSync3(join2(outDir, "sidebars.ts")) || existsSync3(join2(outDir, "docusaurus.config.ts")) || existsSync3(join2(outDir, "docusaurus.config.js"));
   }
 };
 registerAdapter(docusaurusAdapter);
@@ -510,16 +577,26 @@ var nextraAdapter = {
   transformPages(pages, _context) {
     return pages.map((page) => ({
       path: page.path.replace(/\.md$/, ".mdx"),
-      content: addNextraFrontmatter(page)
+      content: addNextraFrontmatter(page),
+      stub: page.stub
     }));
   },
   generateConfig(context) {
     return buildMetaFiles(context.pages);
   },
+  getDevCommand(outDir) {
+    return {
+      bin: "npx",
+      args: ["next", "dev"],
+      cwd: outDir,
+      label: "Nextra Dev Server (Next.js)",
+      url: "http://localhost:3000"
+    };
+  },
   async detectExisting(outDir) {
-    const { existsSync: existsSync2 } = await import("fs");
+    const { existsSync: existsSync3 } = await import("fs");
     const { join: join2 } = await import("path");
-    return existsSync2(join2(outDir, "content/_meta.js")) || existsSync2(join2(outDir, "next.config.ts")) || existsSync2(join2(outDir, "next.config.js"));
+    return existsSync3(join2(outDir, "content/_meta.js")) || existsSync3(join2(outDir, "next.config.ts")) || existsSync3(join2(outDir, "next.config.js"));
   }
 };
 registerAdapter(nextraAdapter);
@@ -650,7 +727,8 @@ var vitepressAdapter = {
   transformPages(pages, _context) {
     return pages.map((page) => ({
       path: page.path.endsWith(".mdx") ? page.path.replace(/\.mdx$/, ".md") : page.path,
-      content: addVitepressFrontmatter(page)
+      content: addVitepressFrontmatter(page),
+      stub: page.stub
     }));
   },
   generateConfig(context) {
@@ -661,10 +739,19 @@ var vitepressAdapter = {
       }
     ];
   },
+  getDevCommand(outDir) {
+    return {
+      bin: "npx",
+      args: ["vitepress", "dev"],
+      cwd: outDir,
+      label: "VitePress Dev Server",
+      url: "http://localhost:5173"
+    };
+  },
   async detectExisting(outDir) {
-    const { existsSync: existsSync2 } = await import("fs");
+    const { existsSync: existsSync3 } = await import("fs");
     const { join: join2 } = await import("path");
-    return existsSync2(join2(outDir, ".vitepress"));
+    return existsSync3(join2(outDir, ".vitepress"));
   }
 };
 registerAdapter(vitepressAdapter);
@@ -984,7 +1071,7 @@ function generateMarkdown(symbols, config, options = {}) {
   }
   parts.push("# API Reference\n");
   parts.push(
-    `Generated by [forge-ts](https://github.com/forge-ts/forge-ts) from \`${config.rootDir}\`.
+    `Generated by [forge-ts](https://github.com/kryptobaseddev/forge-ts) from \`${config.rootDir}\`.
 `
   );
   if (topLevel.length > 0) {
@@ -1133,6 +1220,15 @@ function buildFrontmatterFields(title, description, ssgTarget, sidebarPosition)
       return {};
   }
 }
+function slugLink(path) {
+  let slug = path.startsWith("./") ? path.slice(2) : path;
+  slug = slug.replace(/\.(mdx?)$/, "");
+  return `/${slug}`;
+}
+function truncate(text, maxLen = 80) {
+  if (text.length <= maxLen) return text;
+  return `${text.slice(0, maxLen - 3)}...`;
+}
 function groupSymbolsByPackage(symbols, rootDir) {
   const result = /* @__PURE__ */ new Map();
   for (const symbol of symbols) {
@@ -1147,45 +1243,285 @@ function groupSymbolsByPackage(symbols, rootDir) {
 }
 var TYPE_KINDS = /* @__PURE__ */ new Set(["interface", "type", "enum"]);
 var FUNCTION_KINDS = /* @__PURE__ */ new Set(["function", "class"]);
-function renderPropertyRow(child) {
-  const name = `\`${child.name}\``;
-  const type = child.signature ? `\`${escapePipe(child.signature)}\`` : "\u2014";
-  const optional = child.signature?.includes("?") || child.signature?.includes("undefined") ? "No" : "Yes";
-  const description = escapePipe(child.documentation?.summary ?? "");
-  return `| ${name} | ${type} | ${optional} | ${description} |`;
-}
-function renderOverviewPage(packageName, symbols, _options) {
+function renderProjectIndexPage(symbolsByPackage, options) {
+  const lines = [];
+  if (options.projectDescription) {
+    lines.push(`**${options.projectName}** \u2014 ${options.projectDescription}`);
+  } else {
+    lines.push(
+      `**${options.projectName}** is a TypeScript documentation toolkit that performs a single AST traversal of your project and produces API docs, OpenAPI specs, executable doctests, and AI context files in one pass.`
+    );
+  }
+  lines.push("");
+  lines.push("## Features");
+  lines.push("");
+  const pkgCount = symbolsByPackage.size;
+  if (pkgCount > 1) {
+    lines.push(`- ${pkgCount} packages with full TypeScript support`);
+  } else {
+    lines.push("- Full TypeScript support with TSDoc extraction");
+  }
+  lines.push("- Auto-generated API reference from source code");
+  lines.push("- Executable `@example` blocks as doctests");
+  lines.push("- AI-ready context files from a single build pass");
+  lines.push("");
+  lines.push("## Installation");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(`npm install -D ${options.packageName ?? "@forge-ts/cli"}`);
+  lines.push("```");
+  lines.push("");
+  let firstExample;
+  outer: for (const [, symbols] of symbolsByPackage) {
+    for (const s of symbols) {
+      if (!s.exported || s.kind !== "function") continue;
+      const ex = s.documentation?.examples?.[0];
+      if (ex) {
+        firstExample = ex;
+        break outer;
+      }
+    }
+  }
+  if (firstExample) {
+    lines.push("## Quick Example");
+    lines.push("");
+    lines.push(`\`\`\`${firstExample.language || "typescript"}`);
+    lines.push(firstExample.code.trim());
+    lines.push("```");
+    lines.push("");
+  }
+  if (symbolsByPackage.size > 0) {
+    lines.push("## Packages");
+    lines.push("");
+    lines.push("| Package | Description |");
+    lines.push("|---------|-------------|");
+    for (const [pkgName, symbols] of symbolsByPackage) {
+      const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
+      const exported = symbols.filter(
+        (s) => s.exported && s.kind !== "method" && s.kind !== "property"
+      );
+      const rawDesc = pkgDoc ?? `${exported.length} exported symbol(s).`;
+      const desc = escapePipe(truncate(rawDesc));
+      const link = `[\`${pkgName}\`](${slugLink(`packages/${pkgName}/index`)})`;
+      lines.push(`| ${link} | ${desc} |`);
+    }
+    lines.push("");
+  }
+  lines.push("## Next Steps");
+  lines.push("");
+  lines.push(`- [Getting Started](/getting-started) \u2014 Step-by-step guide`);
+  lines.push(`- [API Reference](/packages) \u2014 Full API documentation`);
+  lines.push(`- [Concepts](/concepts) \u2014 How it works`);
+  return lines.join("\n");
+}
+function renderGettingStartedPage(symbolsByPackage, options) {
+  let firstExample;
+  outer: for (const [, symbols] of symbolsByPackage) {
+    for (const s of symbols) {
+      if (!s.exported || s.kind !== "function") continue;
+      const ex = s.documentation?.examples?.[0];
+      if (ex) {
+        firstExample = ex;
+        break outer;
+      }
+    }
+  }
+  const lines = [];
+  lines.push(`Get up and running with **${options.projectName}** in minutes.`);
+  if (options.projectDescription) {
+    lines.push("");
+    lines.push(options.projectDescription);
+  }
+  lines.push("");
+  lines.push("## Step 1: Install");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(`npm install -D ${options.packageName ?? "@forge-ts/cli"}`);
+  lines.push("```");
+  lines.push("");
+  lines.push("## Step 2: Add TSDoc to your code");
+  lines.push("");
+  lines.push("Add TSDoc comments to your exported functions and types:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push("/**");
+  lines.push(" * Adds two numbers together.");
+  lines.push(" * @param a - First number");
+  lines.push(" * @param b - Second number");
+  lines.push(" * @returns The sum of a and b");
+  lines.push(" * @example");
+  lines.push(" * ```typescript");
+  lines.push(" * const result = add(1, 2); // => 3");
+  lines.push(" * ```");
+  lines.push(" */");
+  lines.push("export function add(a: number, b: number): number {");
+  lines.push("  return a + b;");
+  lines.push("}");
+  lines.push("```");
+  lines.push("");
+  lines.push("## Step 3: Run forge-ts check");
+  lines.push("");
+  lines.push("Lint your TSDoc coverage before generating docs:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("npx forge-ts check");
+  lines.push("```");
+  lines.push("");
+  lines.push("Expected output:");
+  lines.push("");
+  lines.push("```");
+  lines.push("forge-ts: checking TSDoc coverage...");
+  lines.push("  \u2713 All public symbols documented");
+  lines.push("```");
+  lines.push("");
+  lines.push("## Step 4: Generate docs");
+  lines.push("");
+  lines.push("Build your documentation site:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("npx forge-ts build");
+  lines.push("```");
+  lines.push("");
+  if (firstExample) {
+    lines.push("Your code examples become live documentation:");
+    lines.push("");
+    lines.push(`\`\`\`${firstExample.language || "typescript"}`);
+    lines.push(firstExample.code.trim());
+    lines.push("```");
+    lines.push("");
+  }
+  lines.push("## What's Next?");
+  lines.push("");
+  lines.push("- [Concepts](/concepts) \u2014 Understand how forge-ts works");
+  lines.push("- [API Reference](/packages) \u2014 Full API documentation");
+  lines.push("- [Guides](/guides) \u2014 Practical how-to guides");
+  return lines.join("\n");
+}
+function renderConceptsPage(symbolsByPackage, options) {
+  const lines = [];
+  lines.push(`This page explains the core concepts behind **${options.projectName}**.`);
+  lines.push("");
+  lines.push(
+    "> This is a stub page. Edit this file to add your project's conceptual documentation."
+  );
+  lines.push("> Auto-generated sections below (inside FORGE:AUTO markers) update on every build.");
+  lines.push("");
+  const pkgDoc = [...symbolsByPackage.values()].flatMap((syms) => syms.map((s) => s.documentation?.tags?.packageDocumentation?.[0])).find(Boolean);
+  lines.push("<!-- FORGE:AUTO-START how-it-works -->");
+  lines.push("## How It Works");
+  lines.push("");
+  if (pkgDoc) {
+    lines.push(pkgDoc);
+  } else {
+    lines.push(
+      `${options.projectName} processes your TypeScript source with a single AST traversal, extracting TSDoc comments and type information to generate documentation.`
+    );
+  }
+  lines.push("");
+  lines.push("<!-- FORGE:AUTO-END how-it-works -->");
+  lines.push("");
+  const allTypeSymbols = [...symbolsByPackage.values()].flat().filter((s) => s.exported && TYPE_KINDS.has(s.kind));
+  if (allTypeSymbols.length > 0) {
+    lines.push("<!-- FORGE:AUTO-START key-abstractions -->");
+    lines.push("## Key Abstractions");
+    lines.push("");
+    for (const s of allTypeSymbols) {
+      const desc = s.documentation?.summary ?? `The \`${s.name}\` ${s.kind}.`;
+      lines.push(`- **\`${s.name}\`** \u2014 ${desc}`);
+    }
+    lines.push("");
+    lines.push("<!-- FORGE:AUTO-END key-abstractions -->");
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderGuidesIndexPage() {
+  return [
+    "Practical how-to guides for common tasks.",
+    "",
+    "> Add your guides to the `guides/` directory. Each `.md` or `.mdx` file will appear here automatically.",
+    "",
+    "## Getting Things Done",
+    "",
+    "Guides will appear here as you add them. Start by creating a file like `guides/my-guide.md`.",
+    ""
+  ].join("\n");
+}
+function renderApiIndexPage(pkgName, symbols) {
   const exported = symbols.filter(
     (s) => s.exported && s.kind !== "method" && s.kind !== "property"
   );
-  const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
+  const functions = exported.filter((s) => FUNCTION_KINDS.has(s.kind));
+  const types = exported.filter((s) => TYPE_KINDS.has(s.kind));
+  const others = exported.filter((s) => !FUNCTION_KINDS.has(s.kind) && !TYPE_KINDS.has(s.kind));
   const lines = [];
-  lines.push(`# ${packageName}`);
-  lines.push("");
+  const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
   if (pkgDoc) {
     lines.push(pkgDoc);
     lines.push("");
+  } else {
+    lines.push(`API reference for the \`${pkgName}\` package.`);
+    lines.push("");
   }
-  if (exported.length > 0) {
-    lines.push("## Exported Symbols");
+  const renderGroup = (group, heading, pathSuffix) => {
+    if (group.length === 0) return;
+    lines.push(`## ${heading}`);
     lines.push("");
     lines.push("| Symbol | Kind | Description |");
     lines.push("|--------|------|-------------|");
-    for (const s of exported) {
+    for (const s of group) {
       const ext = s.kind === "function" ? "()" : "";
-      const name = `[\`${s.name}${ext}\`](./api-reference.md#${toAnchor2(`${s.name}${ext}`)})`;
-      const summary = escapePipe(s.documentation?.summary ?? "");
-      lines.push(`| ${name} | ${s.kind} | ${summary} |`);
+      const anchor = toAnchor2(`${s.name}${ext}`);
+      const link = `[\`${s.name}${ext}\`](${slugLink(`packages/${pkgName}/${pathSuffix}`)}#${anchor})`;
+      const rawSummary = s.documentation?.summary ?? "";
+      const summary = escapePipe(truncate(rawSummary));
+      lines.push(`| ${link} | ${s.kind} | ${summary} |`);
     }
     lines.push("");
+  };
+  renderGroup(functions, "Functions & Classes", "api/functions");
+  renderGroup(types, "Types & Interfaces", "api/types");
+  renderGroup(others, "Other Exports", "api/functions");
+  return lines.join("\n");
+}
+function renderPackageOverviewPage(packageName, symbols, _options) {
+  const exported = symbols.filter(
+    (s) => s.exported && s.kind !== "method" && s.kind !== "property"
+  );
+  const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
+  const lines = [];
+  if (pkgDoc) {
+    lines.push(pkgDoc);
+    lines.push("");
+  }
+  if (exported.length > 0) {
+    const functions = exported.filter((s) => FUNCTION_KINDS.has(s.kind));
+    const types = exported.filter((s) => TYPE_KINDS.has(s.kind));
+    const others = exported.filter((s) => !FUNCTION_KINDS.has(s.kind) && !TYPE_KINDS.has(s.kind));
+    const renderGroup = (group, heading) => {
+      if (group.length === 0) return;
+      lines.push(`## ${heading}`);
+      lines.push("");
+      lines.push("| Symbol | Kind | Description |");
+      lines.push("|--------|------|-------------|");
+      for (const s of group) {
+        const ext = s.kind === "function" ? "()" : "";
+        const name = `[\`${s.name}${ext}\`](${slugLink(`packages/${packageName}/api/index`)}#${toAnchor2(`${s.name}${ext}`)})`;
+        const rawSummary = s.documentation?.summary ?? "";
+        const summary = escapePipe(truncate(rawSummary));
+        lines.push(`| ${name} | ${s.kind} | ${summary} |`);
+      }
+      lines.push("");
+    };
+    renderGroup(functions, "Functions & Classes");
+    renderGroup(types, "Types & Interfaces");
+    renderGroup(others, "Other Exports");
   }
   return lines.join("\n");
 }
 function renderTypesPage(packageName, symbols, _options) {
   const typeSymbols = symbols.filter((s) => s.exported && TYPE_KINDS.has(s.kind));
   const lines = [];
-  lines.push(`# ${packageName} \u2014 Types`);
-  lines.push("");
   lines.push("Type contracts exported by this package: interfaces, type aliases, and enums.");
   lines.push("");
   for (const s of typeSymbols) {
@@ -1210,22 +1546,24 @@ function renderTypesPage(packageName, symbols, _options) {
       lines.push("| Property | Type | Required | Description |");
       lines.push("|----------|------|----------|-------------|");
       for (const child of children) {
-        lines.push(renderPropertyRow(child));
+        const name = `\`${child.name}\``;
+        const type = child.signature ? `\`${escapePipe(child.signature)}\`` : "\u2014";
+        const optional = child.signature?.includes("?") || child.signature?.includes("undefined") ? "No" : "Yes";
+        const description = escapePipe(child.documentation?.summary || child.name);
+        lines.push(`| ${name} | ${type} | ${optional} | ${description} |`);
       }
       lines.push("");
     }
   }
+  void packageName;
   return lines.join("\n");
 }
 function renderFunctionsPage(packageName, symbols, _options) {
   const fnSymbols = symbols.filter((s) => s.exported && FUNCTION_KINDS.has(s.kind));
   const lines = [];
-  lines.push(`# ${packageName} \u2014 Functions & Classes`);
-  lines.push("");
   lines.push("Functions and classes exported by this package.");
   lines.push("");
   for (const s of fnSymbols) {
-    const _ext = s.kind === "function" ? "()" : "";
     const paramSig = s.kind === "function" && s.documentation?.params ? s.documentation.params.map((p) => p.name).join(", ") : "";
     const heading = s.kind === "function" ? `${s.name}(${paramSig})` : s.name;
     lines.push(`## ${heading}`);
@@ -1253,7 +1591,14 @@ function renderFunctionsPage(packageName, symbols, _options) {
       lines.push("| Name | Type | Description |");
       lines.push("|------|------|-------------|");
       for (const p of params) {
-        const type = p.type ? `\`${escapePipe(p.type)}\`` : "\u2014";
+        let resolvedType = p.type;
+        if (!resolvedType && s.signature) {
+          const typeMatch = new RegExp(`\\b${p.name}\\s*[?:]\\s*([^,)]+)`).exec(s.signature);
+          if (typeMatch) {
+            resolvedType = typeMatch[1].trim();
+          }
+        }
+        const type = resolvedType ? `\`${escapePipe(resolvedType)}\`` : "\u2014";
         lines.push(`| \`${p.name}\` | ${type} | ${escapePipe(p.description)} |`);
       }
       lines.push("");
@@ -1278,7 +1623,7 @@ function renderFunctionsPage(packageName, symbols, _options) {
       const ex = examples[0];
       lines.push("**Example**");
       lines.push("");
-      lines.push(`\`\`\`${ex.language}`);
+      lines.push(`\`\`\`${ex.language || "typescript"}`);
       lines.push(ex.code.trim());
       lines.push("```");
       lines.push("");
@@ -1303,6 +1648,7 @@ function renderFunctionsPage(packageName, symbols, _options) {
       }
     }
   }
+  void packageName;
   return lines.join("\n");
 }
 function renderExamplesPage(packageName, symbols, _options) {
@@ -1310,8 +1656,6 @@ function renderExamplesPage(packageName, symbols, _options) {
     (s) => s.exported && s.kind !== "method" && s.kind !== "property"
   );
   const lines = [];
-  lines.push(`# ${packageName} \u2014 Examples`);
-  lines.push("");
   lines.push("All usage examples from the package, aggregated for quick reference.");
   lines.push("");
   let hasExamples = false;
@@ -1326,10 +1670,12 @@ function renderExamplesPage(packageName, symbols, _options) {
       lines.push(`_${s.documentation.summary}_`);
       lines.push("");
     }
-    lines.push(`[View in API reference](./api-reference.md#${toAnchor2(s.name)})`);
+    lines.push(
+      `[View in API reference](${slugLink(`packages/${packageName}/api/functions`)}#${toAnchor2(s.name)})`
+    );
     lines.push("");
     for (const ex of examples) {
-      lines.push(`\`\`\`${ex.language}`);
+      lines.push(`\`\`\`${ex.language || "typescript"}`);
       lines.push(ex.code.trim());
       lines.push("```");
       lines.push("");
@@ -1341,184 +1687,94 @@ function renderExamplesPage(packageName, symbols, _options) {
   }
   return lines.join("\n");
 }
-var KIND_ORDER2 = [
-  "function",
-  "class",
-  "interface",
-  "type",
-  "enum",
-  "variable"
-];
-var KIND_LABELS2 = {
-  function: "Functions",
-  class: "Classes",
-  interface: "Interfaces",
-  type: "Types",
-  enum: "Enums",
-  variable: "Variables"
-};
-function renderApiSymbol(symbol, depth) {
-  const hashes = "#".repeat(depth);
-  const ext = symbol.kind === "function" || symbol.kind === "method" ? "()" : "";
+function renderConfigurationPage(symbolsByPackage, options) {
+  const configSymbol = [...symbolsByPackage.values()].flat().find((s) => s.exported && TYPE_KINDS.has(s.kind) && /config/i.test(s.name));
   const lines = [];
-  lines.push(`${hashes} \`${symbol.name}${ext}\``);
+  lines.push(`Configuration reference for **${options.projectName}**.`);
   lines.push("");
-  if (symbol.documentation?.deprecated) {
-    lines.push(`> **Deprecated**: ${symbol.documentation.deprecated}`);
-    lines.push("");
-  }
-  if (symbol.signature) {
-    lines.push("```typescript");
-    lines.push(symbol.signature);
-    lines.push("```");
-    lines.push("");
-  }
-  if (symbol.documentation?.summary) {
-    lines.push(symbol.documentation.summary);
-    lines.push("");
-  }
-  const params = symbol.documentation?.params ?? [];
-  if (params.length > 0) {
-    lines.push("**Parameters**");
-    lines.push("");
-    for (const p of params) {
-      const typeStr = p.type ? ` (\`${p.type}\`)` : "";
-      lines.push(`- \`${p.name}\`${typeStr} \u2014 ${p.description}`);
-    }
-    lines.push("");
-  }
-  if (symbol.documentation?.returns) {
-    const retType = symbol.documentation.returns.type ? ` (\`${symbol.documentation.returns.type}\`)` : "";
-    lines.push(`**Returns**${retType}: ${symbol.documentation.returns.description}`);
-    lines.push("");
-  }
-  const throws = symbol.documentation?.throws ?? [];
-  if (throws.length > 0) {
-    lines.push("**Throws**");
+  lines.push("## forge-ts.config.ts");
+  lines.push("");
+  lines.push("Create a `forge-ts.config.ts` file in your project root:");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push('import { defineConfig } from "@forge-ts/core";');
+  lines.push("");
+  lines.push("export default defineConfig({");
+  lines.push('  rootDir: ".",');
+  lines.push('  outDir: "docs/generated",');
+  lines.push("});");
+  lines.push("```");
+  lines.push("");
+  if (configSymbol) {
+    lines.push(`## \`${configSymbol.name}\``);
     lines.push("");
-    for (const t of throws) {
-      const typeStr = t.type ? `\`${t.type}\` \u2014 ` : "";
-      lines.push(`- ${typeStr}${t.description}`);
+    if (configSymbol.documentation?.summary) {
+      lines.push(configSymbol.documentation.summary);
+      lines.push("");
     }
-    lines.push("");
-  }
-  const examples = symbol.documentation?.examples ?? [];
-  if (examples.length > 0) {
-    lines.push("**Examples**");
-    lines.push("");
-    for (const ex of examples) {
-      lines.push(`\`\`\`${ex.language}`);
-      lines.push(ex.code.trim());
-      lines.push("```");
+    const children = (configSymbol.children ?? []).filter(
+      (c) => c.kind === "property" || c.kind === "method"
+    );
+    if (children.length > 0) {
+      lines.push("| Property | Type | Required | Description |");
+      lines.push("|----------|------|----------|-------------|");
+      for (const child of children) {
+        const name = `\`${child.name}\``;
+        const type = child.signature ? `\`${escapePipe(child.signature)}\`` : "\u2014";
+        const optional = child.signature?.includes("?") || child.signature?.includes("undefined") ? "No" : "Yes";
+        const description = escapePipe(child.documentation?.summary || child.name);
+        lines.push(`| ${name} | ${type} | ${optional} | ${description} |`);
+      }
       lines.push("");
     }
   }
-  const children = symbol.children ?? [];
-  if (children.length > 0 && depth < 5) {
-    for (const child of children) {
-      lines.push(renderApiSymbol(child, depth + 1));
-    }
-  }
   return lines.join("\n");
 }
-function renderApiReferencePage(packageName, symbols) {
-  const exported = symbols.filter(
-    (s) => s.exported && s.kind !== "method" && s.kind !== "property"
-  );
-  const groups = /* @__PURE__ */ new Map();
-  for (const s of exported) {
-    const list = groups.get(s.kind) ?? [];
-    list.push(s);
-    groups.set(s.kind, list);
-  }
-  const lines = [];
-  lines.push(`# ${packageName} \u2014 API Reference`);
-  lines.push("");
-  for (const kind of KIND_ORDER2) {
-    const group = groups.get(kind);
-    if (!group || group.length === 0) continue;
-    lines.push(`## ${KIND_LABELS2[kind]}`);
-    lines.push("");
-    for (const s of group) {
-      lines.push(renderApiSymbol(s, 3));
-      lines.push("");
-    }
-  }
-  return lines.join("\n");
-}
-function renderProjectIndexPage(symbolsByPackage, options) {
-  const lines = [];
-  lines.push(`# ${options.projectName}`);
-  lines.push("");
-  if (options.projectDescription) {
-    lines.push(options.projectDescription);
-    lines.push("");
-  }
-  lines.push("## Packages");
-  lines.push("");
-  for (const [pkgName, symbols] of symbolsByPackage) {
-    const exported = symbols.filter(
-      (s) => s.exported && s.kind !== "method" && s.kind !== "property"
-    );
-    const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
-    const summary = pkgDoc ?? `${exported.length} exported symbol(s).`;
-    lines.push(`### [${pkgName}](./packages/${pkgName}/index.md)`);
-    lines.push("");
-    lines.push(summary);
-    lines.push("");
-  }
-  return lines.join("\n");
-}
-function renderGettingStartedPage(symbolsByPackage, options) {
-  let firstExample;
-  let firstSymbolName = "";
-  let firstPackageName = "";
-  outer: for (const [pkgName, symbols] of symbolsByPackage) {
-    for (const s of symbols) {
-      if (!s.exported || s.kind !== "function") continue;
-      const ex = s.documentation?.examples?.[0];
-      if (ex) {
-        firstExample = ex;
-        firstSymbolName = s.name;
-        firstPackageName = pkgName;
-        break outer;
-      }
-    }
-  }
-  const lines = [];
-  lines.push("# Getting Started");
-  lines.push("");
-  lines.push(`Welcome to **${options.projectName}**.`);
-  if (options.projectDescription) {
-    lines.push("");
-    lines.push(options.projectDescription);
-  }
-  lines.push("");
-  lines.push("## Installation");
-  lines.push("");
-  lines.push("```bash");
-  lines.push(`npm install ${options.projectName}`);
-  lines.push("```");
-  lines.push("");
-  if (firstExample) {
-    lines.push("## Quick Start");
-    lines.push("");
-    lines.push(
-      `The following example demonstrates \`${firstSymbolName}\` from the \`${firstPackageName}\` package.`
-    );
-    lines.push("");
-    lines.push(`\`\`\`${firstExample.language}`);
-    lines.push(firstExample.code.trim());
-    lines.push("```");
-    lines.push("");
-  }
-  lines.push("## Next Steps");
-  lines.push("");
-  lines.push("- Browse the [API Reference](./packages/)");
-  for (const pkgName of symbolsByPackage.keys()) {
-    lines.push(`  - [${pkgName}](./packages/${pkgName}/api-reference.md)`);
-  }
-  return lines.join("\n");
+function renderChangelogPage(options) {
+  const repoUrl = options.repositoryUrl ?? "";
+  const changelogLink = repoUrl ? `See [CHANGELOG.md](${repoUrl}/blob/main/CHANGELOG.md) for the full release history.` : "See your project's `CHANGELOG.md` for the full release history.";
+  return [
+    `Release history for **${options.projectName}**.`,
+    "",
+    "> This is a stub page. Link to or embed your `CHANGELOG.md` here.",
+    "",
+    changelogLink,
+    ""
+  ].join("\n");
+}
+function renderFaqPage(options) {
+  return [
+    `Frequently asked questions about **${options.projectName}**.`,
+    "",
+    "> This is a stub page. Common questions will be added here as they arise.",
+    "",
+    "## How do I configure forge-ts?",
+    "",
+    "Create a `forge-ts.config.ts` file in your project root. See [Configuration](/configuration).",
+    "",
+    "## What TypeScript version is required?",
+    "",
+    "forge-ts requires TypeScript 5.0 or later.",
+    "",
+    "## How do I run @example blocks as tests?",
+    "",
+    "```bash",
+    "npx forge-ts test",
+    "```",
+    ""
+  ].join("\n");
+}
+function renderContributingPage(options) {
+  const repoUrl = options.repositoryUrl ?? "";
+  const contribLink = repoUrl ? `See [CONTRIBUTING.md](${repoUrl}/blob/main/CONTRIBUTING.md) for contribution guidelines.` : "See your project's `CONTRIBUTING.md` for contribution guidelines.";
+  return [
+    `Contributing to **${options.projectName}**.`,
+    "",
+    "> This is a stub page. Link to or embed your `CONTRIBUTING.md` here.",
+    "",
+    contribLink,
+    ""
+  ].join("\n");
 }
 function generateDocSite(symbolsByPackage, config, options) {
   const ext = options.format === "mdx" ? "mdx" : "md";
@@ -1549,10 +1805,38 @@ function generateDocSite(symbolsByPackage, config, options) {
 `,
     frontmatter: gettingStartedFrontmatter
   });
+  const conceptsContent = renderConceptsPage(symbolsByPackage, options);
+  const conceptsFrontmatter = buildFrontmatterFields(
+    "Concepts",
+    `Core concepts behind ${options.projectName}`,
+    options.ssgTarget,
+    3
+  );
+  pages.push({
+    path: `concepts.${ext}`,
+    content: `${serializeFrontmatter(conceptsFrontmatter)}${conceptsContent.trimEnd()}
+`,
+    frontmatter: conceptsFrontmatter,
+    stub: true
+  });
+  const guidesContent = renderGuidesIndexPage();
+  const guidesFrontmatter = buildFrontmatterFields(
+    "Guides",
+    `How-to guides for ${options.projectName}`,
+    options.ssgTarget,
+    4
+  );
+  pages.push({
+    path: `guides/index.${ext}`,
+    content: `${serializeFrontmatter(guidesFrontmatter)}${guidesContent.trimEnd()}
+`,
+    frontmatter: guidesFrontmatter,
+    stub: true
+  });
   let pkgPosition = 1;
   for (const [pkgName, symbols] of symbolsByPackage) {
     const pkgBase = `packages/${pkgName}`;
-    const overviewContent = renderOverviewPage(pkgName, symbols, options);
+    const overviewContent = renderPackageOverviewPage(pkgName, symbols, options);
     const overviewFrontmatter = buildFrontmatterFields(
       pkgName,
       `${pkgName} package overview`,
@@ -1565,29 +1849,17 @@ function generateDocSite(symbolsByPackage, config, options) {
 `,
       frontmatter: overviewFrontmatter
     });
-    const apiContent = renderApiReferencePage(pkgName, symbols);
-    const apiFrontmatter = buildFrontmatterFields(
+    const apiIndexContent = renderApiIndexPage(pkgName, symbols);
+    const apiIndexFrontmatter = buildFrontmatterFields(
       `${pkgName} \u2014 API Reference`,
       `Full API reference for the ${pkgName} package`,
       options.ssgTarget
     );
     pages.push({
-      path: `${pkgBase}/api-reference.${ext}`,
-      content: `${serializeFrontmatter(apiFrontmatter)}${apiContent.trimEnd()}
-`,
-      frontmatter: apiFrontmatter
-    });
-    const typesContent = renderTypesPage(pkgName, symbols, options);
-    const typesFrontmatter = buildFrontmatterFields(
-      `${pkgName} \u2014 Types`,
-      `Type contracts for the ${pkgName} package`,
-      options.ssgTarget
-    );
-    pages.push({
-      path: `${pkgBase}/types.${ext}`,
-      content: `${serializeFrontmatter(typesFrontmatter)}${typesContent.trimEnd()}
+      path: `${pkgBase}/api/index.${ext}`,
+      content: `${serializeFrontmatter(apiIndexFrontmatter)}${apiIndexContent.trimEnd()}
 `,
-      frontmatter: typesFrontmatter
+      frontmatter: apiIndexFrontmatter
     });
     const functionsContent = renderFunctionsPage(pkgName, symbols, options);
     const functionsFrontmatter = buildFrontmatterFields(
@@ -1596,11 +1868,23 @@ function generateDocSite(symbolsByPackage, config, options) {
       options.ssgTarget
     );
     pages.push({
-      path: `${pkgBase}/functions.${ext}`,
+      path: `${pkgBase}/api/functions.${ext}`,
       content: `${serializeFrontmatter(functionsFrontmatter)}${functionsContent.trimEnd()}
 `,
       frontmatter: functionsFrontmatter
     });
+    const typesContent = renderTypesPage(pkgName, symbols, options);
+    const typesFrontmatter = buildFrontmatterFields(
+      `${pkgName} \u2014 Types`,
+      `Type contracts for the ${pkgName} package`,
+      options.ssgTarget
+    );
+    pages.push({
+      path: `${pkgBase}/api/types.${ext}`,
+      content: `${serializeFrontmatter(typesFrontmatter)}${typesContent.trimEnd()}
+`,
+      frontmatter: typesFrontmatter
+    });
     const examplesContent = renderExamplesPage(pkgName, symbols, options);
     const examplesFrontmatter = buildFrontmatterFields(
       `${pkgName} \u2014 Examples`,
@@ -1608,17 +1892,595 @@ function generateDocSite(symbolsByPackage, config, options) {
       options.ssgTarget
     );
     pages.push({
-      path: `${pkgBase}/examples.${ext}`,
+      path: `${pkgBase}/api/examples.${ext}`,
       content: `${serializeFrontmatter(examplesFrontmatter)}${examplesContent.trimEnd()}
 `,
       frontmatter: examplesFrontmatter
     });
     pkgPosition++;
   }
+  const configContent = renderConfigurationPage(symbolsByPackage, options);
+  const configFrontmatter = buildFrontmatterFields(
+    "Configuration",
+    `Configuration reference for ${options.projectName}`,
+    options.ssgTarget
+  );
+  pages.push({
+    path: `configuration.${ext}`,
+    content: `${serializeFrontmatter(configFrontmatter)}${configContent.trimEnd()}
+`,
+    frontmatter: configFrontmatter
+  });
+  const changelogContent = renderChangelogPage(options);
+  const changelogFrontmatter = buildFrontmatterFields(
+    "Changelog",
+    `Release history for ${options.projectName}`,
+    options.ssgTarget
+  );
+  pages.push({
+    path: `changelog.${ext}`,
+    content: `${serializeFrontmatter(changelogFrontmatter)}${changelogContent.trimEnd()}
+`,
+    frontmatter: changelogFrontmatter,
+    stub: true
+  });
+  const faqContent = renderFaqPage(options);
+  const faqFrontmatter = buildFrontmatterFields(
+    "FAQ",
+    `Frequently asked questions about ${options.projectName}`,
+    options.ssgTarget
+  );
+  pages.push({
+    path: `faq.${ext}`,
+    content: `${serializeFrontmatter(faqFrontmatter)}${faqContent.trimEnd()}
+`,
+    frontmatter: faqFrontmatter,
+    stub: true
+  });
+  const contributingContent = renderContributingPage(options);
+  const contributingFrontmatter = buildFrontmatterFields(
+    "Contributing",
+    `How to contribute to ${options.projectName}`,
+    options.ssgTarget
+  );
+  pages.push({
+    path: `contributing.${ext}`,
+    content: `${serializeFrontmatter(contributingFrontmatter)}${contributingContent.trimEnd()}
+`,
+    frontmatter: contributingFrontmatter,
+    stub: true
+  });
   void config;
   return pages;
 }
 
+// src/skill.ts
+function toDirectoryName(name) {
+  return name.replace(/^@[^/]+\//, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+}
+function isConceptKind(kind) {
+  return kind === "interface" || kind === "type" || kind === "class" || kind === "enum";
+}
+function primaryBinName(config) {
+  const bin = config.project.bin;
+  if (!bin) return void 0;
+  const keys = Object.keys(bin);
+  if (keys.length === 0) return void 0;
+  const pkgShort = config.project.packageName?.replace(/^@[^/]+\//, "");
+  return keys.find((k) => k === pkgShort) ?? keys[0];
+}
+function buildDescription(symbols, config) {
+  const exported = symbols.filter((s) => s.exported);
+  const projectName = config.project.packageName ?? config.rootDir.split("/").pop() ?? "this project";
+  const pkgDoc = symbols.find((s) => s.documentation?.tags?.packageDocumentation);
+  const leadSentence = config.project.description ?? pkgDoc?.documentation?.summary ?? exported.find((s) => s.documentation?.summary)?.documentation?.summary;
+  const triggers = [];
+  let n = 1;
+  const cliName = primaryBinName(config);
+  if (cliName) {
+    triggers.push(`(${n++}) running ${cliName} CLI commands`);
+  }
+  const functionCount = exported.filter((s) => s.kind === "function").length;
+  if (functionCount > 0) {
+    triggers.push(`(${n++}) calling its ${functionCount} API functions`);
+  }
+  const hasRoutes = exported.some((s) => s.documentation?.tags?.route !== void 0);
+  if (hasRoutes) {
+    triggers.push(`(${n++}) building HTTP API routes`);
+  }
+  const configSym = exported.find(
+    (s) => (s.kind === "interface" || s.kind === "type") && /config/i.test(s.name) && (s.children?.length ?? 0) > 0
+  );
+  if (configSym) {
+    triggers.push(`(${n++}) configuring ${projectName}`);
+  }
+  const typeCount = exported.filter(
+    (s) => s.kind === "interface" || s.kind === "type" || s.kind === "enum"
+  ).length;
+  if (typeCount > 0) {
+    triggers.push(`(${n++}) understanding its ${typeCount} type definitions`);
+  }
+  const classCount = exported.filter((s) => s.kind === "class").length;
+  if (classCount > 0) {
+    triggers.push(`(${n++}) working with its ${classCount} classes`);
+  }
+  const keywords = config.project.keywords ?? [];
+  if (keywords.length > 0) {
+    const kwStr = keywords.slice(0, 5).join('", "');
+    triggers.push(`(${n++}) user mentions "${kwStr}"`);
+  }
+  triggers.push(`(${n}) user mentions "${projectName}" or asks about its API`);
+  let description = "";
+  if (leadSentence) {
+    description += `${leadSentence} `;
+  }
+  description += `Use when: ${triggers.join(", ")}.`;
+  if (description.length > 1024) {
+    description = `${description.slice(0, 1021)}...`;
+  }
+  return description;
+}
+function renderQuickStart(symbols, config) {
+  const lines = [];
+  const projectName = config.project.packageName ?? "project";
+  const cliName = primaryBinName(config);
+  lines.push("## Quick Start");
+  lines.push("");
+  lines.push("```bash");
+  lines.push(`npm install ${cliName ? "-D " : ""}${projectName}`);
+  lines.push("```");
+  lines.push("");
+  if (cliName && config.project.scripts) {
+    const scripts = config.project.scripts;
+    const relevantKeys = ["check", "test", "build", "lint", "dev", "start", "generate"];
+    const cliCommands = [];
+    for (const key of relevantKeys) {
+      const script = scripts[key];
+      if (script && script.includes(cliName)) {
+        cliCommands.push(`npx ${cliName} ${key}`);
+      }
+    }
+    if (cliCommands.length === 0) {
+      cliCommands.push(`npx ${cliName} --help`);
+    }
+    if (cliCommands.length > 0) {
+      lines.push("```bash");
+      for (const cmd of cliCommands.slice(0, 5)) {
+        lines.push(cmd);
+      }
+      lines.push("```");
+      lines.push("");
+    }
+  } else {
+    const exported = symbols.filter((s) => s.exported);
+    for (const sym of exported) {
+      if (sym.kind !== "function" && sym.kind !== "class") continue;
+      const ex = sym.documentation?.examples?.[0];
+      if (ex) {
+        lines.push(`\`\`\`${ex.language || "typescript"}`);
+        lines.push(ex.code.trim());
+        lines.push("```");
+        lines.push("");
+        break;
+      }
+    }
+  }
+  return lines;
+}
+function renderApiSummaryTable(symbols) {
+  const exported = symbols.filter((s) => s.exported);
+  const functions = exported.filter((s) => s.kind === "function");
+  if (functions.length === 0) return [];
+  const lines = [];
+  lines.push("## API");
+  lines.push("");
+  lines.push("| Function | Description |");
+  lines.push("|----------|-------------|");
+  for (const fn of functions.slice(0, 15)) {
+    const desc = fn.documentation?.summary ?? "";
+    lines.push(`| \`${fn.name}()\` | ${desc} |`);
+  }
+  if (functions.length > 15) {
+    lines.push(`| ... | ${functions.length - 15} more \u2014 see API reference |`);
+  }
+  lines.push("");
+  return lines;
+}
+function renderKeyTypes(symbols, max = 10) {
+  const lines = [];
+  let count = 0;
+  for (const sym of symbols) {
+    if (count >= max) break;
+    if (!sym.exported) continue;
+    if (!isConceptKind(sym.kind)) continue;
+    const summary = sym.documentation?.summary ?? "";
+    const label = summary ? `**\`${sym.name}\`** \u2014 ${summary}` : `**\`${sym.name}\`**`;
+    lines.push(`- ${label}`);
+    count++;
+  }
+  return lines;
+}
+function renderConfigSection(symbols, config) {
+  const exported = symbols.filter((s) => s.exported);
+  const configSymbol = exported.find(
+    (s) => (s.kind === "interface" || s.kind === "type") && /config/i.test(s.name) && (s.children?.length ?? 0) > 0
+  );
+  if (!configSymbol) return [];
+  const lines = [];
+  lines.push("## Configuration");
+  lines.push("");
+  const children = configSymbol.children ?? [];
+  if (children.length > 0) {
+    const projectName = config.project.packageName ?? "project";
+    const importSource = projectName.includes("/") ? projectName.split("/")[0] + "/" + projectName.split("/")[1] : projectName;
+    lines.push("```typescript");
+    lines.push(`import type { ${configSymbol.name} } from "${importSource}";`);
+    lines.push("");
+    lines.push(`const config: Partial<${configSymbol.name}> = {`);
+    for (const child of children.slice(0, 10)) {
+      const comment = child.documentation?.summary;
+      if (comment) {
+        lines.push(`  // ${comment}`);
+      }
+      const type = extractType(child.signature);
+      const defaultVal = inferDefaultValue(type, child.name);
+      lines.push(`  ${child.name}: ${defaultVal},`);
+    }
+    if (children.length > 10) {
+      lines.push(`  // ... ${children.length - 10} more options`);
+    }
+    lines.push("};");
+    lines.push("```");
+    lines.push("");
+  }
+  lines.push("See [references/CONFIGURATION.md](references/CONFIGURATION.md) for full details.");
+  lines.push("");
+  return lines;
+}
+function extractType(signature) {
+  if (!signature) return "";
+  const trimmed = signature.trim();
+  if (/^[{(]/.test(trimmed) || /[|]/.test(trimmed.split(":")[0])) {
+    return trimmed;
+  }
+  const colonIdx = trimmed.indexOf(":");
+  if (colonIdx === -1) return trimmed;
+  const left = trimmed.slice(0, colonIdx).trim();
+  if (/^[a-zA-Z_$][a-zA-Z0-9_$?]*$/.test(left)) {
+    return trimmed.slice(colonIdx + 1).trim();
+  }
+  return trimmed;
+}
+function inferDefaultValue(type, name) {
+  const t = type.trim();
+  if (t === "boolean" || t.startsWith("boolean")) return "true";
+  if (t === "string" || t.startsWith("string")) return `"..."`;
+  if (t === "number" || t.startsWith("number")) return "0";
+  if (t.includes("[]") || t.startsWith("Array")) return "[]";
+  if (t.startsWith("{") || /^[A-Z]/.test(t)) return "{ /* ... */ }";
+  if (/dir|path/i.test(name)) return `"."`;
+  return `undefined`;
+}
+function renderGotchas(symbols) {
+  const lines = [];
+  const exported = symbols.filter((s) => s.exported);
+  const deprecated = exported.filter((s) => s.documentation?.deprecated);
+  for (const sym of deprecated) {
+    const reason = sym.documentation?.deprecated ?? "";
+    const msg = reason && reason !== "true" ? `: ${reason}` : "";
+    lines.push(`- \`${sym.name}\` is deprecated${msg}`);
+  }
+  const throwers = exported.filter(
+    (s) => s.kind === "function" && (s.documentation?.throws?.length ?? 0) > 0
+  );
+  for (const sym of throwers) {
+    for (const t of sym.documentation?.throws ?? []) {
+      lines.push(
+        `- \`${sym.name}()\` throws${t.type ? ` \`${t.type}\`` : ""}: ${t.description}`
+      );
+    }
+  }
+  const enums = exported.filter((s) => s.kind === "enum" && (s.children?.length ?? 0) > 0);
+  for (const sym of enums) {
+    const values = (sym.children ?? []).map((c) => c.name).join(", ");
+    lines.push(`- \`${sym.name}\` enum values: ${values}`);
+  }
+  return lines;
+}
+function buildSkillMd(symbols, config, directoryName) {
+  const projectName = config.project.packageName ?? config.rootDir.split("/").pop() ?? "Project";
+  const description = buildDescription(symbols, config);
+  const lines = [];
+  lines.push("---");
+  lines.push(`name: ${directoryName}`);
+  lines.push("description: >");
+  for (const segment of description.split("\n")) {
+    lines.push(`  ${segment}`);
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push(`# ${projectName}`);
+  lines.push("");
+  const pkgDoc = symbols.find((s) => s.documentation?.tags?.packageDocumentation);
+  const overview = config.project.description ?? pkgDoc?.documentation?.summary ?? symbols.filter((s) => s.exported).find((s) => s.documentation?.summary)?.documentation?.summary;
+  if (overview) {
+    lines.push(overview);
+    lines.push("");
+  }
+  lines.push(...renderQuickStart(symbols, config));
+  lines.push(...renderApiSummaryTable(symbols));
+  lines.push(...renderConfigSection(symbols, config));
+  const customSections = config.skill.customSections ?? [];
+  for (const section of customSections) {
+    lines.push(`## ${section.heading}`);
+    lines.push("");
+    lines.push(section.content);
+    lines.push("");
+  }
+  const gotchaLines = renderGotchas(symbols);
+  const extraGotchas = config.skill.extraGotchas ?? [];
+  for (const gotcha of extraGotchas) {
+    gotchaLines.push(`- ${gotcha}`);
+  }
+  if (gotchaLines.length > 0) {
+    lines.push("## Gotchas");
+    lines.push("");
+    lines.push(...gotchaLines);
+    lines.push("");
+  }
+  const keyTypeLines = renderKeyTypes(symbols);
+  if (keyTypeLines.length > 0) {
+    lines.push("## Key Types");
+    lines.push("");
+    lines.push(...keyTypeLines);
+    lines.push("");
+  }
+  lines.push("## References");
+  lines.push("");
+  lines.push("- [references/CONFIGURATION.md](references/CONFIGURATION.md) \u2014 Full config options");
+  lines.push(
+    "- [references/API-REFERENCE.md](references/API-REFERENCE.md) \u2014 Signatures, parameters, examples"
+  );
+  lines.push("");
+  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}
+`;
+}
+function buildApiReferenceMd(symbols, config) {
+  const projectName = config.project.packageName ?? config.rootDir.split("/").pop() ?? "Project";
+  const exported = symbols.filter((s) => s.exported);
+  const lines = [];
+  lines.push(`# ${projectName} \u2014 API Reference`);
+  lines.push("");
+  const functions = exported.filter((s) => s.kind === "function");
+  const classes = exported.filter((s) => s.kind === "class");
+  const types = exported.filter(
+    (s) => s.kind === "interface" || s.kind === "type" || s.kind === "enum"
+  );
+  const variables = exported.filter((s) => s.kind === "variable");
+  const tocEntries = [];
+  if (functions.length > 0) tocEntries.push("- [Functions](#functions)");
+  if (types.length > 0) tocEntries.push("- [Types](#types)");
+  if (classes.length > 0) tocEntries.push("- [Classes](#classes)");
+  if (variables.length > 0) tocEntries.push("- [Constants](#constants)");
+  if (tocEntries.length > 0) {
+    lines.push("## Table of Contents");
+    lines.push("");
+    lines.push(...tocEntries);
+    lines.push("");
+  }
+  if (functions.length > 0) {
+    lines.push("## Functions");
+    lines.push("");
+    for (const sym of functions) {
+      lines.push(...renderSymbolDetail(sym));
+    }
+  }
+  if (types.length > 0) {
+    lines.push("## Types");
+    lines.push("");
+    for (const sym of types) {
+      lines.push(...renderSymbolDetail(sym));
+    }
+  }
+  if (classes.length > 0) {
+    lines.push("## Classes");
+    lines.push("");
+    for (const sym of classes) {
+      lines.push(...renderSymbolDetail(sym));
+    }
+  }
+  if (variables.length > 0) {
+    lines.push("## Constants");
+    lines.push("");
+    for (const sym of variables) {
+      lines.push(...renderSymbolDetail(sym));
+    }
+  }
+  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}
+`;
+}
+function renderSymbolDetail(sym) {
+  const lines = [];
+  lines.push(`### \`${sym.name}\``);
+  lines.push("");
+  if (sym.documentation?.summary) {
+    lines.push(sym.documentation.summary);
+    lines.push("");
+  }
+  if (sym.signature) {
+    lines.push("```typescript");
+    lines.push(sym.signature);
+    lines.push("```");
+    lines.push("");
+  }
+  if (sym.documentation?.params && sym.documentation.params.length > 0) {
+    lines.push("**Parameters:**");
+    lines.push("");
+    for (const p of sym.documentation.params) {
+      lines.push(`- \`${p.name}\`${p.type ? ` (\`${p.type}\`)` : ""} \u2014 ${p.description}`);
+    }
+    lines.push("");
+  }
+  if (sym.documentation?.returns) {
+    lines.push(`**Returns:** ${sym.documentation.returns.description}`);
+    lines.push("");
+  }
+  if (sym.children && sym.children.length > 0) {
+    lines.push("**Members:**");
+    lines.push("");
+    for (const child of sym.children) {
+      const desc = child.documentation?.summary ?? "";
+      lines.push(`- \`${child.name}\`${desc ? ` \u2014 ${desc}` : ""}`);
+    }
+    lines.push("");
+  }
+  for (const ex of sym.documentation?.examples ?? []) {
+    const lang = ex.language || "typescript";
+    lines.push(`\`\`\`${lang}`);
+    lines.push(ex.code.trim());
+    lines.push("```");
+    lines.push("");
+  }
+  return lines;
+}
+function buildConfigurationMd(symbols, config) {
+  const projectName = config.project.packageName ?? config.rootDir.split("/").pop() ?? "Project";
+  const exported = symbols.filter((s) => s.exported);
+  const lines = [];
+  lines.push(`# ${projectName} \u2014 Configuration Reference`);
+  lines.push("");
+  const configSymbols = exported.filter(
+    (s) => (s.kind === "interface" || s.kind === "type") && /config/i.test(s.name) && (s.children?.length ?? 0) > 0
+  );
+  for (const configSym of configSymbols) {
+    lines.push(`## \`${configSym.name}\``);
+    lines.push("");
+    if (configSym.documentation?.summary) {
+      lines.push(configSym.documentation.summary);
+      lines.push("");
+    }
+    const children = configSym.children ?? [];
+    if (children.length > 0) {
+      const importSource = projectName.includes("/") ? projectName : projectName;
+      lines.push("```typescript");
+      lines.push(`import type { ${configSym.name} } from "${importSource}";`);
+      lines.push("");
+      lines.push(`const config: Partial<${configSym.name}> = {`);
+      for (const child of children) {
+        if (child.documentation?.summary) {
+          lines.push(`  // ${child.documentation.summary}`);
+        }
+        const type = extractType(child.signature);
+        const defaultVal = inferDefaultValue(type, child.name);
+        lines.push(`  ${child.name}: ${defaultVal},`);
+      }
+      lines.push("};");
+      lines.push("```");
+      lines.push("");
+    }
+    lines.push("| Property | Type | Description |");
+    lines.push("|----------|------|-------------|");
+    for (const child of children) {
+      const type = extractType(child.signature);
+      const desc = child.documentation?.summary ?? "";
+      lines.push(`| \`${child.name}\` | \`${type}\` | ${desc} |`);
+    }
+    lines.push("");
+  }
+  if (configSymbols.length === 0) {
+    lines.push("No configuration types detected in this project.");
+    lines.push("");
+  }
+  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}
+`;
+}
+function buildScripts(config) {
+  const scripts = [];
+  const cliName = primaryBinName(config);
+  const pkgScripts = config.project.scripts ?? {};
+  if (cliName) {
+    if (pkgScripts.build) {
+      scripts.push({
+        path: "scripts/build.sh",
+        content: [
+          "#!/usr/bin/env bash",
+          `# Run ${cliName} build pipeline`,
+          "set -euo pipefail",
+          `npx ${cliName} build "$@"`,
+          ""
+        ].join("\n")
+      });
+    }
+    const checkCmd = pkgScripts.check ?? pkgScripts.lint;
+    if (checkCmd) {
+      const subcommand = checkCmd.includes("check") ? "check" : "lint";
+      scripts.push({
+        path: "scripts/check.sh",
+        content: [
+          "#!/usr/bin/env bash",
+          `# Run ${cliName} ${subcommand}`,
+          "set -euo pipefail",
+          `npx ${cliName} ${subcommand} "$@"`,
+          ""
+        ].join("\n")
+      });
+    }
+    if (pkgScripts.test) {
+      scripts.push({
+        path: "scripts/test.sh",
+        content: [
+          "#!/usr/bin/env bash",
+          `# Run ${cliName} test suite`,
+          "set -euo pipefail",
+          `npx ${cliName} test "$@"`,
+          ""
+        ].join("\n")
+      });
+    }
+  }
+  if (scripts.length === 0) {
+    scripts.push({
+      path: "scripts/test.sh",
+      content: [
+        "#!/usr/bin/env bash",
+        "# Run the project's test suite",
+        "# Usage: ./scripts/test.sh [additional args]",
+        "",
+        "if [ -f package.json ]; then",
+        '  npm test "$@"',
+        "else",
+        '  echo "No package.json found"',
+        "  exit 1",
+        "fi",
+        ""
+      ].join("\n")
+    });
+  }
+  return scripts;
+}
+function generateSkillPackage(symbols, config) {
+  const projectName = config.project.packageName ?? config.rootDir.split("/").pop() ?? "Project";
+  const directoryName = toDirectoryName(projectName);
+  const skillMd = buildSkillMd(symbols, config, directoryName);
+  const apiRefMd = buildApiReferenceMd(symbols, config);
+  const configMd = buildConfigurationMd(symbols, config);
+  const scripts = buildScripts(config);
+  return {
+    directoryName,
+    files: [
+      { path: "SKILL.md", content: skillMd },
+      { path: "references/API-REFERENCE.md", content: apiRefMd },
+      { path: "references/CONFIGURATION.md", content: configMd },
+      ...scripts
+    ]
+  };
+}
+function generateSkillMd(symbols, config) {
+  const projectName = config.project.packageName ?? config.rootDir.split("/").pop() ?? "Project";
+  const directoryName = toDirectoryName(projectName);
+  return buildSkillMd(symbols, config, directoryName);
+}
+
 // src/ssg-config.ts
 function pageSlug5(pagePath) {
   return pagePath.replace(/\.[^.]+$/, "");
@@ -1783,11 +2645,34 @@ function generateSSGConfigs(pages, target, projectName) {
 }
 
 // src/index.ts
-import { mkdir, writeFile as writeFile2 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+import { mkdir, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import { dirname, join } from "path";
 import { createWalker } from "@forge-ts/core";
-async function generate(config) {
+function updateAutoSections(existing, generated) {
+  const markerPattern = /<!-- FORGE:AUTO-START (\S+) -->([\s\S]*?)<!-- FORGE:AUTO-END \1 -->/g;
+  const newSections = /* @__PURE__ */ new Map();
+  let match;
+  while ((match = markerPattern.exec(generated)) !== null) {
+    newSections.set(match[1], match[0]);
+  }
+  if (newSections.size === 0) return null;
+  let updated = existing;
+  let changed = false;
+  for (const [id, replacement] of newSections) {
+    const sectionPattern = new RegExp(
+      `<!-- FORGE:AUTO-START ${id} -->[\\s\\S]*?<!-- FORGE:AUTO-END ${id} -->`
+    );
+    if (sectionPattern.test(updated)) {
+      updated = updated.replace(sectionPattern, replacement);
+      changed = true;
+    }
+  }
+  return changed ? updated : null;
+}
+async function generate(config, options) {
   const start = Date.now();
+  const forceStubs = options?.forceStubs ?? false;
   const walker = createWalker(config);
   const symbols = walker.walk();
   await mkdir(config.outDir, { recursive: true });
@@ -1798,7 +2683,8 @@ async function generate(config) {
     const ext = format === "mdx" ? "mdx" : "md";
     await writeFile2(join(config.outDir, `api-reference.${ext}`), content, "utf8");
   }
-  const projectName = config.rootDir.split("/").pop() ?? "Project";
+  const resolvedRoot = config.rootDir === "." ? process.cwd() : config.rootDir;
+  const projectName = resolvedRoot.split("/").pop() ?? "Project";
   const symbolsByPackage = groupSymbolsByPackage(symbols, config.rootDir);
   const target = config.gen.ssgTarget ?? DEFAULT_TARGET;
   const adapter = getAdapter(target);
@@ -1806,7 +2692,9 @@ async function generate(config) {
     const pages = generateDocSite(symbolsByPackage, config, {
       format,
       ssgTarget: config.gen.ssgTarget,
-      projectName
+      projectName,
+      repositoryUrl: config.project.repository,
+      packageName: config.project.packageName
     });
     const adapterContext = {
       config,
@@ -1818,6 +2706,14 @@ async function generate(config) {
     const transformedPages = adapter.transformPages(pages, adapterContext);
     for (const file of transformedPages) {
       const filePath = join(config.outDir, file.path);
+      if (file.stub && existsSync2(filePath) && !forceStubs) {
+        const existingContent = await readFile2(filePath, "utf8");
+        const merged = updateAutoSections(existingContent, file.content);
+        if (merged) {
+          await writeFile2(filePath, merged, "utf8");
+        }
+        continue;
+      }
       await mkdir(dirname(filePath), { recursive: true });
       await writeFile2(filePath, file.content, "utf8");
     }
@@ -1835,6 +2731,17 @@ async function generate(config) {
     await writeFile2(join(config.outDir, "llms.txt"), llms, "utf8");
     const llmsFull = generateLlmsFullTxt(symbols, config);
     await writeFile2(join(config.outDir, "llms-full.txt"), llmsFull, "utf8");
+    const skillEnabled = config.skill.enabled !== false;
+    if (skillEnabled) {
+      const skillPkg = generateSkillPackage(symbols, config);
+      const skillDir = join(config.outDir, skillPkg.directoryName);
+      await mkdir(skillDir, { recursive: true });
+      for (const file of skillPkg.files) {
+        const filePath = join(skillDir, file.path);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile2(filePath, file.content, "utf8");
+      }
+    }
   }
   if (config.gen.readmeSync) {
     await syncReadme(join(config.rootDir, "README.md"), symbols);
@@ -1855,6 +2762,8 @@ export {
   generateLlmsTxt,
   generateMarkdown,
   generateSSGConfigs,
+  generateSkillMd,
+  generateSkillPackage,
   getAdapter,
   getAvailableTargets,
   groupSymbolsByPackage,