@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/docs/handbook/guides/oauth.md

@@ -0,0 +1,105 @@
+# OAuth provider and consent
+
+Auth remains app-owned. Install the existing optional Better Auth peers and
+create your `betterAuth()` instance with `jwt({ disableSettingJwtHeader: true })`
+and `oauthProvider` (or the provider's MCP preset). Append `oauthGrantExtension`
+**first** in its `extensions`. The helper comes from
+`@aotter/mantle/auth/oauth` and binds issued access tokens to the current consent
+ID and Better Auth’s consent reference without changing `referenceId`.
+Configure
+`consentPage: "/oauth/consent"`, loginPage,
+resources, allowed/default client registration scopes, and public/native DCR
+explicitly. For MCP clients use the SDK's `mcp` preset, `allowPublicClientPrelogin:
+true`, and a `90d` registration client-secret expiration. The application selects
+plugins and options; Mantle does not wrap Better Auth or run runtime DDL.
+
+With Mantle's native adapters, `oauthProvider.resources` comes from runtime
+configuration, including environment-derived identifiers. `schema.sql` contains
+auth DDL only. On the first OAuth lookup of a configured resource (authorization,
+token issuance, registration defaults or audience checks), the adapter validates
+and inserts the missing row with insert-if-absent semantics. Concurrent requests
+are safe; subsequent lookups preserve persisted policy edits. No resource deploy
+step is required, and `resourceSeedMode` does not overwrite existing rows.
+To retire a resource, set its persisted `disabled` policy (or configure it disabled
+before its first lookup). Removing configuration does not disable an existing row.
+Do not delete a configured resource row: a later lookup in a new adapter instance
+can recreate it from configuration. On
+`/oauth2/authorize` an invalid configured identifier surfaces as the provider's
+`invalid_target` redirect rather than HTTP 500.
+
+Auth initialization, cookie/bearer resolution and normal MCP/REST requests perform
+no resource SELECT or INSERT. The adapter suppresses the provider's eager and
+bulk lazy seeding. Invalid configured identifiers produce HTTP 500 with
+`AUTH_CONFIGURATION_ERROR` and no write; unconfigured identifiers keep the
+provider's normal rejection. Validation follows upstream's identifier validator
+(or absolute URI without a fragment by default); unsupported signing algorithms
+are dropped before insertion.
+
+```ts
+import { authRoutes } from "@aotter/mantle/auth/routes";
+import { authLoader } from "@aotter/mantle/auth";
+const auth = authLoader(() => import("./auth.js").then(m => m.auth));
+const routes = authRoutes(auth, {
+  methods: [{ kind: "email-otp" }],
+  connectedAppsPage: "/admin/connected-apps", // optional; otherwise plain HTML
+});
+// In fetch: await routes(request) ?? otherRoutes(request).
+```
+
+`GET /api/auth/methods` exposes only the supplied method descriptions and does
+not load auth. `basePath` must match Better Auth if changed. Better Auth owns all
+`/api/auth/*` endpoints and RFC 8414/9728 well-known discovery routes. Mount those
+well-known paths at the origin, before a catch-all or proxy; retain the external
+issuer/resource URL and trusted forwarding rules. The SDK handler receives them
+unchanged. A POST registration whose redirect URIs are all HTTP localhost,
+127.0.0.1 or [::1] becomes `application_type: "native"` when omitted; explicit
+types and mixed/external callbacks stay under the SDK's validation.
+
+`/oauth/consent` and `/oauth/consents` serve escaped, script-free English or zh-TW
+HTML. Their `/data` routes serve the 0.2 UI JSON shapes. Consent approval and
+`POST /oauth/consents/revoke` require a live cookie session and same-origin
+mutation; bearer credentials cannot grant or disconnect apps. Consent completion
+uses only the provider-validated signed query and redirect. All responses are
+private/no-store. Connected-app redirects must be same-origin paths.
+
+`resolveCaller(request, loader, { audience, scopes })` verifies token signature,
+issuer, audience and request-bound DPoP through Better Auth, including a durable
+single-use proof reservation. It then checks the live consent and session and
+loads the current database user.
+All of sub, azp, sid, mantle_consent_id and the consent reference must match;
+the consent must cover the resource and every token scope, and the session must
+still be alive. `scopes` adds a resource-specific scope floor (403 when missing).
+Unbound legacy tokens fail closed. Disconnect deletes the grant first, revokes
+its access/refresh tokens. Tokens issued without an active consent fail closed.
+First-party `skip_consent` tokens instead require a live, enabled client with
+`skipConsent` and allowed scopes, plus a live user session. Already-issued
+JWTs fail on the next call, and reconsenting cannot revive the old JWT lineage.
+Database failures remain server errors, rather than silently authenticating.
+
+For app-owned API keys/personal tokens, supply `resolveCredential(request)` in
+`resolveCaller` options. It runs before OAuth/cookies; return a verified user
+Caller or null when absent, and throw when presented but invalid. The same scope
+floor applies. Any non-Bearer/DPoP Authorization header (including Basic from a staging
+gateway), unless handled by the app-owned credential hook, is UNAUTHENTICATED
+and never falls back to a cookie. The application owns credential verification;
+Mantle loads live roles, bans and declared stored fields.
+
+For the 0.2 legacy-DCR cleanup policy, call `pruneLegacyOAuthClients(auth)` from
+an application-owned hourly scheduled job. It deletes only ownerless,
+non-CIMD/non-reference clients older than 90 days; it runs no boot-time work.
+
+When configuring session secondary storage, set `verification.storeInDatabase: true` and `session.storeSessionInDatabase: true`: live grants and durable DPoP single-use reservations must use the database, never a non-atomic session KV cache.
+
+Auth routing also guards Better Auth’s raw `/api/auth/admin/*` endpoints (including percent-encoded admin paths): only a fresh primary-database `admin` cookie session may enter, and mutations require same origin. A stale admin snapshot in session KV cannot bypass demotion, ban or session deletion. App-owned auth mounts can reuse `guardAuthAdminRequest` from `@aotter/mantle/auth/admin` with a resolver that reads current authority.
+
+Use primary database sessions without session secondaryStorage as the simple
+safe configuration. If optional session caching is enabled, use the
+**authority-bound** secondary-storage adapter from the identity/auth template
+(`@aotter/mantle/auth/hardening`, #1499): every snapshot must be checked against the primary session and current
+user before the SDK can read it, including raw SDK endpoints and session lists.
+Arbitrary session KV snapshots are outside this secure configuration: middleware
+may trust stale roles or refresh an expired primary session from a snapshot.
+Merely setting storeSessionInDatabase true does not fix those SDK endpoints.
+Mantle's caller and raw-admin guard validate primary authority before refreshing,
+but do not make arbitrary SDK session caching safe. Keep verification
+consumption and DPoP single-use reservations in the database.

package/docs/handbook/guides/postgres-adapters.md

@@ -0,0 +1,56 @@
+# Application-owned PostgreSQL adapters
+
+Bun.SQL and postgres.js satisfy `Postgres` from `@aotter/mantle/contracts` directly. Other drivers need `unsafe(text, values)` returning a row array with `.count`, and `begin(options, fn)` pinning one connection until the callback resolves and COMMIT succeeds. Preserve native SQLSTATE/severity evidence; generated writes classify uncertain commits.
+
+This node-postgres adapter accepts an app-owned `pg.Pool` through its structural shape:
+
+```ts
+import type { Postgres } from '@aotter/mantle/contracts';
+
+type Connection = {
+  query(text: string, values?: any[]): Promise<{ rows: any[]; rowCount: number | null }>;
+};
+// Pass a node-postgres Pool; its connections and lifetime stay app-owned.
+export function nodePostgres(pool: Connection & {
+  connect(): Promise<Connection & { release(discard?: boolean): void }>;
+}): Postgres {
+  const unsafe = (connection: Connection): Postgres['unsafe'] => async (text, values) => {
+    const result = await connection.query(text, values);
+    return Object.assign(result.rows, { count: result.rowCount });
+  };
+  return {
+    unsafe: unsafe(pool),
+    async begin(options, fn) {
+      if (!/^isolation level (serializable|repeatable read|read committed|read uncommitted)$/.test(options))
+        throw new Error('Unsupported transaction options');
+      const client = await pool.connect();
+      let discard = false;
+      try {
+        await client.query(`BEGIN ${options}`);
+        const tx: Postgres = {
+          unsafe: unsafe(client),
+          begin: async () => { throw new Error('Nested transactions are unsupported'); },
+        };
+        let value;
+        try { value = await fn(tx); }
+        catch (error) {
+          try { await client.query('ROLLBACK'); } catch { discard = true; }
+          throw error;
+        }
+        await client.query('COMMIT');
+        return value;
+      } catch (error) { discard = true; throw error; }
+      finally { client.release(discard); }
+    },
+  };
+}
+```
+
+The pool stays application-owned. There is no automatic retry. A COMMIT connection failure remains an error with its original evidence; the SDK can report `OUTCOME_UNKNOWN`. Adapters without interactive transactions must reject in `begin` before invoking the callback. They cannot run multi-statement Procedures or multi-write batches by independent autocommit calls.
+
+Test on disposable storage with the [adapter conformance corpus](../../source/scripts/postgres-adapter.ts), covering bound date-time/date/JSON text, SELECT and RETURNING timestamp microseconds,
+row arrays/counts, safe and unsafe int8 precision (including int64 extrema), aliased
+selected-page integer/version number-or-string outputs, native numeric text and
+booleans, unique/OCC failures, commit/rollback, nested handles and uncertain outcomes. This is an application-owned adapter, not an additional supported driver. Mantle's supported PostgreSQL drivers are Bun.SQL and postgres.js.
+
+The driver layer is open; [dialects remain postgres and sqlite only](../concepts/runtime-and-adapters.md#drivers-and-dialects).

package/docs/handbook/guides/public-pages.md

@@ -0,0 +1,53 @@
+# Public pages: SEO, AEO and languages
+
+This page is the one list of what a public (anonymous, indexable) page emits. Skills, examples and other pages link
+here instead of repeating it.
+
+## Two ways to serve them
+
+- **Generated `web()`**: list and detail pages straight from public Views, with `llms.txt`, sitemap, Markdown
+  alternates and canonical tags. Its contract and limits are in [surface contracts](../reference/surface.md#optional-web-output);
+  the smallest example is `docs/examples/generated-web`.
+- **App-owned pages** in `src/routes.ts`, when the page needs its own layout, JSON-LD or languages. The reference
+  implementation is `docs/examples/recipes` (`src/pages.ts`, `src/routes.ts`; `smoke.mjs` checks every item below).
+
+## Every public page
+
+- Server-rendered HTML per URL with the content in the body. A client-only SPA shell or metadata set by script is not
+  enough for search or answer engines.
+- `<html lang>`, `<title>`, `<meta name="description">`.
+- `<link rel="canonical">` built from the configured origin (`PUBLIC_ORIGIN`), never from the request `Host`.
+- Open Graph: `og:type`, `og:url` (the canonical), `og:title`, `og:description`, `og:site_name`, `og:locale`
+  (underscore form, `zh_TW`), and `og:image` when the content has an image.
+- Unknown URLs answer 404; drafts and anything a visitor may not read are absent, even when the request carries an
+  admin session (read as an anonymous caller).
+
+## Detail pages
+
+- JSON-LD of the matching schema.org type (`Recipe`, `Article`, `Event`, `Product`, ...), built from the same row as
+  the visible content: `name`, `description`, `url`, `inLanguage`, `datePublished`, `dateModified`, and `image` when
+  there is one (some rich results require it). Escape `<` in the serialized JSON so stored text cannot close the
+  script element. Do not add facts the page does not show.
+- A short answer block for answer engines: one question heading and a one-sentence answer from the row's data.
+- A Markdown alternate at `<url>.md`, linked with `<link rel="alternate" type="text/markdown">`.
+
+## More than one language
+
+- One URL per language (`/{locale}/...`), with `hreflang` alternates for each language the page exists in, plus
+  `x-default`. A language that is not published for this item gets no alternate and its URL is a 404.
+- `og:locale:alternate` for the other languages, and a visible language switcher with `hreflang` and `lang` on links.
+- Per-language Markdown alternates; `llms.txt` lists each language's items.
+
+## Site files
+
+- `/sitemap.xml` with every public URL in every language, walking the complete cursor chain of the list View (the
+  recipes example reads one page of 100 per language and marks the paging as `AGENT:` work).
+- `/robots.txt` with `Disallow: /admin/` and the sitemap URL.
+- `/llms.txt` ([llmstxt.org](https://llmstxt.org)): a title, a one-line summary and a link to each item's Markdown
+  alternate.
+
+## Check before you report done
+
+Request the HTML without running JavaScript and check the items above; publish, edit and unpublish an item and check
+that its page, Markdown, sitemap and `llms.txt` follow. The `mantle` skill's
+`references/local-testing.md` covers running this against `wrangler dev`.

package/docs/handbook/guides/size-and-startup.md

@@ -0,0 +1,9 @@
+# Size and startup
+
+The SDK ships kernel, CLI, generator and private compiler together. Request modules do not import compiler code. Import only selected generated operations and bindings; direct operations can omit Store/Admin/auth entirely.
+
+Workers use `mantle bundle` to emit split ESM. Keep Better Auth behind `authLoader(() => import(...))`; the startup graph guard rejects eager auth imports. The official MCP SDK and selected Admin operations load on matching requests. Generated module imports perform no SQL or kernel initialization; Store metadata initializes on first use without SQL.
+
+Contributor checks use tracked fixtures to compare runtime/startup graphs against `size-budgets.json` and inspect the published allowlist in `check:package`. Package packed/unpacked bytes are reported separately from request startup and query costs. Do not infer latency from bundle bytes.
+
+Cloudflare startup_time_ms needs an actual upload/deployment; offline dry runs do not measure it. Measure on the selected host and report first use and warm work separately. Applications own deployment authorization and resources.

package/docs/handbook/guides/typed-queries.md

@@ -1,26 +1,20 @@
 ---
-description: Read and write through the typed Store from handlers and service code, call named Views, and choose between ctx.store, runtime.store and runtime.store.as(caller).
+description: Choose Store for writes and simple lookups; declare internal Views for richer reads.
 ---
 # Query from TypeScript
 
-Handler and service code reach Mantle-owned rows only through Store. The
-generated `.mantle/generated/mantle.ts` types it over your Schemas and Views:
-`ctx.store` in a `MantleHandlers` handler is its `CallerStore`, while
-`runtime.store` is the untyped `MantleStore` until you cast it to the
-generated `Store`.
+| Work | Data path |
+| --- | --- |
+| Writes | Store `insert` / `update` / `delete`, atomic `batch`, supported `transaction`, or declared Procedures |
+| Id lookup or simple AND filter | Store `findById` / `find` / `first`, inside handlers or an existing application |
+| Joins, aggregates, OR, reusable reads | Internal View: manifest SQL that is reviewable and typed |
 
-| Store | Where | Scope |
-|---|---|---|
-| `ctx.store` | inside a `ref` handler | bound to the invocation's caller. A guard or a before hook gets a read-only one |
-| `runtime.store.as(caller)` | service code that has resolved a caller | that caller |
-| `runtime.store` | trusted host code (imports, maintenance) | none: no caller scope. TTL still applies |
-
-Each one applies TTL visibility, and published-only on public Views. Only
-`runtime.store` skips caller scope, so never hand it a request's input
-unchecked.
+Never write raw SQL to Mantle collections: it bypasses scope, TTL, publishing and system-column rules. The Store applies row rules but does not check a View's or Procedure's `requires`; authorize your handler before using it.
 
 ## Declare an internal View
 
+Save this as `manifests/tickets.yaml`:
+
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
@@ -49,107 +43,50 @@ spec:
     properties:
       ticketState: { type: string, enum: [open, closed] }
   sql: |
-    SELECT id, subject, ticketState FROM tickets
+    SELECT id, subject, ticketState AS "ticketState" FROM tickets
     WHERE ticketState = input.ticketState
-    ORDER BY created_at DESC LIMIT 50
+    ORDER BY id ASC
 ```
 
-`internal` keeps the View off REST, MCP and Admin. It is still in the plan and
-the typed Store. It is not a security bypass: a `requires` on it is checked
-for the caller the Store is bound to.
-
-## Call it
+Generate with `mantle generate cloudflare-d1 generated manifests/tickets.yaml`.
+An internal View has no public REST route or MCP tool. Its generated function still applies declared authorization and compiled row policy.
 
 ```ts
-import type { MantleHandlers } from "../.mantle/generated/mantle.js";
-
-export const handlers: MantleHandlers = {
-  closeStale: async (_input, ctx) => {
-    const { rows, nextCursor } = await ctx.store.view("tickets-by-state", { input: { ticketState: "open" }, limit: 20 });
-    // rows: { id: unknown; subject: string | null; ticketState: "open" | "closed" | null }[]
-    return { open: rows.length, more: nextCursor !== undefined };
-  },
-};
+import { store } from './generated/generated.js';
+import ticketsByState from './generated/views/tickets-by-state.js';
+import type { Caller } from '@aotter/mantle/contracts';
+
+export async function readTickets(db: Parameters<typeof store>[0], caller: Caller) {
+  const tickets = store(db, caller).collection('tickets');
+  const first = await tickets.first({ where: { ticketstate: 'open' } });
+  const rows = await ticketsByState(db, caller, { ticketState: 'open' });
+  return { first, rows };
+}
 ```
 
-The View name, its `input` and its row type are checked by `tsc`. A staff View
-with `uiSchema.list.searchFields` or `filterFields` also takes `search` and
-`filters` (`ctx.store.view(name, { search: "refund", filters: { ticketState: "open" } })`);
-Store refuses a filter the View does not declare. An output that reads a
-Schema field unchanged has that field's type, `created_at` and `updated_at`
-are `string | null`, and an expression, or another native column such as `id`,
-is `unknown`. Page with `limit` (default 50, at most 500) and the opaque
-`cursor` from `nextCursor`.
+The app supplies a verified Caller and its existing native handle. External input needs boundary validation. Store rows, filters and writes use storage names (`ticketstate`, `created_at`); View aliases use the SQL output names.
 
-## `select` and `write`
+## Store reads and writes
 
-For a query that needs no declared View, `select` takes a JSON query over one
-Schema:
+`find` returns `{ rows, cursor }` (null cursor on the last page), with limits 1–500 and opaque keyset cursors. `where` combines fields with AND; `orderBy` selects a generated indexed column with `id` ties. Most order columns must be NOT NULL; publishing `published_at` supports nulls. For a proved pageable internal View, import `paged/views/<encoded-name>.ts` and call `(db, caller, input, { limit?, cursor? })`. Other internal Views retain their bare row-array function.
 
-```ts
-const { rows } = await ctx.store.select({
-  from: "tickets",
-  columns: ["id", "subject"],
-  where: { ticketState: "open", subject: { like: "%refund%" } },
-  orderBy: { updatedAt: "desc" },
-  limit: 20,
-});
-```
+Store keeps `find({ search: 'text' })`, `first({ search: 'text' })` and `count(where?)`. Search matches exact id or declared searchable fields under the same row policy.
 
-- `where`: `{ column: value }` is equality and sibling keys are AND; also
-  `{ column: { eq, ne, gt, gte, lt, lte, like, in, notIn, isNull } }`, and
-  `and`, `or`, `not`. `in` takes a list or `{ select, from, where }`.
-- `orderBy`: one column; `id` breaks ties. Default `{ updatedAt: "desc" }`.
-- `search`: text matched against `searchableFields` (and `id`).
-- Native columns are camelCase here (`createdAt`, `authorId`), while SQL spells
-  them snake_case (`created_at`).
+`count` scans every matching row. For large tables or frequently shown totals, use an internal View with indexed predicates or avoid exact totals; a View's aggregate still scans the matching rows.
 
-`write` applies every operation or none, in order:
+Store search, Admin list search and Views using `mantle.search` share the same dialect search. SQLite/D1 use FTS5 trigram for queries of 3 or more characters, and LIKE for shorter queries. PostgreSQL uses ILIKE over the declared fields, which scans by default. A View does not make PostgreSQL search faster. For large PostgreSQL tables, the application's agent adds trigram indexes in a migration; ILIKE then uses them with no code change:
 
-```ts
-await ctx.store.write([
-  { update: "tickets", set: { ticketState: "closed" }, where: { id }, lock: expectedVersion },
-  { insert: "ticket-events", values: { ticketId: id, kind: "closed" } },
-]);
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE INDEX articles_title_trgm ON articles USING gin (title gin_trgm_ops);
 ```
 
-- `insert` with `values`, optional client `id` (`ctx.store.id()`) and
-  `onConflict: "ignore" | { columns, update }`. A scoped Schema refuses a
-  client `id`, because a chosen id could collide with another owner's row and
-  reveal it: give such rows a field of your own that is unique with the scope
-  field (`uniqueIndexes: [[owner, clientKey]]`) when other rows of the same
-  write must point at them, or when a retry must find them.
-- `update` with `set` and `where`; `delete` with `where`. A `where` that pins
-  `id` is a row op: it may carry `lock` (the version the caller saw), and
-  writing no row is `CONFLICT`.
-- A result is `{ id, version }` for a row op and `{ affected }` for a set op.
-- `set` and `values` never name the scope field or a native column (except
-  `status` on a `publishing` Schema, below); Store
-  fills them. A `null` leaves empty, or clears, a field the Schema does not
-  require (the generated `values` and `set` types accept it); for a required
-  field it is refused. On a `publishing` Schema, `set: { status }` is how a `ref`
-  handler publishes, unpublishes or archives.
-
-Failures throw `DiagnosticError` with `INPUT_VALIDATION_FAILED` (including a
-failed `check`), `CONFLICT` (`conflict.reason` is `lock`, `expect` or
-`unique`, and `conflict.opIndex` names the operation; for `unique` it is
-present when exactly one operation of the write targets the violated Schema,
-since the engine names the table and not the statement), `RESOURCE_UNAVAILABLE`
-or `OUTCOME_UNKNOWN`. Nothing is written on any failure. After
-`OUTCOME_UNKNOWN`, retry with the same client ids and locks: a replayed insert
-conflicts on its id, a replayed update on its lock.
-
-## From service code
-
-The service's `fetch` receives the runtime. Resolve the caller first, as the
-generated `withCaller` does, and bind Store to it:
+Index each searched field as needed and inspect EXPLAIN for the workload. Case folding follows the engine.
 
-```ts
-const caller = await resolveCaller(request);
-if (!("caller" in caller)) return new Response("unauthorized", { status: 401 });
-const { rows } = await runtime.store.as(caller.caller).view("tickets-by-state", { input: { ticketState: "open" } });
-```
+Writes are lazy and execute once when awaited. Insert/update return native rows; delete returns void. `update(id, set, { lock })` and `delete(id, { lock })` require the version the caller reviewed. A stale lock, excluded row or unique clash is `CONFLICT`. `batch` atomically executes unused Writes from one Store in input order; a step cannot use a prior result.
+
+Interactive `transaction(async tx => …)` exists on bun:sqlite and PostgreSQL, with collections, Views and Procedures bound to the transaction. D1 supports batches only. PostgreSQL defaults to serializable, with an explicit isolation override; SQLite uses BEGIN IMMEDIATE. Use `tx` inside the callback, not the outer Store or handle. Nested transactions and `tx.batch` are refused; there is no automatic retry.
+
+Ref handlers receive `{ caller, db, store }` bound to the same Caller and transaction. Implement the generated `Handlers` interface and pass it to `store(db, caller, { handlers })`. Direct Procedure modules expose SQL Procedures; ref Procedures are reached through the bound Store or selected surfaces.
 
-To run a Procedure from service code, with its auth, guard and validation, call
-`runtime.invokeProcedure({ procedure, input, caller, cause: { kind: "internal", id } })`.
-Inside a handler, `ctx.invoke(name, input)` does the same and keeps the caller.
+See [native execution](native-execution.md) for values and write outcomes and [migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations) before changing a Schema.

package/docs/handbook/navigation.json

@@ -4,66 +4,200 @@
     {
       "text": "Start here",
       "items": [
-        { "text": "Handbook overview", "link": "/start/overview" },
-        { "text": "Quickstart: a service on Workers", "link": "/start/quickstart-worker" },
-        { "text": "Project layout and CLI", "link": "/start/project-and-cli" }
+        {
+          "text": "Handbook overview",
+          "link": "/start/overview"
+        },
+        {
+          "text": "Quickstart: a service on Workers",
+          "link": "/start/quickstart-worker"
+        },
+        {
+          "text": "Project layout and CLI",
+          "link": "/start/project-and-cli"
+        }
       ]
     },
     {
       "text": "Task guides",
       "items": [
-        { "text": "Agent installation and handoff", "link": "/guides/agent-setup" },
-        { "text": "Query from TypeScript", "link": "/guides/typed-queries" },
-        { "text": "Customize Admin from manifests", "link": "/guides/admin-ui" }
+        {
+          "text": "Agent installation and handoff",
+          "link": "/guides/agent-setup"
+        },
+        {
+          "text": "Query from TypeScript",
+          "link": "/guides/typed-queries"
+        },
+        {
+          "text": "Public pages: SEO, AEO and languages",
+          "link": "/guides/public-pages"
+        },
+        {
+          "text": "Native Admin",
+          "link": "/guides/native-admin"
+        },
+        {
+          "text": "Customize Admin",
+          "link": "/guides/admin-ui"
+        },
+        {
+          "text": "Extend Admin",
+          "link": "/guides/admin-extensions"
+        },
+        {
+          "text": "Another host or engine",
+          "link": "/guides/adapter-guide"
+        },
+        {
+          "text": "Native execution",
+          "link": "/guides/native-execution"
+        },
+        {
+          "text": "PostgreSQL adapters",
+          "link": "/guides/postgres-adapters"
+        },
+        {
+          "text": "OAuth and consent",
+          "link": "/guides/oauth"
+        },
+        {
+          "text": "Transactional email",
+          "link": "/guides/email"
+        },
+        {
+          "text": "MCP Apps",
+          "link": "/guides/mcp-apps"
+        },
+        {
+          "text": "Size and startup",
+          "link": "/guides/size-and-startup"
+        }
       ]
     },
     {
       "text": "Concepts",
       "items": [
-        { "text": "The four atoms", "link": "/concepts/four-atoms" },
-        { "text": "Lifecycle and locales", "link": "/concepts/lifecycle-and-locales" },
-        { "text": "Reads: Views, REST and MCP", "link": "/concepts/views" },
-        { "text": "Writes: Procedures, Triggers and hooks", "link": "/concepts/procedures-and-triggers" },
-        { "text": "Authorization", "link": "/concepts/authorization" },
-        { "text": "MCP and agents", "link": "/concepts/mcp-and-agents" },
-        { "text": "Runtime, Store and dialects", "link": "/concepts/runtime-and-adapters" }
+        {
+          "text": "The four atoms",
+          "link": "/concepts/four-atoms"
+        },
+        {
+          "text": "Lifecycle and locales",
+          "link": "/concepts/lifecycle-and-locales"
+        },
+        {
+          "text": "Reads: Views, REST and MCP",
+          "link": "/concepts/views"
+        },
+        {
+          "text": "Writes: Procedures and Triggers",
+          "link": "/concepts/procedures-and-triggers"
+        },
+        {
+          "text": "Authorization",
+          "link": "/concepts/authorization"
+        },
+        {
+          "text": "MCP and agents",
+          "link": "/concepts/mcp-and-agents"
+        },
+        {
+          "text": "Runtime, Store and dialects",
+          "link": "/concepts/runtime-and-adapters"
+        }
       ]
     },
     {
       "text": "Reference",
       "items": [
-        { "text": "Manifest feature table", "link": "/reference/features" },
-        { "text": "Manifest envelope", "link": "/reference/manifest" },
-        { "text": "Schema", "link": "/reference/schema" },
-        { "text": "View", "link": "/reference/view" },
-        { "text": "Procedure", "link": "/reference/procedure" },
-        { "text": "Trigger", "link": "/reference/trigger" },
-        { "text": "Authorization requirements", "link": "/reference/authorization" },
-        { "text": "Site defaults and site_config", "link": "/reference/site-config" },
-        { "text": "Diagnostic codes", "link": "/reference/diagnostics" },
-        { "text": "HTTP, MCP, CLI and packages", "link": "/reference/surface" }
+        {
+          "text": "Manifest feature table",
+          "link": "/reference/features"
+        },
+        {
+          "text": "Manifest envelope",
+          "link": "/reference/manifest"
+        },
+        {
+          "text": "Schema",
+          "link": "/reference/schema"
+        },
+        {
+          "text": "View",
+          "link": "/reference/view"
+        },
+        {
+          "text": "Procedure",
+          "link": "/reference/procedure"
+        },
+        {
+          "text": "Trigger",
+          "link": "/reference/trigger"
+        },
+        {
+          "text": "Authorization requirements",
+          "link": "/reference/authorization"
+        },
+        {
+          "text": "Site defaults and site_config",
+          "link": "/reference/site-config"
+        },
+        {
+          "text": "Diagnostic codes",
+          "link": "/reference/diagnostics"
+        },
+        {
+          "text": "HTTP, MCP, CLI and packages",
+          "link": "/reference/surface"
+        },
+        {
+          "text": "Generated Admin descriptors",
+          "link": "/reference/admin-descriptors"
+        }
       ]
     },
     {
       "text": "Cloudflare",
       "items": [
-        { "text": "The service and its entry", "link": "/cloudflare/service-entry" },
-        { "text": "Authentication", "link": "/cloudflare/authentication" },
-        { "text": "Media uploads with R2", "link": "/cloudflare/media-r2" },
-        { "text": "Deploy and operate", "link": "/cloudflare/deploy-and-operate" },
-        { "text": "Mantle on ChatGPT Sites", "link": "/cloudflare/chatgpt-sites" }
+        {
+          "text": "The service and its entry",
+          "link": "/cloudflare/service-entry"
+        },
+        {
+          "text": "Authentication",
+          "link": "/cloudflare/authentication"
+        },
+        {
+          "text": "Media uploads with R2",
+          "link": "/cloudflare/media-r2"
+        },
+        {
+          "text": "Deploy and operate",
+          "link": "/cloudflare/deploy-and-operate"
+        },
+        {
+          "text": "Mantle on ChatGPT Sites",
+          "link": "/cloudflare/chatgpt-sites"
+        }
       ]
     },
     {
       "text": "Examples",
       "items": [
-        { "text": "Examples", "link": "/examples/hub" }
+        {
+          "text": "Examples",
+          "link": "/examples/hub"
+        }
       ]
     },
     {
       "text": "Releases",
       "items": [
-        { "text": "Releases", "link": "/releases/index" }
+        {
+          "text": "Releases",
+          "link": "/releases/index"
+        }
       ]
     }
   ]