@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

package/llms-full.txt

@@ -1,5 +1,5 @@
 <!-- Generated by scripts/build-llms-full.ts (npm run docs:llms). Do not edit; edit the source documents. -->
-<!-- Consolidated URLCode authoring reference: 15 documents, about 47,012 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 52,663 tokens (estimate: characters / 4). -->
 
 # URLCode
 
@@ -36,7 +36,8 @@ Agents that explicitly want the complete consolidated reference in one fetch sho
 12. [Conditional routing](#conditional-routing)
 13. [Bounded proxy and webhook transport](#bounded-proxy-and-webhook-transport)
 14. [Operator-installed extensions](#operator-installed-extensions)
-15. [Function execution: trusted by default, sandboxed opt-in](#function-execution-trusted-by-default-sandboxed-opt-in)
+15. [Composing a site from ui, auth and admin](#composing-a-site-from-ui-auth-and-admin)
+16. [Function execution: trusted by default, sandboxed opt-in](#function-execution-trusted-by-default-sandboxed-opt-in)
 
 ---
 
@@ -51,26 +52,26 @@ claim here is implemented in the linked repository; nothing is roadmap.
 
 ### Four packages, one project shape
 
-| Package | Repository | What it adds | How a project declares it |
+| Package | Source | What it adds | How a project declares it |
 |---|---|---|---|
-| `@jimhoyd/urlcode` | [urlcode](https://github.com/jimhoyd-com/urlcode) | The runtime: YAML routes, functions and middleware (trusted by default, `sandbox: true` opt-in), pages and assets, policies, site conventions, CLI, provider adapters, the extension contract | `urlcode.yaml` with `version: "1"` |
-| `@jimhoyd/urlcode-ui` | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, one stylesheet with light and dark, themes, translations, the `ui` extension that serves the kit's assets | `extensions.ui` plus an asset mount route |
-| `@jimhoyd/urlcode-auth` | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-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` | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
-
-The core is Apache-2.0 and released. The three extension packages are
-Apache-2.0 and published to npm as alphas (`@jimhoyd/urlcode-ui@0.1.0-alpha.4`,
-`@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`,
-on core `0.4.0-alpha.1`). An alpha on npm is a distribution channel, not an
-endorsement: the source is complete, but independent review, deployment
-evidence and an accessibility assessment are still pending
+| `@jimhoyd/urlcode` | this repository | The runtime: YAML routes, functions and middleware (trusted by default, `sandbox: true` opt-in), pages and assets, policies, site conventions, CLI, provider adapters, the extension contract | `urlcode.yaml` with `version: "1"` |
+| `@jimhoyd/urlcode-ui` | [`packages/ui`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui) | Shared presentation: escaped templates, shadcn/ui partials, one stylesheet with light and dark, themes, translations, the `ui` extension that serves the kit's assets | `extensions.ui` plus an asset mount route |
+| `@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
 ([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-auth/blob/main/IMPLEMENTATION-STATUS.md),
-[admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/IMPLEMENTATION-STATUS.md),
-[ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/IMPLEMENTATION-STATUS.md).
-Which core version each package supports, how it declares that, and the order
-in which a core change reaches the downstream repositories are recorded in
-[core version alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md).
+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),
+[ui](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui/IMPLEMENTATION-STATUS.md).
+The current version of each package is its own manifest, and the peer ranges it
+declares are in that manifest too; do not read a version number out of this
+page. How versions, channels and release tags line up is recorded in
+[package and channel alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md), and `npm run
+release:status` reports the live registry and tag state.
 
 ### The ladder
 
@@ -87,8 +88,10 @@ Each rung's YAML is valid on every rung above it.
 3. **Functions and middleware.** `function` routes and ordered `middleware`
    in JavaScript, trusted and in-process by default; a route declaring
    `sandbox: true` runs isolated instead (QuickJS inside WebAssembly, fresh
-   heap per call, no Node, filesystem or network). Secrets reach a function
-   only through an operator grant pinned to the project revision.
+   heap per call, no Node, filesystem or network). The `env`/`secrets` the
+   runtime injects into a function come only from an operator grant pinned to
+   the project revision; the grant governs that injected context, not the
+   ambient Node environment trusted in-process code can reach on its own.
 4. **Accounts.** The `auth` extension: sign-in, registration, MFA, account
    page and protected routes. The operator installs it in a host file outside
    the project; YAML only declares the mount and configuration.
@@ -100,27 +103,29 @@ Each rung's YAML is valid on every rung above it.
    project copy, template and stylesheet overrides for kit-rendered pages.
 
 Stored short links previously sat here as a native `link` route; that handler
-was removed from core. A future `urlcode-dynamic-link` package (not yet
-published, so this one line is the exception to "nothing is roadmap" above)
-is expected to own them the same way `auth`/`admin` own their mounts.
+was removed from core. A `urlcode-dynamic-link` package owned them the same way
+`auth`/`admin` own their mounts, but it has been retired and unpublished; no
+package occupies this rung today.
 
 Rungs 1 to 3 need only the core package. Rungs 4 to 6 need the extension
-packages, installed from npm as `0.1.0-alpha.x` prereleases, and a Node host
-with a patched SQLite build; see each repository's README for the exact
-requirement.
+packages installed from npm and a Node host with a
+patched SQLite build; see each package's README ([auth](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/README.md),
+[admin](https://github.com/jimhoyd-com/urlcode/blob/main/packages/admin/README.md), [ui](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui/README.md)) for the
+exact requirement.
 
 ### The composition contract
 
-An extended project starts with the packages and one command:
+After the aligned `0.4.1` packages are published, an extended project starts
+with the packages and one command:
 
 ```sh
-npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
-urlcode init my-site --with auth,admin
+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
+urlcode init my-site --with ui,auth,admin
 ```
 
-Installing from npm is the normal path; the extension repositories'
-`pack-sources.mjs` still builds local tarballs from a reviewed checkout for
-operators who install only source they have read. Three files make an extended
+Installing from npm is the normal path; `scripts/pack-sources.mjs` still builds
+local tarballs from a reviewed checkout for operators who install only source
+they have read — one revision now covers core and every extension. Three files make an extended
 project. Nothing else is discovered by convention.
 
 ```
@@ -152,7 +157,8 @@ routes:
         auth: {}
 ```
 
-The operator host wires the packages, once, in code the project cannot reach:
+The operator host explicitly registers the packages. Registration is an
+activation boundary; it does not isolate trusted application code from the host:
 
 ```js
 import { createUiExtension } from '@jimhoyd/urlcode-ui/host';
@@ -172,18 +178,18 @@ export default {
 };
 ```
 
-Auth and admin pages currently render through the shared primitives and a
-`presentation` (catalogue and `--ui-*` theme variables). The `ui` extension
-serves the template kit and its assets for pages an extension renders through
-`ui.kit`; moving the auth and admin screens onto the kit is a listed remaining
-item in the ui repository, so today one `presentation` restyles them and the
-`ui` block is optional.
+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.
 
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
 ```
 
-`urlcode init <dir> --with auth,admin` writes this layout in one step: it
+`urlcode init <dir> --with ui,auth,admin` writes this layout in one step: it
 resolves each installed `@jimhoyd/urlcode-<name>` from the current directory,
 calls its `scaffold` export and merges the fragments into `app/urlcode.yaml`,
 one `host.mjs` and one `README.md`, refusing before writing anything when a
@@ -194,12 +200,24 @@ administrator from JSON on stdin. `inspectExtensionRevision(project)` prints
 the SHA-256 that `projectSha256` must carry; changing extension YAML, policies
 or mounts changes the revision and needs an explicit operator reapproval.
 
+The presentation tooling composes the same way, by naming packages rather than
+depending on them. `urlcode-ui` is the kit alone until
+`--extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin` names the packages
+that ship the other namespaces: each is resolved from `--project` with Node
+package resolution and imported for the namespace it exports, so `list`,
+`doctor`, `eject`, `preview` and `copy --missing` cover the `auth/*` and
+`admin/*` templates and copy the host registers, and a project override of an
+extension template is checked against the shipped view model. A package that is
+not installed is skipped. `urlcode init --with` writes the commands with the
+flag already set; `@jimhoyd/urlcode-ui` still depends on neither peer.
+
 ### Rules an agent must follow
 
 These are the facts that keep generated projects valid. The full matrix is in
 [AI authoring](https://github.com/jimhoyd-com/urlcode/blob/main/docs/AI-AUTHORING.md); this is the short list.
 
-- **YAML never names code, packages, databases or credentials.** Extensions are
+- **Extension YAML names logical extensions, not host packages or credentials.**
+  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.
 - **One handler per route.** `redirect`, `respond`, `page`, `static`, `download`,
@@ -210,13 +228,15 @@ These are the facts that keep generated projects valid. The full matrix is in
   It runs in-process with full Node access unless the route declares
   `sandbox: true`, which isolates it to a text/JSON `Request`/`Response`
   subset, validated `args` and granted `env`, with no `fetch`, Node,
-  filesystem or timers. Either way, `args`/`env`/`secrets` are exactly what
+  filesystem or general network access; bounded timers are available. Either way, `args`/`env`/`secrets` are exactly what
   the route declares and an operator grants — trust changes where code runs,
   not what it is handed. See docs/SPIKE-DEFAULT-TRUST-MODEL.md and
   docs/FUNCTION-SECURITY.md.
 - **Authentication is host processing.** Do not build login forms, session
-  cookies or password checks in functions. Declare `policies.extensions.auth`
-  on the route; the runtime withholds `Cookie` and `Authorization` from guests.
+  cookies or password checks in functions. With the auth extension declared,
+  prefer `auth: true` or `auth: {role: admin}`; these expand to
+  `policies.extensions.auth`. The runtime filters credential headers passed to
+  application handlers. This is not a security boundary against trusted Node code.
 - **Everything is validated before it runs.** `urlcode validate --local`,
   `urlcode test`, `urlcode audit --expect-routes N`. Unsupported features fail
   with the route named; nothing degrades silently.
@@ -235,10 +255,10 @@ These are the facts that keep generated projects valid. The full matrix is in
 | Need | Read |
 |---|---|
 | Write or change routes | [YAML guide](https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-GUIDE.md), [field reference](https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-REFERENCE.md), [cookbook](https://github.com/jimhoyd-com/urlcode/blob/main/examples/cookbook/README.md) |
-| Add accounts | [auth README](https://github.com/jimhoyd-com/urlcode-auth#readme), [auth security](https://github.com/jimhoyd-com/urlcode-auth/blob/main/SECURITY.md) |
-| Add administration | [admin README](https://github.com/jimhoyd-com/urlcode-admin#readme) |
-| Restyle every page | [ui README](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/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/SPIKE-EXTENSION-MODEL.md) |
+| 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) |
 | 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) |
 
 ---
@@ -272,7 +292,11 @@ fields or bypass target limits or operator grants. See [the design principle](ht
 6. [Readiness](https://github.com/jimhoyd-com/urlcode/blob/main/docs/READINESS.md), [capacity](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CAPACITY.md), [DDoS/recovery](https://github.com/jimhoyd-com/urlcode/blob/main/docs/RESILIENCE.md).
 7. [The framework](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FRAMEWORK.md) for accounts, administration and presentation:
    `extensions.<name>` blocks and `extension` mounts are the only YAML those
-   packages need; their configuration is documented in their own repositories.
+   packages need. [Composing a site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/COMPOSING-A-SITE.md) is the map of what a
+   consumer may then change: the `config` each package accepts, the
+   presentation overrides under `ui/`, the project functions its lifecycle
+   hooks call, and when a requirement instead needs a new extension in
+   TypeScript.
 
 The root [llms.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms.txt) is a compact discovery index; the generated
 [llms-full.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms-full.txt) concatenates the authoring documents above in
@@ -353,7 +377,7 @@ The benchmark operates locally; it is not a load test of an external deployment.
 | Parameter validation and JSON body syntax checks | Full OpenAPI or JSON Schema validation of request bodies |
 | Local test/audit/benchmark | Route-local YAML tests, managed monitoring, production load certification |
 | Local/self-hosted runtime; limited AWS/Vercel/Cloudflare implementations with local tests | Verified provider deployments or full cross-provider parity |
-| File authoring and snapshot reload | General guest storage broker; stored short links (moving to a future `urlcode-dynamic-link` extension package, not yet published) |
+| File authoring and snapshot reload | General guest storage broker; stored short links (no supported package; the `urlcode-dynamic-link` extension was retired) |
 | Optional host `policies` (`throttle`, `agents`, `security`, `compression`, `cache`) and reusable `profiles` | Plugins named in YAML, shared multi-instance counters, CORS, verified-bot checks |
 | Optional top-level `site` (`robots`, `sitemap`, `favicon`, `securityTxt`, `llms`) generating native routes | Per-route `noindex` field, sitemap index files, `humans.txt`, signed `security.txt` |
 
@@ -487,9 +511,12 @@ Put that justification where tooling can see it, not only in a source
 comment: an optional `sandboxReason` string on the route (up to 500
 characters, `schemas/urlcode.schema.json`) records why a route needs
 isolation, or why it is safe to trust, regardless of whether `sandbox` is
-`true` or `false`. `urlcode explain`/`context` surface it next to the
-route's `sandbox` boolean, so the trust decision has a reviewable trail
-without reading every route's source file:
+`true` or `false`. `urlcode explain`/`context`, the manifest and the
+`routes` inventory all surface it next to the route's `sandbox` boolean —
+per route, not per handler, so a native handler that runs `middleware`
+reports its execution mode too, and `routes --compare` shows a flip between
+trusted and sandboxed execution as a changed route. The trust decision has a
+reviewable trail without reading every route's source file:
 
 ```yaml
 routes:
@@ -570,8 +597,9 @@ trust (adding `sandbox: true` without saying why, or relying on the trusted
 default for code that plainly needed isolation) to work around them.
 
 There is no native `link` handler or `dynamicLinks` project flag; both were
-removed. Report a request for live stored links as a gap pending the future
-`urlcode-dynamic-link` extension package rather than inventing a `link` field.
+removed. The `urlcode-dynamic-link` extension package that briefly owned them
+has been retired and unpublished, so there is no supported replacement. Report a
+request for live stored links as a gap rather than inventing a `link` field.
 
 See [capabilities and normalized route representation](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CAPABILITIES.md) for the target catalog,
 programmatic compatibility analysis and provider verification limits.
@@ -1255,10 +1283,10 @@ keys preserve repeated values. Headers are forwarded only through explicit maps.
 ### Stored links
 
 Core has no native `link` handler or `dynamicLinks` project flag; both were
-removed. Stored short links are moving to a future `urlcode-dynamic-link`
-extension package (mount-based, like `auth`/`admin`), not yet published. A
-project needing them declares an `extension` mount once that package exists;
-there is no in-core replacement or deprecation shim for `link`/`dynamicLinks`.
+removed. The `urlcode-dynamic-link` extension package that replaced them has
+been retired and unpublished, so a project needing stored short links owns that
+storage itself; there is no in-core replacement or deprecation shim for
+`link`/`dynamicLinks`.
 
 ### Functions
 
@@ -1299,7 +1327,11 @@ 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.
 
-ES modules only (`.mjs` or `.js`, independent of Node package settings).
+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
+nearest `package.json` to declare `"type": "module"`; under `"type": "commonjs"`
+it fails activation. Prefer `.mjs` for modules that must work in either mode.
 [Build-time TypeScript authoring](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TYPESCRIPT-AUTHORING.md) can produce these
 JavaScript modules in a separate output project; serving does not transpile them.
 The build never imports application code into Node, uses fixed compiler settings,
@@ -1426,7 +1458,9 @@ are local Git-owned examples; they grant no capabilities. [Build-time TypeScript
 is separate from runtime execution.
 
 The [tooling SDK and optional local MCP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md) inspect and validate without
-executing handlers or reading binding values. [Provider conformance](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROVIDER-VERIFICATION.md)
+executing handlers or reading binding values. MCP defaults to inspection; the
+explicit `--allow-authoring` option enables bounded project writes, separately
+from host-file loading and grants. [Provider conformance](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROVIDER-VERIFICATION.md)
 distinguishes local adapter replay from actual deployment observations; no real
 provider deployment is implied by CI. [Proxy and signal egress](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EGRESS.md) requires
 external revision-pinned operator grants and bounded host-owned transport;
@@ -1539,10 +1573,9 @@ any per-visitor session record. Git owns route behavior and code; user-created r
 their own persistence, backup and export lifecycle.
 
 Core has no native handler for this today: the `link` handler that implemented
-it was removed. Stored short links are moving to a future
-`urlcode-dynamic-link` extension package (mount-based, like `auth`/`admin`,
-not yet published); a project needing them declares an `extension` mount once
-that package exists.
+it was removed. The `urlcode-dynamic-link` extension package that replaced it
+has been retired and unpublished, so a project needing stored short links owns
+that storage itself.
 
 Functions still cannot access databases, the filesystem or network directly.
 General application state and realtime sessions remain future work.
@@ -1735,12 +1768,18 @@ Every middleware and the function share the same request and context. Validated
 with a fresh `context.state` object for this chain. State never survives the
 request. Header edits are visible downstream; editing the request does not
 reroute it or change already validated inputs. Request bodies are single-use:
-reading one consumes it for downstream code. There is no `clone()` or streaming
-API; pass parsed data through `context.state` when needed.
+reading one consumes it for downstream code. On a `sandbox: true` route there is
+no `clone()` or streaming API at all, so pass parsed data through
+`context.state`; a trusted route receives Node's own `Request`/`Response` and so
+does have `clone()`, but passing parsed data through `context.state` keeps the
+chain portable between the two modes.
 
 Function responses support the existing text/JSON guest API. To transform their
-body, read it and return a new `Response`. Native redirect/respond/page/static/
-download bodies are opaque and cannot be read through `text()` or `json()`.
+body, read it and return a new `Response`. On a `sandbox: true` route, native
+redirect/respond/page/static/download bodies are opaque and cannot be read
+through `text()` or `json()`; a trusted chain receives them as an ordinary
+`Response` and can read them, so wrapping `respond: {text: hello}` and returning
+`HELLO` works there and fails in the guest.
 Returning the same native response preserves original bytes, including binary
 files, ranges and HEAD lengths. You may add headers, but cannot change its
 original status or existing native headers while preserving that body. To replace
@@ -1790,7 +1829,8 @@ Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/ASSETS.md
 
 Native file handlers are implemented in 0.1.0-alpha.3. They work in the local
 Node runtime and self-hosted process/container. Provider adapters remain planned.
-They do not run user functions or expose filesystem APIs to sandboxed code.
+They do not run user functions or expose filesystem APIs to guest code, trusted
+or sandboxed.
 
 ```yaml
 version: "1"
@@ -1902,9 +1942,10 @@ Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/POLICIES.md
 Policies are host-enforced behavior declared in YAML around a route: a
 per-client request budget, a User-Agent deny list, a security-header profile,
 content-coding negotiation and an HTTP caching strategy. They run in the host
-process, outside the sandbox, so they can see the client address, keep counters
-across requests and touch the transport, which route middleware by design
-cannot ([middleware](https://github.com/jimhoyd-com/urlcode/blob/main/docs/MIDDLEWARE.md), [function security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)).
+process, outside function/middleware execution — trusted or sandboxed alike —
+so they can see the client address, keep counters across requests and touch
+the transport, which route middleware by design cannot
+([middleware](https://github.com/jimhoyd-com/urlcode/blob/main/docs/MIDDLEWARE.md), [function security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)).
 
 Everything here is optional and off by default. A project with no `policies`
 key and no `profiles` key behaves exactly as before: no policy module is
@@ -1919,7 +1960,7 @@ compiled and the request path is unchanged. Each policy has its own page:
 | `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/SPIKE-EXTENSIONS.md). Operators who need behavior 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.
 
@@ -1941,7 +1982,14 @@ routes:
 `policies` at the top level sets project defaults; `routes.<path>.policies`
 adjusts them for one route. Two route-level short forms exist. `auth`
 expands to `policies.extensions.auth` when the project declares an auth
-[extension](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md). `cache: {strategy, maxAge, ...}` expands to
+[extension](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md), carrying the same keys minus `required`;
+`required: false` documents the intent and emits no policy. It accepts
+`required`, `role`, `permission`, `verified`, `freshWithinSeconds` and
+`onDeny` and nothing else — `role` is singular, and there is no `roles`. Like
+`cache` below, it is refused rather than silently ignored in three cases: when
+the project declares no `extensions.auth`, when the route also sets
+`policies.extensions.auth` (use one form), and when the route sets
+`policies.extensions: false`. `cache: {strategy, maxAge, ...}` expands to
 `policies.cache` the same way — the compiler merges it into that route's
 `policies` before anything else reads the project, so `routes`, `audit` and
 `explain` see only the expanded long form, and it is refused alongside a
@@ -2477,10 +2525,11 @@ and admin implementations live in `urlcode-auth` and `urlcode-admin`; the runtim
 supplies only the generic integration contract. No project file can import a host
 extension or choose its npm package.
 
-Stored short links are moving out of core this way too: a future
-`urlcode-dynamic-link` package (mount-based, like `auth`/`admin`, not yet
-published) will own the durable link store, its CLI and management API. Core
-no longer has a native `link` handler or a `dynamicLinks` project flag.
+Stored short links moved out of core this way too: a `urlcode-dynamic-link`
+package (mount-based, like `auth`/`admin`) owned the durable link store, its CLI
+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.
 
 A project declares versioned configuration and exclusive route mounts:
 
@@ -2663,7 +2712,7 @@ project customizes an extension's *look* through `urlcode-ui`'s
 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-auth/blob/main/docs/SPIKE-AUTH.md)
+[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
@@ -2727,7 +2776,16 @@ each half of a hook's `sandbox: true` opt-in has its own answer:
   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.
+  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
@@ -2797,16 +2855,15 @@ boundary, not a JavaScript sandbox or an independent security review.
 
 ### Scaffolding with `init --with`
 
-`urlcode init <directory> --with auth,admin` produces the layered site the
+`urlcode init <directory> --with ui,auth,admin` produces the layered site the
 [framework page](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FRAMEWORK.md#the-composition-contract) describes in one
 command: the starter under `<directory>/app/`, one `host.mjs`, one `README.md`,
 and each extension's own operator files. Core never bundles or imports the
 extension packages at build time; at run time it resolves
 `@jimhoyd/urlcode-<name>` for each name with Node's package resolution from
-the invoking directory (so `npm install @jimhoyd/urlcode-auth` in that
-directory, from npm where the packages are published as `0.1.0-alpha.x`
-prereleases, is the normal path and what makes `--with auth` work), imports
-the package and calls its
+the invoking directory. Install a compatible package set there, as shown in
+[the framework guide](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FRAMEWORK.md#the-composition-contract), before using
+`--with ui,auth`; UI must activate before auth. Core imports the package and calls its
 `scaffold` export with this request:
 
 ```ts
@@ -2862,6 +2919,37 @@ Assembly rules, in `--with` order:
   review the project and pin it explicitly; the host is generated to require
   the pin, never to compute it.
 
+#### Recorded versions
+
+`init --with` also writes `<directory>/package.json`: a private manifest that
+pins, at exactly the version that was resolved, the running runtime, every
+extension named in `--with`, and every package those extensions declare in
+`peerDependencies` (so `@jimhoyd/urlcode-ui` is pinned for an `auth,admin` site
+although nobody named it). Before anything is written, the whole set is checked
+against every declared peer range; an incompatible combination or a missing
+required peer refuses and names it, leaving no directory behind.
+
+Nothing is installed. The generated site has no `node_modules` and no
+`package-lock.json` until you run `npm install` in it yourself, which the
+command and the generated README both state as the next step. Reproducibility
+comes from that install, not from generation.
+
+- `--no-manifest` generates the site without a `package.json`, for a site whose
+  dependencies are managed elsewhere. Plain `urlcode init` is unchanged and
+  still writes no manifest; add `--manifest` to pin the runtime for a
+  route-only project too.
+- `--pin <package>=<specifier>` records a specifier instead of the resolved
+  version, for local tarball or offline development
+  (`--pin @jimhoyd/urlcode-auth=file:/abs/urlcode-auth-0.1.0-alpha.6.tgz`). A
+  package installed from a local path or tarball is detected from npm's own
+  install record and pinned by that path without any flag; the README says so,
+  because such a pin only reproduces where that path exists.
+
+There is no upgrade command. Moving a generated project to newer versions today
+means editing its `package.json` and re-running `npm install` yourself; nothing
+in this runtime selects a newer tested set, shows the change, or updates a
+lockfile for you.
+
 Serving the result is the usual explicit host binding:
 
 ```sh
@@ -2870,6 +2958,289 @@ urlcode validate --project app --host-file "$PWD/host.mjs" --origin https://site
 
 ---
 
+# Composing a site from ui, auth and admin
+
+Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/COMPOSING-A-SITE.md
+
+One command produces a site that already has accounts, an administration
+console and a presentation kit wired together:
+
+```sh
+npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
+urlcode init site --with ui,auth,admin
+```
+
+This page is the map of what you may then change, and with which tool. It
+covers three different activities that are easy to confuse:
+
+| You want to | Use | Code? |
+|---|---|---|
+| Change what an extension is configured to do | the `config` block in `app/urlcode.yaml` | none |
+| Change how its screens look or read | files under `<site>/ui/` | none (templates are data) |
+| Run your own logic at one of its lifecycle points | a project function named from that `config` | first-party project JavaScript |
+| Add a capability none of the three provides | a new extension package | TypeScript against the runtime contract |
+
+Work down that list, not up. The [declarative-first
+principle](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROJECT-DIRECTION.md#design-principle-declarative-first) applies
+here as much as it does to routes: reach for the next row only when the one
+above it cannot express the requirement.
+
+### What `--with ui,auth,admin` generates
+
+- `site/app/` — the route project: `urlcode.yaml` with an `extensions` block
+  per package, and `routes/extensions.yaml` holding `/assets/ui/*`,
+  `/account/*`, `/private` and `/admin/*`.
+- `site/host.mjs` — the operator host module, the one place that holds code.
+  It builds the kit with `createUiExtension`, passes the returned object into
+  `authExtension` and `adminExtension`, and lists `ui.registration` first.
+- `site/ui/` — `copy/`, `templates/` and `extra.css`, the project's
+  presentation overrides, beside the host and **outside** `app/`.
+- `site/operator-service.mjs`, `site/data/` — auth's operator service and its
+  private key material, mode `0600`.
+- `site/README.md` — the merged next steps, environment table and the project
+  revision to review and pin.
+
+Nothing about that wiring is manual any more. The generated host registers
+`authCatalogue` as a copy source and both `authUiTemplates` and
+`adminUiTemplates` as template namespaces, because auth and admin render only
+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` | Result |
+|---|---|
+| `ui` | Kit only; the host wires no peer catalogue or templates. |
+| `ui,auth` | Accounts on `/account/*`, rendered through the kit. |
+| `ui,auth,admin` | The full composition above. |
+| `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. |
+
+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
+revision: the UI primitive fallback was retired, so the kit is the only render
+path (see [OPEN-DECISIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md)).
+
+### Declarative configuration
+
+Each package owns one `extensions.<name>` block. The block itself is core
+schema (`version` plus `config`); what may go inside `config` is the
+package's own JSON Schema, which you can print rather than guess:
+
+```sh
+urlcode extensions --project ./site/app --host-file "$PWD/site/host.mjs" --json
+```
+
+The same report is the MCP tool `get_extensions`, and it is the authoritative
+answer for both the configuration schema and the per-route policy schema. The
+generated site starts from something like this:
+
+```yaml
+version: "1"
+extensions:
+  ui:
+    version: "1"
+    config:
+      theme:
+        name: My Site
+      languages: [en]
+      copy: ui/copy
+      templates: ui/templates
+      stylesheet: ui/extra.css
+  auth:
+    version: "1"
+    config:
+      registration: "off"
+  admin:
+    version: "1"
+    config: {}
+```
+
+Routes mount an extension, and policies require one:
+
+```yaml
+routes:
+  /assets/ui/*:
+    extension: ui
+    methods: [GET, HEAD]
+  /account/*:
+    extension: auth
+    methods: [GET, HEAD, POST]
+  /admin/*:
+    extension: admin
+    methods: [GET, HEAD, POST]
+  /private:
+    respond:
+      text: Signed in
+    policies:
+      extensions:
+        auth: {}
+```
+
+See [EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md) for the `auth` route short form, extension
+middleware, and the host-file trust boundary.
+
+### Presentation overrides
+
+The `ui` config's `copy`, `templates` and `stylesheet` paths point at the
+project's own directories. Nothing here forks a package.
+
+| 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. |
+
+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
+cannot weaken the screen it restyles. Stylesheets containing `@import`,
+`script`, `javascript:` or `expression(` are refused.
+
+Names, coverage and what the runtime will actually load:
+
+```sh
+npx urlcode-ui list --project ./site --extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin
+npx urlcode-ui doctor --project ./site --extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin --copy ui/copy --templates ui/templates --stylesheet ui/extra.css
+npx urlcode-ui eject auth/sign-in --out ./site/ui/templates --project ./site --extensions @jimhoyd/urlcode-auth
+npx urlcode-ui copy --missing fr --project ./site --extensions @jimhoyd/urlcode-auth --copy ui/copy --languages en,fr
+```
+
+`eject` copies the shipped source so an override starts from what ships and
+never overwrites an existing file. `ui/` lives outside `app/`, so editing copy
+or templates does **not** change the project revision and does not require
+re-pinning `PROJECT_SHA256`.
+
+**Name the packages that ship the other namespaces.** `urlcode-ui` is this
+kit alone until `--extensions` names them. Each package is resolved from
+`--project` with Node package resolution and imported for the namespace it
+exports; one that is not installed there is skipped with a note, so the
+command still runs. The site's `host.mjs` is never read: it builds services
+and reads secrets at its top level, and a read-only `list` or `doctor` must
+not run it. With the packages named:
+
+- `list` shows the `auth/*` and `admin/*` names beside the kit's own, each
+  with its origin, and `eject auth/sign-in` copies the shipped source.
+- `doctor` reports an `expected` view model for an extension template, so its
+  `behind` flag tells you when an override of one has fallen behind what
+  ships. Its `extensions` field names the namespaces the report covers, so a
+  report built without a peer is visible as such.
+- `preview auth/sign-in` renders the extension's own sample view model.
+- `copy --missing` skeletons cover the auth ids the account screens use.
+  Admin-owned `adminUi.*` ids are deliberately not offered: admin composes
+  its catalogue onto the kit's presentation rather than registering it there,
+  and those translations do not currently reach the console
+  ([#227](https://github.com/jimhoyd-com/urlcode/issues/227)).
+
+`urlcode init <directory> --with ui,auth,admin` writes these commands into the
+generated README with the flag already set. `@jimhoyd/urlcode-ui` depends on
+neither peer; the operator names them.
+
+Overrides of extension templates and of extension-owned catalogue ids reach
+the rendered screens, which is what the regression test below asserts.
+
+### Project functions: lifecycle hooks
+
+A hook is your own function, named from the extension's `config`, that the
+extension calls at a lifecycle point it defines. It uses the same source shape
+a `function` route uses — a bare path, or `{source, export}` — resolved
+relative to the route project.
+
+```yaml
+extensions:
+  auth:
+    version: "1"
+    config:
+      registration: open
+      hooks:
+        beforeRegister:
+          source: ./hooks/registration-rule.mjs
+          export: default
+        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 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.
+
+#### `@jimhoyd/urlcode-auth`
+
+| Hook | Input | Returns | Called |
+|---|---|---|---|
+| `beforeRegister` | `{email, profile?}` | `{allow: boolean, reason?}` | Before an account is created, on `POST /account/register` and on `POST /account/signup/begin`. |
+| `onSignUp` | `{accountId, email}` | ignored | After a genuinely new account is created — on `/account/register`, and on `/account/signup/complete` only when that completion created an account rather than signing an existing one in. |
+| `onDelete` | `{accountId, email}` | ignored | After the account owner's own deletion is scheduled. Not on an administrator-initiated deletion, and not on the background purge when the grace period ends. |
+
+#### `@jimhoyd/urlcode-admin`
+
+| Hook | Input | Returns | Called |
+|---|---|---|---|
+| `beforeRoleChange` | `{accountId, currentRoles, requestedRoles, actorId, reason}` | `{allow: boolean, reason?}` | Before roles are applied, after the administrator's permission check. A veto means the auth service is never asked. |
+| `onRegistrationApproved` | `{requestId, accountId, email, actorId, reason}` | ignored | After a registration request is approved. |
+| `onAccountStatusChanged` | `{accountId, status, actorId, reason}` | ignored | After an account is locked or unlocked. |
+
+#### Verdicts and failure
+
+- **A veto is explicit.** A pre-action hook allows only by returning
+  `allow: true`. `allow: false`, or no verdict at all, rejects the operation
+  with `403` and the hook's own `reason`, or a generic message when it gave
+  none. Nothing is written. A hook that *throws* has not returned a verdict:
+  the operation is still refused, but as a generic `500`, so return a verdict
+  rather than throwing when you mean to deny.
+- **Broken hooks fail at activation, not at the first request.** A missing
+  module, a source path escaping the project, an export that is not a
+  function, or `sandbox: true` all throw while the extension activates, naming
+  the hook. The site does not start.
+- **A post-action hook cannot undo anything.** `onSignUp`,
+  `onDelete`, `onRegistrationApproved` and `onAccountStatusChanged` run after
+  the operation has committed. Throwing from one replaces the success response
+  with a `500` while the account, approval or status change stands. There is
+  no retry and no rollback. Keep them non-throwing: catch your own errors and
+  queue the work instead of failing the request.
+- **A hook's message is not a channel to the browser.** Only a pre-action
+  `reason` is shown. An uncaught error surfaces as a generic failure.
+- **An edited hook needs a restart.** Activation re-imports the hook's entry
+  module, so a reload picks up an edit to that file — but modules it imports
+  stay on Node's module cache, exactly as for trusted route functions.
+
+### TypeScript: implementing a new extension
+
+Only write an extension when a capability is genuinely absent — not to
+customize one of the three above. An extension is an operator-installed
+package whose host object core activates; it is named in `host.mjs`, never
+in YAML. The contract, the activation inputs, `ExtensionActivation.root`,
+credential headers and the `projectSha256` pin are in
+[EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md) and [TYPESCRIPT.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TYPESCRIPT.md); the
+`scaffold` export that makes a package work with `init --with` is in
+[EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#scaffolding-with-init---with).
+
+If its screens should be themeable the same way auth's and admin's are, it
+also exports a template namespace (and, if it ships English wording, a
+catalogue) for a host to pass to `createUiExtension`. That is what makes
+`ui/templates/<yourname>/<screen>.html` work in a consumer project without a
+fork.
+
+### What this page does not claim
+
+The composition, the refusals and the override path are exercised by
+`test/workspace-scaffold.integration.ts`, which runs `init --with` against the
+built packages, drops a template and a copy catalogue into the generated
+`ui/` directory and asserts both reach a rendered auth screen and a rendered
+admin screen. That runs in-process against the generated host: no HTTP
+listener, TLS proxy, browser or deployed site is exercised, and no published
+npm tarball is checked against this checkout.
+
+---
+
 # Function execution: trusted by default, sandboxed opt-in
 
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md
@@ -2914,6 +3285,35 @@ API is all it has, so its binding grant *is* effectively its whole reach into
 the environment. Trusted code's reach is not bounded that way; treat the
 grant as scoping `context`, not as scoping the process.
 
+### Migrating to the trusted default
+
+If you are upgrading a project from a release before this change shipped:
+**every existing `function` and `middleware` route silently changes execution
+mode**, from sandboxed to trusted, unless it already has (or you add)
+`sandbox: true`. This is a real behavior change on upgrade, not a
+documentation update — a route that used to run with no filesystem or network
+access will, after the upgrade, run with full Node access unless you opt it
+back into the sandbox.
+
+Before upgrading:
+
+- List every `function` and `middleware` route in the project.
+- For each one, decide whether you fully trust that code to run in-process
+  with full Node/filesystem/network access — the same trust you would extend
+  to any other code you deploy to that server.
+- Add `sandbox: true` explicitly to any route whose code you do not fully
+  trust, that processes input from a source you don't control, or that handles
+  a secret binding you want isolated — before you upgrade, not after.
+- Routes you do want running trusted need no change; that is now the default.
+
+The change moves the sandbox from an unconditional guarantee to an explicit,
+per-route choice, mainly for performance: the previous blanket sandbox capped
+concurrency at two workers with no queue shared across every function route on
+the server, which does not scale to real concurrent traffic. It also brings
+first-party code in line with how the rest of the Node ecosystem treats
+deployed application code. The sandbox itself is unchanged for routes that opt
+into it; only the default for routes that declare neither option has changed.
+
 ### What "sandboxed" (`sandbox: true`) still guarantees
 
 - Function sources are parsed/snapshotted without importing them into Node.
@@ -2990,6 +3390,21 @@ it is handed *through `context`*. It does not change what the code can go get
 on its own once it is running; see "binding grants are unaffected" above for
 that distinction.
 
+### Trusted code, not trusted requests
+
+"Trusted" describes the code's authorship — first-party project code you
+reviewed and deployed — not the requests it handles. Every request, in either
+mode, still carries client-controlled path, query, header and body data that is
+exactly as adversarial as it always was. Running trusted means that code
+executes with full Node access if it mishandles that input; it does not mean
+the input itself became safe to trust. Declare `parameters` and `request.body`
+validation in YAML, check `args` and any other request data again inside
+function/middleware code, and implement your own authentication and
+authorization — no route, sandboxed or trusted, adds automatic auth.
+`sandbox: true` narrows what a bug or an unreviewed dependency in the *code*
+can do with that same request data; it is not a substitute for validating or
+authenticating the request itself.
+
 ### Granting selected bindings
 
 An application may request a named binding in YAML, but only an operator can