@haruhimemoe/next-kit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-04
+
+### Added
+- `docs` entry point: a content registry (`defineContent`, `CONTENT_SECTIONS`, `SECTION_LABELS`) and the path helpers (`contentPath`, `markdownPath`, `findEntry`, `contentParams`) for an app's docs, guides and legal pages, plus app-made extra entries like bb's tag pages. No runtime imports.
+- `mdxToMarkdown` in `docs`: converts bb-flavored MDX to plain Markdown (callouts to blockquotes, import/export lines dropped, capitalized JSX removed, root-relative links and images absolutized, a title heading added when missing). Content inside fenced code blocks is left untouched. Still no runtime imports.
+- `docs/files` entry point: `readContentMarkdown` reads and converts a registered entry's markdown file, and `contentFileDrift` compares a registry against the files on disk. Loads `node:fs`.
+- `contentLlmsTxt`, `contentLlmsFull`, `contentSitemap` and `contentRewrites` in `docs`: llms.txt (sections in order Docs, Guides, API, Legal, empty ones left out), llms-full.txt (each entry's own leading H1 stripped, since `llmsFull` writes the part title), sitemap records per section (an index path, each entry, each extra) and the one rewrite rule for a content page's ".md" mirror. Built on `llmsTxt`/`llmsFull`/`SitemapRecord` from `seo`. Still no runtime imports.
+
+### Changed
+- **Breaking (check only).** `next-kit check` now also checks files under `content/` and adds the `brand` and `legal` standards: `brand/page.tsx` and `legal/page.tsx` plus `legal/[x]/page.tsx`, `legal/[x]/md/route.ts`, `content/legal/terms.mdx` and `content/legal/privacy.mdx` are required on every app. A `docs` standard (`docs/page.tsx`, `docs/[x]/page.tsx`, `docs/[x]/md/route.ts`) joins in once `src/app/api/v1` exists or any `content/docs` file does; a `guides` standard joins in only once a `content/guides` file does. The `api` standard drops its `docs/api/page.tsx` requirement in favor of `content/docs/api.mdx`. `checkStandards` takes a second `contentFiles` argument; `StandardResult.missing` entries now carry their own `src/app/` or `content/` prefix. This is a 0.x minor: an app with no `/brand`, `/legal` route or legal content fails `next-kit check` in CI until it adds them.
+- `@haruhimemoe/ui` peer range also covers 0.10.0 (not yet published).
+
 ## [0.5.0] - 2026-10-04
 
 ### Added
@@ -62,7 +74,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 - `@haruhimemoe/next-kit/auth-react`: `createSignedInMarker`, `createAccountStore`, `useAccount`, `createAccount`, `RestoreSignedIn` and `osuSignIn`.
 - `@haruhimemoe/next-kit/testing`: `startMemoryMongo`, `setupTestDb`, `setupMsw` and the fake osu! app env.
 
-[unreleased]: https://github.com/haruhimemoe/next-kit/compare/v0.5.0...HEAD
+[unreleased]: https://github.com/haruhimemoe/next-kit/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/haruhimemoe/next-kit/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/haruhimemoe/next-kit/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/haruhimemoe/next-kit/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/haruhimemoe/next-kit/compare/v0.2.1...v0.3.0

package/README.md

@@ -12,6 +12,7 @@ The Next.js server plumbing the haruhime.moe tools share. [packs.haruhime.moe](h
 - **`/seo`:** Next.js metadata that keeps each page's canonical, og:url and preview image together, robots.txt with the AI crawler stance written down, sitemap entries with honest lastmod, schema.org JSON-LD builders, and llms.txt. No runtime imports; all four haruhime.moe sites use it.
 - **`/testing`:** Vitest helpers: one in-memory MongoDB per run, an msw server that refuses unhandled requests, and a fake env.
 - **`/api-keys`:** the shared key format (an app prefix like `hpk_` plus 32 random bytes), a key store over `api_keys`, and the `/api/v1` guard with the standard limits.
+- **`/docs`:** a content registry for an app's docs, guides and legal pages: sections, entries, app-made extra entries (like bb's tag pages), the path helpers a dynamic route needs, and `mdxToMarkdown` to turn bb-flavored MDX into plain Markdown. No runtime imports. **`/docs/files`:** reads the markdown files a registry's entries point at and reports drift between the registry and disk (node:fs).
 
 Every name, path, limit and message comes from the caller. There is no root entry point; import a subpath.
 
@@ -30,10 +31,12 @@ bun add @haruhimemoe/next-kit zod
 | `env` | nothing else |
 | `mongo` | `mongodb` ^7.6.0, `mongoose` ^9.10.2 |
 | `auth` | `better-auth` ^1.7.5, `mongodb`, `@haruhimemoe/osu` 0.2 or 0.3 |
-| `auth-react` | `react` ^19.3.0, `next` ^16.3.6, `@haruhimemoe/ui` ^0.5.0 \|\| ^0.6.0 \|\| ^0.7.0 \|\| ^0.8.0 \|\| ^0.9.0 (with its theme set up) |
+| `auth-react` | `react` ^19.3.0, `next` ^16.3.6, `@haruhimemoe/ui` ^0.5.0 \|\| ^0.6.0 \|\| ^0.7.0 \|\| ^0.8.0 \|\| ^0.9.0 \|\| ^0.10.0 (with its theme set up) |
 | `seo` | `next` ^16.3.6 types only (nothing loads at runtime) |
 | `testing` | `vitest` ^5.0.1, `msw` ^2.15.0, `mongodb-memory-server` ^11.3.0 |
 | `api-keys` | `mongodb` ^7.6.0 |
+| `docs` | nothing else |
+| `docs/files` | nothing else (`node:fs` is built in) |
 
 ## Use
 
@@ -149,15 +152,84 @@ export default async () => sitemapEntries(SEO_SITE, [["/", "/search"], pools.map
 export const GET = () => textResponse(llmsTxt({ title: "pools.haruhime.moe", summary: SEO_SITE.description, sections }));
 ```
 
+### Docs (./docs)
+
+One registry per app, built from its docs, guides and legal entries; the crawl helpers and a dynamic route are built on top of it.
+
+```ts
+// src/constants/content.ts
+import { defineContent } from "@haruhimemoe/next-kit/docs";
+
+export const CONTENT = defineContent({
+  docs: [{ slug: "api", title: "API", description: "The /api/v1 reference.", lastUpdated: "2026-10-04" }],
+  guides: [{ slug: "make-a-pack", title: "Make a pack", description: "Build your first mappool.", lastUpdated: "2026-10-04" }],
+  legal: [
+    { slug: "terms", title: "Terms of service", description: "The rules for using pools.", lastUpdated: "2026-10-04" },
+    { slug: "privacy", title: "Privacy policy", description: "What pools stores and why.", lastUpdated: "2026-10-04" },
+  ],
+});
+
+// src/app/docs/[slug]/page.tsx (and guides/, legal/, the same shape)
+import { findEntry } from "@haruhimemoe/next-kit/docs";
+import { readContentMarkdown } from "@haruhimemoe/next-kit/docs/files";
+import { CONTENT } from "../../../constants/content";
+
+export default async function DocPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const entry = findEntry(CONTENT, "docs", slug);
+  if (!entry) return notFound();
+  const markdown = await readContentMarkdown(CONTENT, "docs", slug, { siteUrl: SEO_SITE.url });
+  return <Markdown>{markdown}</Markdown>;
+}
+
+// src/app/llms.txt/route.ts
+import { contentLlmsTxt } from "@haruhimemoe/next-kit/docs";
+import { textResponse } from "@haruhimemoe/next-kit/seo";
+
+export const GET = () =>
+  textResponse(contentLlmsTxt({ site: SEO_SITE, title: "pools.haruhime.moe", summary: SEO_SITE.description, content: CONTENT }));
+
+// src/app/llms-full.txt/route.ts
+import { contentLlmsFull } from "@haruhimemoe/next-kit/docs";
+import { readContentMarkdown } from "@haruhimemoe/next-kit/docs/files";
+
+export const GET = async () =>
+  textResponse(
+    await contentLlmsFull({
+      site: SEO_SITE, title: "pools.haruhime.moe", content: CONTENT,
+      read: (section, slug) => readContentMarkdown(CONTENT, section, slug, { siteUrl: SEO_SITE.url }),
+    }),
+  );
+
+// src/app/sitemap.ts
+import { contentSitemap } from "@haruhimemoe/next-kit/docs";
+
+export default async () => sitemapEntries(SEO_SITE, [["/", "/search"], contentSitemap(CONTENT)]);
+
+// next.config.ts
+import { contentRewrites } from "@haruhimemoe/next-kit/docs";
+
+export default { async rewrites() { return contentRewrites(); } };
+```
+
 ## Standards check
 
-`next-kit check [dir]` walks `src/app` (default: the current directory) and confirms every standard route exists, so CI catches a missing one before a page does:
+`next-kit check [dir]` walks `src/app` and, when it exists, `content/` (both under `dir`, default: the current directory) and confirms every standard file exists, so CI catches a missing one before a page does. It checks files only; the content registry itself is never parsed.
 
 ```sh
 bunx next-kit check
 ```
 
-It always checks the crawl files: `robots.ts`, `sitemap.ts`, `llms.txt/route.ts`, `llms-full.txt/route.ts`, and `.well-known/security.txt/route.ts` (each also accepted as a route handler, like `robots.txt/route.ts`). Once an app has `src/app/api/v1/`, it also checks the public API: `api/v1/me/route.ts`, `api/v1/openapi.json/route.ts`, `api/me/api-key/route.ts`, and a `docs/api` page (a dynamic `docs/[slug]/page.tsx` counts too). Route groups like `(public)/` are ignored, since they don't change the URL.
+Every app is checked against:
+
+- **crawl** (always): `robots.ts`, `sitemap.ts`, `llms.txt/route.ts`, `llms-full.txt/route.ts`, and `.well-known/security.txt/route.ts` (each also accepted as a route handler, like `robots.txt/route.ts`).
+- **brand** (always): `brand/page.tsx`.
+- **legal** (always): `legal/page.tsx`, `legal/[x]/page.tsx`, `legal/[x]/md/route.ts` (any dynamic segment name), and `content/legal/terms.mdx` plus `content/legal/privacy.mdx`.
+- **docs**, once `src/app/api/v1` exists or any `content/docs` file does: `docs/page.tsx`, `docs/[x]/page.tsx`, `docs/[x]/md/route.ts`.
+- **guides**, only once a `content/guides` file exists: the same three files under `guides/`. An app with no guides is never asked for them.
+- **api**, once `src/app/api/v1` exists: `api/v1/me/route.ts`, `api/v1/openapi.json/route.ts`, `api/me/api-key/route.ts`, and `content/docs/api.mdx`.
+
+Route groups like `(public)/` are ignored, since they don't change the URL. A missing route file prints as `missing src/app/<path>`; a missing content file prints as `missing content/<path>`.
 
 The command prints one `pass` or `FAIL` line per standard, names each missing file, and exits 1 on a failure (or when `src/app` is missing). Add it to CI:
 
@@ -290,6 +362,35 @@ Since 0.3.0. Every helper takes the app's `Site`: `name`, `url` (the canonical o
 | `API_SERVER_ERROR` | The 500 message when a key lookup or handler throws. |
 | `createApiKeyGuard({ store, limiter, resolveCaller, messages, limits?, now? })` | Returns `withApiKey(handler)`: a `/api/v1` route handler that runs `handler(request, caller, context)` only for a good key under `API_LIMITS`, with `RateLimit-*` headers, `Cache-Control: no-store`, a 401 with `WWW-Authenticate: Bearer` for a missing or bad key (counted per IP), and a JSON 500 for a thrown error. No CORS headers: the API is for servers and bots. |
 
+### docs
+
+No runtime imports.
+
+| Export | What it does |
+| --- | --- |
+| `CONTENT_SECTIONS`, `ContentSection` | The sections a site can have, in display order: `"docs"`, `"guides"`, `"legal"`. |
+| `SECTION_LABELS` | The nav label for each section, like "Guides". |
+| `defineContent(input)` | Validates and fills in a `Content`: `sections` lists only the non-empty ones, in `CONTENT_SECTIONS` order; `entries` and `extra` hold every section (empty arrays for the ones left out). Throws naming the section and slug (or extra href) for a bad slug (lowercase words, single hyphens), a duplicate slug or extra href, a `lastUpdated` that isn't a real `YYYY-MM-DD` date, or a blank title. |
+| `ContentEntry`, `HowToStep` | A markdown-backed page: `slug`, `title`, `navTitle?`, `description`, `lastUpdated` (`YYYY-MM-DD`), `howTo?` (numbered steps). |
+| `ExtraEntry` | An app-made page shown in a section's nav and search, like bb's tag pages: `href`, `title`, `navTitle?`, `description`, `group`, `badge?`, `lastUpdated?`, `markdownHref?`. |
+| `contentPath(section, slug)`, `markdownPath(section, slug)` | `/section/slug` and `/section/slug.md`. |
+| `findEntry(content, section, slug)` | The matching `ContentEntry`, or undefined. |
+| `contentParams(content, section)` | `{ slug }[]` for a dynamic route's `generateStaticParams`. |
+| `mdxToMarkdown(source, { title, siteUrl, transforms? })` | Converts bb-flavored MDX to plain Markdown, outside fenced code blocks only: CRLF/CR become LF (`transforms` run first, on the whole source); top-level `import`/`export` lines and an `export const x = {` block are dropped; `<Callout type="..." title="...">body</Callout>` becomes a blockquote (`> **Type:** body`, type missing means "Note"); other capitalized JSX tags are removed (text between them stays, lowercase HTML tags stay); a link or image target starting with a single `/` becomes absolute with `siteUrl`; `title` is prepended as a `# ` heading when the first non-blank line isn't one; runs of 3+ blank lines collapse to 2, and the result ends with exactly one newline. |
+| `contentLlmsTxt({ site, title, summary, notes?, content, api? })` | The llms.txt body: sections in order Docs, Guides, API, Legal. Each entry links to its absolute `.md` URL with its description as the note; an extra links to `markdownHref` when set, else `href`. An empty section (no entries, no extras, no `api` links) is left out. |
+| `contentLlmsFull({ site, title, summary?, content, read, before?, after? })` | The llms-full.txt body: `before`, then every registry entry in section order (title, its absolute page URL, and `read(section, slug)`'s Markdown with its own leading `# ` heading stripped, since `llmsFull` writes the part title as the H1), then `after`. `read` is usually `readContentMarkdown` from `docs/files`. |
+| `contentSitemap(content)` | A `SitemapRecord[]` for `seo`'s `sitemapEntries`: one non-empty section's index path (like `/docs`, `lastModified` set to the newest `lastUpdated` among its entries and extras, omitted when none have one), then each entry with its own `lastUpdated`, then each extra with its own `lastUpdated` when set. |
+| `contentRewrites()` | The one Next.js rewrite rule that mirrors a content page's `.md` URL (`/docs/x.md`, `/guides/x.md`, `/legal/x.md`) to its route handler (`/docs/x/md`, ...). Pure, takes no registry. |
+
+### docs/files
+
+`node:fs`. Markdown source for an entry lives at `<root>/content/<section>/<slug>.mdx`.
+
+| Export | What it does |
+| --- | --- |
+| `readContentMarkdown(content, section, slug, { root?, siteUrl, transforms? })` | Reads a registered entry's markdown file and converts it with `mdxToMarkdown` (using the entry's `title`). `root` defaults to `process.cwd()`. Returns null for an unregistered slug; rejects (ENOENT) when the slug is registered but its file is missing. |
+| `contentFileDrift(content, { root? })` | `{ missingFiles, unregistered }`: `missingFiles` lists registered entries with no file on disk (like `"guides/x.mdx"`); `unregistered` lists `.mdx` files on disk with no registry entry. `root` defaults to `process.cwd()`. |
+
 ## Migration
 
 Both apps can drop their copies for the subpaths above. Where the copies differed, this package keeps pools.haruhime.moe's behavior. What changes for packs.haruhime.moe:
@@ -308,7 +409,7 @@ For pools.haruhime.moe, `createMongo` runs `onConnect` (the privilege check, ind
 
 ## Compatibility
 
-ES modules for Node 22.12+ on the server. `auth-react` also runs in browsers; its hook and component files keep `"use client"`, and it loads only `react`, `next/navigation.js` and `@haruhimemoe/ui`. `server` loads `node:crypto` for machine auth. `seo` loads nothing at runtime (Next's types only), so it runs anywhere.
+ES modules for Node 22.12+ on the server. `auth-react` also runs in browsers; its hook and component files keep `"use client"`, and it loads only `react`, `next/navigation.js` and `@haruhimemoe/ui`. `server` loads `node:crypto` for machine auth. `seo` and `docs` load nothing at runtime (Next's types only, or nothing), so they run anywhere; `docs/files` loads `node:fs` and stays server only.
 
 ## License
 

package/dist/check/cli.d.ts

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
 /**
  * @file src/check/cli.ts
- * @desc `next-kit check [dir]`: lists src/app under dir (default: the working directory), runs
- *       checkStandards and prints one line per standard. Exits 1 when one fails or src/app is
- *       missing.
+ * @desc `next-kit check [dir]`: lists src/app and content (when it exists) under dir (default:
+ *       the working directory), runs checkStandards and prints one line per standard. Exits 1
+ *       when one fails or src/app is missing.
  * @author David @dvhsh (https://dvh.sh)
  * @created Sat Oct 3, 2026
- * @modified Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
  */
 /**
  * @function runCheck
- * @param root {string} the app's root (holds src/app)
+ * @param root {string} the app's root (holds src/app and, optionally, content/)
  * @param log {(line: string) => void} where lines go (default console.log)
  * @returns {number} 0 when every standard passes, otherwise 1
  */

package/dist/check/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 /**
  * @file src/check/cli.ts
- * @desc `next-kit check [dir]`: lists src/app under dir (default: the working directory), runs
- *       checkStandards and prints one line per standard. Exits 1 when one fails or src/app is
- *       missing.
+ * @desc `next-kit check [dir]`: lists src/app and content (when it exists) under dir (default:
+ *       the working directory), runs checkStandards and prints one line per standard. Exits 1
+ *       when one fails or src/app is missing.
  * @author David @dvhsh (https://dvh.sh)
  * @created Sat Oct 3, 2026
- * @modified Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
  */
 import { existsSync, readdirSync, realpathSync } from "node:fs";
 import { join, relative, sep } from "node:path";
@@ -14,9 +14,10 @@ import { argv, cwd, exit } from "node:process";
 import { pathToFileURL } from "node:url";
 import { checkStandards } from "./standards.js";
 const walk = (dir) => readdirSync(dir, { withFileTypes: true }).flatMap((entry) => entry.isDirectory() ? walk(join(dir, entry.name)) : [join(dir, entry.name)]);
+const relativeFiles = (dir) => walk(dir).map((file) => relative(dir, file).split(sep).join("/"));
 /**
  * @function runCheck
- * @param root {string} the app's root (holds src/app)
+ * @param root {string} the app's root (holds src/app and, optionally, content/)
  * @param log {(line: string) => void} where lines go (default console.log)
  * @returns {number} 0 when every standard passes, otherwise 1
  */
@@ -26,12 +27,13 @@ export const runCheck = (root, log = console.log) => {
         log(`next-kit check: no src/app in ${root}`);
         return 1;
     }
-    const files = walk(app).map((file) => relative(app, file).split(sep).join("/"));
-    const results = checkStandards(files);
+    const contentDir = join(root, "content");
+    const contentFiles = existsSync(contentDir) ? relativeFiles(contentDir) : [];
+    const results = checkStandards(relativeFiles(app), contentFiles);
     for (const result of results) {
         log(`${result.ok ? "pass" : "FAIL"}  ${result.label}`);
-        for (const name of result.missing)
-            log(`      missing src/app/${name}`);
+        for (const missing of result.missing)
+            log(`      missing ${missing}`);
     }
     return results.every((result) => result.ok) ? 0 : 1;
 };

package/dist/check/standards.d.ts

@@ -1,13 +1,17 @@
 /**
  * @file src/check/standards.ts
- * @desc The routes every haruhime app serves, checked against an app's file list (paths under
- *       src/app). Crawl files always; the API standard once api/v1 exists. Brand and guides
- *       join in phase 2.
+ * @desc The routes and content files every haruhime app serves, checked against an app's route
+ *       file list (paths under src/app) and content file list (paths under content/). Crawl and
+ *       brand are always checked; legal always checks its three routes plus its two content
+ *       files; docs joins in once api/v1 exists or a content/docs file does; guides joins in
+ *       only once a content/guides file does; the API standard, once api/v1 exists, checks its
+ *       three routes plus content/docs/api.mdx. Checks files only: the content registry itself
+ *       is never parsed.
  * @author David @dvhsh (https://dvh.sh)
  * @created Sat Oct 3, 2026
- * @modified Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
  */
-/** One standard's outcome. */
+/** One standard's outcome. `missing` entries carry their own prefix (src/app/... or content/...). */
 export type StandardResult = {
     id: string;
     label: string;
@@ -16,7 +20,10 @@ export type StandardResult = {
 };
 /**
  * @function checkStandards
- * @param files {readonly string[]} every file under src/app, relative, "/"-separated
- * @returns {StandardResult[]} crawl files always, the API standard when api/v1 exists
+ * @param appFiles {readonly string[]} every file under src/app, relative, "/"-separated
+ * @param contentFiles {readonly string[]} every file under content/, relative, "/"-separated
+ * @returns {StandardResult[]} crawl and brand always, legal always, docs once api/v1 exists or
+ *   a content/docs file does, guides once a content/guides file does, and the API standard once
+ *   api/v1 exists
  */
-export declare const checkStandards: (files: readonly string[]) => StandardResult[];
+export declare const checkStandards: (appFiles: readonly string[], contentFiles?: readonly string[]) => StandardResult[];

package/dist/check/standards.js

@@ -1,51 +1,85 @@
 /**
  * @file src/check/standards.ts
- * @desc The routes every haruhime app serves, checked against an app's file list (paths under
- *       src/app). Crawl files always; the API standard once api/v1 exists. Brand and guides
- *       join in phase 2.
+ * @desc The routes and content files every haruhime app serves, checked against an app's route
+ *       file list (paths under src/app) and content file list (paths under content/). Crawl and
+ *       brand are always checked; legal always checks its three routes plus its two content
+ *       files; docs joins in once api/v1 exists or a content/docs file does; guides joins in
+ *       only once a content/guides file does; the API standard, once api/v1 exists, checks its
+ *       three routes plus content/docs/api.mdx. Checks files only: the content registry itself
+ *       is never parsed.
  * @author David @dvhsh (https://dvh.sh)
  * @created Sat Oct 3, 2026
- * @modified Sat Oct 3, 2026
+ * @modified Sun Oct 4, 2026
  */
-const has = (...patterns) => (files) => files.some((file) => patterns.some((pattern) => pattern.test(file)));
+/** A route under src/app, matched against any of `patterns`. */
+const route = (name, ...patterns) => ({
+    missing: `src/app/${name}`,
+    matches: (app) => app.some((file) => patterns.some((pattern) => pattern.test(file))),
+});
+/** A file under content/, matched by exact path. */
+const content = (path) => ({
+    missing: `content/${path}`,
+    matches: (_app, files) => files.includes(path),
+});
 const CRAWL = [
-    { name: "robots.ts", matches: has(/^robots\.(ts|js)$/, /^robots\.txt\/route\.(ts|js)$/) },
-    { name: "sitemap.ts", matches: has(/^sitemap\.(ts|js)$/, /^sitemap\.xml\/route\.(ts|js)$/) },
-    { name: "llms.txt/route.ts", matches: has(/^llms\.txt\/route\.(ts|js)$/) },
-    { name: "llms-full.txt/route.ts", matches: has(/^llms-full\.txt\/route\.(ts|js)$/) },
-    {
-        name: ".well-known/security.txt/route.ts",
-        matches: has(/^\.well-known\/security\.txt\/route\.(ts|js)$/),
-    },
+    route("robots.ts", /^robots\.(ts|js)$/, /^robots\.txt\/route\.(ts|js)$/),
+    route("sitemap.ts", /^sitemap\.(ts|js)$/, /^sitemap\.xml\/route\.(ts|js)$/),
+    route("llms.txt/route.ts", /^llms\.txt\/route\.(ts|js)$/),
+    route("llms-full.txt/route.ts", /^llms-full\.txt\/route\.(ts|js)$/),
+    route(".well-known/security.txt/route.ts", /^\.well-known\/security\.txt\/route\.(ts|js)$/),
 ];
+const BRAND = [route("brand/page.tsx", /^brand\/page\.(tsx|jsx|ts|js)$/)];
+/** docs/page.tsx, docs/[x]/page.tsx and docs/[x]/md/route.ts under a section, any segment name. */
+const sectionRoutes = (section) => [
+    route(`${section}/page.tsx`, new RegExp(`^${section}/page\\.(tsx|jsx|ts|js)$`)),
+    route(`${section}/[x]/page.tsx`, new RegExp(`^${section}/\\[[^\\]]+\\]/page\\.(tsx|jsx|ts|js)$`)),
+    route(`${section}/[x]/md/route.ts`, new RegExp(`^${section}/\\[[^\\]]+\\]/md/route\\.(ts|js)$`)),
+];
+const LEGAL = [
+    ...sectionRoutes("legal"),
+    content("legal/terms.mdx"),
+    content("legal/privacy.mdx"),
+];
+const DOCS = sectionRoutes("docs");
+const GUIDES = sectionRoutes("guides");
 const API = [
-    { name: "api/v1/me/route.ts", matches: has(/^api\/v1\/me\/route\.(ts|js)$/) },
-    {
-        name: "api/v1/openapi.json/route.ts",
-        matches: has(/^api\/v1\/openapi\.json\/route\.(ts|js)$/),
-    },
-    { name: "api/me/api-key/route.ts", matches: has(/^api\/me\/api-key\/route\.(ts|js)$/) },
-    {
-        name: "docs/api/page.tsx",
-        matches: has(/^(\([^)]+\)\/)?docs\/(api|\[[^\]]+\])\/page\.(tsx|jsx|ts|js)$/),
-    },
+    route("api/v1/me/route.ts", /^api\/v1\/me\/route\.(ts|js)$/),
+    route("api/v1/openapi.json/route.ts", /^api\/v1\/openapi\.json\/route\.(ts|js)$/),
+    route("api/me/api-key/route.ts", /^api\/me\/api-key\/route\.(ts|js)$/),
+    content("docs/api.mdx"),
 ];
-const evaluate = (id, label, reqs, files) => {
-    const missing = reqs.filter((req) => !req.matches(files)).map((req) => req.name);
+const evaluate = (id, label, reqs, app, files) => {
+    const missing = reqs.filter((req) => !req.matches(app, files)).map((req) => req.missing);
     return { id, label, ok: missing.length === 0, missing };
 };
 /** Route groups like (public)/ don't change the URL, so they are dropped before matching. */
 const ungrouped = (file) => file.replace(/(^|\/)\([^)]+\)(?=\/)/g, "").replace(/^\//, "");
 /**
  * @function checkStandards
- * @param files {readonly string[]} every file under src/app, relative, "/"-separated
- * @returns {StandardResult[]} crawl files always, the API standard when api/v1 exists
+ * @param appFiles {readonly string[]} every file under src/app, relative, "/"-separated
+ * @param contentFiles {readonly string[]} every file under content/, relative, "/"-separated
+ * @returns {StandardResult[]} crawl and brand always, legal always, docs once api/v1 exists or
+ *   a content/docs file does, guides once a content/guides file does, and the API standard once
+ *   api/v1 exists
  */
-export const checkStandards = (files) => {
-    const flat = files.map(ungrouped);
-    const results = [evaluate("crawl", "Crawl files", CRAWL, flat)];
-    if (flat.some((file) => file.startsWith("api/v1/"))) {
-        results.push(evaluate("api", "Public API", API, flat));
+export const checkStandards = (appFiles, contentFiles = []) => {
+    const app = appFiles.map(ungrouped);
+    const hasApi = app.some((file) => file.startsWith("api/v1/"));
+    const hasDocsContent = contentFiles.some((file) => file.startsWith("docs/"));
+    const hasGuidesContent = contentFiles.some((file) => file.startsWith("guides/"));
+    const results = [
+        evaluate("crawl", "Crawl files", CRAWL, app, contentFiles),
+        evaluate("brand", "Brand page", BRAND, app, contentFiles),
+        evaluate("legal", "Legal pages", LEGAL, app, contentFiles),
+    ];
+    if (hasApi || hasDocsContent) {
+        results.push(evaluate("docs", "Docs pages", DOCS, app, contentFiles));
+    }
+    if (hasGuidesContent) {
+        results.push(evaluate("guides", "Guides pages", GUIDES, app, contentFiles));
+    }
+    if (hasApi) {
+        results.push(evaluate("api", "Public API", API, app, contentFiles));
     }
     return results;
 };

package/dist/docs/crawl.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file src/docs/crawl.ts
+ * @desc /llms.txt, /llms-full.txt, sitemap entries and the ".md" mirror rewrite, built straight
+ *       from a content registry. Pure: no node: imports or file reads here (an app's
+ *       `read`/`readContentMarkdown` provides the Markdown), so it runs anywhere `docs` does.
+ *       Reuses `llmsTxt`/`llmsFull` from `../seo/llms.js` for formatting, so escaping and section
+ *       shape stay the same as every other haruhime.moe crawl file.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { type LlmsFullPart } from "../seo/llms.js";
+import { type Site } from "../seo/site.js";
+import type { SitemapRecord } from "../seo/sitemap.js";
+import { type Content, type ContentSection } from "./registry.js";
+/** The "API" section's links: a title, an already-absolute URL and an optional note. */
+export type ContentApiLink = {
+    title: string;
+    url: string;
+    note?: string;
+};
+/** contentLlmsTxt's options. */
+export type ContentLlmsTxtOptions = {
+    site: Site;
+    title: string;
+    summary: string;
+    notes?: readonly string[];
+    content: Content;
+    /** The "API" section's links, like the OpenAPI document or `/api/v1/me`. */
+    api?: readonly ContentApiLink[];
+};
+/**
+ * @function contentLlmsTxt
+ * @param options {ContentLlmsTxtOptions} the site, the file's head, the registry and the API
+ *   section's links
+ * @returns {string} the llms.txt body, sections in order Docs, Guides, API, Legal; an empty
+ *   section (no entries, no extras, no `api` links) is left out
+ */
+export declare const contentLlmsTxt: (options: ContentLlmsTxtOptions) => string;
+/** contentLlmsFull's options. */
+export type ContentLlmsFullOptions = {
+    site: Site;
+    title: string;
+    summary?: string;
+    content: Content;
+    /** Reads one entry's Markdown, usually `readContentMarkdown` from `docs/files`. */
+    read: (section: ContentSection, slug: string) => Promise<string>;
+    /** Parts written before the registry's entries, like a brief introduction. */
+    before?: readonly LlmsFullPart[];
+    /** Parts written after the registry's entries, like extras an app reads on its own. */
+    after?: readonly LlmsFullPart[];
+};
+/**
+ * @function contentLlmsFull
+ * @param options {ContentLlmsFullOptions} the site, the file's head, the registry, a reader and
+ *   extra parts to place before and after the registry's entries
+ * @returns {Promise<string>} the llms-full.txt body: `before`, then every registry entry in
+ *   section order (title, its absolute page URL, and `read`'s Markdown with its own leading H1
+ *   stripped, since `llmsFull` writes the part title as the H1), then `after`
+ */
+export declare const contentLlmsFull: (options: ContentLlmsFullOptions) => Promise<string>;
+/**
+ * @function contentSitemap
+ * @param content {Content} a registry from `defineContent`
+ * @returns {SitemapRecord[]} one record per non-empty section: the section's index path (like
+ *   "/docs") with `lastModified` set to the newest `lastUpdated` among its entries and extras
+ *   (omitted when none have one), then each entry with its own `lastUpdated`, then each extra
+ *   with its own `lastUpdated` when set
+ */
+export declare const contentSitemap: (content: Content) => SitemapRecord[];
+/** One Next.js rewrite rule: `source` and `destination`. */
+export type ContentRewriteRule = {
+    source: string;
+    destination: string;
+};
+/**
+ * @function contentRewrites
+ * @returns {ContentRewriteRule[]} the one rule that mirrors a content page's ".md" URL
+ *   (`/docs/x.md`, `/guides/x.md`, `/legal/x.md`) to its route handler (`/docs/x/md`, ...)
+ */
+export declare const contentRewrites: () => ContentRewriteRule[];

package/dist/docs/crawl.js

@@ -0,0 +1,115 @@
+/**
+ * @file src/docs/crawl.ts
+ * @desc /llms.txt, /llms-full.txt, sitemap entries and the ".md" mirror rewrite, built straight
+ *       from a content registry. Pure: no node: imports or file reads here (an app's
+ *       `read`/`readContentMarkdown` provides the Markdown), so it runs anywhere `docs` does.
+ *       Reuses `llmsTxt`/`llmsFull` from `../seo/llms.js` for formatting, so escaping and section
+ *       shape stay the same as every other haruhime.moe crawl file.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Sun Oct 4, 2026
+ * @modified Sun Oct 4, 2026
+ */
+import { llmsFull, llmsTxt, } from "../seo/llms.js";
+import { absoluteUrl } from "../seo/site.js";
+import { contentPath, markdownPath, SECTION_LABELS, } from "./registry.js";
+const sectionLinks = (site, content, section) => [
+    ...content.entries[section].map((entry) => ({
+        title: entry.title,
+        url: absoluteUrl(site, markdownPath(section, entry.slug)),
+        note: entry.description,
+    })),
+    ...content.extra[section].map((extra) => ({
+        title: extra.title,
+        url: absoluteUrl(site, extra.markdownHref ?? extra.href),
+        note: extra.description,
+    })),
+];
+/**
+ * @function contentLlmsTxt
+ * @param options {ContentLlmsTxtOptions} the site, the file's head, the registry and the API
+ *   section's links
+ * @returns {string} the llms.txt body, sections in order Docs, Guides, API, Legal; an empty
+ *   section (no entries, no extras, no `api` links) is left out
+ */
+export const contentLlmsTxt = (options) => {
+    const { site, title, summary, notes, content, api = [] } = options;
+    const sections = [
+        { heading: SECTION_LABELS.docs, links: sectionLinks(site, content, "docs") },
+        { heading: SECTION_LABELS.guides, links: sectionLinks(site, content, "guides") },
+        {
+            heading: "API",
+            links: api.map(({ title: t, url, note }) => ({ title: t, url, ...(note ? { note } : {}) })),
+        },
+        { heading: SECTION_LABELS.legal, links: sectionLinks(site, content, "legal") },
+    ];
+    return llmsTxt({ title, summary, ...(notes ? { notes } : {}), sections });
+};
+/** A leading "# ...\n" line, and the one blank line after it, if any. */
+const LEADING_HEADING = /^# [^\n]*\n\n?/;
+const stripLeadingHeading = (markdown) => markdown.replace(LEADING_HEADING, "");
+/**
+ * @function contentLlmsFull
+ * @param options {ContentLlmsFullOptions} the site, the file's head, the registry, a reader and
+ *   extra parts to place before and after the registry's entries
+ * @returns {Promise<string>} the llms-full.txt body: `before`, then every registry entry in
+ *   section order (title, its absolute page URL, and `read`'s Markdown with its own leading H1
+ *   stripped, since `llmsFull` writes the part title as the H1), then `after`
+ */
+export const contentLlmsFull = async (options) => {
+    const { site, title, summary, content, read, before = [], after = [] } = options;
+    const parts = [...before];
+    for (const section of content.sections) {
+        for (const entry of content.entries[section]) {
+            const markdown = await read(section, entry.slug);
+            parts.push({
+                title: entry.title,
+                url: absoluteUrl(site, contentPath(section, entry.slug)),
+                markdown: stripLeadingHeading(markdown),
+            });
+        }
+    }
+    parts.push(...after);
+    return llmsFull(parts, { title, ...(summary ? { summary } : {}) });
+};
+const newestDate = (dates) => dates.length ? dates.reduce((newest, date) => (date > newest ? date : newest)) : undefined;
+/**
+ * @function contentSitemap
+ * @param content {Content} a registry from `defineContent`
+ * @returns {SitemapRecord[]} one record per non-empty section: the section's index path (like
+ *   "/docs") with `lastModified` set to the newest `lastUpdated` among its entries and extras
+ *   (omitted when none have one), then each entry with its own `lastUpdated`, then each extra
+ *   with its own `lastUpdated` when set
+ */
+export const contentSitemap = (content) => {
+    const records = [];
+    for (const section of content.sections) {
+        const entries = content.entries[section];
+        const extras = content.extra[section];
+        const newest = newestDate([
+            ...entries.map((entry) => entry.lastUpdated),
+            ...extras.flatMap((extra) => (extra.lastUpdated ? [extra.lastUpdated] : [])),
+        ]);
+        records.push({ path: `/${section}`, ...(newest ? { lastModified: newest } : {}) });
+        for (const entry of entries) {
+            records.push({ path: contentPath(section, entry.slug), lastModified: entry.lastUpdated });
+        }
+        for (const extra of extras) {
+            records.push({
+                path: extra.href,
+                ...(extra.lastUpdated ? { lastModified: extra.lastUpdated } : {}),
+            });
+        }
+    }
+    return records;
+};
+/**
+ * @function contentRewrites
+ * @returns {ContentRewriteRule[]} the one rule that mirrors a content page's ".md" URL
+ *   (`/docs/x.md`, `/guides/x.md`, `/legal/x.md`) to its route handler (`/docs/x/md`, ...)
+ */
+export const contentRewrites = () => [
+    {
+        source: "/:section(docs|guides|legal)/:slug([a-z0-9-]+).md",
+        destination: "/:section/:slug/md",
+    },
+];