@raybase/docs 0.0.2 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Itself & Co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+export type DocsCliPlugin = {
+    id: "docs";
+    packageName: "@raybase/docs";
+    commands: string[];
+    doctorHooks: string[];
+};
+export declare function docsCliPlugin(): DocsCliPlugin;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,eAAe,CAAC;IAC7B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB,CAAC;AAEF,wBAAgB,aAAa,IAAI,aAAa,CAO7C"}

package/dist/cli.js

@@ -0,0 +1,9 @@
+export function docsCliPlugin() {
+    return {
+        id: "docs",
+        packageName: "@raybase/docs",
+        commands: [],
+        doctorHooks: ["docs"]
+    };
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,EAAE,EAAE,MAAM;QACV,WAAW,EAAE,eAAe;QAC5B,QAAQ,EAAE,EAAE;QACZ,WAAW,EAAE,CAAC,MAAM,CAAC;KACtB,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import { type RaybaseModule } from "@raybase/core";
+export type DocsPlacement = "spine" | "site";
+export type DocsAudience = "signed-in" | "public";
+export type DocsModuleOptions = {
+    placement?: DocsPlacement;
+    audience?: DocsAudience;
+    pathPrefix?: string;
+};
+export declare function docsModule<Env = any>(options?: DocsModuleOptions): RaybaseModule<Env>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAExE,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;AAC7C,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,QAAQ,CAAC;AAElD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,wBAAgB,UAAU,CAAC,GAAG,GAAG,GAAG,EAAE,OAAO,GAAE,iBAAsB,GAAG,aAAa,CAAC,GAAG,CAAC,CAWzF"}

package/dist/index.js

@@ -0,0 +1,14 @@
+import { defineRaybaseModule } from "@raybase/core";
+export function docsModule(options = {}) {
+    const placement = options.placement ?? "spine";
+    const audience = options.audience ?? (placement === "site" ? "public" : "signed-in");
+    const pathPrefix = options.pathPrefix ?? "/docs";
+    return defineRaybaseModule({
+        id: "docs",
+        packageName: "@raybase/docs",
+        runtime: () => ({
+            agentSurfaces: [{ surface: "docs", pathPrefix, owner: placement, audience }]
+        })
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAsB,MAAM,eAAe,CAAC;AAWxE,MAAM,UAAU,UAAU,CAAY,UAA6B,EAAE;IACnE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC;IAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;IACrF,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC;IACjD,OAAO,mBAAmB,CAAC;QACzB,EAAE,EAAE,MAAM;QACV,WAAW,EAAE,eAAe;QAC5B,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;YACd,aAAa,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;SAC7E,CAAC;KACH,CAAC,CAAC;AACL,CAAC"}

package/dist/install.d.ts

@@ -0,0 +1,35 @@
+export type DocsInstallOptions = {
+    template?: "tanstack-start" | "react-router" | "astro-emdash";
+    placement?: "spine" | "site";
+};
+export declare const docsModuleManifest: {
+    readonly schemaVersion: 1;
+    readonly id: "docs";
+    readonly name: "Raybase Docs";
+    readonly packageName: "@raybase/docs";
+    readonly version: "0.1.0";
+    readonly skills: readonly ["raybase-docs-writing"];
+    readonly commands: readonly [];
+    readonly doctorHooks: readonly ["docs"];
+};
+export declare const docsModuleInstaller: {
+    readonly schemaVersion: 1;
+    readonly id: "docs";
+    readonly name: "Raybase Docs";
+    readonly packageName: "@raybase/docs";
+    readonly version: "0.1.0";
+    readonly skills: readonly ["raybase-docs-writing"];
+    readonly commands: readonly [];
+    readonly doctorHooks: readonly ["docs"];
+};
+export declare function docsInstallRecipe(_options?: DocsInstallOptions): {
+    dependencies: string[];
+    devDependencies: string[];
+    packageTargets: {
+        path: string;
+        dependencies: string[];
+        devDependencies: string[];
+    }[];
+    skills: string[];
+};
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,EAAE,gBAAgB,GAAG,cAAc,GAAG,cAAc,CAAC;IAC9D,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC9B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;CASrB,CAAC;AAEX,eAAO,MAAM,mBAAmB;;;;;;;;;CAAqB,CAAC;AAEtD,wBAAgB,iBAAiB,CAAC,QAAQ,GAAE,kBAAuB;;;;;;;;;EAiBlE"}

package/dist/install.js

@@ -0,0 +1,29 @@
+export const docsModuleManifest = {
+    schemaVersion: 1,
+    id: "docs",
+    name: "Raybase Docs",
+    packageName: "@raybase/docs",
+    version: "0.1.0",
+    skills: ["raybase-docs-writing"],
+    commands: [],
+    doctorHooks: ["docs"]
+};
+export const docsModuleInstaller = docsModuleManifest;
+export function docsInstallRecipe(_options = {}) {
+    const placement = _options.placement ?? "spine";
+    const rootDependencies = ["@raybase/docs"];
+    const fumadocsDependencies = ["fumadocs-core", "fumadocs-ui", "lucide-react"];
+    const fumadocsDevDependencies = ["fumadocs-mdx", "@types/mdx"];
+    return {
+        dependencies: placement === "site" ? rootDependencies : [...rootDependencies, ...fumadocsDependencies],
+        devDependencies: placement === "site" ? [] : fumadocsDevDependencies,
+        packageTargets: placement === "site"
+            ? [
+                { path: "package.json", dependencies: rootDependencies, devDependencies: [] },
+                { path: "site/package.json", dependencies: fumadocsDependencies, devDependencies: fumadocsDevDependencies }
+            ]
+            : [{ path: "package.json", dependencies: [...rootDependencies, ...fumadocsDependencies], devDependencies: fumadocsDevDependencies }],
+        skills: ["raybase-docs-writing"]
+    };
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,aAAa,EAAE,CAAC;IAChB,EAAE,EAAE,MAAM;IACV,IAAI,EAAE,cAAc;IACpB,WAAW,EAAE,eAAe;IAC5B,OAAO,EAAE,OAAO;IAChB,MAAM,EAAE,CAAC,sBAAsB,CAAC;IAChC,QAAQ,EAAE,EAAE;IACZ,WAAW,EAAE,CAAC,MAAM,CAAC;CACb,CAAC;AAEX,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAEtD,MAAM,UAAU,iBAAiB,CAAC,WAA+B,EAAE;IACjE,MAAM,SAAS,GAAG,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC;IAChD,MAAM,gBAAgB,GAAG,CAAC,eAAe,CAAC,CAAC;IAC3C,MAAM,oBAAoB,GAAG,CAAC,eAAe,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC;IAC9E,MAAM,uBAAuB,GAAG,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;IAC/D,OAAO;QACL,YAAY,EAAE,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,GAAG,gBAAgB,EAAE,GAAG,oBAAoB,CAAC;QACtG,eAAe,EAAE,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,uBAAuB;QACpE,cAAc,EACZ,SAAS,KAAK,MAAM;YAClB,CAAC,CAAC;gBACE,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,EAAE,EAAE;gBAC7E,EAAE,IAAI,EAAE,mBAAmB,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,uBAAuB,EAAE;aAC5G;YACH,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,GAAG,gBAAgB,EAAE,GAAG,oBAAoB,CAAC,EAAE,eAAe,EAAE,uBAAuB,EAAE,CAAC;QACxI,MAAM,EAAE,CAAC,sBAAsB,CAAC;KACjC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,16 +1,46 @@
 {
   "name": "@raybase/docs",
-  "version": "0.0.2",
-  "description": "Reserved for Raybase. Nothing is released under this name yet.",
-  "license": "UNLICENSED",
+  "version": "0.1.2",
+  "description": "First-party Raybase Docs module for generated Fumadocs documentation.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./install": {
+      "types": "./dist/install.d.ts",
+      "default": "./dist/install.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "default": "./dist/cli.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "peerDependencies": {
+    "@raybase/core": "0.3.3"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3",
+    "@raybase/core": "0.3.3"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/raybasedev/raybase.git"
+    "url": "git+https://github.com/raybasedev/raybase.git",
+    "directory": "packages/docs"
   },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
-}
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/templates/astro-emdash/content/docs/getting-started.mdx

@@ -0,0 +1,13 @@
+---
+title: Opening the CMS
+description: Sign in and start editing pages.
+public: false
+---
+
+Sign in with the account your team gave you, then open the public site and choose CMS from the signed-in menu.
+
+Start with Pages. Open an existing draft to review the editing pattern, or create a page when you need a new public URL.
+
+Use the page content field to arrange reusable sections. Each section owns its own copy, media, links, and display options.
+
+Preview before publishing. If a page needs a new reusable section or a layout change, note the goal clearly and ask the project maintainer to add the building block.

package/templates/astro-emdash/content/docs/index.mdx

@@ -0,0 +1,13 @@
+---
+title: Editing the site
+description: A quick map for signed-in content editors.
+public: false
+---
+
+The CMS is where signed-in editors manage public site pages, drafts, media, and reusable page sections.
+
+Use the CMS link in the signed-in site menu to open the editing workspace. If the link is not visible, ask the person who manages access to invite you or adjust your role.
+
+Most pages are built from a title, slug, metadata, and a sequence of reusable sections. Edit copy and media in the CMS, preview changes, then publish when the page is ready.
+
+Keep structural changes deliberate. If you need a new section type, navigation pattern, layout, or data-backed block, ask the project maintainer to add it safely.

package/templates/astro-emdash/content/docs/mcp.mdx

@@ -0,0 +1,11 @@
+---
+title: Connecting an assistant
+description: How signed-in members can connect an approved assistant.
+public: false
+---
+
+Some apps let signed-in members connect an approved AI assistant through the app's `/mcp` endpoint.
+
+Only connect assistants you trust. The assistant should explain what it can read or change before you approve a task.
+
+If the connection fails, confirm you are signed in and ask the project maintainer whether assistant access is enabled for your role.

package/templates/astro-emdash/content/docs/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Docs",
+  "pages": ["index", "getting-started", "mcp"]
+}

package/templates/astro-emdash/site/content/docs/getting-started.mdx

@@ -0,0 +1,12 @@
+---
+title: Finding and updating pages
+description: Navigate published pages and make safe CMS edits.
+---
+
+Use the site navigation to find published pages. Editors can sign in, open the CMS from the site menu, and work with drafts before publishing.
+
+Start with Pages. Open an existing draft to review the editing pattern, or create a page when you need a new public URL.
+
+Use the page content field to arrange reusable sections. Each section owns its own copy, media, links, and display options.
+
+Preview before publishing. If a page needs a new reusable section or a layout change, note the goal clearly and ask the project maintainer to add the building block.

package/templates/astro-emdash/site/content/docs/index.mdx

@@ -0,0 +1,12 @@
+---
+title: Using the site
+description: A quick map for readers and signed-in editors.
+---
+
+The site is built from pages, reusable sections, and published media. Visitors can read published pages, while signed-in editors can open the CMS to manage drafts and updates.
+
+Editors use the CMS link in the signed-in site menu. If the link is not visible, ask the person who manages access to invite you or adjust your role.
+
+Most pages are built from a title, slug, metadata, and a sequence of reusable sections. Edit copy and media in the CMS, preview changes, then publish when the page is ready.
+
+Keep structural changes deliberate. If you need a new section type, navigation pattern, layout, or data-backed block, ask the project maintainer to add it safely.

package/templates/astro-emdash/site/content/docs/mcp.mdx

@@ -0,0 +1,10 @@
+---
+title: Connecting an assistant
+description: How signed-in members can connect an approved assistant.
+---
+
+Some apps let signed-in members connect an approved AI assistant through the app's `/mcp` endpoint.
+
+Only connect assistants you trust. The assistant should explain what it can read or change before you approve a task.
+
+If the connection fails, confirm you are signed in and ask the project maintainer whether assistant access is enabled for your role.

package/templates/astro-emdash/site/content/docs/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Docs",
+  "pages": ["index", "getting-started", "mcp"]
+}

package/templates/astro-emdash/site/source.config.ts

@@ -0,0 +1,10 @@
+import { defineDocs } from "fumadocs-mdx/config";
+
+export const docs = defineDocs({
+  dir: "content/docs",
+  docs: {
+    postprocess: {
+      includeProcessedMarkdown: true
+    }
+  }
+});

package/templates/astro-emdash/site/src/docs/docs-assets.ts

@@ -0,0 +1 @@
+export const docsClientScriptSrc = import.meta.env.DEV ? "/src/docs/docs-client.tsx" : "/assets/raybase-docs-client.js";

package/templates/astro-emdash/site/src/docs/docs-client.tsx

@@ -0,0 +1,22 @@
+import "@vitejs/plugin-react/preamble";
+import { StrictMode, startTransition } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { DocsRoot, preloadDocsContent, type DocsPageData } from "./docs-page";
+
+const root = document.getElementById("raybase-docs-root");
+const dataScript = document.getElementById("raybase-docs-page-data");
+
+if (root && dataScript?.textContent) {
+  const data = JSON.parse(dataScript.textContent) as DocsPageData;
+
+  startTransition(() => {
+    void preloadDocsContent(data).then(() => {
+      hydrateRoot(
+        root,
+        <StrictMode>
+          <DocsRoot data={data} />
+        </StrictMode>
+      );
+    });
+  });
+}

package/templates/astro-emdash/site/src/docs/docs-data.ts

@@ -0,0 +1,24 @@
+import type { SerializedPageTree } from "fumadocs-core/source/client";
+import type { DocsPageData } from "./docs-page";
+import { preloadDocsContent } from "./docs-page";
+import { source } from "./source";
+
+export async function loadDocsPageTree(): Promise<SerializedPageTree> {
+  return source.serializePageTree(source.getPageTree());
+}
+
+export async function loadDocsPageData(slugs: string[]): Promise<DocsPageData | null> {
+  const page = source.getPage(slugs);
+  if (!page) return null;
+
+  const data = {
+    path: page.path,
+    url: page.url,
+    title: page.data.title,
+    description: page.data.description,
+    pageTree: await loadDocsPageTree()
+  } satisfies DocsPageData;
+
+  await preloadDocsContent(data);
+  return data;
+}

package/templates/astro-emdash/site/src/docs/docs-handler.tsx

@@ -0,0 +1,105 @@
+import { createFromSource } from "fumadocs-core/search/server";
+import { renderToReadableStream } from "react-dom/server";
+import docsCss from "../styles-docs.css?inline";
+import { docsClientScriptSrc } from "./docs-assets";
+import { loadDocsPageData, loadDocsPageTree } from "./docs-data";
+import { DocsRoot, type DocsPageData } from "./docs-page";
+import { getDocsMarkdownResponse, getDocsSlugs } from "./llm-text";
+import { source } from "./source";
+
+const docsThemeInitScript =
+  "(function(){try{var t=localStorage.getItem('theme');var d=t==='dark'||((!t||t==='system')&&matchMedia('(prefers-color-scheme: dark)').matches);document.documentElement.classList.toggle('dark',d);}catch(e){}})();";
+
+const search = createFromSource(source, {
+  language: "english"
+});
+
+export async function handleDocsRequest(request: Request): Promise<Response> {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/docs/api/search") {
+    return search.GET(request);
+  }
+
+  if (url.pathname === "/docs/api/markdown") {
+    const response = await getDocsMarkdownResponse(url.searchParams.get("path"));
+    return response ?? new Response("Not found", { status: 404 });
+  }
+
+  if (/\.mdx?$/.test(url.pathname)) {
+    const response = await getDocsMarkdownResponse(url.pathname);
+    return response ?? new Response("Not found", { status: 404 });
+  }
+
+  const data = await loadDocsPageData(getDocsSlugs(url.pathname));
+  if (!data) {
+    return docsHtmlResponse(
+      {
+        path: "",
+        url: url.pathname,
+        title: "Docs page not found",
+        pageTree: await loadDocsPageTree()
+      },
+      "<main class=\"mx-auto flex min-h-screen max-w-3xl flex-col justify-center px-6 py-16\"><p class=\"text-sm font-medium text-fd-muted-foreground\">404</p><h1 class=\"mt-3 text-3xl font-semibold text-fd-foreground\">Docs page not found</h1><p class=\"mt-3 text-fd-muted-foreground\">The requested documentation page does not exist.</p><a class=\"mt-6 inline-flex text-sm font-medium text-fd-primary underline-offset-4 hover:underline\" href=\"/docs\">Back to docs</a></main>",
+      404
+    );
+  }
+
+  return docsHtmlResponse(data, await renderDocsBody(data));
+}
+
+async function renderDocsBody(data: DocsPageData): Promise<string> {
+  const stream = await renderToReadableStream(<DocsRoot data={cloneDocsPageData(data)} />);
+  await stream.allReady;
+  return new Response(stream).text();
+}
+
+function cloneDocsPageData(data: DocsPageData): DocsPageData {
+  return JSON.parse(JSON.stringify(data)) as DocsPageData;
+}
+
+function docsHtmlResponse(data: DocsPageData, body: string, status = 200): Response {
+  const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapeHtml(data.title)}</title>
+    <script>${docsThemeInitScript}</script>
+    <style id="raybase-docs-styles">${docsCss}</style>
+  </head>
+  <body>
+    <div id="raybase-docs-root">${body}</div>
+    <script type="application/json" id="raybase-docs-page-data">${escapeJson(data)}</script>
+    <script type="module" async src="${docsClientScriptSrc}"></script>
+  </body>
+</html>`;
+
+  return new Response(html, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8"
+    }
+  });
+}
+
+function escapeJson(value: unknown): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+function escapeHtml(value: string): string {
+  return value.replace(/[&<>"']/g, (char) => {
+    switch (char) {
+      case "&":
+        return "&amp;";
+      case "<":
+        return "&lt;";
+      case ">":
+        return "&gt;";
+      case "\"":
+        return "&quot;";
+      default:
+        return "&#39;";
+    }
+  });
+}

package/templates/astro-emdash/site/src/docs/docs-layout.tsx

@@ -0,0 +1,56 @@
+import type { DocsLayoutProps } from "fumadocs-ui/layouts/docs";
+import type { ComponentProps } from "react";
+import { ThemeSwitch } from "fumadocs-ui/layouts/shared/slots/theme-switch";
+import { ArrowLeft } from "lucide-react";
+import { appConfig } from "../raybase.config";
+
+const appHomeHref = "/";
+
+export function baseOptions(): Omit<DocsLayoutProps, "children" | "tree"> {
+  return {
+    nav: {
+      title: DocsNavTitle,
+      url: appHomeHref
+    },
+    sidebar: {
+      footer: <DocsSidebarFooter />
+    },
+    themeSwitch: {
+      enabled: false
+    }
+  };
+}
+
+function DocsNavTitle({ className, href = appHomeHref, ...props }: ComponentProps<"a">) {
+  return (
+    <div className={className}>
+      <div className="inline-flex min-w-0 flex-col items-start gap-0.5 leading-none">
+        <a
+          {...props}
+          href={href}
+          title={`Back to ${appConfig.appName}`}
+          className="max-w-44 truncate rounded-sm text-[0.9375rem] font-semibold leading-none text-fd-foreground underline-offset-4 transition-colors hover:text-fd-primary hover:underline focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+        >
+          {appConfig.appName}
+        </a>
+        <span className="text-[0.6875rem] font-medium leading-none text-fd-muted-foreground">Docs</span>
+      </div>
+    </div>
+  );
+}
+
+function DocsSidebarFooter() {
+  return (
+    <div className="mt-2 flex min-w-0 items-center justify-between gap-3 border-t pt-3">
+      <a
+        href={appHomeHref}
+        title={`Back to ${appConfig.appName}`}
+        className="inline-flex min-w-0 items-center gap-1.5 rounded-md px-1 py-1 text-xs font-medium text-fd-muted-foreground transition-colors hover:text-fd-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-fd-ring"
+      >
+        <ArrowLeft className="size-3.5 shrink-0" aria-hidden="true" />
+        <span className="truncate">Back to app</span>
+      </a>
+      <ThemeSwitch className="shrink-0 p-0" />
+    </div>
+  );
+}

package/templates/astro-emdash/site/src/docs/docs-mdx.tsx

@@ -0,0 +1,79 @@
+import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { MDXComponents } from "mdx/types";
+
+interface McpServerUrlProps {
+  path?: string;
+}
+
+interface ClaudeMcpAddCommandProps extends McpServerUrlProps {
+  name?: string;
+}
+
+interface CodexMcpAddCommandProps extends McpServerUrlProps {
+  name?: string;
+}
+
+function browserOrigin() {
+  return typeof window === "undefined" ? "" : window.location.origin;
+}
+
+function currentUrl(path = "/mcp") {
+  const origin = browserOrigin();
+  return origin ? new URL(path, origin).toString() : path;
+}
+
+function McpServerUrl(props: McpServerUrlProps) {
+  return <code suppressHydrationWarning>{currentUrl(props.path)}</code>;
+}
+
+function McpServerUrlBlock(props: McpServerUrlProps) {
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{currentUrl(props.path)}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+function ClaudeMcpAddCommand(props: ClaudeMcpAddCommandProps) {
+  const command = `claude mcp add --transport http ${props.name ?? "this-app"} "${currentUrl(props.path)}"`;
+
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{command}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+function CodexMcpAddCommand(props: CodexMcpAddCommandProps) {
+  const command = `codex mcp add ${props.name ?? "this-app"} --url "${currentUrl(props.path)}"`;
+
+  return (
+    <CodeBlock>
+      <Pre>
+        <code suppressHydrationWarning>{command}</code>
+      </Pre>
+    </CodeBlock>
+  );
+}
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...defaultMdxComponents,
+    McpServerUrl,
+    McpServerUrlBlock,
+    ClaudeMcpAddCommand,
+    CodexMcpAddCommand,
+    ...components
+  } satisfies MDXComponents;
+}
+
+export const useMDXComponents = getMDXComponents;
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}