@forge-ts/gen 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,3 +1,761 @@
+// src/adapters/registry.ts
+var adapters = /* @__PURE__ */ new Map();
+function registerAdapter(adapter) {
+  adapters.set(adapter.target, adapter);
+}
+function getAdapter(target) {
+  const adapter = adapters.get(target);
+  if (!adapter) {
+    const available = [...adapters.keys()].join(", ");
+    throw new Error(`Unknown SSG target "${target}". Available targets: ${available}`);
+  }
+  return adapter;
+}
+function getAvailableTargets() {
+  return [...adapters.keys()];
+}
+var DEFAULT_TARGET = "mintlify";
+
+// src/adapters/mintlify.ts
+var styleGuide = {
+  pageExtension: "mdx",
+  supportsMdx: true,
+  requiresFrontmatter: true,
+  maxHeadingDepth: 3,
+  defaultImports: [],
+  codeBlockLanguage: "typescript"
+};
+function pageSlug(pagePath) {
+  return pagePath.replace(/\.[^.]+$/, "");
+}
+function buildDocsJson(context) {
+  const { pages, projectName } = context;
+  const byPackage = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const slug = pageSlug(page.path);
+    const packageMatch = /^packages\/([^/]+)\/(.+)$/.exec(slug);
+    if (packageMatch) {
+      const pkgName = packageMatch[1];
+      const list = byPackage.get(pkgName) ?? [];
+      list.push(slug);
+      byPackage.set(pkgName, list);
+    }
+  }
+  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 apiGroups = [];
+    for (const [pkgName, slugs] of byPackage) {
+      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 });
+    }
+    tabs.push({ tab: "API Reference", groups: apiGroups });
+  }
+  return {
+    name: projectName,
+    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) {
+  const title = String(page.frontmatter.title ?? "");
+  const description = page.frontmatter.description ? String(page.frontmatter.description) : void 0;
+  const lines = ["---", `title: "${title}"`];
+  if (description) {
+    lines.push(`description: "${description}"`);
+  }
+  lines.push("---", "");
+  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
+  return lines.join("\n") + body;
+}
+var mintlifyAdapter = {
+  target: "mintlify",
+  displayName: "Mintlify",
+  styleGuide,
+  scaffold(context) {
+    const docsJson = buildDocsJson(context);
+    return {
+      target: "mintlify",
+      files: [{ path: "docs.json", content: JSON.stringify(docsJson, null, 2) }],
+      dependencies: {},
+      devDependencies: {},
+      scripts: {},
+      instructions: [
+        "Preview locally: npx @mintlify/cli dev",
+        "Deploy: Push to GitHub and connect at mintlify.com"
+      ]
+    };
+  },
+  transformPages(pages, _context) {
+    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);
+    return [
+      {
+        path: "docs.json",
+        content: `${JSON.stringify(config, null, 2)}
+`
+      }
+    ];
+  },
+  getDevCommand(outDir) {
+    return {
+      bin: "npx",
+      args: ["@mintlify/cli", "dev"],
+      cwd: outDir,
+      label: "Mintlify Dev Server",
+      url: "http://localhost:3000"
+    };
+  },
+  async detectExisting(outDir) {
+    const { existsSync: existsSync3 } = await import("fs");
+    const { join: join2 } = await import("path");
+    return existsSync3(join2(outDir, "docs.json"));
+  }
+};
+registerAdapter(mintlifyAdapter);
+
+// src/adapters/docusaurus.ts
+var styleGuide2 = {
+  pageExtension: "mdx",
+  supportsMdx: true,
+  requiresFrontmatter: true,
+  maxHeadingDepth: 4,
+  defaultImports: [],
+  codeBlockLanguage: "typescript"
+};
+function pageSlug2(pagePath) {
+  return pagePath.replace(/\.[^.]+$/, "");
+}
+function buildSidebarsTs(pages) {
+  const topLevel = [];
+  const byPackage = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const slug = pageSlug2(page.path);
+    const packageMatch = /^packages\/([^/]+)\/(.+)$/.exec(slug);
+    if (packageMatch) {
+      const pkgName = packageMatch[1];
+      const list = byPackage.get(pkgName) ?? [];
+      list.push(slug);
+      byPackage.set(pkgName, list);
+    } else {
+      topLevel.push(slug);
+    }
+  }
+  const items = [...topLevel];
+  for (const [pkgName, slugs] of byPackage) {
+    items.push({
+      type: "category",
+      label: pkgName,
+      items: slugs
+    });
+  }
+  const sidebarObj = { docs: items };
+  const json = JSON.stringify(sidebarObj, null, 2);
+  return `import type { SidebarsConfig } from "@docusaurus/plugin-content-docs";
+
+const sidebars: SidebarsConfig = ${json};
+
+export default sidebars;
+`;
+}
+function buildDocusaurusConfig(context) {
+  const { projectName, projectDescription } = context;
+  const description = projectDescription ?? `${projectName} documentation`;
+  return `import { themes as prismThemes } from "prism-react-renderer";
+import type { Config } from "@docusaurus/types";
+import type * as Preset from "@docusaurus/preset-classic";
+
+const config: Config = {
+  title: "${projectName}",
+  tagline: "${description}",
+  url: "https://your-domain.com",
+  baseUrl: "/",
+  onBrokenLinks: "throw",
+  onBrokenMarkdownLinks: "warn",
+  i18n: {
+    defaultLocale: "en",
+    locales: ["en"],
+  },
+  presets: [
+    [
+      "classic",
+      {
+        docs: {
+          routeBasePath: "/",
+          sidebarPath: "./sidebars.ts",
+        },
+        blog: false,
+      } satisfies Preset.Options,
+    ],
+  ],
+  themeConfig: {
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+} satisfies Config;
+
+export default config;
+`;
+}
+function buildPackageJson(context) {
+  const pkg = {
+    name: `${context.projectName}-docs`,
+    version: "0.0.0",
+    private: true,
+    scripts: {
+      "docs:dev": "docusaurus start",
+      "docs:build": "docusaurus build",
+      "docs:serve": "docusaurus serve"
+    },
+    dependencies: {
+      "@docusaurus/core": "^3.9.2",
+      "@docusaurus/preset-classic": "^3.9.2",
+      "@mdx-js/react": "^3.0.0",
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
+      "prism-react-renderer": "^2.3.0"
+    },
+    devDependencies: {
+      "@docusaurus/tsconfig": "^3.9.2",
+      "@docusaurus/types": "^3.9.2"
+    }
+  };
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
+function addDocusaurusFrontmatter(page) {
+  const title = String(page.frontmatter.title ?? "");
+  const description = page.frontmatter.description ? String(page.frontmatter.description) : void 0;
+  const sidebarLabel = page.frontmatter.sidebar_label ? String(page.frontmatter.sidebar_label) : title;
+  const sidebarPosition = page.frontmatter.sidebar_position;
+  const lines = ["---", `title: "${title}"`, `sidebar_label: "${sidebarLabel}"`];
+  if (sidebarPosition !== void 0) {
+    lines.push(`sidebar_position: ${sidebarPosition}`);
+  }
+  if (description) {
+    lines.push(`description: "${description}"`);
+  }
+  lines.push("---", "");
+  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
+  return lines.join("\n") + body;
+}
+var docusaurusAdapter = {
+  target: "docusaurus",
+  displayName: "Docusaurus",
+  styleGuide: styleGuide2,
+  scaffold(context) {
+    return {
+      target: "docusaurus",
+      files: [
+        { path: "docusaurus.config.ts", content: buildDocusaurusConfig(context) },
+        { path: "sidebars.ts", content: buildSidebarsTs(context.pages) },
+        { path: "package.json", content: buildPackageJson(context) },
+        { path: "tsconfig.json", content: '{ "extends": "@docusaurus/tsconfig" }\n' }
+      ],
+      dependencies: {
+        "@docusaurus/core": "^3.9.2",
+        "@docusaurus/preset-classic": "^3.9.2",
+        "@mdx-js/react": "^3.0.0",
+        react: "^19.0.0",
+        "react-dom": "^19.0.0",
+        "prism-react-renderer": "^2.3.0"
+      },
+      devDependencies: {
+        "@docusaurus/tsconfig": "^3.9.2",
+        "@docusaurus/types": "^3.9.2"
+      },
+      scripts: {
+        "docs:dev": "docusaurus start",
+        "docs:build": "docusaurus build",
+        "docs:serve": "docusaurus serve"
+      },
+      instructions: [`Run \`npm run docs:dev\` inside ${context.outDir} to preview your docs`]
+    };
+  },
+  transformPages(pages, _context) {
+    return pages.map((page) => ({
+      path: page.path.replace(/\.md$/, ".mdx"),
+      content: addDocusaurusFrontmatter(page),
+      stub: page.stub
+    }));
+  },
+  generateConfig(context) {
+    return [
+      {
+        path: "sidebars.ts",
+        content: buildSidebarsTs(context.pages)
+      }
+    ];
+  },
+  getDevCommand(outDir) {
+    return {
+      bin: "npx",
+      args: ["docusaurus", "start"],
+      cwd: outDir,
+      label: "Docusaurus Dev Server",
+      url: "http://localhost:3000"
+    };
+  },
+  async detectExisting(outDir) {
+    const { existsSync: existsSync3 } = await import("fs");
+    const { join: join2 } = await import("path");
+    return existsSync3(join2(outDir, "sidebars.ts")) || existsSync3(join2(outDir, "docusaurus.config.ts")) || existsSync3(join2(outDir, "docusaurus.config.js"));
+  }
+};
+registerAdapter(docusaurusAdapter);
+
+// src/adapters/nextra.ts
+var styleGuide3 = {
+  pageExtension: "mdx",
+  supportsMdx: true,
+  requiresFrontmatter: false,
+  maxHeadingDepth: 4,
+  defaultImports: [],
+  codeBlockLanguage: "typescript"
+};
+function pageSlug3(pagePath) {
+  return pagePath.replace(/\.[^.]+$/, "");
+}
+function slugToLabel(slug) {
+  return slug.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function renderMetaJs(meta) {
+  const json = JSON.stringify(meta, null, 2);
+  return `export default ${json};
+`;
+}
+function buildMetaFiles(pages) {
+  const topLevel = [];
+  const byPackage = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const slug = pageSlug3(page.path);
+    const packageMatch = /^packages\/([^/]+)\/(.+)$/.exec(slug);
+    if (packageMatch) {
+      const pkgName = packageMatch[1];
+      const list = byPackage.get(pkgName) ?? [];
+      list.push(slug);
+      byPackage.set(pkgName, list);
+    } else {
+      topLevel.push(slug);
+    }
+  }
+  const files = [];
+  const rootMeta = {};
+  for (const slug of topLevel) {
+    const segment = slug.split("/").pop() ?? slug;
+    rootMeta[segment] = slugToLabel(segment);
+  }
+  if (byPackage.size > 0) {
+    rootMeta.packages = "Packages";
+  }
+  files.push({
+    path: "content/_meta.js",
+    content: renderMetaJs(rootMeta)
+  });
+  for (const [pkgName, slugs] of byPackage) {
+    const pkgMeta = {};
+    for (const slug of slugs) {
+      const segment = slug.split("/").pop() ?? slug;
+      pkgMeta[segment] = slugToLabel(segment);
+    }
+    files.push({
+      path: `content/packages/${pkgName}/_meta.js`,
+      content: renderMetaJs(pkgMeta)
+    });
+  }
+  if (byPackage.size > 1) {
+    const packagesMeta = {};
+    for (const pkgName of byPackage.keys()) {
+      packagesMeta[pkgName] = pkgName;
+    }
+    files.push({
+      path: "content/packages/_meta.js",
+      content: renderMetaJs(packagesMeta)
+    });
+  }
+  return files;
+}
+function buildAppLayout(context) {
+  const { projectName } = context;
+  return `import { Layout } from "nextra-theme-docs";
+import { Head } from "nextra/components";
+import { getPageMap } from "nextra/page-map";
+import type { ReactNode } from "react";
+
+export const metadata = {
+  title: {
+    template: \`%s \u2013 ${projectName}\`,
+  },
+};
+
+export default async function RootLayout({ children }: { children: ReactNode }) {
+  const pageMap = await getPageMap();
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <Head />
+      <body>
+        <Layout pageMap={pageMap} docsRepositoryBase="">
+          {children}
+        </Layout>
+      </body>
+    </html>
+  );
+}
+`;
+}
+function buildCatchAllPage() {
+  return `import { generateStaticParamsFor, importPage } from "nextra/pages";
+
+export const generateStaticParams = generateStaticParamsFor("mdxPath");
+
+export async function generateMetadata(props: {
+  params: Promise<Record<string, string[]>>;
+}) {
+  const params = await props.params;
+  const { metadata } = await importPage(params.mdxPath);
+  return metadata;
+}
+
+const Wrapper = importPage;
+export default async function Page(props: {
+  params: Promise<Record<string, string[]>>;
+}) {
+  const params = await props.params;
+  const result = await importPage(params.mdxPath);
+  const { default: MDXContent } = result;
+  return <MDXContent {...props} params={params} />;
+}
+`;
+}
+function buildMdxComponents() {
+  return `import { useMDXComponents as getNextraComponents } from "nextra-theme-docs";
+
+export function useMDXComponents(components: Record<string, unknown>) {
+  return getNextraComponents(components);
+}
+`;
+}
+function buildNextConfig() {
+  return `import nextra from "nextra";
+
+const withNextra = nextra({
+  contentDirBasePath: "/",
+});
+
+export default withNextra({
+  output: "export",
+  images: { unoptimized: true },
+});
+`;
+}
+function buildPackageJson2(context) {
+  const pkg = {
+    name: `${context.projectName}-docs`,
+    version: "0.0.0",
+    private: true,
+    scripts: {
+      "docs:dev": "next dev",
+      "docs:build": "next build",
+      "docs:serve": "next start"
+    },
+    dependencies: {
+      next: "^15",
+      nextra: "^4",
+      "nextra-theme-docs": "^4",
+      react: "^19",
+      "react-dom": "^19"
+    }
+  };
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
+function addNextraFrontmatter(page) {
+  const title = String(page.frontmatter.title ?? "");
+  if (!title) {
+    return page.content;
+  }
+  const lines = ["---", `title: "${title}"`, "---", ""];
+  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
+  return lines.join("\n") + body;
+}
+var nextraAdapter = {
+  target: "nextra",
+  displayName: "Nextra",
+  styleGuide: styleGuide3,
+  scaffold(context) {
+    const metaFiles = buildMetaFiles(context.pages);
+    return {
+      target: "nextra",
+      files: [
+        { path: "next.config.ts", content: buildNextConfig() },
+        { path: "package.json", content: buildPackageJson2(context) },
+        { path: "mdx-components.ts", content: buildMdxComponents() },
+        { path: "app/layout.tsx", content: buildAppLayout(context) },
+        { path: "app/[[...mdxPath]]/page.tsx", content: buildCatchAllPage() },
+        ...metaFiles
+      ],
+      dependencies: {
+        next: "^15",
+        nextra: "^4",
+        "nextra-theme-docs": "^4",
+        react: "^19",
+        "react-dom": "^19"
+      },
+      devDependencies: {},
+      scripts: {
+        "docs:dev": "next dev",
+        "docs:build": "next build",
+        "docs:serve": "next start"
+      },
+      instructions: [`Run \`npm run docs:dev\` inside ${context.outDir} to preview your docs`]
+    };
+  },
+  transformPages(pages, _context) {
+    return pages.map((page) => ({
+      path: page.path.replace(/\.md$/, ".mdx"),
+      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: existsSync3 } = await import("fs");
+    const { join: join2 } = await import("path");
+    return existsSync3(join2(outDir, "content/_meta.js")) || existsSync3(join2(outDir, "next.config.ts")) || existsSync3(join2(outDir, "next.config.js"));
+  }
+};
+registerAdapter(nextraAdapter);
+
+// src/adapters/vitepress.ts
+var styleGuide4 = {
+  pageExtension: "md",
+  supportsMdx: false,
+  requiresFrontmatter: true,
+  maxHeadingDepth: 4,
+  defaultImports: [],
+  codeBlockLanguage: "typescript"
+};
+function pageSlug4(pagePath) {
+  return pagePath.replace(/\.[^.]+$/, "");
+}
+function slugToLabel2(slug) {
+  return slug.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function buildSidebar(pages) {
+  const topLevel = [];
+  const byPackage = /* @__PURE__ */ new Map();
+  for (const page of pages) {
+    const slug = pageSlug4(page.path);
+    const packageMatch = /^packages\/([^/]+)\/(.+)$/.exec(slug);
+    if (packageMatch) {
+      const pkgName = packageMatch[1];
+      const list = byPackage.get(pkgName) ?? [];
+      list.push(slug);
+      byPackage.set(pkgName, list);
+    } else {
+      topLevel.push(slug);
+    }
+  }
+  const sidebar = [];
+  if (topLevel.length > 0) {
+    const items = topLevel.map((slug) => {
+      const segment = slug.split("/").pop() ?? slug;
+      const link = slug === "index" ? "/" : `/${slug}`;
+      return { text: slugToLabel2(segment), link };
+    });
+    sidebar.push({ text: "Getting Started", items });
+  }
+  for (const [pkgName, slugs] of byPackage) {
+    const items = slugs.map((slug) => {
+      const segment = slug.split("/").pop() ?? slug;
+      const isIndex = segment === "index";
+      const link = isIndex ? `/packages/${pkgName}/` : `/${slug}`;
+      return { text: slugToLabel2(segment), link };
+    });
+    sidebar.push({ text: pkgName, items });
+  }
+  return sidebar;
+}
+function buildVitePressConfig(context) {
+  const { projectName, projectDescription } = context;
+  const description = projectDescription ?? `${projectName} documentation`;
+  const sidebar = buildSidebar(context.pages);
+  const sidebarJson = JSON.stringify(sidebar, null, 4).split("\n").join("\n  ");
+  return `import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "${projectName}",
+  description: "${description}",
+  themeConfig: {
+    nav: [
+      { text: "Home", link: "/" },
+    ],
+    sidebar: ${sidebarJson},
+    socialLinks: [],
+  },
+});
+`;
+}
+function buildPackageJson3(context) {
+  const pkg = {
+    name: `${context.projectName}-docs`,
+    version: "0.0.0",
+    private: true,
+    type: "module",
+    scripts: {
+      "docs:dev": "vitepress dev",
+      "docs:build": "vitepress build",
+      "docs:preview": "vitepress preview"
+    },
+    devDependencies: {
+      vitepress: "^2.0.0"
+    }
+  };
+  return `${JSON.stringify(pkg, null, 2)}
+`;
+}
+function addVitepressFrontmatter(page) {
+  const title = String(page.frontmatter.title ?? "");
+  const description = page.frontmatter.description ? String(page.frontmatter.description) : void 0;
+  const lines = ["---", `title: "${title}"`, "outline: deep"];
+  if (description) {
+    lines.push(`description: "${description}"`);
+  }
+  lines.push("---", "");
+  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
+  return lines.join("\n") + body;
+}
+var vitepressAdapter = {
+  target: "vitepress",
+  displayName: "VitePress",
+  styleGuide: styleGuide4,
+  scaffold(context) {
+    return {
+      target: "vitepress",
+      files: [
+        { path: ".vitepress/config.mts", content: buildVitePressConfig(context) },
+        { path: "package.json", content: buildPackageJson3(context) }
+      ],
+      dependencies: {},
+      devDependencies: {
+        vitepress: "^2.0.0"
+      },
+      scripts: {
+        "docs:dev": "vitepress dev",
+        "docs:build": "vitepress build",
+        "docs:preview": "vitepress preview"
+      },
+      instructions: [`Run \`npm run docs:dev\` inside ${context.outDir} to preview your docs`]
+    };
+  },
+  transformPages(pages, _context) {
+    return pages.map((page) => ({
+      path: page.path.endsWith(".mdx") ? page.path.replace(/\.mdx$/, ".md") : page.path,
+      content: addVitepressFrontmatter(page),
+      stub: page.stub
+    }));
+  },
+  generateConfig(context) {
+    return [
+      {
+        path: ".vitepress/config.mts",
+        content: buildVitePressConfig(context)
+      }
+    ];
+  },
+  getDevCommand(outDir) {
+    return {
+      bin: "npx",
+      args: ["vitepress", "dev"],
+      cwd: outDir,
+      label: "VitePress Dev Server",
+      url: "http://localhost:5173"
+    };
+  },
+  async detectExisting(outDir) {
+    const { existsSync: existsSync3 } = await import("fs");
+    const { join: join2 } = await import("path");
+    return existsSync3(join2(outDir, ".vitepress"));
+  }
+};
+registerAdapter(vitepressAdapter);
+
 // src/llms.ts
 function compactEntry(symbol) {
   if (symbol.signature) {
@@ -313,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) {
@@ -462,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) {
@@ -476,55 +1243,295 @@ 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) {
-  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);
+function renderProjectIndexPage(symbolsByPackage, options) {
   const lines = [];
-  lines.push(`# ${packageName}`);
-  lines.push("");
-  if (pkgDoc) {
-    lines.push(pkgDoc);
-    lines.push("");
+  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.`
+    );
   }
-  if (exported.length > 0) {
-    lines.push("## Exported Symbols");
-    lines.push("");
-    lines.push("| Symbol | Kind | Description |");
-    lines.push("|--------|------|-------------|");
-    for (const s of exported) {
-      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} |`);
-    }
-    lines.push("");
+  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");
   }
-  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("- 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("Type contracts exported by this package: interfaces, type aliases, and enums.");
+  lines.push("## Installation");
   lines.push("");
-  for (const s of typeSymbols) {
-    lines.push(`## ${s.name}`);
-    lines.push("");
-    if (s.documentation?.deprecated) {
-      lines.push(`> **Deprecated**: ${s.documentation.deprecated}`);
-      lines.push("");
-    }
-    if (s.documentation?.summary) {
+  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 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 = [];
+  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("");
+  }
+  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 group) {
+      const ext = s.kind === "function" ? "()" : "";
+      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("Type contracts exported by this package: interfaces, type aliases, and enums.");
+  lines.push("");
+  for (const s of typeSymbols) {
+    lines.push(`## ${s.name}`);
+    lines.push("");
+    if (s.documentation?.deprecated) {
+      lines.push(`> **Deprecated**: ${s.documentation.deprecated}`);
+      lines.push("");
+    }
+    if (s.documentation?.summary) {
       lines.push(s.documentation.summary);
       lines.push("");
     }
@@ -539,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}`);
@@ -582,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("");
@@ -607,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("");
@@ -632,6 +1648,7 @@ function renderFunctionsPage(packageName, symbols, _options) {
       }
     }
   }
+  void packageName;
   return lines.join("\n");
 }
 function renderExamplesPage(packageName, symbols, _options) {
@@ -639,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;
@@ -655,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("");
@@ -670,185 +1687,95 @@ 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" ? "()" : "";
-  const lines = [];
-  lines.push(`${hashes} \`${symbol.name}${ext}\``);
-  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("");
-    for (const t of throws) {
-      const typeStr = t.type ? `\`${t.type}\` \u2014 ` : "";
-      lines.push(`- ${typeStr}${t.description}`);
-    }
-    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("```");
-      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);
-  }
+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(`# ${packageName} \u2014 API Reference`);
+  lines.push(`Configuration reference for **${options.projectName}**.`);
   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("## forge-ts.config.ts");
   lines.push("");
-  lines.push(`Welcome to **${options.projectName}**.`);
-  if (options.projectDescription) {
-    lines.push("");
-    lines.push(options.projectDescription);
-  }
+  lines.push("Create a `forge-ts.config.ts` file in your project root:");
   lines.push("");
-  lines.push("## Installation");
+  lines.push("```typescript");
+  lines.push('import { defineConfig } from "@forge-ts/core";');
   lines.push("");
-  lines.push("```bash");
-  lines.push(`npm install ${options.projectName}`);
+  lines.push("export default defineConfig({");
+  lines.push('  rootDir: ".",');
+  lines.push('  outDir: "docs/generated",');
+  lines.push("});");
   lines.push("```");
   lines.push("");
-  if (firstExample) {
-    lines.push("## Quick Start");
+  if (configSymbol) {
+    lines.push(`## \`${configSymbol.name}\``);
     lines.push("");
-    lines.push(
-      `The following example demonstrates \`${firstSymbolName}\` from the \`${firstPackageName}\` package.`
+    if (configSymbol.documentation?.summary) {
+      lines.push(configSymbol.documentation.summary);
+      lines.push("");
+    }
+    const children = (configSymbol.children ?? []).filter(
+      (c) => c.kind === "property" || c.kind === "method"
     );
-    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)`);
+    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("");
+    }
   }
   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";
   const pages = [];
@@ -878,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`,
@@ -894,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(
@@ -925,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`,
@@ -937,26 +1892,604 @@ 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 pageSlug(pagePath) {
+function pageSlug5(pagePath) {
   return pagePath.replace(/\.[^.]+$/, "");
 }
 function partitionPages(pages) {
   const topLevel = [];
   const byPackage = /* @__PURE__ */ new Map();
   for (const page of pages) {
-    const slug = pageSlug(page.path);
+    const slug = pageSlug5(page.path);
     const packageMatch = /^packages\/([^/]+)\/(.+)$/.exec(slug);
     if (packageMatch) {
       const pkgName = packageMatch[1];
@@ -969,7 +2502,7 @@ function partitionPages(pages) {
   }
   return { topLevel, byPackage };
 }
-function slugToLabel(slug) {
+function slugToLabel3(slug) {
   return slug.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function generateMintlifyConfig(pages, projectName) {
@@ -1032,7 +2565,7 @@ function generateNextraConfigs(pages, _projectName) {
   const rootMeta = {};
   for (const slug of topLevel) {
     const segment = slug.split("/").pop() ?? slug;
-    rootMeta[segment] = slugToLabel(segment);
+    rootMeta[segment] = slugToLabel3(segment);
   }
   if (byPackage.size > 0) {
     rootMeta.packages = "Packages";
@@ -1046,7 +2579,7 @@ function generateNextraConfigs(pages, _projectName) {
     const pkgMeta = {};
     for (const slug of slugs) {
       const segment = slug.split("/").pop() ?? slug;
-      pkgMeta[segment] = slugToLabel(segment);
+      pkgMeta[segment] = slugToLabel3(segment);
     }
     files.push({
       path: `packages/${pkgName}/_meta.json`,
@@ -1074,7 +2607,7 @@ function generateVitePressConfig(pages, _projectName) {
     const items = topLevel.map((slug) => {
       const segment = slug.split("/").pop() ?? slug;
       const link = slug === "index" ? "/" : `/${slug}`;
-      return { text: slugToLabel(segment), link };
+      return { text: slugToLabel3(segment), link };
     });
     sidebar.push({ text: "Getting Started", items });
   }
@@ -1083,7 +2616,7 @@ function generateVitePressConfig(pages, _projectName) {
       const segment = slug.split("/").pop() ?? slug;
       const isIndex = segment === "index";
       const link = isIndex ? `/packages/${pkgName}/` : `/${slug}`;
-      return { text: slugToLabel(segment), link };
+      return { text: slugToLabel3(segment), link };
     });
     sidebar.push({ text: pkgName, items });
   }
@@ -1112,11 +2645,34 @@ function generateSSGConfigs(pages, target, projectName) {
 }
 
 // src/index.ts
-import { mkdir, writeFile as writeFile2 } from "fs/promises";
-import { join } from "path";
+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 });
@@ -1127,27 +2683,46 @@ 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);
   for (const format of config.gen.formats) {
     const pages = generateDocSite(symbolsByPackage, config, {
       format,
       ssgTarget: config.gen.ssgTarget,
-      projectName
+      projectName,
+      repositoryUrl: config.project.repository,
+      packageName: config.project.packageName
     });
-    for (const page of pages) {
-      const pagePath = join(config.outDir, page.path);
-      const pageDir = pagePath.substring(0, pagePath.lastIndexOf("/"));
-      await mkdir(pageDir, { recursive: true });
-      await writeFile2(pagePath, page.content, "utf8");
+    const adapterContext = {
+      config,
+      projectName,
+      pages,
+      symbols,
+      outDir: config.outDir
+    };
+    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");
     }
     if (config.gen.ssgTarget) {
-      const configFiles = generateSSGConfigs(pages, config.gen.ssgTarget, projectName);
-      for (const configFile of configFiles) {
-        const configPath = join(config.outDir, configFile.path);
-        const configDir = configPath.substring(0, configPath.lastIndexOf("/"));
-        await mkdir(configDir, { recursive: true });
-        await writeFile2(configPath, configFile.content, "utf8");
+      const configFiles = adapter.generateConfig(adapterContext);
+      for (const file of configFiles) {
+        const filePath = join(config.outDir, file.path);
+        await mkdir(dirname(filePath), { recursive: true });
+        await writeFile2(filePath, file.content, "utf8");
       }
     }
   }
@@ -1156,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);
@@ -1169,13 +2755,19 @@ async function generate(config) {
   };
 }
 export {
+  DEFAULT_TARGET,
   generate,
   generateDocSite,
   generateLlmsFullTxt,
   generateLlmsTxt,
   generateMarkdown,
   generateSSGConfigs,
+  generateSkillMd,
+  generateSkillPackage,
+  getAdapter,
+  getAvailableTargets,
   groupSymbolsByPackage,
+  registerAdapter,
   syncReadme
 };
 //# sourceMappingURL=index.js.map