@jimhoyd/urlcode 0.4.0-alpha.3 → 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 48,160 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.
@@ -105,17 +108,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](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; `scripts/pack-sources.mjs` still builds
@@ -184,7 +189,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
@@ -195,6 +200,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
@@ -239,9 +255,9 @@ 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) |
+| 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) |
 
@@ -276,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
@@ -1307,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,
@@ -1744,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
@@ -2682,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
@@ -2825,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
@@ -2890,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
@@ -2898,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

package/llms.txt

@@ -67,6 +67,7 @@ fields or bypass target limits or operator grants. See [the design principle](do
 
 ## Extensions (accounts, administration, presentation)
 - [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, `extension` mounts, `policies.extensions`, the operator host file, `@jimhoyd/urlcode/extensions`. Project-level lifecycle hooks run trusted via plain `import()`, or sandboxed via `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
+- [Composing a site](docs/COMPOSING-A-SITE.md): what `urlcode init site --with ui,auth,admin` wires, which `--with` combinations are supported, the presentation override paths under `ui/`, and per-package lifecycle hook input, verdict, timing and failure semantics. Separates declarative configuration, project functions and the TypeScript a new extension needs.
 - [urlcode-auth](packages/auth): npm: @jimhoyd/urlcode-auth; accounts, sessions, MFA, roles, account page; its own llms.txt. Lives in this repository as a workspace package.
 - [urlcode-admin](packages/admin): npm: @jimhoyd/urlcode-admin; users, sessions, roles, audit, cases; its own llms.txt. Lives in this repository as a workspace package.
 - [urlcode-ui](packages/ui): npm: @jimhoyd/urlcode-ui; escaped templates, shadcn/ui partials, themes, translations; its own llms.txt. Lives in this repository as a workspace package, not in a separate repository.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.0-alpha.3",
+  "version": "0.4.1",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [
@@ -104,7 +104,8 @@
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --conditions=development --test test/*.test.ts",
     "lint": "eslint .",
-    "check": "node scripts/check.ts && node scripts/check-trust-model-prose.ts && node scripts/check-guidance-claims.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check && npm run release:check",
+    "check": "npm run check:code && npm run check:docs",
+    "check:code": "node scripts/check.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && npm run release:check",
     "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test && npm run verify:workspaces",
     "workspace:styles": "npm run styles --workspace @jimhoyd/urlcode-ui",
     "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run test:workspace-integration",
@@ -128,7 +129,7 @@
     "benchmark:sandbox-vs-trusted": "node benchmarks/sandbox-vs-trusted.ts",
     "benchmark:agent": "node benchmarks/agent/run.ts",
     "sync:agents": "node scripts/sync-agent-lists.ts",
-    "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
+    "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-local-links.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",
     "ci:plan": "node scripts/ci-plan.ts",
     "test:package:built": "node scripts/package-smoke.ts",
     "release:status": "node scripts/release.ts status",
@@ -136,10 +137,12 @@
     "release:publish": "node scripts/release.ts publish",
     "release:run": "node scripts/release-run.ts",
     "release:peers": "node scripts/release.ts peers",
-    "release:check": "node scripts/release.ts check",
+    "release:check": "node scripts/release.ts check && node scripts/release-prepare.ts --check",
     "ci:history": "node scripts/ci-history.ts",
     "ci:report": "node scripts/ci-report.ts",
-    "test:workspace-integration": "node --test test/workspace-scaffold.integration.ts"
+    "test:workspace-integration": "node --test test/workspace-scaffold.integration.ts",
+    "release:prepare": "node scripts/release-prepare.ts",
+    "release:template": "node scripts/release-template.ts"
   },
   "repository": {
     "type": "git",

package/packaging/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "urlcode",
   "description": "Authoring and operating URLCode projects: the implemented YAML contract, capability limits, deployment and verification commands for the pinned runtime revision.",
-  "version": "0.4.0-alpha.3",
+  "version": "0.4.1",
   "author": {
     "name": "jimhoyd-com",
     "url": "https://github.com/jimhoyd-com"

package/recipes/middleware/middleware/envelope.mjs

@@ -1,5 +1,7 @@
-// Wrap successful JSON function responses in a stable envelope. Native bodies are
-// opaque and pass through untouched; only readable JSON is rewritten.
+// Wrap successful JSON function responses in a stable envelope. Only a JSON body
+// this chain can actually read is rewritten; everything else passes through
+// untouched -- on a `sandbox: true` route that includes every native body, which
+// the guest cannot read at all.
 export default async function envelope(request, context, next) {
   const response = await next();
   if (!response.ok || !(response.headers.get('content-type') || '').startsWith('application/json')) return response;