@luckystack/docs-ui 0.10.1 → 0.11.0

package/AGENTS.md

@@ -0,0 +1,5 @@
+# @luckystack/docs-ui — agent guidance
+
+This is a development documentation surface, not a public API catalog by default. Only expose it in production after an explicit access-control decision; generated endpoint metadata and the optional request runner can disclose information or exercise authenticated endpoints. See `README.md` for a minimal start and `docs/mounting.md` for the access boundary.
+
+Escaping endpoint metadata before HTML insertion is a security invariant. Authorization and environment checks belong before serving both page and JSON, and a custom template must uphold its own escaping. Keep this package independent of a React build step; source and generated API docs, not this file, define supported options and field shapes.

package/CHANGELOG.md

@@ -5,7 +5,12 @@ All notable changes to `@luckystack/docs-ui` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.11.0] - 2026-10-14
+
+### Changed
+
+- Type declarations are emitted per source file by TypeScript 7 (`tsc -b`) instead of one bundled `.d.ts` per entry, so the framework build no longer runs package by package. The exported types are unchanged; relative imports inside the declarations carry `.js`, so `moduleResolution: "node16"`/`"nodenext"` projects resolve them as before.
+- Package design guidance now ships as `AGENTS.md`, not `CLAUDE.md`. Handwritten docs focus on rationale and safety; exact API contracts remain in installed declarations/source.
 
 ## [0.8.1] - 2026-07-27
 

package/README.md

@@ -1,90 +1,5 @@
 # @luckystack/docs-ui
 
-Dev-only API docs UI for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2).
+A development UI for generated LuckyStack API documentation. In a scaffolded project use `npx luckystack add docs-ui`, or install `@luckystack/docs-ui` and mount its handler through the server's custom routes. Generate API artifacts with the project's `generateArtifacts` script if the UI reports that they are missing. See [mounting](./docs/mounting.md) for the access boundary.
 
-Mounts a single page at `/_docs` that fetches the framework's generated
-`apiDocs.generated.json` and renders every API endpoint grouped by page,
-with HTTP method, auth requirements, rate limit, input shape, and output
-shape.
-
-## Install
-
-```bash
-npm install @luckystack/docs-ui
-```
-
-Peer deps (already installed if you have any other LuckyStack package):
-
-- `@luckystack/core`
-- `@luckystack/server` (the docs UI is mounted via `createLuckyStackServer`'s `customRoutes` option)
-
-## Quickstart
-
-```ts
-// luckystack/docs-ui/index.ts (overlay file — auto-imported by bootstrapLuckyStack)
-import { mountDocsUi } from '@luckystack/docs-ui';
-
-export const docsUiHandler = mountDocsUi({
-  // Title shown in the header + browser tab. Defaults to 'LuckyStack — API docs'.
-  // Pass your project name explicitly — there's no implicit lookup from
-  // ProjectConfig because consumer config shapes vary too widely to introspect.
-  pageTitle: 'My App — API docs',
-});
-```
-
-```ts
-// server/server.ts
-import { docsUiHandler } from '../luckystack/docs-ui';
-import { bootstrapLuckyStack } from '@luckystack/server';
-import { serveFile, serveFavicon } from './prod/serveFile';
-
-await (await bootstrapLuckyStack({
-  serveFile,
-  serveFavicon,
-  customRoutes: docsUiHandler,
-})).listen();
-```
-
-Open `http://localhost/_docs` and you'll see every API in your project,
-grouped by page, with one-click expand for each endpoint's input/output.
-
-## Production
-
-By default the route returns 404 in production (`NODE_ENV === 'production'`).
-Pass `{ enabledInProd: true }` to render it anyway — useful for an internal
-developer-portal deployment, but **never** safe on a public surface unless
-your APIs are intentionally documented to the world.
-
-## Options
-
-| Option | Default | Notes |
-| --- | --- | --- |
-| `routePath` | `/_docs` | Path the page is served from. The JSON is at `${routePath}/api.json`. |
-| `pageTitle` | `LuckyStack — API docs` | Shown in the header + browser tab. Pass your project name explicitly — there is no implicit lookup from `ProjectConfig`. |
-| `enabledInProd` | `false` | Set to `true` to render the docs in production. |
-| `apiDocsPath` | `getGeneratedApiDocsPath()` | Override the JSON file path. Default reads from `ProjectConfig.paths.generatedApiDocs`. |
-| `branding` | `{}` | `{ logoUrl?, brandColor?, fontFamily? }` applied by the default template (logo in the header, accent color, font). Ignored when a custom `template` is supplied. |
-| `template` | `undefined` | `DocsTemplateBuilder` — a custom HTML builder `({ jsonPath, pageTitle, branding }) => string`. When set, the default `renderDocsHtml` is bypassed entirely. |
-| `enableTryItOut` | `false` | Renders an inline request runner (textarea + Send) under each endpoint that calls the live server with `credentials: 'include'`. Needs a logged-in browser session. |
-| `authorize` | `undefined` | `(req) => boolean \| Promise<boolean>` per-request hook, run after the env/bind-address gate. Return `false` to serve `403`. Use to restrict docs access on non-loopback deployments. |
-
-## How it works
-
-The docs page is a single embedded HTML file (no build step, no React, no
-external dependencies). It fetches `${routePath}/api.json` at runtime,
-which is served from the project's `apiDocs.generated.json` — generated by
-`@luckystack/devkit`'s type-map emitter on every dev-server reload and on
-every `npm run generateArtifacts`.
-
-The handler is a `customRoutes` predicate: it returns `true` when it
-matches the configured paths, `false` otherwise — so it composes cleanly
-with any other custom HTTP handler.
-
-## Related architecture docs
-
-- [`docs/ARCHITECTURE_API.md`](../../docs/ARCHITECTURE_API.md) — the lifecycle these endpoints document.
-- [`docs/ARCHITECTURE_PACKAGING.md`](../../docs/ARCHITECTURE_PACKAGING.md) — how `apiDocs.generated.json` is produced.
-
-## License
-
-MIT — see the [repository LICENSE](https://github.com/ItsLucky23/LuckyStack-v2/blob/master/LICENSE).
+**Do not expose the documentation route publicly by accident.** Production access is disabled by default; if you intentionally enable it, add authorization and review generated metadata for sensitive detail. The optional interactive request runner uses the browser's credentials and should only be enabled for trusted developers. Custom HTML templates must escape content from generated metadata; see [HTML generation](./docs/html-generation.md).

package/dist/docsHtml.d.ts

@@ -0,0 +1,14 @@
+export interface RenderDocsHtmlOptions {
+    branding?: {
+        logoUrl?: string;
+        brandColor?: string;
+        fontFamily?: string;
+    };
+    /**
+     * When true, the renderer injects an inline "try-it-out" form per
+     * endpoint. The form calls `apiRequest` from `@luckystack/core` against
+     * the live server. Disabled by default (requires a logged-in session).
+     */
+    enableTryItOut?: boolean;
+}
+export declare const renderDocsHtml: (jsonPath: string, pageTitle: string, options?: RenderDocsHtmlOptions) => string;

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import { IncomingMessage, ServerResponse } from 'node:http';
-
-interface DocsBranding {
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface DocsBranding {
     /**
      * Logo URL shown in the header. Accepts `https:`, `http:`, and scheme-free
      * relative URLs. `data:` and `javascript:` URLs are rejected (the logo will
@@ -18,12 +17,12 @@ interface DocsBranding {
  * (`<!doctype html>` + everything). Use to swap layout entirely (sidebar
  * vs tabs, dark/light theme, embedded auth-token field).
  */
-type DocsTemplateBuilder = (input: {
+export type DocsTemplateBuilder = (input: {
     jsonPath: string;
     pageTitle: string;
     branding: DocsBranding;
 }) => string;
-interface MountDocsUiOptions {
+export interface MountDocsUiOptions {
     /** Path the docs UI is served from. Default: `/_docs`. */
     routePath?: string;
     /**
@@ -70,12 +69,10 @@ interface MountDocsUiOptions {
      */
     authorize?: (req: IncomingMessage) => boolean | Promise<boolean>;
 }
-type DocsRouteHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+export type DocsRouteHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
 /**
  * Returns a route handler compatible with `createLuckyStackServer`'s
  * `customRoutes` option. The handler returns `true` (response sent) when
  * the URL matches the configured docs route, `false` otherwise.
  */
-declare const mountDocsUi: (options?: MountDocsUiOptions) => DocsRouteHandler;
-
-export { type DocsBranding, type DocsRouteHandler, type DocsTemplateBuilder, type MountDocsUiOptions, mountDocsUi };
+export declare const mountDocsUi: (options?: MountDocsUiOptions) => DocsRouteHandler;

package/dist/register.d.ts

@@ -1,2 +1 @@
-
-export {  }
+export {};

package/docs/extension-fields.md

@@ -1,169 +1,5 @@
-# Extension fields on `apiDocs.generated.json`
+# Extending generated API documentation
 
-> Dev-only. These fields are read by the renderer in `@luckystack/docs-ui` only — the framework runtime never inspects them. They are a docs-presentation concern, not a routing concern.
+Optional metadata lets projects annotate documentation without coupling every producer to a fixed UI release. Renderers should ignore unknown fields rather than failing when a newer producer adds them. Producers should not assume every consumer renders an optional field. The generated JSON and producer/renderer source are the authoritative schema; do not duplicate its field inventory here.
 
-`apiDocs.generated.json` is produced by `@luckystack/devkit`'s type-map emitter. The default template in `@luckystack/docs-ui` consumes a small, stable set of core fields and a handful of optional extension fields. Unknown fields pass through cleanly — the renderer ignores anything it doesn't recognize, so adding new metadata is forward-compatible.
-
-This document covers:
-
-- The top-level JSON shape (including the legacy fallback).
-- Core fields the renderer reads at the top level of each endpoint entry.
-- Optional extension fields rendered when present (`stream`, `owner`, `tags`, `deprecated`).
-- How to add your own metadata via the devkit emitter hooks.
-
-For the rendering pipeline that consumes these fields see `./html-generation.md`. For the route that serves the JSON see `./mounting.md`.
-
-## Top-level JSON shape
-
-The current artifact has two top-level maps — `apis` and `syncs` — each keyed by `page`. The value under each page is a **flat array** of endpoint entries (not a nested `name → version` object). Every entry carries its own `name`, `version`, and `path`:
-
-```jsonc
-{
-  "apis": {
-    "<page>": [
-      {
-        "page": "<page>",
-        "name": "<name>",
-        "version": "<version>",
-        "method": "POST",
-        "auth": { "login": true, "additional": [] },
-        "rateLimit": 60,
-        "input": "{ userId: string }",
-        "output": "{ status: 'success', result: { ... } }",
-        "stream": "never",
-        "path": "api/<page>/<name>/<version>",
-        "meta": { "owner": "@team", "tags": ["internal"] }
-      }
-    ]
-  },
-  "syncs": {
-    "<page>": [
-      {
-        "page": "<page>",
-        "name": "<name>",
-        "version": "<version>",
-        "clientInput": "{ ... }",
-        "serverOutput": "{ ... }",
-        "clientOutput": "{ ... }",
-        "serverStream": "never",
-        "clientStream": "never",
-        "path": "sync/<page>/<name>/<version>"
-      }
-    ]
-  }
-}
-```
-
-Legacy/forward fallback: if the root object is the apis map itself (no `apis` wrapper), the renderer normalizes via `data && data.apis ? data.apis : data`. Both shapes are accepted; new code should always emit the wrapped form.
-
-The grouping is `page` → array of entries; `name`, `version`, `method`, `path`, etc. are fields ON each entry. This matches the file-based routing convention (`src/<page>/_api/<name>_v<version>.ts`). The renderer iterates the pages in object-iteration order and each page's array in array order; the emitter is responsible for any sorting.
-
-## Core fields (always read by the renderer)
-
-These are the fields used to build the always-visible row + the default expanded panel:
-
-| Field | Type | Default in renderer | Purpose |
-| --- | --- | --- | --- |
-| `method` | `'GET' \| 'POST' \| 'PUT' \| 'DELETE'` (any string, uppercased) | `'POST'` | Method pill text + CSS class on `.method`. |
-| `rateLimit` | `number \| false \| undefined` | `'default rate'` label | Numeric ⇒ `"<n>/min"`. `false` ⇒ `"no rate limit"`. `undefined` ⇒ `"default rate"`. |
-| `auth` | `{ login?: boolean; additional?: Array<{ key: string; value?: unknown }> }` | `'public'` badge | `auth.login` becomes a `"login required"` badge. Each `additional[]` entry becomes a `"<key>"` or `"<key>=<JSON-stringified value>"` badge. Empty / missing ⇒ single `"public"` badge. |
-| `input` | `string` (already-stringified TS shape) | `'{}'` | Rendered inside `<pre>` in the expanded panel. |
-| `output` | `string` (already-stringified TS shape) | `'unknown'` | Rendered inside `<pre>` in the expanded panel. |
-
-The renderer does not try to JSON-parse `input` / `output`. They are emitted as pre-formatted strings by the devkit emitter so the docs page can display the original TypeScript shape verbatim — including unions, mapped types, and template-literal types — without re-stringifying.
-
-Unknown core fields fall through to their defaults silently; emit a missing `method`, for example, and the row shows `POST`.
-
-## Optional extension fields
-
-The default template renders these only when present. They are additive: omit any of them and the corresponding section is left out of the expanded panel.
-
-### `stream` (top-level)
-
-- Where: a **top-level** field on the entry (a sibling of `input` / `output`), **not** under `meta`. The renderer reads `entry.stream` and shows the section only when the value is truthy and not the `"never"` sentinel.
-- Type: `string` (already-stringified TS shape, same convention as `input` / `output`).
-- Renders as: a `stream` detail section with the value inside a `<pre>` block.
-- Use for endpoints that stream chunks back to the client (e.g. SSE or chunked-transfer responses). The string typically describes the shape of a single chunk.
-- Example payload field:
-
-```jsonc
-{
-  "stream": "{ delta: string } | { done: true }"
-}
-```
-
-### `meta.owner`
-
-- Type: `string`.
-- Renders as: an `owner` detail section with the raw string.
-- Use for triage-friendly attribution — team name, Slack channel, GitHub handle, on-call rotation, etc. The value is escaped before injection so it is safe to include arbitrary text.
-- Example:
-
-```jsonc
-{ "owner": "@platform-team (#help-platform)" }
-```
-
-### `meta.tags`
-
-- Type: `string[]` (or array of values coerced via `String(...)`).
-- Renders as: inline badges in a `tags` detail section, space-separated.
-- Use for cross-cutting categorization the page/name hierarchy can't express — `"v2-migration"`, `"internal"`, `"experimental"`, etc.
-- Example:
-
-```jsonc
-{ "tags": ["experimental", "internal"] }
-```
-
-Note: the renderer treats `tags` as an `Array.isArray(value)` check; arbitrary iterables are not supported. Emit a plain array.
-
-### `meta.deprecated`
-
-- Type: `string | true` (anything truthy; `String(value)` is used for display).
-- Renders as: a `deprecated` detail section with red text (`color: var(--delete)`).
-- Use for a removal notice or migration pointer. The truthiness check means `"true"`, `"yes"`, `"removing v2026.05"`, etc. all render — but the renderer always shows the string value, so prefer a human-readable migration note over a bare boolean.
-- Example:
-
-```jsonc
-{
-  "deprecated": "Removed in v2026.05 — use users/getProfile/v2 instead."
-}
-```
-
-## Forward compatibility
-
-- Adding a new field to a `meta` object is non-breaking. The renderer ignores it.
-- Removing one of the four extension fields above does **not** break the renderer either — each is conditional on truthiness or array length.
-- The renderer does no schema validation. Malformed top-level JSON (e.g. wrong types at the page/name/version levels) shows the page's empty state with a hint to regenerate.
-
-If you need extra fields on the page, you have two options:
-
-1. Extend the devkit emitter to include the field, then customize the rendering side via a `DocsTemplateBuilder` (see `./theming.md`) or, for trivial additions, contribute the field to this package.
-2. Keep your metadata out-of-band (a sibling JSON file) and consume it from a custom template. The default renderer will not surface it, but a `DocsTemplateBuilder` can fetch both files.
-
-## Producer contract — how fields are populated
-
-`apiDocs.generated.json` is written by `@luckystack/devkit`'s type-map emitter on each dev-server reload and on every `npm run generateArtifacts`. Path resolution goes through `ProjectConfig.paths.generatedApiDocs` (consumed by `getGeneratedApiDocsPath()` in `@luckystack/core`).
-
-Emission steps the devkit performs per endpoint:
-
-1. Read the route file (`src/<page>/_api/<name>_v<version>.ts`) and extract exports: `method`, `rateLimit`, `auth`, the `ApiParams.data` interface (rendered into `input`), and the `main` return type (rendered into `output`).
-2. Stringify the types into source-faithful strings — no re-stringification, no JSON.stringify of types.
-3. Run the emitter's `emitterArtifacts` extension hooks (`packages/devkit/src/typeMap/emitterArtifacts.ts`). Hooks can attach `stream`, `owner`, `tags`, `deprecated`, or any new field.
-4. Group by `page` (one flat array of entries per page, each entry carrying its own `name` / `version` / `path`) and write the JSON.
-
-Consumer-side extension (e.g. reading a `@deprecated` JSDoc tag and mapping it to `meta.deprecated`) belongs in an emitter artifact hook, not in `@luckystack/docs-ui`. The docs-ui package only renders what the emitter writes.
-
-## Validation behavior
-
-- No schema validation. The renderer trusts the JSON shape.
-- A missing artifact (`apiDocs.generated.json` not on disk) yields a `404 JSON` response from the `mountDocsUi` handler with `expectedAt` + `hint` — surfaced as an inline error message in the page.
-- An empty / invalid `apis` map yields the page's empty state: `"No API docs available. Run npm run generateArtifacts to generate them."`.
-- Per-endpoint malformations (e.g. `auth` is a string instead of an object) fall back to defaults silently. Bad data does not crash the page; it just shows degraded content.
-
-## Related
-
-- Rendering pipeline that consumes these fields: `./html-generation.md`
-- Mount + route: `./mounting.md`
-- Branding / custom templates: `./theming.md`
-- AI summary + function index: `../CLAUDE.md`
-- Producer: `packages/devkit/src/typeMap/emitter.ts` and `packages/devkit/src/typeMap/emitterArtifacts.ts`
+Treat documentation metadata as publishable information. Ownership labels, tags, stream hints and deprecation messages can disclose private design details if the docs are exposed outside the team. Review the access boundary in `mounting.md` before enabling production serving or a custom renderer.

package/docs/html-generation.md

@@ -1,194 +1,5 @@
 # HTML generation
 
-> Dev-only. The renderer produces a self-contained HTML document with inline CSS and inline JavaScript. There is no build step, no React, and no external runtime dependency — the page works in any modern browser as soon as it can fetch `apiDocs.generated.json`.
+The default documentation page is self-contained HTML rather than a separate React bundle, so a development server can serve generated docs without a frontend build. The UI fetches generated metadata at request time rather than embedding a hand-maintained API inventory. See the renderer source for current selectors, field handling and template-builder parameters.
 
-This document covers the rendering half of `@luckystack/docs-ui`:
-
-- `renderDocsHtml(jsonPath, pageTitle, options?)` — the default HTML builder.
-- `RenderDocsHtmlOptions` — the option shape.
-- `DocsTemplateBuilder` — the hook for replacing the renderer entirely.
-- The embedded client pipeline: fetch, group, render, filter, "try it out".
-
-For the mount/route side see `./mounting.md`. For branding tokens see `./theming.md`. For the JSON fields read by the renderer see `./extension-fields.md`.
-
-## Function signature
-
-```ts
-export const renderDocsHtml = (
-  jsonPath: string,
-  pageTitle: string,
-  options?: RenderDocsHtmlOptions,
-): string;
-
-export interface RenderDocsHtmlOptions {
-  branding?: {
-    logoUrl?: string;
-    brandColor?: string;
-    fontFamily?: string;
-  };
-  enableTryItOut?: boolean;
-}
-```
-
-Return value: a complete `<!DOCTYPE html>...</html>` document as a single UTF-8 string. The caller is responsible for setting the `Content-Type: text/html; charset=utf-8` header (the `mountDocsUi` handler already does this).
-
-### Arguments
-
-| Arg | Type | Required | Purpose |
-| --- | --- | --- | --- |
-| `jsonPath` | `string` | Yes | Path the embedded script fetches with `fetch(jsonPath, { credentials: 'include' })`. Typically the `${routePath}/api.json` sibling produced by `mountDocsUi`, but any URL that returns the expected JSON shape works. |
-| `pageTitle` | `string` | Yes | Used for `<title>` and `<h1>`. Passed through `escapeHtml` before interpolation. |
-| `options.branding` | `DocsBranding` | No | Logo, accent color, font family. See `./theming.md`. |
-| `options.enableTryItOut` | `boolean` | No (default `false`) | When `true`, each endpoint detail panel gets a textarea + Send button that posts to the live server. |
-
-## Document structure
-
-The produced HTML is one document with three logical sections:
-
-1. **`<head>`** — meta tags, `<title>`, and a single inline `<style>` block.
-2. **`<body>`** — a `.layout` wrapper containing the brand row, the filter bar, a summary pill row, and an empty `<div id="content">` filled in by the script.
-3. **Inline `<script>`** — defines render helpers, fetches the JSON, wires up the filter input, and (optionally) the "try it out" runner.
-
-There is no external `<link>`, `<script src="...">`, or web-font import. The page renders correctly when opened with a local file URL too, provided the JSON endpoint is reachable.
-
-### CSS variables in `:root`
-
-```
---bg, --container, --container-hover, --border
---title, --common, --muted
---accent          (from branding.brandColor; default #58a6ff)
---font-family     (from branding.fontFamily; default system stack)
---get             (#3fb950)
---post            (= --accent)
---put             (#d29922)
---delete          (#f85149)
-```
-
-A `@media (prefers-color-scheme: light)` block redefines `--bg`, `--container`, `--container-hover`, `--border`, `--title`, `--common`, `--muted` to a light palette. The accent and method colors do not switch — they are chosen to be legible on both backgrounds.
-
-### Layout selectors
-
-| Selector | Purpose |
-| --- | --- |
-| `.layout` | Outer max-1200px container with vertical padding. |
-| `.brand-row` | Holds the optional `<img>` logo and the `<h1>` page title. |
-| `.summary` / `.summary-pill` | Top-of-page count pills ("`<visible>` of `<total>` endpoints", "`<pages>` pages"). |
-| `.filter-bar input[type="search"]` | The single search input. Autofocus on load. |
-| `.group` / `.group-header` | One block per `page` key in the JSON. |
-| `.endpoint` / `.endpoint-summary` / `.endpoint-detail` | One row per endpoint. The detail panel is hidden until the row is clicked. |
-| `.method.GET / .POST / .PUT / .DELETE` | Method pill, color-coded against the CSS variables above. |
-| `.auth-tag` | Inline badges for each auth rule. |
-| `.try-it-out` | Optional runner panel (only emitted when `enableTryItOut` is true). |
-
-The styles are intentionally close to the framework's Tailwind tokens (background, container, muted, common) so the page looks at home in a LuckyStack project without configuration.
-
-## Client-side rendering pipeline
-
-The embedded `<script>` runs the following sequence after the HTML parses:
-
-1. **`fetch(JSON_PATH, { credentials: 'include' })`** — pulls the JSON from `${routePath}/api.json` (or the explicit URL passed to `renderDocsHtml`). Credentials are included so a session cookie reaches the JSON endpoint when one is required.
-2. On a successful response, the parsed payload is cached on `cachedData` and passed to `render(data, '')`.
-3. On error (non-OK status or network failure) the page replaces `<div id="content">` with an inline error message — no console-only logging — so the user sees the failure without opening devtools.
-4. The `<input type="search" id="filter">` registers an `input` listener that re-invokes `render(cachedData, filterValue)` on every keystroke. The fetch is not repeated.
-
-### `render(data, filter)`
-
-- Accepts either `{ apis, syncs }` (current shape) or a bare `{ [page]: Entry[] }` (legacy shape) — the renderer normalizes via `data && data.apis ? data.apis : data` (and `data.syncs` ?? `{}`), then delegates to `buildGroups(apis, syncs, filter)`.
-- `buildGroups` walks each page's flat array of entries (and the parallel `syncs` map the same way), increments `total`, applies `passesFilter`, and accumulates HTML rows via `renderEndpoint` / `renderSyncEntry`.
-- Pages that have zero matching rows are omitted entirely (no empty `.group` boxes).
-- Writes the `summary-pill` counts (`visible of total`, `pages count`) and the joined `.group` HTML into `<div id="content">`.
-- Open/closed state is toggled by a single delegated `click` listener on `#content` (registered once via `bindEndpointToggles`, not re-bound per render), persisting state in `stateByKey` (keyed by `page + '/' + name + '@' + version`). The state is in-memory only; a hard reload resets all panels to closed.
-
-### `renderEndpoint(entry)`
-
-Takes a single entry object and pulls these fields directly off it:
-
-- `method` — uppercased and used as both the class and the label of the pill. Falls back to `POST` when undefined.
-- `rateLimit` — `false` ⇒ "no rate limit"; `undefined` ⇒ "default rate"; number ⇒ "`<n>`/min".
-- `auth` — passed to `renderAuth`. `auth.login` becomes `"login required"`. Each `auth.additional[]` entry contributes a `"<key>"` or `"<key>=<value>"` badge (value is `JSON.stringify`'d). Empty auth renders a `"public"` badge.
-- `input`, `output` — already-stringified shapes from the type-map emitter. Rendered inside `<pre>` blocks. The fallbacks are `'{}'` and `'unknown'` respectively.
-- `stream` — a top-level field on the entry, rendered when truthy and not `'never'`.
-- `meta.owner`, `meta.tags`, `meta.deprecated` — optional fields under the entry's `meta` object, rendered conditionally. See `./extension-fields.md`.
-
-The displayed endpoint path is `/api/<page>/<name>/<version>`; the path used by the runner is `<page>/<name>/<version>` posted to `/<route>?stream=false` (no leading `/api/`).
-
-### `passesFilter(filter, page, name)`
-
-Lowercase substring match against `page + '/' + name`. The version is not part of the haystack — filtering by version is intentional only via the page/route name.
-
-### `escapeHtml` — two copies
-
-The renderer ships two `escapeHtml` helpers that look identical and **must stay identical**:
-
-1. The TypeScript helper at the bottom of `src/docsHtml.ts` is used to escape `pageTitle`, `jsonPath`, and `branding.logoUrl` before they are interpolated into the template literal at build time of the response.
-2. The JS helper inside the inline `<script>` is used by the client to escape every value pulled from `apiDocs.generated.json` before it is injected into `innerHTML`.
-
-Both map `&`, `<`, `>`, `"`, `'` to their HTML entity equivalents. The renderer never inserts unescaped user-supplied strings.
-
-## "Try it out" runner
-
-Enabled by `options.enableTryItOut === true`. When on:
-
-- `ENABLE_TRY_IT_OUT` is `true` inside the inline script.
-- `renderTryItOut(route, method)` appends a `<div class="try-it-out">` containing a `<textarea>` (default content `{}`), a `Send` button, and an empty `<pre class="result">`.
-- The Send click invokes `runEndpoint(button, route, method, dataField)`.
-
-`runEndpoint` performs:
-
-```js
-const httpMethod = (method || 'POST').toUpperCase();
-const hasBody = httpMethod !== 'GET' && httpMethod !== 'DELETE';
-fetch('/' + route + '?stream=false', {
-  method: httpMethod,
-  headers: hasBody ? { 'Content-Type': 'application/json' } : {},
-  credentials: 'include',
-  body: hasBody ? JSON.stringify(parsed) : undefined,
-})
-```
-
-Behavior:
-
-- The endpoint's declared HTTP method is threaded through (the framework returns `405` on a method mismatch, so a hardcoded `POST` would break every documented GET/PUT/DELETE route). For `GET`/`DELETE` the JSON body and `Content-Type` header are omitted.
-- `dataField.value.trim()` empty ⇒ sends `{}` (for body-bearing methods). Otherwise the textarea value is parsed with `JSON.parse`. A parse error is shown in the result pane and no request is sent.
-- The button is disabled during flight and re-enabled in `finally`.
-- The response body is parsed as JSON when possible (pretty-printed via `JSON.stringify(..., null, 2)`) and otherwise displayed as raw text — this keeps non-JSON error pages readable.
-- `?stream=false` instructs the HTTP API surface to return the full final payload instead of a streamed chunked response, which is what the textarea-and-pre UI is built for.
-- Authentication is implicit via the browser session cookie (`credentials: 'include'`). The runner does not prompt for a token.
-
-Disable the runner (`enableTryItOut: false`) when you ship to environments where developers don't have an authenticated session or you don't want side-effecting POSTs from the docs page.
-
-## `DocsTemplateBuilder` — full replacement
-
-When `mountDocsUi` is called with `template: DocsTemplateBuilder`, the default `renderDocsHtml` pipeline is bypassed entirely. The builder is invoked with:
-
-```ts
-type DocsTemplateBuilder = (input: {
-  jsonPath: string;
-  pageTitle: string;
-  branding: DocsBranding;
-}) => string;
-```
-
-Contract for custom builders:
-
-- Must return a full HTML document. The `mountDocsUi` handler streams the string as-is into `res.end(...)` with `Content-Type: text/html; charset=utf-8`.
-- Should `fetch(jsonPath)` itself (or use `<script>` to do so). The handler does not pre-fetch the JSON.
-- Should HTML-escape any inputs that end up in markup. The builder receives them as raw strings — `mountDocsUi` does not pre-escape.
-- May ignore `branding` if the layout has its own theming primitives.
-- May call `renderDocsHtml` from inside the builder if you only want to wrap the default rendering with extra chrome — but in that case you can usually use `branding` instead.
-
-Use a template builder for full layout replacements (sidebar navigation, tabs, marketing-page chrome, dark/light toggle beyond OS preference). Use `branding` for cosmetic tweaks. See `./theming.md` for the trade-off.
-
-## Forward compatibility
-
-- Unknown `meta` fields on endpoints are ignored by the renderer.
-- The renderer never schema-validates the JSON; malformed input falls back to the empty state with a `Run npm run generateArtifacts` hint.
-- The two-shape acceptance (`{ apis }` vs bare map) is intentional to preserve compatibility with older artifact generators.
-
-## Related
-
-- Mounting + route handler: `./mounting.md`
-- Branding tokens + template trade-off: `./theming.md`
-- Extension fields rendered by the default template: `./extension-fields.md`
-- AI summary + function index: `../CLAUDE.md`
-- Source: `../src/docsHtml.ts`
+Generated endpoint metadata is not inherently safe HTML: escape text and attribute content before inserting it. Reject dangerous image schemes such as `data:` and `javascript:` for branding logos, including SVG payloads. A replacement template takes ownership of that escaping and URL validation. The optional interactive request runner sends live requests using the browser's session; enabling it on an untrusted surface is not just a documentation choice. Restrict access before making it available, and avoid reflecting sensitive response bodies in logs.

package/docs/mounting.md

@@ -1,226 +1,5 @@
 # Mounting the docs UI
 
-> Dev-only. The default route returns `404` in production unless `enabledInProd: true` is explicitly set. Never mount this on a public surface where API discoverability is sensitive.
+The docs handler composes with the server's custom-route mechanism rather than taking over general request routing. Mount it only where generated API docs should be available. See `README.md` for a short start and the installed `mountDocsUi` types for current options and handler signatures.
 
-`@luckystack/docs-ui` exposes a single mount function that builds a `customRoutes` handler. The handler is composable with `createLuckyStackServer` / `bootstrapLuckyStack` and does not take ownership of the request pipeline — it claims the configured docs route and falls through for everything else.
-
-This document is the deep reference for:
-
-- `mountDocsUi(options?)` — the factory that builds the handler.
-- `DocsRouteHandler` — the handler contract.
-- `MountDocsUiOptions` — the full option surface.
-
-For the HTML rendering side of the pipeline see `./html-generation.md`. For optional branding/template overrides see `./theming.md`. For the JSON fields the renderer consumes see `./extension-fields.md`.
-
-## Function signatures
-
-```ts
-export const mountDocsUi = (options?: MountDocsUiOptions): DocsRouteHandler;
-
-export type DocsRouteHandler = (
-  req: IncomingMessage,
-  res: ServerResponse,
-) => Promise<boolean>;
-
-export interface MountDocsUiOptions {
-  routePath?: string;
-  pageTitle?: string;
-  enabledInProd?: boolean;
-  apiDocsPath?: string;
-  branding?: DocsBranding;
-  template?: DocsTemplateBuilder;
-  enableTryItOut?: boolean;
-  authorize?: (req: IncomingMessage) => boolean | Promise<boolean>;
-}
-```
-
-## `MountDocsUiOptions` argument breakdown
-
-| Option | Type | Default | Purpose |
-| --- | --- | --- | --- |
-| `routePath` | `string` | `/_docs` | URL path the HTML page is served from. The JSON sibling is automatically derived as `${routePath}/api.json`. Both paths are claimed by the handler. |
-| `pageTitle` | `string` | `LuckyStack — API docs` | Used for the `<title>` element and the `<h1>` in the header. Pass your project name explicitly — there is no implicit lookup from `ProjectConfig` because consumer config shapes vary too widely to introspect. |
-| `enabledInProd` | `boolean` | `false` | Set to `true` to render the docs in production (`NODE_ENV === 'production'`). Use only for an internal developer-portal deployment with its own auth layer in front. |
-| `apiDocsPath` | `string` | `getGeneratedApiDocsPath()` | Absolute filesystem path to `apiDocs.generated.json`. Default reads from `ProjectConfig.paths.generatedApiDocs` via `@luckystack/core`. Override only when running a non-standard artifact layout. |
-| `branding` | `DocsBranding` | `{}` | Optional logo / accent color / font family. Applied by the default template only. See `./theming.md`. |
-| `template` | `DocsTemplateBuilder` | `undefined` | Custom HTML builder. When provided, the default `renderDocsHtml` is bypassed entirely. See `./html-generation.md` and `./theming.md`. |
-| `enableTryItOut` | `boolean` | `false` | Renders an inline request runner under each endpoint. Off by default — the runner needs a logged-in browser session because it hits the live server with `credentials: 'include'`. |
-| `authorize` | `(req: IncomingMessage) => boolean \| Promise<boolean>` | `undefined` | Optional per-request authorization hook. Called after the env/bind-address gate passes (so it only runs when the route is being served). Return `true` to allow the request, `false` to serve `403 Forbidden`. Use to restrict docs access to authenticated or IP-allowlisted callers on non-loopback deployments (e.g. an internal developer-portal opened with `enabledInProd: true`). |
-
-All options are individually optional; calling `mountDocsUi()` with no arguments is valid and produces the default behavior.
-
-## `DocsRouteHandler` contract
-
-The factory returns an async function with this exact shape:
-
-```ts
-type DocsRouteHandler = (
-  req: IncomingMessage,
-  res: ServerResponse,
-) => Promise<boolean>;
-```
-
-Return-value contract:
-
-- `true` — the handler has fully processed the request and called `res.end(...)`. The caller (typically `@luckystack/server`'s `customRoutes` orchestration) must not invoke any further handler for this request.
-- `false` — the handler did not match the URL. The request body is untouched and the response is unwritten. The caller is free to delegate to the next handler or fall through to the framework's default routing.
-
-The handler is safe to compose: it inspects only `req.url` and `req.method` and never reads the body. It is always async because reading `apiDocs.generated.json` from disk happens via `fs.promises.readFile` wrapped in `tryCatch`.
-
-## Compositing with `createLuckyStackServer`
-
-Minimum integration — pass the handler as `customRoutes`:
-
-```ts
-// luckystack/docs-ui/index.ts (overlay file)
-import { mountDocsUi } from '@luckystack/docs-ui';
-
-export const docsUiHandler = mountDocsUi({
-  pageTitle: 'My App — API docs',
-});
-```
-
-```ts
-// server/server.ts
-import { bootstrapLuckyStack } from '@luckystack/server';
-import { docsUiHandler } from '../luckystack/docs-ui';
-import { serveFile, serveFavicon } from './prod/serveFile';
-
-await (await bootstrapLuckyStack({
-  serveFile,
-  serveFavicon,
-  customRoutes: docsUiHandler,
-})).listen();
-```
-
-Composing with another custom handler — chain by `await`-ing the docs handler first and only continuing when it returns `false`:
-
-```ts
-import type { IncomingMessage, ServerResponse } from 'node:http';
-import { mountDocsUi } from '@luckystack/docs-ui';
-import { metricsHandler } from './metrics';
-
-const docsHandler = mountDocsUi();
-
-export const customRoutes = async (
-  req: IncomingMessage,
-  res: ServerResponse,
-): Promise<boolean> => {
-  if (await docsHandler(req, res)) return true;
-  if (await metricsHandler(req, res)) return true;
-  return false;
-};
-```
-
-The order matters only when two handlers would claim the same path; `mountDocsUi` only ever claims `routePath` + `${routePath}/api.json`, so collisions are easy to avoid by picking a unique `routePath`.
-
-## Behavior matrix
-
-The handler's branches map directly to the request shape. The order is exactly as evaluated in `src/index.ts`:
-
-| Step | Condition | Result |
-| --- | --- | --- |
-| 1 | `pathOnly !== routePath && pathOnly !== ${routePath}/api.json` | Returns `false` (pass-through). No response written. |
-| 2 | (`NODE_ENV === 'production'` **or** `!isLoopbackIp(getBindAddress().ip)`) and `!options.enabledInProd` | `404 Not Found` (`text/plain`). Returns `true`. The non-loopback bind-address check means a server bound to a public interface is gated even outside `NODE_ENV=production`. |
-| 3 | `options.authorize` is set and returns/resolves `false` | `403 Forbidden` (`text/plain`). Returns `true`. Runs only after the env/bind gate (step 2) passes. |
-| 4 | `req.method !== 'GET'` | `405 Method Not Allowed` (`text/plain`). Returns `true`. |
-| 5 | `pathOnly === ${routePath}/api.json` and the file is readable | `200 OK` (`application/json`, `Cache-Control: no-store`) with the raw file contents. Returns `true`. |
-| 6 | `pathOnly === ${routePath}/api.json` and the file is missing/unreadable | `404 Not Found` (`application/json`) with `{ error, expectedAt, hint }`. Returns `true`. |
-| 7 | `pathOnly === routePath` and `options.template` is set | `200 OK` (`text/html; charset=utf-8`) with the template builder's output. Returns `true`. |
-| 8 | `pathOnly === routePath` and no template | `200 OK` (`text/html; charset=utf-8`) with `renderDocsHtml(...)`. Returns `true`. |
-
-The order is critical: the env/bind gate runs before the `authorize` hook and before method-checking, so a `POST /_docs` in production (or on a public-bind server) still returns `404` — it's gated first — not `405`, and `authorize` is never consulted on a gated request. The gate fires on `NODE_ENV === 'production'` **or** a non-loopback bind address (`!isLoopbackIp(getBindAddress().ip)`), so a staging/preview server bound to a public interface is locked down even when `NODE_ENV` is not `production`; set `enabledInProd: true` to serve the route there. The match itself ignores query strings (the path is split on `?` before comparing) and is strict on trailing slashes — `/_docs/` does NOT match the default route.
-
-## Response shapes
-
-### HTML page (`GET ${routePath}`)
-
-```
-HTTP/1.1 200 OK
-Content-Type: text/html; charset=utf-8
-Cache-Control: no-store
-
-<!DOCTYPE html>
-<html lang="en">
-...self-contained docs page (see ./html-generation.md)...
-```
-
-### JSON endpoint, success (`GET ${routePath}/api.json`)
-
-```
-HTTP/1.1 200 OK
-Content-Type: application/json
-Cache-Control: no-store
-
-{ "apis": { "<page>": [ { "name": "<name>", "version": "<version>", "method": "POST", ... } ] }, "syncs": { "<page>": [ { ... } ] } }
-```
-
-The file is streamed as-is from disk; the handler does not parse, validate, or transform it. Forward-compatible extension fields (see `./extension-fields.md`) pass through unchanged.
-
-### JSON endpoint, missing file
-
-```
-HTTP/1.1 404 Not Found
-Content-Type: application/json
-
-{
-  "error": "apiDocs.generated.json not found",
-  "expectedAt": "<resolved apiDocsPath>",
-  "hint": "Run `npm run generateArtifacts` to generate it."
-}
-```
-
-This is intentionally a structured payload so the client-side renderer can surface a helpful empty state. `Cache-Control` is omitted on the error path — the request should be retried after running the artifact generator.
-
-`expectedAt` is **dev-only**: it exposes the absolute filesystem path and is omitted when `NODE_ENV === 'production'` to avoid leaking internal directory structure (DOCSUI-8). In production the payload contains only `error` and `hint`.
-
-### Production lockdown (`enabledInProd: false`)
-
-```
-HTTP/1.1 404 Not Found
-Content-Type: text/plain
-
-Not Found
-```
-
-The same plain `Not Found` is returned for both the HTML and the JSON sub-route, so probing tools cannot infer which routes the handler owns.
-
-### Wrong method
-
-```
-HTTP/1.1 405 Method Not Allowed
-Content-Type: text/plain
-
-Method Not Allowed
-```
-
-`POST`, `PUT`, `DELETE`, and other verbs all map to `405`. The `enableTryItOut` runner posts to `/api/<page>/<name>/<version>?stream=false` (the framework's HTTP API surface), not to the docs route — so `GET`-only is sufficient.
-
-## `apiDocsPath` resolution
-
-The default `apiDocsPath` is resolved lazily on every request via `getGeneratedApiDocsPath()` from `@luckystack/core`. That helper reads `ProjectConfig.paths.generatedApiDocs`, which is populated either via the framework defaults or via an overlay's `registerProjectConfig` call.
-
-When you pass `apiDocsPath` explicitly:
-
-- The value must be an absolute path. The handler does no resolution relative to `process.cwd()`.
-- The file is read with `fs.promises.readFile(path, 'utf8')` on every request — there is no in-memory cache. The doc-set is dev-only and the artifact regenerates often; caching is intentionally avoided.
-- Read errors are caught via `tryCatch`. The response is a structured `404` with `expectedAt` pointing at the resolved path so you can diff it against your actual layout.
-
-## Edge cases
-
-- **Missing `apiDocs.generated.json`** — Returns the structured `404` JSON payload above. Run `npm run generateArtifacts` to produce it.
-- **Trailing slashes** — The handler does strict string equality on the resolved path. `/_docs/` is treated as a different route from `/_docs`. Configure `routePath` to include or omit the trailing slash consistently with the rest of your router.
-- **Query strings** — The path is split on `?` before comparison, so `/_docs?theme=dark` matches. Query parameters are otherwise ignored by the handler.
-- **Custom `routePath`** — Any string is accepted; the `${routePath}/api.json` sibling is derived by simple concatenation. Avoid trailing slashes in `routePath` (`/_docs/` would yield `/_docs//api.json`).
-- **`HEAD` requests** — Not special-cased. They fall into the `405` branch. If you need `HEAD` support, wrap the handler.
-- **Concurrent requests** — Each request reads the JSON file independently. There is no shared mutable state inside the handler.
-- **`req.url` missing** — The handler treats an undefined `url` as an empty string, which never matches `routePath`. It returns `false` (pass-through) cleanly.
-
-## Related
-
-- HTML rendering pipeline: `./html-generation.md`
-- Branding and full template replacement: `./theming.md`
-- Extension fields rendered from `apiDocs.generated.json`: `./extension-fields.md`
-- AI summary + function index: `../CLAUDE.md`
-- Consumer quickstart: `../README.md`
-- Source: `../src/index.ts`
+**Default production lockdown is intentional.** Even without an interactive request runner, generated endpoint names, auth requirements and data shapes may be sensitive. If production access is necessary, explicitly enable it and enforce per-request authorization before returning both the page and its JSON. A non-loopback development bind also warrants access review. A missing generated file is not authorization to serve old or invented documentation: regenerate artifacts instead.

package/docs/theming.md

@@ -1,172 +1,5 @@
-# Theming the docs UI
+# Docs UI theming
 
-> Dev-only. The default docs page is a single self-contained HTML document with inline CSS. Theming is intentionally minimal — three branding tokens for cosmetic tweaks, plus a full template-builder hook when you need a different layout.
+Lightweight branding lets an internal documentation page resemble its host project without requiring a frontend build. Use the built-in branding option for cosmetic changes; a full custom template is appropriate only when the document structure must change. The custom template takes responsibility for escaped content, accessibility and secure request-runner behavior.
 
-This document covers:
-
-- `DocsBranding` — the three branding tokens and how they map to CSS variables.
-- The default palette + dark/light auto-switch.
-- `DocsTemplateBuilder` — the escape hatch for full layout replacement.
-- When to choose `branding` vs `template`.
-
-For the renderer that consumes these tokens see `./html-generation.md`. For the route handler that wires them in see `./mounting.md`.
-
-## `DocsBranding`
-
-```ts
-export interface DocsBranding {
-  logoUrl?: string;
-  brandColor?: string;
-  fontFamily?: string;
-}
-```
-
-All three keys are optional. Pass through `mountDocsUi({ branding: { ... } })` or directly to `renderDocsHtml(jsonPath, pageTitle, { branding })`.
-
-| Token | Type | Default | Mapping |
-| --- | --- | --- | --- |
-| `logoUrl` | `string` | _(no logo)_ | Injected as `<img src="..." alt="logo" style="height:32px;width:auto;margin-right:12px;" />` in the brand row, to the left of the `<h1>`. The URL is HTML-escaped before injection. |
-| `brandColor` | `string` (CSS color) | `#58a6ff` | Sets the CSS variable `--accent` and (because POST is the canonical authenticated verb in LuckyStack) also `--post`, the POST method pill color. |
-| `fontFamily` | `string` (CSS font-family) | `system-ui, -apple-system, "Segoe UI", Roboto, Helvetica, Arial, sans-serif` | Sets `--font-family`. Applied to `<body>` and inherited by inputs (the search bar uses `font-family: inherit`). |
-
-The renderer applies these tokens in the inline `<style>` block at the top of the document. There is no runtime style swap; changing branding requires a fresh HTML response.
-
-### Logo handling
-
-- The renderer accepts `https:`, `http:`, and scheme-free relative URLs (e.g. `/logo.svg`). `data:` and `javascript:` URLs are **rejected** — the logo will be silently omitted — because SVG data-URIs can carry script.
-- The string is escaped via the same `escapeHtml` helper used for `pageTitle` and `jsonPath`. Embedding hostile content in the `logoUrl` cannot break out of the `src` attribute.
-- The img tag is fixed at `height: 32px; width: auto;`. If you need a different size, embed an SVG with a `viewBox` so it scales correctly, or use a `template` builder.
-- When `logoUrl` is omitted, the brand row contains only the `<h1>`. There is no placeholder block.
-
-### Brand color cascade
-
-The branding color is wired into two CSS variables:
-
-```
---accent: <brandColor>
---post:   <brandColor>     // (POST method pill)
-```
-
-All other method colors are fixed:
-
-```
---get:    #3fb950    (green)
---put:    #d29922    (amber, with dark text)
---delete: #f85149    (red)
-```
-
-This intentional split keeps GET/PUT/DELETE recognizable across themes while letting the POST pill match the brand. If you need per-method theming, use a `template` builder.
-
-### Font handling
-
-`fontFamily` flows into `--font-family` and is consumed by `<body>` via `font-family: var(--font-family);`. The `<input type="search">` uses `font-family: inherit` so the search bar adopts the brand font. Code blocks (`pre`, `.endpoint`, `.try-it-out textarea`) use a fixed monospace stack (`ui-monospace, SFMono-Regular, "SF Mono", Consolas, monospace`) and are not affected by `fontFamily`.
-
-Quoting and escaping: `fontFamily` is interpolated **as-is** into the CSS string. Provide a valid CSS font-family value, including quotes around multi-word family names when needed (e.g. `'Inter', system-ui, sans-serif`).
-
-## Dark / light auto-switch
-
-The page respects the OS preference via `prefers-color-scheme`. There is no in-page theme toggle.
-
-Dark palette (default `:root` values):
-
-```
---bg: #0e1116        --container: #161b22        --container-hover: #1c232b
---border: #2a313c    --title: #e6edf3            --common: #c9d1d9
---muted: #8b949e
-```
-
-Light palette (overridden inside `@media (prefers-color-scheme: light)`):
-
-```
---bg: #ffffff        --container: #f6f8fa        --container-hover: #eaeef2
---border: #d0d7de    --title: #1f2328            --common: #1f2328
---muted: #59636e
-```
-
-Variables that are **not** overridden in the light block — `--accent`, `--font-family`, `--get`, `--post`, `--put`, `--delete` — are chosen to be legible against both surfaces. The PUT pill flips its text color to dark via `.method.PUT { color: #1f2328; }` to remain legible on amber.
-
-## When to use `branding` vs `template`
-
-Use `branding` (default template) when:
-
-- You only need to swap the logo, the accent color, and/or the font.
-- You're happy with the single-column endpoints-grouped-by-page layout.
-- You want light/dark auto-switching for free.
-- You don't need to change the inline runner, the filter UI, or the JSON-fetch flow.
-
-Use `template: DocsTemplateBuilder` when:
-
-- You need a different layout — sidebar navigation, tabs, a marketing-page wrapper, an embedded auth-token field, a two-pane editor/inspector view.
-- You want a per-method palette beyond the POST = `brandColor` cascade.
-- You need to integrate with a corporate design system (component library, web fonts loaded from a CDN, etc.).
-- You want an in-page light/dark toggle independent of the OS preference.
-
-## Example — corporate brand palette
-
-```ts
-import { mountDocsUi } from '@luckystack/docs-ui';
-
-export const docsUiHandler = mountDocsUi({
-  pageTitle: 'Acme — API docs',
-  branding: {
-    logoUrl: 'https://cdn.acme.example/logo.svg',
-    brandColor: '#7c3aed',
-    fontFamily: `'Inter', system-ui, -apple-system, sans-serif`,
-  },
-});
-```
-
-This renders the default layout with the Acme logo, purple accent (also applied to the POST pill), and Inter as the body font. GET/PUT/DELETE pills remain green/amber/red.
-
-## Example — full template replacement
-
-```ts
-import { mountDocsUi, type DocsTemplateBuilder } from '@luckystack/docs-ui';
-
-const sidebarTemplate: DocsTemplateBuilder = ({ jsonPath, pageTitle, branding }) => `
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <title>${pageTitle}</title>
-  <link rel="stylesheet" href="https://cdn.example.com/corporate-tokens.css" />
-</head>
-<body>
-  <aside class="sidebar">${branding.logoUrl ? `<img src="${branding.logoUrl}" />` : ''}</aside>
-  <main id="content">Loading...</main>
-  <script>
-    fetch(${JSON.stringify(jsonPath)}, { credentials: 'include' })
-      .then(r => r.json())
-      .then(data => { /* render however you like */ });
-  </script>
-</body>
-</html>`;
-
-export const docsUiHandler = mountDocsUi({
-  template: sidebarTemplate,
-  branding: { logoUrl: 'https://cdn.example.com/logo.svg' },
-});
-```
-
-Contract reminders for custom templates (see `./html-generation.md` for the full contract):
-
-- Return a complete `<!DOCTYPE html>...</html>` document.
-- HTML-escape any inputs that end up in markup — the builder receives raw strings.
-- Fetch `jsonPath` yourself; the handler does not pre-fetch.
-- You may receive a non-empty `branding` even when you don't use it — that's fine, ignore the fields you don't need.
-
-## Limits
-
-- No per-endpoint color override. The method pill colors are fixed CSS variables.
-- No runtime theme switcher beyond OS preference in the default template. Implement one inside a custom template if needed.
-- No web-font loading. The default template does not inject `<link rel="stylesheet">` tags — bring your own via a custom template.
-- No localization. Strings like "Try it out (live request)", "No matches.", "Run `npm run generateArtifacts`" are hardcoded English. Replace via a custom template if you need translations.
-- `brandColor` must be a valid single CSS color value (hex, named, `rgb()`, `hsl()`). Gradients are not supported.
-
-## Related
-
-- The renderer that consumes these tokens: `./html-generation.md`
-- The mount handler that accepts them: `./mounting.md`
-- The JSON fields the page renders: `./extension-fields.md`
-- AI summary + function index: `../CLAUDE.md`
-- Source: `../src/index.ts`, `../src/docsHtml.ts`
+The installed renderer and types define supported branding fields. Avoid copying a palette/default table here: values and theme behavior belong in source, while the important design boundary is that appearance changes do not bypass the environment or authorization gate. See `mounting.md` before enabling production access.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckystack/docs-ui",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "private": false,
   "publishConfig": {
     "access": "public",
@@ -44,7 +44,7 @@
   "files": [
     "dist",
     "README.md",
-    "CLAUDE.md",
+    "AGENTS.md",
     "docs",
     "LICENSE",
     "CHANGELOG.md"
@@ -55,10 +55,10 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@luckystack/core": "^0.10.1"
+    "@luckystack/core": "^0.11.0"
   },
   "peerDependencies": {
-    "@luckystack/server": "^0.10.1"
+    "@luckystack/server": "^0.11.0"
   },
   "peerDependenciesMeta": {
     "@luckystack/server": {

package/CLAUDE.md

@@ -1,55 +0,0 @@
-# @luckystack/docs-ui
-
-> AI summary + function INDEX. For deep specs see `docs/` next to this file.
-
-## What this package does
-
-Dev-only API docs browser for LuckyStack. Mounts a single page (default `/_docs`) that fetches the framework's generated `apiDocs.generated.json` and renders every API endpoint grouped by page, with HTTP method, auth, rate limit, input shape, and output shape. Sync events appear alongside APIs when the type-map emitter has produced metadata for them. Ships a `customRoutes` handler — composable with `createLuckyStackServer`'s `customRoutes` option without taking ownership of the request pipeline.
-
-## When to USE this package
-
-- Local development: developer wants a Swagger-style overview of every route in the project without leaving the browser.
-- Internal developer-portal: opt-in production rendering via `enabledInProd: true` for an authenticated team-only deploy.
-- Custom branded API docs: replace the default template via the `template: DocsTemplateBuilder` option to render in a sidebar/tabs/marketing layout while reusing the JSON endpoint.
-- Inline request runner: enable `enableTryItOut` so each endpoint gets a textarea + Send button that posts against the live server using the browser session cookie.
-
-## When to NOT suggest this (yet)
-
-- Public production surface where API discoverability is sensitive — keep the default `enabledInProd: false` and don't mount in prod.
-- Replacement for `apiDocs.generated.json` itself — this package only reads/renders that file; regenerate via `@luckystack/devkit`'s type-map emitter (`npm run generateArtifacts`).
-- A non-HTTP transport — the handler is bound to `IncomingMessage` / `ServerResponse`; do not wire it directly into Socket.io handlers.
-- React-tree integration — the docs UI is a single self-contained HTML document with no React/Tailwind dependency on the client; do not import `renderDocsHtml` into the app bundle.
-
-## Function Index
-
-| Function / Export | 1-regel | Deep doc |
-|---|---|---|
-| `mountDocsUi(options?)` | Returns a `DocsRouteHandler` for `customRoutes`; serves HTML + JSON | → docs/mounting.md |
-| `renderDocsHtml(jsonPath, pageTitle, options?)` | Builds the self-contained docs HTML document | → docs/html-generation.md |
-| Type: `DocsRouteHandler` | `(req, res) => Promise<boolean>`; returns `true` when route handled | → docs/mounting.md |
-| Type: `DocsTemplateBuilder` | Custom HTML builder hook: `({ jsonPath, pageTitle, branding }) => string` | → docs/html-generation.md |
-| Type: `MountDocsUiOptions` | All mount inputs (routePath, enabledInProd, branding, template, enableTryItOut, ...) | → docs/mounting.md |
-| Type: `DocsBranding` | `{ logoUrl?, brandColor?, fontFamily? }` applied by default template | → docs/theming.md |
-| Type: `RenderDocsHtmlOptions` | `{ branding?, enableTryItOut? }` passed to `renderDocsHtml` | → docs/html-generation.md |
-| Extension field: `meta.stream` | Per-endpoint stream shape rendered in expanded detail panel | → docs/extension-fields.md |
-| Extension field: `meta.owner` | Owner string rendered in expanded detail panel | → docs/extension-fields.md |
-| Extension field: `meta.tags` | Tag badges rendered in expanded detail panel | → docs/extension-fields.md |
-| Extension field: `meta.deprecated` | Deprecation note (red) rendered in expanded detail panel | → docs/extension-fields.md |
-
-## Config keys (env vars + registerProjectConfig slots)
-
-- `NODE_ENV` (env) — when `'production'`, the route returns `404` unless `enabledInProd: true` is set.
-- `ProjectConfig.paths.generatedApiDocs` (config, resolved via `getGeneratedApiDocsPath()` from `@luckystack/core`) — default JSON file path; override per-mount via `options.apiDocsPath`.
-- No package-private env vars. All behavior is controlled via `MountDocsUiOptions`.
-
-## Peer dependencies
-
-- **Required**: `@luckystack/core` (provides `getGeneratedApiDocsPath` + `tryCatch`).
-- **Required (runtime composition)**: `@luckystack/server` — the handler is intended to be passed to `createLuckyStackServer({ customRoutes })` / `bootstrapLuckyStack({ customRoutes })`. The package itself does not import `@luckystack/server`; the dependency is on the consumer side.
-- **Required (data source)**: `@luckystack/devkit` (build-time) — emits `apiDocs.generated.json`. Without it the JSON endpoint returns a 404 with a hint to run `npm run generateArtifacts`.
-
-## Related
-
-- Architecture deep-dives: `/docs/ARCHITECTURE_API.md` (lifecycle of documented endpoints), `/docs/ARCHITECTURE_PACKAGING.md` (how the JSON artifact is produced).
-- README (consumer quickstart): `./README.md`.
-- Source: `./src/index.ts` (mount + route handling), `./src/docsHtml.ts` (embedded HTML renderer).