@jimhoyd/urlcode 0.4.1 → 0.4.6

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,663 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.6`. `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,13 +647,18 @@ 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
-first-party project code with the same trusted-by-default rule and the same
-`sandbox: true` opt-in as any `function`/`middleware` route, no special
-case. See [EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks).
+first-party project code with the same trusted-by-default rule as a
+`function`/`middleware` route. Extension hook contract v1 is trusted-only;
+`sandbox: true` is rejected rather than silently ignored. See
+[EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks).
 
 Guest TypeScript needs `build-typescript --project SOURCE --out NEW_DIRECTORY`
 before serving. Only the emitted `.js`/`.mjs` executes, in QuickJS for a
@@ -561,7 +677,7 @@ origin grants pinned to the project revision. These are self-hosted features;
 providers refuse them. Signals are bounded best effort with drops, no retries
 or persistence. Never turn a user request into an implicit network grant.
 
-Before using a feature, ask `urlcode capabilities <name>` for its constraints, grants and target support and `urlcode schema <path>` for only that YAML fragment (MCP: `get_capability`, `get_schema`), instead of guessing.
+Before using a feature, ask `urlcode capabilities <name>` for its constraints, grants and target support and `urlcode schema <path>` for only that YAML fragment (MCP: `get_capability`, `get_schema`), instead of guessing. For an installed extension, use `urlcode extensions --host-file ... --json` or MCP `get_extensions`; its hook contracts include the accepted names, purpose and input/output schemas. Prefer extension configuration and UI copy/templates/theme/CSS, then a declared project hook, and only then a new extension or fork.
 The [tooling SDK and stdio MCP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md) inspect, validate, explain and preview
 without guest execution, environment reads or writes. Run `urlcode explain /route`
 to check effective methods, policies and cache outcome, and `urlcode manifest`
@@ -610,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.6. 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
 
@@ -693,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 |
@@ -710,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 |
@@ -770,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 | — |
@@ -950,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 |
@@ -1114,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 |
 
 ---
 
@@ -1126,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.
 
@@ -1231,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`,
@@ -1253,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.
@@ -1327,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
@@ -1645,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
@@ -1684,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
@@ -1959,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
 
@@ -2181,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}}
 ```
@@ -2290,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 |
@@ -2531,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
@@ -2702,29 +2970,18 @@ Node adapter conformance is not a live-provider deployment claim.
 
 ### Project-level lifecycle hooks
 
-`authorize` and `middleware` let core call *into* an extension. They do not
-let a project hand its own code *to* an extension to run at a defined point.
-That gap matters once an extension has meaningful lifecycle events —
-registration, deletion, an administrative action, a link resolution, and so
-on. Presentation already has a standard layering mechanism for this: a
-project customizes an extension's *look* through `urlcode-ui`'s
-`copy`/`extra.css`/`templates` without forking it. Behavior needs the same
-standard, or every extension author (and every project depending on one)
-either reinvents it or forks the extension. `urlcode-auth` and
-`urlcode-admin` independently hit this gap (auth/#35, admin/#32); auth's own
-[SPIKE-AUTH.md](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/docs/SPIKE-AUTH.md)
-already scoped a shape for `onSignUp`/`beforeRegister`/`onDelete`.
-
-**The pattern.** An extension with lifecycle events an author judges worth
-exposing should let the project name its own function in the extension's own
-`config`, using the same source shape `function`/`middleware` routes already
-use (a string path, or `{source, export, args}` — `schemas/urlcode.schema.json`),
-and add its own `sandbox` boolean next to it (below). The extension's own
-`activate()` reads that config, and its own runtime dispatch — not a new core
-primitive, an ordinary call the extension package makes with the request
-context it already has — invokes the named function at the lifecycle point
-it defines, with a typed input and a typed verdict the extension's own
-schema documents. For example, an auth-style extension might declare:
+Extensions expose project customization points through the core hook primitive.
+Each registration publishes `hooks`, a machine-readable list containing the
+hook name, whether it is a value-transforming `filter` or side-effect `action`,
+its description and its input/output JSON Schemas. The extension embeds
+`extensionHooksSchema(contracts)` in its configuration schema and calls
+`loadExtensionHooks(config.hooks, contracts, context)` during activation.
+Core then enforces the common source/export shape, project-root confinement,
+known names, eager module/export validation, input/output schemas and reload
+cache busting. Hook entry bytes participate in the project revision, so editing
+a hook invalidates the operator's extension pin.
+
+Projects select those declared hooks in the extension's own configuration:
 
 ```yaml
 extensions:
@@ -2740,76 +2997,59 @@ extensions:
 ```
 
 with `beforeRegister` called before an account is created, given a typed
-`{email, traits}`-shaped input and returning a typed verdict (`{allow: true}`
+`{email, profile?}` input and returning a typed verdict (`{allow: true}`
 or `{allow: false, reason}`), and `onSignUp` called after, for side effects
-such as provisioning a workspace. The exact hook names, input/verdict shapes
-and invocation points are the extension's own design — `hooks` is not a core
-schema key — but the source/export/sandbox shape, and the fact that this is
-project code the extension calls rather than an operator callback in
-`host.mjs`, should be consistent across extensions so an author who has
-learned one has learned the pattern.
-
-**Trust and execution mode.** Project-level lifecycle hooks are first-party
-project code, the same category as any `function`/`middleware` route, and
-follow the same trusted-by-default rule with no special case
-(docs/SPIKE-DEFAULT-TRUST-MODEL.md, [FUNCTION-SECURITY.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)):
-trusted, in-process execution by default; a project sets `sandbox: true` on
-a given hook to opt that hook into isolated QuickJS/WASM execution, exactly
-the mechanism `function`/`middleware` routes already use and for the same
-reason — the hook's own code, not the trustworthiness of whatever triggered
-it, is what calls for isolation (docs/AI-AUTHORING.md's "Deciding when a
-route needs `sandbox: true`"). This was raised as an open question — whether
-a lifecycle hook should always run sandboxed because it makes a
-security-relevant decision — and settled the other way: uniformity with the
-rest of the trust model was chosen over hardwiring isolation for lifecycle
-hooks specifically, the same "no special case" call already made between
-`function` and `middleware` trust. A `beforeRegister` hook enforcing "only
-`@acme.com` may register" is the project's own governance rule over its own
-signup flow; it is not more dangerous than any other route the project
-wrote, and does not get a different default.
-
-Core's own trusted/sandboxed dispatch (`TrustedFunctions`/`FunctionPool`,
-`src/runtime.ts`) is wired to route dispatch, not exposed to extensions — but
-each half of a hook's `sandbox: true` opt-in has its own answer:
-
-- **Trusted (the default, no `sandbox: true`).** No core primitive is needed
-  or provided: this is ordinary first-party project code, and the
-  extension's own `activate()` already has `ExtensionActivation.root` to
-  resolve the hook's `source` against and can `import()` it directly, the
-  same way any trusted `function`/`middleware` route does. Do that import
-  with a per-activation cache-busting query, the way core's own trusted
-  route activation does (`src/trusted-functions.ts`): Node's ESM loader
-  caches a resolved module forever by URL, so a plain `import()` of the
-  unchanged file URL makes a second activation in the same process keep
-  serving the hook code that was on disk at the first one
-  (jimhoyd-com/urlcode#198). Only the hook's **entry** module is refreshed
-  this way — modules the hook itself imports stay on Node's module cache,
-  the same limitation the trusted route path has, so a change to a hook's
-  own dependency still needs a process restart.
-- **Sandboxed (`sandbox: true`).** `@jimhoyd/urlcode/sandbox` exports
-  `SandboxPool`, the same QuickJS/worker-thread engine that backs a
-  sandboxed `function`/`middleware` route — the identical module-allowlist
-  walk, memory/stack limits, two-layer deadline enforcement, `maxBytes` and
-  response-shape validation, with no separate or weaker engine for
-  extensions. It takes an explicit list of `{source, export}` entries
-  (resolve a hook's `source` string with the re-exported `functionFile()`,
-  the same resolution/validation a native route's `source` gets) instead of
-  anything route/YAML-shaped, and `execute({entry, chain}, request, context)`
-  in place of a `FunctionRoute`. There is no "trusted" mode exported
-  alongside it — `SandboxPool` is only ever the isolated path; see
-  [FUNCTION-SECURITY.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md) and
-  [TYPESCRIPT.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TYPESCRIPT.md) for the full contract.
-
-An extension honoring a hook's `sandbox: true` is expected to actually
-isolate that invocation through `SandboxPool` now that the primitive exists
-(or document plainly that it does not yet, rather than accepting the field
-and silently running it trusted) — say which, in the extension's own docs,
-so an author reading them is not misled about what opt-in exists.
+such as provisioning a workspace. Hook names and lifecycle timing remain the
+extension's domain, while their declaration, loading and discovery are shared.
+
+Hooks are first-party project code and run trusted in-process by default, with
+full Node access, like trusted `function` and `middleware` routes. Contract v1
+does not define an arbitrary-value sandbox hook protocol. A hook reference with
+`sandbox: true` is rejected during activation rather than silently run trusted.
+Only the entry module is refreshed during reactivation; its imported dependencies
+remain in Node's module cache until restart.
+
+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. 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
+
+An extension package should export a registration factory and, when it supports
+`urlcode init --with`, a side-effect-free `scaffold` function. The registration:
+
+1. Declares its logical name, contract version, supported targets, exact project
+   revision pin and strict configuration/policy schemas.
+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. 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.
+5. Returns `handle` for mounts and optionally `authorize`/`middleware` for route
+   policies. It closes resources it owns.
+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
+register it in `host.mjs`. They modify it through declared configuration,
+presentation layers and hooks. A fork is reserved for changing behavior the
+extension has not exposed; that is evidence for a new declarative field or hook.
+See [Composing a site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/COMPOSING-A-SITE.md) for the complete ui/auth/admin example.
 
 ### Discovering schemas
 
 Each registration carries the JSON Schemas that validate its `config` block and
-its per-route policy requirements. `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
@@ -2818,6 +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, 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
@@ -2890,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;
@@ -2904,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.
@@ -3007,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 |
 |---|---|
@@ -3018,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
@@ -3088,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
@@ -3139,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.
 
@@ -3162,15 +3443,24 @@ extensions:
         onSignUp: ./hooks/on-signup.mjs
 ```
 
-`hooks` is not a core schema key. It is each package's own config, validated
-by that package's schema before `activate()`, which is why `get_extensions` is
-the place to check what a given version accepts.
+`hooks` remains each package's own config, but core supplies the reference
+schema, trusted loader and machine-readable hook contract. `get_extensions`
+reports those contracts, so an agent can discover accepted names, purpose and
+input/output shapes without guessing from prose.
 
 Hooks are first-party project code and run **trusted and in-process**, the
 same default `function` and `middleware` routes have
-([FUNCTION-SECURITY.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)). Neither package implements
-sandboxed hook execution yet; `sandbox: true` on a hook is rejected loudly at
-activation rather than accepted and silently run trusted.
+([FUNCTION-SECURITY.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)). Extension hook contract v1 is
+trusted-only; `sandbox: true` is rejected loudly at activation.
+
+#### `@jimhoyd/urlcode-ui`
+
+| Hook | Input | Returns | Called |
+|---|---|---|---|
+| `transformView` | `{template, view}` | the view object to render | Synchronously before each public `ui.kit.render()` or `ui.kit.page()` call. Use it only when theme, copy, templates and CSS cannot express the change. |
+
+For example, `transformView: ./hooks/ui-view.mjs` can add project-computed
+navigation or labels to an auth/admin view without editing either package.
 
 #### `@jimhoyd/urlcode-auth`
 
@@ -3338,14 +3628,11 @@ machinery either way.
 
 This engine — worker spawning, the module-allowlist walk, the two-layer
 deadline, `maxBytes` and response-shape validation — is one implementation
-shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`,
-the public primitive an extension package uses to run a project-supplied hook
-through this exact isolation when the project's own config declares
-`sandbox: true` on it (see [EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks)
-and [TYPESCRIPT.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TYPESCRIPT.md)). Every guarantee above applies identically
-through that entry point; there is no separate, weaker sandbox for extensions
-to reach for, and no "trusted" mode exported there — trusted execution needs
-no primitive at all (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
+That public HTTP-shaped primitive remains available to extension authors, but
+project extension hooks use arbitrary typed values and contract v1 runs them
+trusted in-process; it rejects `sandbox: true` rather than claiming HTTP sandbox
+semantics apply to them. See [extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks).
 
 ### What the trusted default can and can't do