@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/handbook/cloudflare/low-level-composition.md

@@ -1,169 +0,0 @@
----
-description: Own the top-level Hono assembly with the same public primitives createMantleWorker uses, and the invariants you must keep.
----
-# Low-level composition
-
-Use `createMantleWorker` unless the deployment must own its top-level Worker lifecycle. This page covers when that is true, what it costs, the exported building blocks, the assembly order, and the invariants a hand-assembled Worker must preserve.
-
-## When you need it
-
-You need low-level composition when the Worker entry must do something the facade's single `extend` seam cannot: run logic around every response (an audit queue, custom telemetry), select bindings or Auth per request, or interleave Mantle with another framework's router. Custom handlers, routes, credential resolvers and capability bindings do not require it; see [The conventional Worker](./conventional-worker.md).
-
-The cost is ownership. The Worker entry, error boundary, readiness handling and cache boundary become application code, and there is no automatic merge path back to `createMantleWorker`. Mantle still owns the imported adapters and standard route behavior; update them through the package version and never copy their source.
-
-## Building blocks
-
-All of these are exported from `@aotter/mantle/cloudflare` unless noted:
-
-| Export | Role |
-|---|---|
-| `createConventionalBindings(env, cacheScope?)` | `DB` to D1 driver, `ASSETS` to Admin assets, optional deployment-scoped `MANTLE_KV` |
-| `createConventionalAuth(env)`, `createAuth(config)` | Mode-driven Auth, or a curated custom factory |
-| `conventionalMcpResource(env)`, `conventionalAuthBaseURL(env)` | `<PUBLIC_ORIGIN>/mcp` and the canonical base URL |
-| `setupIncompleteAuthResponse(request, auth)` | The `503 setup_incomplete` guard for Auth-owned paths |
-| `createMantleRuntimeRef(config)` | Per-isolate runtime singleton with `get()`, `web()`, `auth`, `plan` |
-| `mountRuntimeEndpoints(app, ref)` | HTTP Triggers, `GET /api/views`, `GET /api/views/<name>` |
-| `mountAdmin(app, ref, assets)` | Admin routes and SPA |
-| `mountMantleOAuth(app, { auth, assets })` | OAuth consent and discovery, from `@aotter/mantle/admin` |
-| `createMcpApiHandler({ ref, surface, resource })` | `/mcp` (`"public"`) and `/mcp/staff` (`"staff"`) handlers |
-| `mountPublicRoutes(app, ref, options)` | Public HTML, `.md`, `llms.txt`, sitemap |
-| `applyCachePolicy(request, response, cacheTag?)` | The final cache decision |
-| `runMantleWorkerRequest(fn)` | Redacted `500 internal_error` boundary |
-| `D1DatabaseDriver`, `AssetsAssetServer`, `R2MediaStorage`, `WorkersQueueHookDispatcher`, `createQueueHandler`, `KvSiteConfigRepository`, `cloudflareTurnstileCheck`, `resolveCaller` | Individual adapters and helpers |
-| `MANTLE_RESERVED_PATH_PREFIXES`, `MANTLE_RESERVED_WELL_KNOWN_PREFIX`, `MANTLE_RESERVED_EXACT_PATHS` | Core-owned path constants |
-
-## Assembly
-
-The order is bindings, Auth, runtime ref, Hono app, runtime endpoints, Admin, OAuth, MCP handlers, then the cache policy on every response. This example adds one application-owned audit message after each request:
-
-```ts
-import { Hono } from "hono";
-import {
-  applyCachePolicy,
-  conventionalMcpResource,
-  createMantleRuntimeRef,
-  createConventionalAuth,
-  createConventionalBindings,
-  createMcpApiHandler,
-  mountAdmin,
-  mountRuntimeEndpoints,
-  runMantleWorkerRequest,
-  scopedPublicCacheTag,
-  setupIncompleteAuthResponse,
-  type MantleCloudflareEnv,
-} from "@aotter/mantle/cloudflare";
-import { mountMantleOAuth } from "@aotter/mantle/admin";
-import { plan } from "../.mantle/generated/mantle.js";
-
-interface Env extends MantleCloudflareEnv {
-  readonly AUDIT_QUEUE: Queue<{ kind: "request-complete"; path: string; status: number }>;
-}
-
-let assembled: ReturnType<typeof assemble> | undefined;
-const CACHE_SCOPE = "my-site-production";
-const CACHE_TAG = scopedPublicCacheTag(CACHE_SCOPE)!;
-
-export default {
-  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
-    return runMantleWorkerRequest(async () => {
-      const worker = assembled ??= assemble(env);
-      if (worker.auth.ready) ctx.waitUntil(worker.auth.ready.catch((error) => {
-        if (assembled === worker) assembled = undefined;   // evict a failed assembly
-        throw error;
-      }));
-      const incomplete = await setupIncompleteAuthResponse(request, worker.auth);
-      const response = incomplete ?? await worker.fetch(request, env, ctx);
-      ctx.waitUntil(env.AUDIT_QUEUE.send({
-        kind: "request-complete",
-        path: new URL(request.url).pathname,
-        status: response.status,
-      }));
-      return response;
-    });
-  },
-} satisfies ExportedHandler<Env>;
-
-function assemble(env: Env) {
-  const bindings = createConventionalBindings(env, CACHE_SCOPE);
-  const auth = createConventionalAuth(env);
-  const ref = createMantleRuntimeRef({
-    plan,
-    bindings,
-    auth,
-    cacheScope: CACHE_SCOPE,
-    onPublicChange: purgePublicCache,
-  });
-  const app = new Hono<{ Bindings: Env }>();
-
-  mountRuntimeEndpoints(app, ref);
-  if (bindings.adminAssets) mountAdmin(app, ref, bindings.adminAssets);
-  mountMantleOAuth(app, { auth, assets: bindings.adminAssets });
-  app.get("/cache-probe", () => new Response("public", {
-    headers: { "cache-control": "public, s-maxage=60" },
-  }));
-
-  const resource = conventionalMcpResource(env);
-  const mcp = new Map([
-    ["/mcp/staff", createMcpApiHandler<Env>({ ref, surface: "staff", resource })],
-    ["/mcp", createMcpApiHandler<Env>({ ref, surface: "public", resource })],
-  ]);
-
-  return {
-    auth,
-    async fetch(request: Request, workerEnv: Env, ctx: ExecutionContext) {
-      // Prepare the canonical D1 schema before Better Auth handles a
-      // token, client, consent or CIMD request.
-      await ref.get();
-      const handler = mcp.get(new URL(request.url).pathname);
-      const response = handler?.fetch
-        ? await handler.fetch(request, workerEnv, ctx)
-        : await app.fetch(request, workerEnv, ctx);
-      return applyCachePolicy(request, response, CACHE_TAG);
-    },
-  };
-}
-
-async function purgePublicCache() {
-  try {
-    const { cache } = await import("cloudflare:workers");
-    const result = await cache.purge({ tags: [CACHE_TAG] });
-    if (!result.success) console.error("public cache purge failed", result.errors);
-  } catch (error) {
-    console.error("public cache purge failed", error);
-  }
-}
-```
-
-```jsonc
-{
-  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
-  "queues": { "producers": [{ "binding": "AUDIT_QUEUE", "queue": "my-site-audit" }] }
-}
-```
-
-## Invariants to keep
-
-- Await `ref.get()` before Better Auth handles a token, client, consent or CIMD request. The facade does this for Auth, `/oauth`, `/mcp`, `/admin/api` and `/.well-known/oauth*`; the example awaits before every request.
-- Evict the memoized assembly when `auth.ready` rejects, so a transient D1 failure during boot does not poison the isolate.
-- Pass every response through `applyCachePolicy`, after Admin, Auth, API, OAuth, MCP, application routes, redirects and errors. It marks private surfaces `private, no-store`, strips CDN override headers, and keeps only anonymous `200` `GET`/`HEAD` responses with explicit `public` freshness.
-- Return `setupIncompleteAuthResponse` before dispatch so misconfigured Auth fails closed on Auth-owned paths only.
-- Keep the conventional `DB` binding, both compatibility flags, and the optional `MANTLE_KV` binding. Low-level bindings may instead set `mcpCatalogKv: { namespace, scope }` with a stable deployment-owned scope, never one derived from a request.
-- Pass `reservedHttpPathPrefixes` (the exported constants plus `auth.basePath`) to `createMantleRuntimeRef` so a manifest HTTP Trigger cannot claim a Core path.
-- If you mount public routes, provide a stable `cacheScope`, pass `onPublicChange` to `createMantleRuntimeRef`, and purge the resulting scoped tag there with the Workers cache API. The facade wires this purge itself; a bare `createMantleRuntimeRef` does not.
-- Do not replace Auth, MCP or cache handling with local copies.
-
-## Adding an application queue producer
-
-The audit queue above is the pattern: declare the binding in `Env` and `wrangler.jsonc`, send from `ctx.waitUntil` after the response is decided, and keep the message contract application-owned. Consume it in the same Worker by switching on `batch.queue`; see [Deferred hooks with Queues](./deferred-hooks-queues.md#multiplexing-application-queues). For the runtime pipeline these pieces sit on, see [Runtime and adapters](../concepts/runtime-and-adapters.md).
-
-## Source
-- [`docs/cloudflare-low-level-composition.md`](../../../docs/cloudflare-low-level-composition.md)
-- [`packages/adapters/cloudflare/README.md`](../../../packages/adapters/cloudflare/README.md)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/adapters/cloudflare/src/mount/bootRuntimeOnce.ts`](../../../packages/adapters/cloudflare/src/mount/bootRuntimeOnce.ts)
-- [`packages/adapters/cloudflare/src/mount/cmsConfig.ts`](../../../packages/adapters/cloudflare/src/mount/cmsConfig.ts)
-- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
-- [`packages/adapters/cloudflare/src/index.ts`](../../../packages/adapters/cloudflare/src/index.ts)
-- [`packages/adapters/cloudflare/src/bindings/index.ts`](../../../packages/adapters/cloudflare/src/bindings/index.ts)
-- [`packages/adapters/cloudflare/src/mount/index.ts`](../../../packages/adapters/cloudflare/src/mount/index.ts)
-- [`packages/adapters/cloudflare/src/worker/index.ts`](../../../packages/adapters/cloudflare/src/worker/index.ts)

package/docs/handbook/cloudflare/public-web.md

@@ -1,144 +0,0 @@
----
-description: Opt a Worker into public HTML, Markdown mirrors, llms.txt and sitemap with mountPublicRoutes, templates and a path resolver.
----
-# Public web, SEO and cache
-
-Public rendering is opt-in. A headless Worker serves Views and Triggers only; this page shows how to add server-rendered pages, their agent-readable mirrors and discovery files, and what the cache contract guarantees.
-
-## Three inputs that must agree
-
-1. `mountPublicRoutes(app, ref, { collectionRoutes, ... })` inside `extend.mount` declares which collections have URLs.
-2. A `TemplateRegistry` with an entry template (and optionally a list template) for each of those collections, passed as `templates`.
-3. A `PublicPathResolver` from `createPublicPathResolver({ collectionRoutes })`, passed as `publicPathResolver`, so canonical URLs, sitemap entries and hreflang siblings match the mounted routes.
-
-Mounting every Schema automatically is not supported: some collections are private even when they carry a slug. Without a `publicPathResolver`, `/sitemap.xml` returns `500`.
-
-## Worked example: a blog
-
-```ts
-// src/web/templates.ts
-import { createPublicPathResolver, TemplateRegistry, renderSeoTagsHtml } from "@aotter/mantle-web";
-
-export const publicPathResolver = createPublicPathResolver({
-  collectionRoutes: { posts: { segment: "posts" } },
-});
-
-export const collectionRoutes = [
-  { collection: "posts", segment: "posts", listRoute: true },
-] as const;
-
-export function createBlogTemplates(): TemplateRegistry {
-  const templates = new TemplateRegistry();
-
-  templates.registerEntryTemplate("posts", ({ entry, site, seo }) => {
-    const title = String(entry.data.title ?? site.title);
-    const meta = seo && {
-      ...seo,
-      jsonLd: { "@context": "https://schema.org", "@type": "BlogPosting", headline: title, url: seo.canonical },
-    };
-    return `<html lang="${entry.locale ?? "en"}"><head><title>${escape(title)}</title>
-      ${meta ? renderSeoTagsHtml(meta) : ""}<link rel="stylesheet" href="/blog.css"></head>
-      <body><article><h1>${escape(title)}</h1>
-      ${seo?.alternateMarkdown ? `<a href="${seo.alternateMarkdown}">Read as Markdown</a>` : ""}
-      ${renderMarkdown(String(entry.data.body ?? ""))}</article></body></html>`;
-  });
-
-  templates.registerListTemplate("posts", ({ entries, locale, site, seo }) => {
-    const items = entries.map((entry) => {
-      const href = publicPathResolver.forEntry(entry) ?? `/${locale}/posts/${entry.id}`;
-      return `<li><a href="${href}">${escape(String(entry.data.title ?? entry.id))}</a></li>`;
-    }).join("");
-    return `<html lang="${locale}"><head><title>Blog · ${escape(site.brand)}</title>
-      ${seo ? renderSeoTagsHtml(seo) : ""}</head><body><ul>${items}</ul></body></html>`;
-  });
-
-  return templates;
-}
-```
-
-```ts
-// worker entry
-export default createMantleWorker<Env>({
-  plan,
-  templates: createBlogTemplates(),
-  publicPathResolver,
-  siteDefaults: (env) => ({ /* ... */ origin: env.PUBLIC_ORIGIN, locales: ["en", "zh-TW"] }),
-  extend: ({ env }) => ({
-    mount({ app, ref }) {
-      mountPublicRoutes(app as never, ref, {
-        collectionRoutes: [...collectionRoutes],
-        notFoundRenderer: async () => htmlNotFound(),
-        liveDev: new URL(env.PUBLIC_ORIGIN).hostname === "localhost",
-      });
-    },
-  }),
-});
-```
-
-Templates return complete HTML strings; the renderer prepends the doctype. Escape every value you interpolate. Analytics, pixels and verification tags are host chrome — add them in the template or on Cloudflare. See [Site chrome](./site-chrome.md).
-
-## Template signatures
-
-```ts
-templates.registerEntryTemplate(collection, ({ entry, site, mediaAssets?, seo? }) => string);
-templates.registerListTemplate(collection, ({ collection, locale, entries, site, mediaAssets?, seo? }) => string);
-```
-
-`seo` is a composed `SeoMeta`:
-
-| Field | Content |
-|---|---|
-| `canonical` | Absolute canonical URL from `site.origin` and the resolved path |
-| `alternateMarkdown` | Absolute `.md` mirror URL, or `null` when the entry has no Markdown body |
-| `hreflangs` | One row per locale plus `x-default` on multi-locale sites |
-| `description`, `og`, `twitter` | Description, Open Graph and Twitter card blocks |
-| `jsonLd` | A default object; replace it before rendering, as the example does |
-
-`renderSeoTagsHtml(seo)` emits the corresponding tags. Entry pages also get `<link rel="alternate" type="text/markdown">` so crawlers and agents can fetch clean Markdown.
-
-## Routes produced
-
-| Route | Condition |
-|---|---|
-| `GET /` → `302` to `/<canonicalLocale>` | `homeRenderer` set |
-| `GET /:locale`, `GET /:locale.md` | `homeRenderer` set; body from `homeMarkdown` or the `homeSlug` entry |
-| `GET /:locale/<segment>`, `GET /:locale/<segment>.md` | `listRoute: true` |
-| `GET /:locale/<segment>/:slug` | always |
-| `GET /:locale/<segment>/:slug.md` | `markdownMirror` not `false` (default on) |
-| `GET /:locale/<segment>/:slug?preview=1` | staff session; renders live, `private, no-store` |
-| `GET /llms.txt`, `GET /:locale/llms.txt` | always |
-| `GET /sitemap.xml` | always; a urlset, or a sitemap index linking `/sitemap.xml?part=1&cursor=...` parts |
-| `GET /robots.txt` | always; `Allow: /` plus the sitemap URL |
-
-`CollectionRouteConfig` fields: `collection`, `segment` (empty string mounts entries directly under `/:locale/`), `listRoute` (default `false`), `markdownMirror` (default `true`), `homeSlug` (collapse one slug to `/:locale`). `slugOverrides` serve one `(collection, slug)` pair from your own renderer and take precedence over preview and standard rendering. `notFoundRenderer` is required; every miss falls through it. `liveDev` switches entry and list responses to `private, no-store` for local work.
-
-Only entries with `status: published` render. Drafts never appear on pages, mirrors, `llms.txt` or the sitemap; preview needs a staff session and answers `401` or `403` otherwise.
-
-## Pagination
-
-Lists and `llms.txt` return 50 entries per page, ordered `updatedAt DESC, id DESC`, with a forward `cursor`. A continuation adds `Link: <...?cursor=...>; rel="next"`; HTML lists also get a visible `<nav aria-label="Pagination">` Next link, and `llms.txt` appends a `## Continue` section. Sitemap parts hold up to 2,000 URLs divided by the locale count. See [Views](../concepts/views.md) for View-level paging.
-
-## Cache contract
-
-With a valid `cacheScope`, public responses carry `Cache-Control: public, max-age=0, s-maxage=300` and a deployment-scoped cache tag. The facade's final policy keeps that only for anonymous `200` `GET`/`HEAD` responses with no request `Cookie` or `Authorization` and no `Set-Cookie`, and adds `Vary: Cookie, Authorization`. Everything else becomes `private, no-store`, and CDN override headers are removed.
-
-Publishing-content and site-setting writes purge the scoped tag through the native Workers cache API. Purge is best effort after the canonical write. Operational records and static assets are outside that boundary. Enable the cache with `"cache": { "enabled": true }`; see [Bindings](./bindings.md#workers-cache).
-
-> **Warning**
-> The local emulator does not simulate the entrypoint Workers Cache or its purge API. Verify `cf-cache-status` and post-publish invalidation on a deployed environment, not with `wrangler dev`.
-
-## Static assets for templates
-
-Reference CSS, JS and icons by root path (`/blog.css`, `/site-icon.svg`); the `ASSETS` binding serves them from `public/`. Keep public content prefixes in `run_worker_first` so a static file never shadows a rendered route, and leave asset paths out of it so they bypass the Worker.
-
-## Source
-- [`packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts`](../../../packages/adapters/cloudflare/src/mount/mountPublicRoutes.ts)
-- [`packages/adapters/cloudflare/src/oauth/cachePolicy.ts`](../../../packages/adapters/cloudflare/src/oauth/cachePolicy.ts)
-- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
-- [`packages/mantle-web/README.md`](../../../packages/mantle-web/README.md)
-- [`packages/mantle-web/src/model/TemplateRegistry.ts`](../../../packages/mantle-web/src/model/TemplateRegistry.ts)
-- [`packages/mantle-web/src/model/SeoMeta.ts`](../../../packages/mantle-web/src/model/SeoMeta.ts)
-- [`packages/mantle-web/src/service/SeoMetaComposer.ts`](../../../packages/mantle-web/src/service/SeoMetaComposer.ts)
-- [`packages/mantle-web/src/service/PublicPathResolver.ts`](../../../packages/mantle-web/src/service/PublicPathResolver.ts)
-- [`docs/adapter-guide.md`](../../../docs/adapter-guide.md)
-- [`docs/performance-harness.md`](../../../docs/performance-harness.md)

package/docs/handbook/cloudflare/site-chrome.md

@@ -1,75 +0,0 @@
----
-description: Host-owned site chrome — Cloudflare-first analytics, verification, robots, and what still belongs in mantle-web.
----
-# Site chrome
-
-Core `siteConfig` is deployment identity: locales, brand, title, description, origin, icons and media. Visitor analytics, pixels, search-engine verification tokens, `ads.txt` and similar chrome are **host responsibility**. Admin Settings does not accept tracking IDs, and `@aotter/mantle-web` does not inject vendor snippets from `siteConfig`.
-
-Cloudflare-native platform capabilities are the first-class place for chrome that the zone already covers. Do not invent a parallel “CDN settings center” inside Mantle.
-
-## Why Core does not inject
-
-A headless runtime that rewrites the first `</head>` (or prepends to `<body>`) on a composed HTML string assumes one frontend shape: a complete SSR document that Core is allowed to mutate after the fact. Hosts are not one shape.
-
-Frontends are plural. A Mantle consumer may serve SSR full HTML documents, a Vite/React (or other) SPA, a Worker plus static assets, Cloudflare Pages, or a custom wrapper that already owns `<html>`. Only the first of those even has a complete document string a runtime could splice into — and even then the attach point is the host template, not Core.
-
-SPA, client-routed and hydration hosts attach analytics in **their own entry**: GTM or Zaraz, the app bootstrap, or Cloudflare Web Analytics. They do not expect Runtime or `mantle-web` to parse an HTML string and splice tags into it.
-
-Silent injection from `siteConfig` would be a surprising side effect for any host that did not opt into “I emit a full document and you may rewrite it.” Core must not pretend to know every frontend’s attach point.
-
-Therefore tracking and verification stay **host chrome**. Core `siteConfig` is not a tag-manager. The tables below say where to put chrome.
-
-## Two layers
-
-| Concern | Prefer | Usually still app / mantle-web |
-|---|---|---|
-| `robots.txt`, simple redirects, some `/.well-known` files, Cloudflare Web Analytics | **Cloudflare-native** | — |
-| Dynamic sitemap (grows with content), `llms.txt`, SEO `.md` mirrors | — | Application mount or `@aotter/mantle-web` composition, then serve publicly |
-
-Turning on Cloudflare Web Analytics is **not** the same as having an indexable sitemap or `llms.txt`. Analytics answers “who visited”; discovery files answer “what can a crawler or agent list”. Keep those jobs on the layer that owns the data.
-
-Cloud tenant UX for ads.txt / robots / sitemap tools lives on the host product. Core stays injection-free.
-
-## Cloudflare-first install
-
-Use the dashboard, Wrangler, or an agent that can edit Worker / Pages config. None of these paths write Core Admin fields.
-
-### Analytics
-
-Prefer **Cloudflare Web Analytics** (and Zaraz when you need a tag manager) for first-party traffic measurement. Enable it on the zone; no Core `siteConfig` key is required.
-
-To add GA4 or Meta Pixel:
-
-1. Add the provider through **Cloudflare Zaraz** (recommended on a CF zone), or
-2. Emit the vendor snippet from **your** entry/list templates in `@aotter/mantle-web`, or from a host HTML wrapper.
-
-Do not put Measurement IDs or Pixel IDs in `siteDefaults`. Core does not persist or inject them.
-
-### Search Console and Bing verification
-
-Verify ownership with a host-owned method. On Cloudflare, prefer in this order:
-
-1. **DNS TXT** at the zone apex (Search Console and Bing Webmaster both accept this).
-2. **Cloudflare-managed HTML** via Zaraz or a small Worker / Pages header rewrite that adds `<meta name="google-site-verification">` / Bing equivalent.
-3. A **static verification file** at `/` or `/.well-known/` served from `public/` / the `ASSETS` binding.
-
-HTML-tag verification belongs in the host template `<head>`, not in Core Settings.
-
-### robots.txt, redirects, well-known
-
-Serve a static `robots.txt` from assets, or use Cloudflare Redirect Rules / Transform Rules / a tiny Worker route. `mountPublicRoutes` also emits `GET /robots.txt` (`Allow: /` plus the sitemap URL) when you opt into public pages — that is an application mount, not a Core Admin setting. See [Public web](./public-web.md).
-
-Simple path redirects and most `/.well-known` files (including verification and `security.txt`) belong on the same Cloudflare-native layer.
-
-## What still belongs in the app
-
-Dynamic **sitemap** and **`llms.txt`** grow with published content. Compose them with `@aotter/mantle-web` (`composeSitemap`, `composeLlmsTxt`) and mount the public URLs, or implement the same contract in the application. Cloudflare Web Analytics does not generate those files.
-
-SEO `.md` mirrors are likewise application / `mantle-web` composition. Details: [Public web](./public-web.md) and [Site config](../reference/site-config.md).
-
-## Source
-
-- [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
-- [`packages/mantle-web/src/service/HtmlRenderer.ts`](../../../packages/mantle-web/src/service/HtmlRenderer.ts)
-- [`docs/handbook/reference/site-config.md`](../reference/site-config.md)
-- [`docs/handbook/cloudflare/public-web.md`](./public-web.md)

package/docs/handbook/examples/commerce-transaction.md

@@ -1,11 +0,0 @@
----
-description: Redirects to the Cloudflare primitives commerce inventory example in the Examples hub.
----
-# Commerce: catalog, orders, inventory authority and asynchronous settlement
-
-This example lives in the Examples hub: [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md). The Builder-safe catalog is [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md).
-
-## Source
-
-- [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md)
-- [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md)

package/docs/handbook/examples/commerce.md

@@ -1,11 +0,0 @@
----
-description: Redirects to the builtin commerce catalog example in the Examples hub.
----
-# Commerce catalog and orders
-
-This example lives in the Examples hub: [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md). Stock authority and settlement are [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md).
-
-## Source
-
-- [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md)
-- [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md)

package/docs/handbook/examples/guarded-api.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the guarded API example in the Examples hub.
----
-# Guarded API access: API keys, scopes and entitlement
-
-This example lives in the Examples hub: [`docs/examples/cf-primitives-guarded-api.md`](../../examples/cf-primitives-guarded-api.md).
-
-## Source
-
-- [`docs/examples/cf-primitives-guarded-api.md`](../../examples/cf-primitives-guarded-api.md)

package/docs/handbook/examples/intake-form.md

@@ -1,12 +0,0 @@
----
-description: Redirects to the builtin public intake form in the Examples hub.
----
-# Intake form
-
-This example lives in the Examples hub: [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md). Turnstile and email hooks are [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md).
-
-## Source
-
-- [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md)
-- [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md)
-- [`docs/examples/README.md`](../../examples/README.md)

package/docs/handbook/examples/intake-hooks.md

@@ -1,11 +0,0 @@
----
-description: Redirects to the Turnstile and email intake hooks in the Examples hub.
----
-# Intake form with bot check and notification
-
-This example lives in the Examples hub: [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md). The Builder-safe Manifest is [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md).
-
-## Source
-
-- [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md)
-- [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md)

package/docs/handbook/examples/legal-documents.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin legal documents example in the Examples hub.
----
-# Legal documents and consent
-
-This example lives in the Examples hub: [`docs/examples/builtin-legal-documents.md`](../../examples/builtin-legal-documents.md).
-
-## Source
-
-- [`docs/examples/builtin-legal-documents.md`](../../examples/builtin-legal-documents.md)

package/docs/handbook/examples/procurement-approvals.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin procurement example in the Examples hub.
----
-# Procurement approvals with member and staff roles
-
-This example lives in the Examples hub: [`docs/examples/builtin-procurement.md`](../../examples/builtin-procurement.md).
-
-## Source
-
-- [`docs/examples/builtin-procurement.md`](../../examples/builtin-procurement.md)

package/docs/handbook/examples/publication.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin publication example in the Examples hub.
----
-# Publication: localized posts with a public list
-
-This example lives in the Examples hub: [`docs/examples/builtin-publication.md`](../../examples/builtin-publication.md).
-
-## Source
-
-- [`docs/examples/builtin-publication.md`](../../examples/builtin-publication.md)

package/docs/handbook/examples/reservation.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin reservation example in the Examples hub.
----
-# Reservation requests
-
-This example lives in the Examples hub: [`docs/examples/builtin-reservation.md`](../../examples/builtin-reservation.md).
-
-## Source
-
-- [`docs/examples/builtin-reservation.md`](../../examples/builtin-reservation.md)

package/docs/handbook/start/quickstart-admin.md

@@ -1,50 +0,0 @@
----
-description: "Open local Admin in one shot: follow the official OTP example, bind ASSETS, sign in with email OTP from wrangler logs, land in the Dev UI."
----
-# Quickstart: local Admin
-
-Admin is **opt-in**: use it when humans need a Dev UI. A complete Mantle
-service does not require this surface. The default embed path — Spec + Worker
-without Admin — is [Quickstart: a minimal Worker](./quickstart-worker.md).
-
-The procedural source of truth is the official example:
-
-**[`docs/examples/host-local-admin-otp/README.md`](../../examples/host-local-admin-otp/README.md)**
-
-Copy that directory outside the SDK checkout (or author the same files from
-it). Interview the human for one value before writing files: the bootstrap
-owner email. The example uses `owner@example.com`. Then:
-
-```sh
-pnpm install && pnpm generate && pnpm dev
-```
-
-Open the wrangler Ready-on URL (`http://127.0.0.1:8787/admin/sign-in`), submit
-the owner email, and read the OTP from wrangler logs. `mantle generate` syncs
-the prebuilt Admin SPA; do not Vite-build Admin.
-
-Traps (documented on the example):
-
-- Prefer `127.0.0.1` over `localhost` (`INVALID_ORIGIN`).
-- `pnpm check` / smoke rewrites `.dev.vars` to a smoke-only port — restore it
-  from `.dev.vars.example` before `pnpm dev`.
-
-Install every `@aotter/mantle*` package from the `latest` dist-tag; see
-[Versions](../reference/surface.md#versions). Admin needs both
-`@aotter/mantle-admin` and `@aotter/mantle-admin-ui`, wrangler `ASSETS` on
-`./public`, and `createAuth` email-otp + `ConsoleEmailSender`.
-
-## Next steps
-
-- [Project layout and the CLI loop](./project-and-cli.md) — the files you own, every CLI flag, the daily check loop, ASSETS as a hard Admin requirement.
-- [Authentication](../cloudflare/authentication.md) — production senders, GitHub / hosted modes, roles.
-- [The conventional Worker](../cloudflare/conventional-worker.md) — handlers and extra routes.
-- [Quickstart: a minimal Worker](./quickstart-worker.md) — API-only embed without Admin.
-
-## Source
-- [`docs/examples/host-local-admin-otp/README.md`](../../../docs/examples/host-local-admin-otp/README.md)
-- [`docs/examples/host-local-admin-otp/package.json`](../../../docs/examples/host-local-admin-otp/package.json)
-- [`docs/examples/host-local-admin-otp/src/index.ts`](../../../docs/examples/host-local-admin-otp/src/index.ts)
-- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
-- [`docs/examples/host-local-admin-otp/.dev.vars.example`](../../../docs/examples/host-local-admin-otp/.dev.vars.example)
-- [`docs/examples/host-local-admin-otp/smoke.mjs`](../../../docs/examples/host-local-admin-otp/smoke.mjs)

package/docs/labels.md

@@ -1,71 +0,0 @@
-# GitHub labels
-
-Labels keep issues and PRs sortable for humans and cold-start AI agents. Apply the smallest useful set: one kind label, one or more area labels, and any gate labels that change review requirements.
-
-## Kind and status
-
-| Label | Meaning | Who applies | Remove when |
-|---|---|---|---|
-| `bug` | Broken, surprising, unsafe, or regressed behavior. | Reporter or triager. | The issue is reclassified. |
-| `enhancement` | New capability, behavior, or process improvement. | Reporter or triager. | The issue is reclassified. |
-| `documentation` | Docs-only change or docs gap. | Reporter, triager, or PR author. | The issue is reclassified. |
-| `question` | Needs an answer or convergence before action. | Reporter or triager. | The answer is captured or the issue is converted. |
-| `good first issue` | Suitable for a new contributor with repo docs only. | Maintainer. | Scope grows or hidden context is required. |
-| `help wanted` | Maintainers want external help. | Maintainer. | No longer seeking help. |
-| `duplicate` | Same work exists elsewhere. | Triager. | Usually never; close with link. |
-| `invalid` | Not actionable for this repo. | Triager. | Usually never; close with reason. |
-| `wontfix` | Valid but intentionally not planned. | Maintainer. | Usually never; close with reason. |
-| `epic` | Tracks a multi-issue initiative. | Maintainer. | The epic closes. |
-| `spike` | Exploratory work, not guaranteed to land. | Triager or maintainer. | The work becomes a concrete proposal or implementation issue. |
-
-## Area
-
-Use at least one `area:*` label when the affected surface is known.
-
-For package README or package-local docs changes, prefer the package area label (`area:spec`, `area:runtime`, `area:cf`, or `area:admin-ui`). Use `area:docs` for repo-wide docs, governance, ADRs, release docs, root README content, and cross-cutting documentation work.
-
-| Label | Meaning |
-|---|---|
-| `area:runtime` | `packages/mantle-runtime` behavior, ports, use cases, dispatcher, and MCP runtime. |
-| `area:spec` | `packages/mantle-spec`, manifest parsing, validation, diagnostics, CLI, spec types. |
-| `area:cf` | `packages/adapters/cloudflare`, Workers adapter, D1/KV/ASSETS wiring, Cloudflare deploy behavior. |
-| `area:skills` | `skills/*` agent briefs and install/extend/provision workflows. |
-| `area:admin-ui` | `packages/mantle-admin-ui` React admin SPA. |
-| `area:docs` | Repo-wide human docs, governance docs, ADR text, release docs, root README content, and cross-cutting documentation work. |
-| `area:adapter` | Adapter boundary work spanning Cloudflare or future adapters. |
-| `area:ci` | GitHub Actions, dependency automation, and repository checks. |
-| `area:starters` | **Legacy only.** Retired `aotter/mantle-starters` source and migration notes. Do not use for new Core work. |
-
-## Release and review gates
-
-| Label | Meaning | Review consequence | Remove when |
-|---|---|---|---|
-| `release-gate` | Blocks a public release or release-quality claim. | Must be resolved or explicitly deferred before release. | The gate is closed or deferred by maintainer decision. |
-| `v0.1.0` | Required for the v0.1.0 release gate. | Track in the v0.1.0 release pass. | The item lands or is moved out of v0.1.0. |
-| `breaking-change` | Semver-relevant breaking change. | Generated release notes must call it out. | The change is redesigned to be non-breaking. |
-| `skip-release-notes` | Release bookkeeping with no user-facing change. | Excluded from generated GitHub Release notes. | The PR contains a user-facing change. |
-| `needs-adr` | Architecture, trust boundary, package boundary, or long-lived decision needs an ADR or ADR-lite proposal. | Do not merge implementation until the decision is captured. | ADR/proposal lands or maintainer confirms an existing ADR covers it. |
-| `needs-grammar-revise` | Manifest grammar or closed-enum change. | Requires grammar-revise round before code/types change. | Grammar decision lands or the change no longer affects grammar. |
-| `needs-discussion` | Not converged enough for implementation. | Do not start coding from this issue. | Closing criteria are met and scope is concrete. |
-
-## Creating missing labels
-
-Use these commands from a checked-out repo:
-
-```bash
-gh label create "area:runtime" --description "Runtime package, ports, use cases, dispatcher, render, MCP runtime" --color "1d76db"
-gh label create "area:spec" --description "Spec package, manifest parsing, validation, diagnostics, CLI, types" --color "1d76db"
-gh label create "area:cf" --description "Cloudflare Workers adapter and bindings" --color "1d76db"
-gh label create "area:skills" --description "Agent Skills and install/extend/provision workflows" --color "1d76db"
-gh label create "area:admin-ui" --description "React admin UI" --color "1d76db"
-gh label create "area:docs" --description "Documentation and governance" --color "1d76db"
-gh label create "area:adapter" --description "Adapter boundary and future adapter work" --color "1d76db"
-gh label create "area:ci" --description "CI, dependency automation, and repository checks" --color "1d76db"
-gh label create "area:starters" --description "Legacy only: retired mantle-starters source and migration" --color "cfd3d7"
-gh label create "breaking-change" --description "Semver-relevant breaking change" --color "b60205"
-gh label create "skip-release-notes" --description "Release bookkeeping only; omit from generated GitHub notes" --color "ededed"
-gh label create "needs-adr" --description "Requires an ADR or ADR-lite decision before merge" --color "d93f0b"
-gh label create "needs-grammar-revise" --description "Requires manifest grammar review before implementation" --color "d93f0b"
-gh label create "needs-discussion" --description "Not converged enough for implementation" --color "fbca04"
-gh label create "spike" --description "Exploratory work, not guaranteed to land" --color "bfdadc"
-```

package/docs/media-uploads.md

@@ -1,5 +0,0 @@
-# Media uploads
-
-This guide moved into the handbook: [`docs/handbook/cloudflare/media-r2.md`](handbook/cloudflare/media-r2.md).
-
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.