@jimhoyd/urlcode 0.4.2 → 0.4.7

package/llms-full.txt

@@ -1,16 +1,17 @@
 <!-- Generated by scripts/build-llms-full.ts (npm run docs:llms). Do not edit; edit the source documents. -->
-<!-- Consolidated URLCode authoring reference: 16 documents, about 52,118 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 57,753 tokens (estimate: characters / 4). -->
 
+<!-- urlcode-current-version:start -->
 # URLCode
 
 > A portable runtime for programmable URL behavior, and the framework that grows
 > from it: routes in YAML, functions and middleware, then accounts, administration and
 > stored links as operator-installed extensions. Stable project format
-> `version: "1"`. Core is Apache-2.0; this revision is `0.4.0-alpha.2`, which makes
-> `function`/`middleware` routes trusted by default with `sandbox: true` as the
-> per-route opt-in; `0.4.0-alpha.1` is the newest alpha published to npm, on top of
-> the `0.3.0` release. The auth, admin and ui extension packages are on npm as
-> `0.1.0-alpha.x`, source-complete, review pending.
+> `version: "1"`. Core is Apache-2.0; this revision is `0.4.7`. `function`/`middleware`
+> routes are trusted by default with `sandbox: true` as the per-route opt-in. The
+> auth, admin and ui extension packages in this repository are versioned at the same
+> revision; confirm what is published with `npm run release:status`.
+<!-- urlcode-current-version:end -->
 
 Use the schema and docs from the runtime revision you run. Do not assume Node
 or fetch inside a `sandbox: true` function, regex routes, database access,
@@ -59,10 +60,12 @@ claim here is implemented in the linked repository; nothing is roadmap.
 | `@jimhoyd/urlcode-auth` | [`packages/auth`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth) | Accounts: password, passkeys, OpenID Connect, email codes, TOTP, recovery, sessions, roles, registration modes, account page, operator CLI | `extensions.auth` plus an `/account/*` mount and `policies.extensions.auth` on protected routes |
 | `@jimhoyd/urlcode-admin` | [`packages/admin`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
 
-All four are Apache-2.0. The `0.4.1` release line aligns their stable versions;
-check `npm run release:status` for publication progress. A stable npm channel is
-not an independent assessment: review, deployment evidence and an accessibility
-assessment are still pending
+All four are Apache-2.0. Each package's npm `latest` tag identifies its stable
+version. The current publisher records the exact four-package stack tested
+together on each new GitHub release and attaches the same information in signed
+`train.json` metadata.
+A stable npm channel is not an independent assessment: review, deployment
+evidence and an accessibility assessment are still pending
 ([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)). Their status
 files say exactly what is built: [auth](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/IMPLEMENTATION-STATUS.md),
 [admin](https://github.com/jimhoyd-com/urlcode/blob/main/packages/admin/IMPLEMENTATION-STATUS.md),
@@ -115,11 +118,12 @@ exact requirement.
 
 ### The composition contract
 
-After the aligned `0.4.1` packages are published, an extended project starts
-with the packages and one command:
+An extended project starts from the current stable packages and one command.
+`--save-exact` records the concrete versions selected from the independent
+`latest` channels:
 
 ```sh
-npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
+npm install --save-exact @jimhoyd/urlcode@latest @jimhoyd/urlcode-ui@latest @jimhoyd/urlcode-auth@latest @jimhoyd/urlcode-admin@latest
 urlcode init my-site --with ui,auth,admin
 ```
 
@@ -178,12 +182,22 @@ export default {
 };
 ```
 
-Auth and admin already render their screens through `ui.kit` when the host
-supplies the UI extension; their package-owned templates and catalogues must be
-registered with that kit. Without it, both retain shared primitive rendering
-through `presentation`. The example above uses that primitive fallback. The UI
-block is optional, and a migration to the kit is not unfinished framework work.
-See each package README for its complete kit registration example.
+Auth and admin render every screen through `ui.kit`; their package-owned
+templates and catalogues must be registered with that kit. Both refuse
+activation when the UI extension is absent or has not activated first. See each
+package README for the complete registration example; the scaffold generated by
+`urlcode init --with ui,auth,admin` wires the same composition.
+
+Treat that composition as one application with package ownership boundaries,
+not as three separate user interfaces. Keep identity, session and recovery
+behavior in auth and authorization, freshness, auditing and mutations in admin.
+Apply product differences through the installed extensions' declared authoring
+surfaces, in this order: configuration and theme, copy, a component or screen
+template, stylesheet, then a supported hook. Create another extension only for
+a reusable capability those surfaces cannot express. `urlcode extensions`
+and the MCP `get_extensions` tool report those surfaces and their fast checks,
+so people and agents can discover the supported path instead of replacing
+package behavior.
 
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
@@ -220,6 +234,12 @@ These are the facts that keep generated projects valid. The full matrix is in
   Function and middleware `source` fields do name project modules. Extensions are
   logical names; the host file chooses the implementation. There is no
   `--extension` flag, no `import` in YAML, no interpolation.
+- **Build one product through declared authoring surfaces.** Inspect extension
+  authoring metadata before generating code. Prefer configuration/theme, copy,
+  the smallest template override, stylesheet and supported hooks, in that
+  order. Add an extension only for a reusable missing capability. Run the
+  reported fast checks while iterating and the full repository checks before
+  handoff.
 - **One handler per route.** `redirect`, `respond`, `page`, `static`, `download`,
   `function`, `proxy`, `conditional` or `extension`, plus optional
   `middleware`. Paths are exact or single-segment `{param}`; `/*` only on
@@ -258,7 +278,7 @@ These are the facts that keep generated projects valid. The full matrix is in
 | Add accounts | [auth README](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/README.md), [auth security](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/SECURITY.md) |
 | Add administration | [admin README](https://github.com/jimhoyd-com/urlcode/blob/main/packages/admin/README.md) |
 | Restyle every page | [ui README](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui/README.md), [ui contract](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui/CONTRACT.md) |
-| Write an extension | [extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md), [extension model review](https://github.com/jimhoyd-com/urlcode/blob/main/docs/archive/2026-09-19/SPIKE-EXTENSION-MODEL.md) |
+| Write an extension | [extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md) |
 | Run it | [operations](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPERATIONS.md), [install](https://github.com/jimhoyd-com/urlcode/blob/main/docs/INSTALL.md), [deployment checks](https://github.com/jimhoyd-com/urlcode/blob/main/docs/DEPLOYMENT-CHECKS.md) |
 
 ---
@@ -267,12 +287,29 @@ These are the facts that keep generated projects valid. The full matrix is in
 
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/AI-AUTHORING.md
 
-Use this as project-authoring context. It describes the implemented source contract, including unreleased additions after 0.3.0,
+Use this as project-authoring context. It describes the implemented source contract, including additions since 0.3.0,
 not a general server framework. Runtime/schema/docs
 must come from the same reviewed revision. The runtime is Apache-2.0; a
 project you generate carries whatever license its owner chooses, so do not
 add one to it automatically.
 
+### First step: one bounded query
+
+Make the first retrieval one bounded query: the MCP tool `get_context` when the
+`urlcode` server is registered, otherwise `urlcode context --project DIR` (add
+`--budget N` when context is scarce). Then retrieve only what the task needs:
+`urlcode capabilities NAME` (MCP `get_capability`) for one capability's limits,
+`get_schema` for one YAML fragment, `urlcode recipes search TEXT`
+(`search_recipes`), `explain` for a route's effective behavior and, when the
+operator supplies a host file, `get_extensions`. Context is a summary with the
+constraints and exact commands, not a schema dump, and it never hides a
+capability limit: ask `capabilities NAME` before promising a feature.
+
+The complete catalogs (`urlcode capabilities`, `recipes list`), the compact
+[llms.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms.txt) index and the generated [llms-full.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms-full.txt)
+stay available as deliberate fallback and reference, not as the opening move.
+The reading order below is for that reference use.
+
 ### Declarative-first default
 
 > Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
@@ -316,18 +353,31 @@ as evidence, and the rules on grants and secrets. Assistants that load skills
 find the same loop in `skills/urlcode/SKILL.md` inside the installed package; it
 teaches how to retrieve the minimum reference through `urlcode capabilities`,
 `urlcode recipes list|show` and `urlcode validate --local` rather than reading
-the documentation whole. Neither file replaces the schema; both defer to it.
+the documentation whole. For a host-composed application, `get_extensions`
+adds each extension's schemas, hooks, supported authoring surfaces and fast
+checks. Agents should use those surfaces before generating replacement package
+behavior. Neither file replaces the schema; both defer to it.
+
+Treat core, installed extensions and product UI as one application with
+different owners. Keep auth/admin security and workflow behavior package-owned;
+keep branding, product navigation and the smallest necessary overrides in the
+project. When a React frontend contains `components.json`, use the installed
+official shadcn/ui skill for component discovery, composition, accessibility
+and semantic Tailwind styling: start with `shadcn info --json`, then use its
+documentation/search flow or configured MCP registry before generating a
+component. The server template kit is shadcn-compatible but does not accept
+React components. See the official [shadcn/ui skills guide](https://ui.shadcn.com/docs/skills).
 
 ### Authoring workflow
 
-Run `urlcode context --project ./my-links` first. It prints, in a few hundred
-tokens, the runtime and schema version, what the project already uses, the
+Start with the bounded query above. It prints the runtime and schema version, what the project already uses, the
 constraints that hold for every project, which targets refuse this project's
 features and the exact validate, test and audit commands with the intentional
 route count filled in. It is derived from the compiled project and the
 capability catalog, never from prose, so prefer it to re-reading the
 documentation; add `--budget N` when context is scarce and `--json` for
-tooling. The same data is available from the MCP tool `get_context`.
+tooling. Its size grows with the project (about a thousand estimated tokens for
+the starter, a few thousand for the cookbook), not with the framework.
 
 - Inspect the existing entry point, included files, functions, tests and pinned
   runtime. Preserve the user's organization and unrelated routes.
@@ -361,6 +411,26 @@ Use the intentional actual count, not always 2. Runtime checkout users can repla
 External bindings require an already reviewed policy; add `--policy` where needed.
 The benchmark operates locally; it is not a load test of an external deployment.
 
+### Feedback from real authoring work
+
+The authoring loop is also a source of roadmap evidence. After completing a
+real task, an assistant should make a feedback **draft** only when a concrete
+attempt exposes a capability gap, repeated framework workaround,
+documentation/discovery gap, or suspected defect. One-off product logic is not
+framework feedback.
+
+The draft must name the installed runtime version and requested target, then
+include a sanitized route/YAML fragment, the exact validation or test
+observation, the smallest expected behavior, and a proposed fixture. It must
+not include secrets, customer URLs, raw application source, or unsupported
+claims inferred from a failed attempt.
+
+Search [existing URLCode issues](https://github.com/jimhoyd-com/urlcode/issues)
+before proposing a new one and identify a likely duplicate when found. An agent
+may present a draft issue or comment for review, but must never create or update
+a GitHub issue without the user's explicit approval. Feedback is evidence for a
+maintainer to review; it is not a promise that the public contract will grow.
+
 ### Capability matrix: do not hallucinate these features
 
 | Available | Unavailable or future |
@@ -406,11 +476,49 @@ declared route at the same path still wins. Count its generated routes in
 `--expect-routes`. `site.sitemap` needs `--origin` at every command that
 activates the project; see [site conventions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md).
 
+### Built-in features by task
+
+Before writing a function, check whether a declarative feature already covers the
+need. Security headers are the usual miss: a project that declares nothing sends
+only the runtime's defaults (`nosniff`, `no-store`, a request ID).
+
+| I need | Declare | Reference |
+|---|---|---|
+| Security headers (CSP, HSTS, frame and referrer policy) | `policies.security: {headers: oshp}` or `policies.profile: hardened` | [security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/security.md) |
+| Cache headers on a page, download or static mount | `cacheControl`: `no-cache` (default), `no-store`, `public, max-age=3600` or `public, max-age=31536000, immutable`; nothing else validates | [assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/assets.md) |
+| A cache strategy on any route | `policies.cache` | [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md) |
+| Body size, required body, content types, JSON syntax and shape | `request.body.maxBytes`, `required`, `contentTypes`, `format`, `schema` | [HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md#body-schema-and-input-patterns) |
+| A uuid path id or a bounded string pattern | parameter `schema: {type: string, format: uuid}` or `pattern` with `maxLength` | [HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md#body-schema-and-input-patterns) |
+| Method gating | `methods` (default GET/HEAD; 405 with `Allow`) | [HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md) |
+| Rate limits, bot and crawler denial, compression | `policies.throttle`, `agents`, `compression` | [policies](https://github.com/jimhoyd-com/urlcode/blob/main/docs/POLICIES.md) |
+| Static JSON or text and fixed headers | `respond`, `response.headers` | [HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md) |
+| robots, sitemap, favicon, security.txt, llms.txt | top-level `site` | [site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md) |
+
+Which handler serves the response:
+
+| The response is | Handler | Recipe |
+|---|---|---|
+| Fixed text or JSON | `respond` | `health-page` |
+| A short HTML snippet | `respond` `text` plus `response.headers` `Content-Type: text/html; charset=utf-8` | [HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md) |
+| One HTML file | `page` | `static-page` |
+| A directory of files | `static` | `static-plus-api` |
+| An attachment | `download` | `protected-download` |
+
+Data persistence has no native handler. The operator-installed `store` extension
+serves declared collections as a CRUD API, and `urlcode recipes search "crud store
+persist"` finds the `store-crud` recipe. It needs the operator to install
+`@jimhoyd/urlcode-store` (on npm) and a host file. `init --with
+ui,auth,store` scaffolds one from the published packages; a no-auth
+`--with store` needs `--ack store:public-write`, which only a core release after the
+store's first publication has, so say so rather than promising it. Report anything beyond that recipe (filtering, sorting, per-record
+ownership, a database) as a gap. `urlcode context` lists the same built-ins so
+they are visible before you write code.
+
 ### Agent skills
 
 This repository ships two agent skills, each a thin trigger pointing at the
-docs that are the actual source of truth, so there is one place to keep
-current rather than two:
+version-matched CLI/schema and documentation bundle that are the actual source
+of truth, so there is one place to keep current rather than two:
 
 - [`urlcode-authoring`](https://github.com/jimhoyd-com/urlcode/blob/main/.claude/skills/urlcode-authoring/SKILL.md) — this
   guide, the schema and the reference. It loads the capability limits and the
@@ -431,7 +539,10 @@ Three ways to get either, all pinned to a runtime revision:
 - **npm.** The published package includes both skill directories. Copy the
   one(s) you want into your project's `.claude/skills/` to pin guidance to the
   same revision as the runtime you installed; a skill inside `node_modules` is
-  not discovered on its own.
+  not discovered on its own. The npm archive keeps `llms-full.txt` as its one
+  offline prose bundle instead of duplicating the repository's `docs/` tree;
+  use the CLI for structured queries and search that bundle by document heading
+  when more explanation is needed.
 - **Plugin marketplace.** `.claude-plugin/marketplace.json` publishes the
   `packaging/claude-plugin` distribution from this repository, carrying both
   skills. Add the marketplace by its Git URL and install the `urlcode` plugin.
@@ -441,7 +552,7 @@ Three ways to get either, all pinned to a runtime revision:
 
 `npm run docs:plugin` regenerates the plugin distribution from both skills;
 `npm run check` fails if it is stale or if either skill names a documentation
-path this revision does not ship.
+path that does not exist in this revision.
 ### Bounded authoring tools
 
 Before generating a common route by hand, search the bundled catalog:
@@ -536,7 +647,11 @@ under `advisories` with "consider whether this route needs `sandbox: true`".
 This is a nudge to look, the same advisory spirit as the rest of `audit`'s
 non-blocking findings — it never fails the check, never sets `ready: false`
 and never infers the actual answer; setting `sandboxReason` (with `sandbox`
-either `true` or `false`) or `sandbox: true` is enough to silence it.
+either `true` or `false`) or `sandbox: true` is enough to silence it. The
+advisory prints the exact line to add. Anything that touches the filesystem
+(a persistent app writing files, for example) must be a trusted route,
+because a sandbox has no filesystem: declare `sandboxReason` with the default
+`sandbox: false` and say why it is trusted, as the `static-plus-api` recipe does.
 
 The same judgment call applies to a project-level lifecycle hook an
 extension invokes (`onSignUp`, `beforeRegister` and the like) — it is
@@ -611,10 +726,12 @@ programmatic compatibility analysis and provider verification limits.
 
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-GUIDE.md
 
-This guide targets URLCode 0.3.0. Start with the function example below,
+<!-- urlcode-current-version:start -->
+This guide targets URLCode 0.4.7. Start with the function example below,
 then add only the fields your route needs. The authoritative machine-readable
 shape is [JSON Schema](https://github.com/jimhoyd-com/urlcode/blob/main/schemas/urlcode.schema.json); semantic rules are in the
 [specification](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPECIFICATION.md). Unsupported fields fail validation.
+<!-- urlcode-current-version:end -->
 
 ### Run all the examples
 
@@ -694,6 +811,8 @@ schema-valid combinations activate successfully.
 | `routes.*.enabled` | boolean | no | — |
 | `routes.*.sandbox` | boolean | no | default: false |
 | `routes.*.sandboxReason` | string | no | maxLength: 500 |
+| `routes.*.coveredElsewhere` | object | no | minProperties: 1 |
+| `routes.*.coveredElsewhere.*` | string | no | minLength: 1; maxLength: 500 |
 | `routes.*.expires` | string | no | — |
 | `routes.*.description` | string | no | maxLength: 1024 |
 | `routes.*.parameters` | array | no | maxItems: 64 |
@@ -711,6 +830,8 @@ schema-valid combinations activate successfully.
 | `routes.*.parameters[].schema.maxLength` | integer | no | minimum: 0; maximum: 8192 |
 | `routes.*.parameters[].schema.minimum` | number | no | — |
 | `routes.*.parameters[].schema.maximum` | number | no | — |
+| `routes.*.parameters[].schema.pattern` | string | no | minLength: 1; maxLength: 128 |
+| `routes.*.parameters[].schema.format` | string | no | enum: ["uuid"] |
 | `routes.*.parameters[].schema.items` | object | no | unknown keys rejected |
 | `routes.*.parameters[].schema.items.type` | string | yes | enum: ["string","integer","number","boolean"] |
 | `routes.*.parameters[].schema.maxItems` | integer | no | minimum: 0; maximum: 100 |
@@ -771,6 +892,7 @@ schema-valid combinations activate successfully.
 | `routes.*.request.body.contentTypes` | array | no | minItems: 1; maxItems: 16; uniqueItems: true |
 | `routes.*.request.body.contentTypes[]` | string | no | pattern: "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$" |
 | `routes.*.request.body.format` | string | no | enum: ["text","json"] |
+| `routes.*.request.body.schema` | object | no | — |
 | `routes.*.response` | object | no | unknown keys rejected |
 | `routes.*.response.headers` | object | no | maxProperties: 64 |
 | `routes.*.response.headers.*` | one of the shapes below | no | — |
@@ -951,6 +1073,7 @@ schema-valid combinations activate successfully.
 | `routes.*.cache.maxBytes` | integer | no | minimum: 0; maximum: 16777216 |
 | `routes.*.cache.maxEntries` | integer | no | minimum: 1; maximum: 1000000 |
 | `routes.*.cache.force` | boolean | no | default: false |
+| `routes.*.use` | string | no | pattern: "^[a-z][a-z0-9-]{0,63}$" |
 | `includes` | array | no | maxItems: 256; uniqueItems: true |
 | `includes[]` | string | no | maxLength: 1024 |
 | `policies` | object | no | unknown keys rejected |
@@ -1115,10 +1238,27 @@ schema-valid combinations activate successfully.
 | `site.securityTxt.encryption` | array | no | maxItems: 64 |
 | `site.securityTxt.encryption[]` | string | no | minLength: 1; maxLength: 2048 |
 | `site.llms` | string | no | minLength: 1; maxLength: 1024 |
+| `site.notFound` | string | no | minLength: 1; maxLength: 1024; pattern: "\\.[hH][tT][mM][lL]?$" |
 | `extensions` | object | no | maxProperties: 16 |
 | `extensions.*` | object | no | unknown keys rejected |
 | `extensions.*.version` | constant | yes | const: "1" |
 | `extensions.*.config` | object | yes | — |
+| `shared` | object | no | maxProperties: 32 |
+| `shared.*` | object | no | unknown keys rejected |
+| `shared.*.request` | object | no | unknown keys rejected |
+| `shared.*.request.body` | object | no | unknown keys rejected |
+| `shared.*.request.body.required` | boolean | no | — |
+| `shared.*.request.body.maxBytes` | integer | no | minimum: 0; maximum: 1048576 |
+| `shared.*.request.body.contentTypes` | array | no | minItems: 1; maxItems: 16; uniqueItems: true |
+| `shared.*.request.body.contentTypes[]` | string | no | pattern: "^[a-z0-9!#$&^_.+-]+/[a-z0-9!#$&^_.+-]+$" |
+| `shared.*.request.body.format` | string | no | enum: ["text","json"] |
+| `shared.*.request.body.schema` | object | no | — |
+| `shared.*.response` | object | no | unknown keys rejected |
+| `shared.*.response.headers` | object | no | maxProperties: 64 |
+| `shared.*.response.headers.*` | one of the shapes below | no | — |
+| `shared.*.response.headers.* (option 1)` | string | no | maxLength: 4096 |
+| `shared.*.response.headers.* (option 2)` | array | no | minItems: 1; maxItems: 16 |
+| `shared.*.response.headers.* (option 2)[]` | string | no | maxLength: 4096 |
 
 ---
 
@@ -1127,7 +1267,7 @@ schema-valid combinations activate successfully.
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPECIFICATION.md
 
 This document and [JSON Schema](https://github.com/jimhoyd-com/urlcode/blob/main/schemas/urlcode.schema.json) describe
-the source contract, including unreleased additions after 0.3.0.
+the source contract, including additions since 0.3.0.
 `version: "1"` remains the project-format contract. Unsupported fields
 are rejected rather than interpreted as future behavior.
 
@@ -1232,6 +1372,31 @@ Routes accept `request.body` validation and `response.headers` overrides. The
 See [HTTP configuration](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md) for the exact supported fields, precedence,
 security restrictions and examples.
 
+### Shared blocks
+
+An optional top-level `shared` map (entry `urlcode.yaml` only; at most 32 names
+matching `^[a-z][a-z0-9-]{0,63}$`) holds named `request` and `response.headers`
+blocks. A route selects one with `use: <name>`. This is the reuse mechanism;
+anchors, aliases and merge keys stay rejected. Rules:
+
+- A route's own `request` (or `response`) key replaces the shared block's key as
+  a whole. There is no deep merge, so a reviewer never reconstructs a header set
+  from two places.
+- Resolution happens at load time, before the route hash, `audit`, `routes` and
+  every compiler run. The resolved route carries no `use`, and changing a shared
+  block changes the hash of exactly the routes that select it.
+- An unknown name fails validation, as does a shared block whose
+  `response.headers` name a header the runtime owns (the same set a route may
+  not set). Included files may `use` names from the entry file but may not
+  declare `shared`. Per-route rules, such as the asset-handler header limits,
+  still apply to the resolved route.
+- Only `request` and `response.headers` are shareable. `sandbox`,
+  `sandboxReason`, `policies` and other route defaults are deliberately left
+  out for now, so each trust decision stays on its route.
+- No cross-file or remote reuse of blocks.
+
+See the [shared-blocks example](https://github.com/jimhoyd-com/urlcode/blob/main/examples/shared-blocks/README.md).
+
 ### Policies
 
 Optional top-level `policies` and `profiles` keys, and `routes.<path>.policies`,
@@ -1254,8 +1419,11 @@ Duplicate scalar query/header inputs return 400. Required missing inputs return
 400; defaults apply only to absent inputs. Empty strings are present values.
 
 Supported validation: `type`, scalar `enum`, `default`, string `minLength`/
-`maxLength`, numeric `minimum`/`maximum`, query array `items` and `maxItems`.
-Regular-expression patterns, structured bodies, cookies, nested inputs and
+`maxLength`, string `format: uuid` and a bounded `pattern` ([restrictions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md#body-schema-and-input-patterns)),
+numeric `minimum`/`maximum`, query array `items` and `maxItems`. JSON bodies are
+validated by `request.body.schema`, not by a parameter (a failure answers 422, as JSON
+when the client explicitly accepts `application/json` and otherwise as text; see
+[HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md#body-schema-and-input-patterns)). Cookies, nested inputs and
 OpenAPI `style`/`explode` fields are not implemented. This uses a documented
 OpenAPI-like input subset; it is not an OpenAPI document or full JSON Schema
 input vocabulary. String limits are at most 8,192 characters.
@@ -1328,6 +1496,16 @@ entry may likewise be a string, normalized to `{source: <string>}`. Only the
 long form exists after loading, so `routes`, `audit`, `explain`, revision hashes
 and the field reference describe the expansion.
 
+Auto-binding belongs to the string form only. The long form (`source`, and
+therefore any `export:`) is taken as written: URLCode does not add `args` or
+path `parameters` to it, so a route like `/api/todos/{id}` with
+`function: {source: ..., export: get}` must declare the `id` parameter under
+`parameters` and map it under `args` by hand, as the example above does. A
+function has one `source` and one `export` per route; to serve several methods
+on one path, branch on `request.method` inside the function, or declare one
+route per method where the path allows it. A `methods:` map of per-method
+functions is not implemented.
+
 ES modules only. `.mjs` is loaded as ESM in both modes. A `sandbox: true` route
 also reads `.js` as ESM independently of Node package settings, but a trusted
 route imports `.js` through Node's own loader, so an ESM `.js` module needs the
@@ -1646,6 +1824,7 @@ status or default `Cache-Control: no-store` on functions/redirects.
 | `request.body.maxBytes` | 0–1048576; tighter per-route budget, enforced while reading fixed/chunked bodies; 413 on overflow |
 | `request.body.contentTypes` | Exact lowercase MIME essences for nonempty bodies; parameters ignored; mismatch/missing type returns 415 |
 | `request.body.format` | `text`: validate UTF-8; `json`: validate UTF-8, JSON media type and JSON syntax; malformed input returns 400 |
+| `request.body.schema` | Requires `format: json`. A JSON Schema subset checked after parsing; a body that breaks it returns 422 (see below) |
 
 The operator request limit remains an upper bound; YAML cannot raise it. A route
 without body policy keeps the existing server limit. A configured body policy
@@ -1685,12 +1864,76 @@ cache and disposition on its own handler. Asset metadata cannot be overridden by
 `response.headers`. On functions/declared responses, Content-Type may be configured;
 JSON declarations require a JSON type. No response header secret interpolation.
 
+#### Body schema and input patterns
+
+`request.body.schema` accepts `type` (`object`, `array`, `string`, `integer`,
+`number`, `boolean`, `null`), `properties`, `required`, `additionalProperties`
+(true or false), `items`, scalar `enum`, `minLength`/`maxLength`, `pattern`,
+`format: uuid`, `minimum`/`maximum` and `minItems`/`maxItems`. Anything else,
+including `$ref`, `oneOf` and `default`, fails activation. A schema is limited to
+6 levels, 128 nodes and 64 properties per object. It is checked by the runtime
+itself, so it behaves the same on every host and is not compiled from author
+code.
+
+A failing body answers **422** as `text/plain`: `Request body failed validation`
+then one line per failure, at most 8, each naming only a path the schema
+declared (`/title must be a string`). Array positions print as `[]`. Nothing the
+client sent is echoed, in line with the fixed-words rule for runtime errors.
+Malformed JSON stays 400 and a wrong media type 415.
+
+A client that sends `Accept: application/json` gets the same failures as
+`application/json` instead (the server and the Cloudflare Worker agree):
+
+```json
+{"error":"body_validation_failed","message":"Request body failed validation","issues":[{"pointer":"/title","keyword":"maxLength","message":"must be at most 8 characters","expected":8}]}
+```
+
+Each issue carries `pointer` (RFC 6901, built only from names the schema
+declared; array positions are `/[]`, not an index; the root is `""`), `keyword`
+(`type`, `enum`, `required`, `additionalProperties`, `minLength`, `maxLength`,
+`format`, `pattern`, `minimum`, `maximum`, `minItems` or `maxItems`), the fixed
+`message`, and where the schema states one, `expected` (the type, bound, format
+or, for `enum`, up to 16 short declared values) or `property` (the missing name
+from `required`). The offending value is never included, because it may hold a
+secret. At most 8 issues are listed and the body is capped at 4096 bytes;
+when trailing issues are dropped to fit, `"truncated":true` is added.
+
+Negotiation is deliberately conservative: JSON is sent only when the Accept
+header names `application/json` explicitly with `q` above 0 and no higher `q` for
+an explicit `text/plain`. A missing header, `*/*`, `application/*`, browsers'
+default Accept and a malformed `q` keep the plain-text answer. The status is 422
+either way and the same checks run before any function or sandbox code.
+
+Parameter schemas (path, query, header) also accept `format: uuid` and `pattern`
+on string inputs, rejecting a mismatch with 400. `pattern` runs on every request
+in the host process, so it is restricted: 1 to 128 characters, `maxLength` of at
+most 128 on the same schema, no group repeated by `*`, `+` or `{n,}`, no
+lookaround, no backreference and at most three unbounded quantifiers. That
+restriction is conservative, not a proof of linear time. It is what stands
+between an author regex and a backtracking stall, so prefer `format` or `enum`
+when either fits.
+
 `respond` is an additional native handler (exactly one handler per route):
 
 - `status`: 200–599, default 200; 206 and 304 are reserved for native asset semantics.
 - `text`: literal UTF-8 body, default content type text/plain.
 - `json`: any JSON-compatible YAML value, serialized with application/json.
 - Omit both for an empty body; declaring both fails. Body limit is 1 MiB.
+- A short HTML answer is `text` plus a declared content type. There is no
+  `respond.html`; use the `page` handler for anything larger than a snippet:
+
+  ```yaml
+  /:
+    respond:
+      text: "<!doctype html><h1>Hello</h1>"
+    response:
+      headers:
+        Content-Type: text/html; charset=utf-8
+  ```
+
+  The body is served verbatim and the default `nosniff` and `no-store` still
+  apply. Under the `oshp` security profile the CSP (`default-src 'self'`) blocks
+  inline `<script>` and `<style>`, so keep the snippet to markup.
 - Status 204/205 cannot declare a nonempty body. HEAD always suppresses the body.
 
 Functions still return their own Response/status/body. YAML header policy does
@@ -1960,10 +2203,8 @@ compiled and the request path is unchanged. Each policy has its own page:
 | `compression` | [compression](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/compression.md) | `Accept-Encoding` negotiation; assets precompressed at snapshot time |
 | `cache` | [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md) | Named strategies from RFC 9111/5861/8246/9213 plus an origin memory cache |
 
-The design and the reasoning behind each choice are in the
-[extensions spike](https://github.com/jimhoyd-com/urlcode/blob/main/docs/archive/2026-09-19/SPIKE-EXTENSIONS.md). Operators who need behavior the
-declarative block cannot express pass host [plugins](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PLUGINS.md) in code; plugins
-are never named in YAML.
+Operators who need behavior the declarative block cannot express pass host
+[plugins](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PLUGINS.md) in code; plugins are never named in YAML.
 
 ### Declaring policies
 
@@ -2182,6 +2423,7 @@ site:
     policy: [https://example.com/security-policy]
     preferredLanguages: [en, fr]
   llms: llms.txt
+  notFound: public/404.html
 routes:
   /: {page: {file: public/index.html}}
 ```
@@ -2291,9 +2533,30 @@ refused).
 A project-relative text file served as a `page` route with
 `text/plain; charset=utf-8` and the default `no-cache`.
 
+#### `notFound` → `/404.html`
+
+A project-relative `.html`/`.htm` file that answers a request matching no
+route. It becomes a `page` route at `/404.html` (`text/html; charset=utf-8`,
+`Cache-Control: no-store`); the runtime serves that page with status **404**
+for an unmatched `GET` or `HEAD`, with the same project security headers and
+`nosniff` as the built-in 404. Other methods keep the plain-text `Not found`.
+A route that matches but is disabled, mismatched by `match:` or denied by a
+policy keeps its own answer; only "no route matched" uses the page.
+
+`/404.html` is also reachable directly and answers 200 (the same as on static
+hosting, which is why the path is fixed). It is one generated route in the
+`routes`/`audit` counts and `explain` reports it as `site.notFound`; the
+sitemap leaves it out. A route you declare at `/404.html` wins and is served
+as the not-found page instead. The page answers every unknown URL, so it cannot depend on the path requested.
+
+`urlcode build --target static` writes it as the object `404.html` (see
+[static hosting](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STATIC.md)); point the host's error document at that key.
+Cloudflare refuses it like any `page` route (no asset binding); the Worker
+has no per-request fallback page, so use the platform's own 404 asset there.
+
 ### Per-target support
 
-| Target | `robots`, `sitemap`, `securityTxt` (`respond`) | `favicon`, `llms` (`page`) |
+| Target | `robots`, `sitemap`, `securityTxt` (`respond`) | `favicon`, `llms`, `notFound` (`page`) |
 | --- | --- | --- |
 | self-hosted, Vercel, AWS | served | served |
 | Cloudflare | compiled into the artifact (`build --origin` for absolute URLs) | refused at build time like any `page` route: the target has no asset binding; serve them from the platform's static assets |
@@ -2532,6 +2795,10 @@ and management API. That package has since been retired and unpublished, so no
 supported stored-link extension ships today. Core no longer has a native `link`
 handler or a `dynamicLinks` project flag.
 
+The `store` extension is the data-owning counterpart: it serves declared,
+bounded collections as a CRUD API from an operator-owned directory. See
+[data store](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STORE.md).
+
 A project declares versioned configuration and exclusive route mounts:
 
 ```yaml
@@ -2746,7 +3013,11 @@ The UI extension exposes `transformView`, a synchronous filter called before a
 named kit template renders. It receives `{template, view}` and returns the view
 model to render. Use copy, templates, theme and CSS for ordinary presentation
 changes; use this hook for project-specific computed view data that those
-declarative layers cannot express.
+declarative layers cannot express. It also exposes `transformPage`, called
+before the shared layout renders. It receives the editable title, layout,
+navigation, account menu and flash message and returns those page fields. This
+lets a product join auth/admin screens to its own shell without replacing their
+security or workflow behavior. Both filters are synchronous and trusted.
 
 ### Building an extension
 
@@ -2758,11 +3029,15 @@ An extension package should export a registration factory and, when it supports
 2. Publishes every project hook through `hooks` and reuses
    `extensionHooksSchema` plus `loadExtensionHooks`; it does not implement its
    own path resolver or dynamic-import cache.
-3. Activates all configuration, files, services and hooks before serving a
+3. Publishes an `authoring` contract listing its supported project-owned
+   configuration, theme/copy, component/template, stylesheet and hook surfaces,
+   plus focused `fastChecks`. Keep descriptions concrete enough that an agent
+   can choose a supported surface instead of copying package behavior.
+4. Activates all configuration, files, services and hooks before serving a
    request. Invalid or stale configuration fails activation.
-4. Returns `handle` for mounts and optionally `authorize`/`middleware` for route
+5. Returns `handle` for mounts and optionally `authorize`/`middleware` for route
    policies. It closes resources it owns.
-5. Keeps credentials, storage and provider setup in the operator host. Project
+6. Keeps credentials, storage and provider setup in the operator host. Project
    YAML contains logical configuration and project-relative hook references.
 
 Consumers install the package, declare its YAML block and mounts/policies, and
@@ -2774,7 +3049,7 @@ See [Composing a site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/COM
 ### Discovering schemas
 
 Each registration carries the JSON Schemas that validate its `config` block and
-its per-route policy requirements, plus its hook contracts. `urlcode extensions` prints them together with
+its per-route policy requirements, plus its hook and authoring contracts. `urlcode extensions` prints them together with
 the project's own declarations so an author can see what a mount accepts:
 
 ```sh
@@ -2783,7 +3058,8 @@ urlcode extensions --project ./site --host-file /absolute/operator/host.mjs [--j
 
 For every registration in the host file it reports the name, contract version,
 targets, credential headers, configuration schema, policy schema (if any),
-declared hook names, kinds, descriptions and input/output schemas,
+declared hook names, kinds, descriptions and input/output schemas, supported
+authoring surfaces and their fast checks,
 whether the project declares it, whether its `projectSha256` matches the current
 revision, the routes that mount it and the routes whose policies require it.
 Declared names the host does not register are listed as unregistered. The command
@@ -2856,7 +3132,27 @@ in memory (core zeroes `Uint8Array` contents after writing or on failure). The
 types are exported from `@jimhoyd/urlcode` for packages that want to typecheck
 against them.
 
-Assembly rules, in `--with` order:
+`--with` is an unordered set. Core sorts the requested names before calling
+each `scaffold` (so `names` is the same for every spelling), then orders the
+results from the optional declarative fields on `ScaffoldResult`:
+
+- `provides`: capability names the extension offers (for example `ui.kit`);
+  a capability must not equal an extension name.
+- `requires`: extensions or capabilities that must be in the set and are
+  placed before this extension. A missing one refuses, naming both.
+- `after`: the same ordering, without requiring presence.
+- `conflicts`: extensions or capabilities that must not be in the set.
+- Risky-scaffold acknowledgements are one generic channel, not a flag per risk. The operator repeats `--ack <extension>:<id>` (both parts lowercase letters, digits and hyphens, for example `store:public-write`); core validates the syntax, de-duplicates and sorts the values and hands them to every scaffold as the opaque `ScaffoldRequest.acknowledgements` (always present, possibly empty). An extension reads only ids qualified with its own name. To require one it throws an `Error` whose message states the risk and that carries `acknowledgement: '<name>:<id>'`; core appends the exact re-run command (the same `--with`, `--pin` and `--no-manifest`, plus every `--ack` already given and the new one), so an agent meets the acknowledgement only when it reaches that risk and never needs it in advance. A scaffold that used one lists it in `ScaffoldResult.acknowledged`; core refuses any `--ack` that no scaffold listed (a typo, an extension not in `--with`, or an unneeded value), before anything is written, and refuses a scaffold that lists an id it was not given or that is not its own. Acknowledgements are never written to project YAML; they are visible in command history, and the extension should state the resulting model in its generated README. `routeNotes` (single-line strings) are written as comments above that extension's routes; core renders them and infers no policy. Core adds no per-extension flag or result field: a new risk needs only a new id in the extension that owns it. `--allow-public-write` was a store-specific predecessor of this channel; it was never in a published core release and is removed rather than aliased (see [store](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STORE.md)).
+
+Core topologically orders by these, taking the lexically smallest ready
+extension first, so every permutation of the same set produces the same host,
+`urlcode.yaml` activation order and README. A cycle or a missing requirement or
+conflict refuses before anything is written, naming the extensions involved.
+Core never adds an extension (auth or ui) and never infers security policy
+from the set. Host setup should be self-contained (own identifiers, such as
+`storeProjectSha256`) unless it declares `requires` for what it references.
+
+Assembly rules, in the resolved order:
 
 - Every package is resolved and every `scaffold` is called before anything is
   written. A name that is not installed refuses with the `npm install` command;
@@ -2870,7 +3166,7 @@ Assembly rules, in `--with` order:
   naming both sources.
 - `host.mjs` is all `hostImports`, then all `hostSetup` lines, then an
   `extensions` array of every `hostEntries` item, then `close()` running the
-  `hostClose` statements in reverse `--with` order so later entries release
+  `hostClose` statements in reverse resolved order so later entries release
   before what they built on. Setup lines share one module scope: admin's entry
   references the `service`, `csrfKey` and `projectSha256` identifiers that
   auth's setup defines, which is why `names` carries the full list.
@@ -2973,8 +3269,10 @@ through the kit and refuse to activate without their own templates present.
 
 #### Supported combinations
 
-`--with` order is the activation order, and the kit must be active before
-anything that renders through it.
+`--with` is an unordered set. Core derives the activation order from each
+extension's declared requirements, so the kit is active before anything that
+renders through it, whatever order you name them in. A missing requirement
+(for example admin without auth) refuses before anything is written.
 
 | `--with` | Result |
 |---|---|
@@ -2984,6 +3282,8 @@ anything that renders through it.
 | `auth` or `auth,admin` | Refused: the scaffold names the missing `ui`. |
 | `auth,admin,ui` | Refused: `ui` must come before the extensions it renders. |
 | `admin` without `auth` | Refused: admin reuses auth's service, CSRF key and revision. |
+| `ui,auth,store` | Todo API and CRUD screen, both protected by `auth: true`. |
+| `store` or `ui,store` | Refused: the writable mount would be public. Add `auth`, or re-run the printed command with `--ack store:public-write` for a documented public-write scaffold; core rejects any `--ack` no scaffold consumed, such as one with auth composed or `store` absent. |
 
 Every refusal happens before anything is written, and leaves no directory
 behind. There is no auth-without-ui or admin-without-ui configuration in this
@@ -3054,12 +3354,20 @@ middleware, and the host-file trust boundary.
 The `ui` config's `copy`, `templates` and `stylesheet` paths point at the
 project's own directories. Nothing here forks a package.
 
+Treat the result as one application. Auth and admin keep ownership of sessions,
+CSRF, permissions, validation and mutations; the project owns its brand,
+product navigation and the smallest presentation differences it needs. Inspect
+`urlcode extensions --host-file ... --json` (MCP: `get_extensions`) and follow
+each registration's `authoring.surfaces` before copying package code.
+
 | Override | File | Effect |
 |---|---|---|
 | Wording and translation | `ui/copy/<locale>.json` | Replaces catalogue ids, including ids the auth and admin packages own. Listed in `languages`. |
 | A whole screen | `ui/templates/<name>.html` | Shadows a kit or extension template of that name, for example `ui/templates/auth/sign-in.html` or `ui/templates/admin/dashboard.html`. |
 | Styling | `ui/extra.css` | Appended after the kit stylesheet; `{file, replace: true}` replaces it instead. |
 | Colours, logo, favicon, radius, font | the `theme` block | Declarative; no file needed. |
+| Computed view data | `extensions.ui.config.hooks.transformView` | Adds project data before a named template renders. |
+| Product shell and navigation | `extensions.ui.config.hooks.transformPage` | Changes title, layout, navigation, account menu or flash before the shared layout renders. |
 
 A template is data in the kit's own language. It cannot add a script, change
 what a form validates, or change what a page sends in headers — so an override
@@ -3105,6 +3413,13 @@ not run it. With the packages named:
 generated README with the flag already set. `@jimhoyd/urlcode-ui` depends on
 neither peer; the operator names them.
 
+Run the extension's published `fastChecks` while editing. Theme and copy changes
+need no framework build. Template and CSS checks load only the UI kit and named
+namespaces; the full runtime validation and request suite remain the final
+evidence. A React product frontend with `components.json` should also install
+and follow the official shadcn/ui skill. The server template kit uses compatible
+tokens but does not accept React components.
+
 Overrides of extension templates and of extension-owned catalogue ids reach
 the rendered screens, which is what the regression test below asserts.