@aotter/mantle 0.1.2-alpha.6 → 0.1.2-rc.1

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

@@ -0,0 +1,75 @@
+---
+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/concepts/authorization.md

@@ -3,7 +3,7 @@ description: One authorization pipeline for REST, MCP and Admin — identity kin
 ---
 # Authorization
 
-Mantle has one authorization pipeline. A manifest HTTP Trigger, a View over REST, an MCP `tools/call` and an Admin operation all reach the same evaluator, so a rule written once holds on every surface. This page explains the model; the exact `requires` grammar is in the [authorization reference](../reference/authorization.md), and a worked ladder of four access levels is in [Guarded API access](../examples/guarded-api.md).
+Mantle has one authorization pipeline. A manifest HTTP Trigger, a View over REST, an MCP `tools/call` and an Admin operation all reach the same evaluator, so a rule written once holds on every surface. This page explains the model; the exact `requires` grammar is in the [authorization reference](../reference/authorization.md), and a worked ladder of four access levels is in [Guarded API access](../../examples/cf-primitives-guarded-api.md).
 
 ## The fixed order
 
@@ -104,7 +104,7 @@ An MCP `tools/call` runs the identical evaluator, in the identical order, with t
 ## Related
 
 - [Authorization requirements](../reference/authorization.md) — the `requires` shape, predicate forms, guard rules, OpenAPI projection.
-- [Guarded API access](../examples/guarded-api.md) — a full resolver, guards and the REST/MCP outcome tables.
+- [Guarded API access](../../examples/cf-primitives-guarded-api.md) — a full resolver, guards and the REST/MCP outcome tables.
 - [Reads: Views, REST and MCP](./views.md) — the `$ctx.user` identity-View sentinel.
 - [Authentication](../cloudflare/authentication.md) — sessions, first owner, role management routes.
 

package/docs/handbook/concepts/four-atoms.md

@@ -26,9 +26,9 @@ The consequence for authors: a Procedure that has no Trigger is unreachable from
 
 ## The composition rule
 
-Anything more domain-shaped than these four is not an atom. A Form, Membership, Email, Webhook, Workflow or ScheduledJob is a composition of Schemas, Views, Procedures and Triggers plus your own TypeScript. An earlier iteration of this grammar shipped eleven domain-shaped kinds; authors could not decide whether a contact form was a Form, a Workflow or an Email, and each kind grew to subsume its neighbors.
+Anything more domain-shaped than these four is not an atom. A Form, Membership, Email, Webhook, Workflow or ScheduledJob is a composition of Schemas, Views, Procedures and Triggers plus your own TypeScript. A fifth kind would recreate the same overlap: authors would have to decide whether a contact form was a Form, a Workflow or an Email.
 
-If you find yourself wanting a fifth kind, sketch the same thing as a composition of the four first. Almost always it works.
+If you find yourself wanting another kind, sketch the same thing as a composition of the four first. Almost always it works.
 
 ## The Manifest envelope
 

package/docs/handbook/concepts/lifecycle-and-locales.md

@@ -129,7 +129,7 @@ The parent holds what every language shares and stays non-localized. The child s
 
 When you keep parallel locale rows in step, translate display strings only. Field names, option values, step identifiers and result keys must stay identical across locales, or the same View and the same MCP tool stop describing the same thing.
 
-The full worked version of this pattern, with a locale-parameterized public View and its REST response, is [Publication](../examples/publication.md).
+The full worked version of this pattern, with a locale-parameterized public View and its REST response, is [Publication](../../examples/builtin-publication.md).
 
 ## Source
 

package/docs/handbook/concepts/mcp-and-agents.md

@@ -33,7 +33,7 @@ Procedures are never exposed on their own. A Procedure becomes a tool only throu
 
 ## The OAuth model
 
-The Cloudflare adapter runs one Better Auth 1.7 instance for staff identity, authorization, consent, client registration and MCP resource verification. Client identity is CIMD-first — the MCP 2026-07-28 Client ID Metadata Document profile, which is why the Worker needs the `global_fetch_strictly_public` flag to fetch client metadata across the public Internet boundary — with unauthenticated legacy DCR kept only as a bounded compatibility path for older clients, on the previous provider's 90-day default lifetime. One non-colon scope, `mcp`, is advertised in `scopes_supported`, because clients such as claude.ai reject colon-shaped scopes; per-surface enforcement then happens server-side, not through scope strings. Authorization is session-bound: the JWT's originating Better Auth session must still exist and be unexpired, so signing out of Admin also ends that session's MCP access, and a refresh token is not an independent authorization. Unauthenticated requests to either mount answer `401` with a `WWW-Authenticate` challenge pointing at the RFC 9728 protected-resource metadata document served under the auth mount. Authorization endpoints live under `/api/auth/oauth2/*` and are discovered from the advertised metadata, never hard-coded.
+The Cloudflare adapter runs one Better Auth 1.7 instance for staff identity, authorization, consent, client registration and MCP resource verification. Client identity is CIMD-first — the MCP 2026-07-28 Client ID Metadata Document profile, which is why the Worker needs the `global_fetch_strictly_public` flag to fetch client metadata across the public Internet boundary. Unauthenticated Dynamic Client Registration remains available as a bounded path with a 90-day default lifetime for clients that do not present CIMD. One non-colon scope, `mcp`, is advertised in `scopes_supported`, because clients such as claude.ai reject colon-shaped scopes; per-surface enforcement then happens server-side, not through scope strings. Authorization is session-bound: the JWT's originating Better Auth session must still exist and be unexpired, so signing out of Admin also ends that session's MCP access, and a refresh token is not an independent authorization. Unauthenticated requests to either mount answer `401` with a `WWW-Authenticate` challenge pointing at the RFC 9728 protected-resource metadata document served under the auth mount. Authorization endpoints live under `/api/auth/oauth2/*` and are discovered from the advertised metadata, never hard-coded.
 
 ## Connecting a local client
 

package/docs/handbook/concepts/procedures-and-triggers.md

@@ -209,7 +209,7 @@ What each piece is doing:
 - `submittedAt` is stamped by the runtime, so it is absent from the Procedure input and from Staff MCP authoring tools.
 - Adding `{ kind: mcp, surface: public }` as a fourth Trigger would publish the same Procedure as an agent tool without touching a handler.
 
-Register the two `ref` keys in the project's handlers map, then run the check loop from [Project layout and the CLI loop](../start/project-and-cli.md). The complete version with real Turnstile and email handlers is [Intake form](../examples/intake-form.md).
+Register the two `ref` keys in the project's handlers map, then run the check loop from [Project layout and the CLI loop](../start/project-and-cli.md). The complete version with real Turnstile and email handlers is [Intake Turnstile and email hooks](../../examples/cf-primitives-intake-hooks.md). The Builder-safe Manifest without those hooks is [Intake form](../../examples/builtin-intake.md).
 
 ## Source
 

package/docs/handbook/concepts/views.md

@@ -47,7 +47,7 @@ A View can filter to the calling user's own rows with the closed sentinel `{ "$c
 2. The View must require a signed-in user: `ctx.user` in `requires.auth.all` — otherwise `VIEW_FILTER_CTX_USER_REF_REQUIRES_AUTH`.
 3. The compared field must be the leftmost field of a declared index on the source Schema — otherwise `VIEW_FILTER_CTX_USER_REF_REQUIRES_INDEX`.
 
-This is a filter, not a row-level policy engine. `requires` authorizes the whole query; it does not inject per-row visibility predicates. Membership, payment and entitlement checks belong in a guard Procedure. See [Procurement approvals](../examples/procurement-approvals.md).
+This is a filter, not a row-level policy engine. `requires` authorizes the whole query; it does not inject per-row visibility predicates. Membership, payment and entitlement checks belong in a guard Procedure. See [Procurement approvals](../../examples/builtin-procurement.md).
 
 ## Shared response cache
 
@@ -176,7 +176,7 @@ spec:
   limit: 200
 ```
 
-`tags` is an array property, so `json_each` unnests it and one request appears once per tag. The runtime wraps the whole statement as a subquery before applying pagination, which is why Admin's search and filters attach to the SQL output aliases — `tag` is a real filterable column even though no Schema property is named `tag`. See [Commerce and settlement](../examples/commerce-transaction.md) for the same technique over order lines.
+`tags` is an array property, so `json_each` unnests it and one request appears once per tag. The runtime wraps the whole statement as a subquery before applying pagination, which is why Admin's search and filters attach to the SQL output aliases — `tag` is a real filterable column even though no Schema property is named `tag`. See [Commerce inventory](../../examples/cf-primitives-commerce-inventory.md) for the same technique over order lines.
 
 ## Source