@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.2

package/docs/EXTENSIONS.md

@@ -183,29 +183,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-auth/blob/main/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:
@@ -221,76 +210,51 @@ 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](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](FUNCTION-SECURITY.md) and
-  [TYPESCRIPT.md](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.
+
+## 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. Activates all configuration, files, services and hooks before serving a
+   request. Invalid or stale configuration fails activation.
+4. Returns `handle` for mounts and optionally `authorize`/`middleware` for route
+   policies. It closes resources it owns.
+5. 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](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 contracts. `urlcode extensions` prints them together with
 the project's own declarations so an author can see what a mount accepts:
 
 ```sh
@@ -299,6 +263,7 @@ 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,
 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
@@ -336,16 +301,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](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](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
@@ -401,6 +365,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

package/docs/FRAMEWORK.md

@@ -7,26 +7,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`](../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`](../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`](../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](VERSION-ALIGNMENT.md).
+files say exactly what is built: [auth](../packages/auth/IMPLEMENTATION-STATUS.md),
+[admin](../packages/admin/IMPLEMENTATION-STATUS.md),
+[ui](../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](VERSION-ALIGNMENT.md), and `npm run
+release:status` reports the live registry and tag state.
 
 ## The ladder
 
@@ -43,8 +43,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.
@@ -61,17 +63,19 @@ was removed from core. A `urlcode-dynamic-link` package owned them the same way
 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](../packages/auth/README.md),
+[admin](../packages/admin/README.md), [ui](../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; `scripts/pack-sources.mjs` still builds
@@ -140,7 +144,7 @@ See each package README for its complete kit registration example.
 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
@@ -151,6 +155,17 @@ 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
@@ -195,8 +210,8 @@ These are the facts that keep generated projects valid. The full matrix is in
 | Need | Read |
 |---|---|
 | Write or change routes | [YAML guide](YAML-GUIDE.md), [field reference](YAML-REFERENCE.md), [cookbook](../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) |
+| Add accounts | [auth README](../packages/auth/README.md), [auth security](../packages/auth/SECURITY.md) |
+| Add administration | [admin README](../packages/admin/README.md) |
+| Restyle every page | [ui README](../packages/ui/README.md), [ui contract](../packages/ui/CONTRACT.md) |
 | Write an extension | [extensions](EXTENSIONS.md), [extension model review](archive/2026-09-19/SPIKE-EXTENSION-MODEL.md) |
 | Run it | [operations](OPERATIONS.md), [install](INSTALL.md), [deployment checks](DEPLOYMENT-CHECKS.md) |

package/docs/FUNCTION-SECURITY.md

@@ -93,14 +93,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](EXTENSIONS.md#project-level-lifecycle-hooks)
-and [TYPESCRIPT.md](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](EXTENSIONS.md#project-level-lifecycle-hooks).
 
 ## What the trusted default can and can't do
 

package/docs/INSTALL.md

@@ -8,8 +8,13 @@ so the installed `urlcode` command runs `dist/cli.js` and needs no build tool.
 
 ## npm
 
+The stable release target is `0.4.1`. Use these commands after publication;
+`npm run release:status` in a checkout reports live registry availability. An
+unversioned npm install selects the current `latest` channel, while `@alpha`
+explicitly selects the separate prerelease channel.
+
 ```sh
-npm install --global @jimhoyd/urlcode
+npm install --global @jimhoyd/urlcode@0.4.1
 urlcode --help
 ```
 
@@ -19,12 +24,12 @@ Which dependency list it belongs in depends on how the project uses URLCode:
 ```sh
 # Using URLCode as a tool: validate, test and build in CI, never imported by
 # the code that serves requests.
-npm install --save-dev @jimhoyd/urlcode
+npm install --save-dev --save-exact @jimhoyd/urlcode@0.4.1
 npx urlcode validate
 
 # Embedding the runtime (see TYPESCRIPT.md): the application imports
 # @jimhoyd/urlcode at startup, so it must survive `npm ci --omit=dev`.
-npm install --save @jimhoyd/urlcode
+npm install --save --save-exact @jimhoyd/urlcode@0.4.1
 ```
 
 A devDependency is absent from a production install, so an application that
@@ -65,7 +70,7 @@ It downloads the release tarball, verifies its SHA-256 against the release's
 `SHA256SUMS`, and installs with npm. Options:
 
 ```sh
-curl -fsSL .../install.sh | sh -s -- --version 0.3.0 --prefix "$HOME/.local"
+curl -fsSL .../install.sh | sh -s -- --version 0.4.1 --prefix "$HOME/.local"
 ```
 
 `--prefix` avoids needing privileges for a global npm directory; add
@@ -76,12 +81,12 @@ for that moment: to inspect first, download it, read it, then run it.
 
 No image is published yet: the release job's GHCR step is gated behind the
 `PUBLISH_CONTAINER` repository variable and has not run, so there is nothing at
-`ghcr.io/jimhoyd-com/urlcode` to pull. Build it from a release checkout:
+`ghcr.io/jimhoyd-com/urlcode` to pull. After the release tag exists, build it from that checkout:
 
 ```sh
-git clone --branch v0.3.0 https://github.com/jimhoyd-com/urlcode.git
-docker build -t urlcode:0.3.0 urlcode
-docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" urlcode:0.3.0 \
+git clone --branch v0.4.1 https://github.com/jimhoyd-com/urlcode.git
+docker build -t urlcode:0.4.1 urlcode
+docker run --rm -p 127.0.0.1:3000:3000 -v "$PWD:/project:ro" urlcode:0.4.1 \
   serve --project /project --host 0.0.0.0
 ```
 

package/docs/MIDDLEWARE.md

@@ -48,12 +48,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