@jimhoyd/urlcode 0.4.8 → 0.5.5

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: 16 documents, about 59,492 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 61,239 tokens (estimate: characters / 4). -->
 
 <!-- urlcode-current-version:start -->
 # URLCode
@@ -7,10 +7,11 @@
 > A portable runtime for programmable URL behavior, and the framework that grows
 > from it: routes in YAML, functions and middleware, then accounts, administration and
 > stored links as operator-installed extensions. Stable project format
-> `version: "1"`. Core is Apache-2.0; this revision is `0.4.8`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.5`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
-> auth, admin and ui extension packages in this repository are versioned at the same
-> revision; confirm what is published with `npm run release:status`.
+> auth, admin, ui and store workspace packages are bundle sources. New sites install
+> core from npm and verified executable extensions from an immutable GitHub Release;
+> see package and channel alignment for the supported release pair.
 <!-- urlcode-current-version:end -->
 
 Use the schema and docs from the runtime revision you run. Do not assume Node
@@ -18,9 +19,6 @@ or fetch inside a `sandbox: true` function, regex routes, database access,
 global middleware, YAML interpolation, or packages named in YAML. Secrets need external revision-pinned
 grants. Unsupported features fail with the route named; nothing degrades silently.
 
-Agents that explicitly want the complete consolidated reference in one fetch should read
-[llms-full.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms-full.txt), generated from the documents below (about 50k tokens, estimated).
-
 ## Contents
 
 1. [The URLCode framework](#the-urlcode-framework)
@@ -46,12 +44,12 @@ Agents that explicitly want the complete consolidated reference in one fetch sho
 
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/FRAMEWORK.md
 
-One page for people and AI agents. It says what the four packages are, how a
+One page for people and AI agents. It says what the six workspace packages are, how a
 project grows from a handful of redirects into an application with accounts
 and an administration console, and which facts an agent must not guess. Every
 claim here is implemented in the linked repository; nothing is roadmap.
 
-### Four packages, one project shape
+### Six workspace packages, one project shape
 
 | Package | Source | What it adds | How a project declares it |
 |---|---|---|---|
@@ -59,12 +57,17 @@ claim here is implemented in the linked repository; nothing is roadmap.
 | `@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. Each package's npm `latest` tag identifies its stable
-version. The current publisher records the exact four-package stack tested
-together on each new GitHub release and attaches the same information in signed
-`train.json` metadata.
-A stable npm channel is not an independent assessment: review, deployment
+| `@jimhoyd/urlcode-store` | [`packages/store`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/store) | Durable bounded JSON collections exposed as a typed CRUD API | `extensions.store` plus a protected collection mount |
+| `@jimhoyd/urlcode-forms` | [`packages/forms`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/forms) | Bounded server-rendered form flows: escaped controls, admission, CSRF, validation and a fixed confirmation | `extensions.forms` plus a `GET, HEAD, POST` form mount; it composes with `ui` and optional `auth` |
+
+All six are Apache-2.0. Core is published through npm, GitHub Releases and
+Homebrew. The first-party executable extensions are published as signed,
+immutable GitHub Release bundles; their source remains in these workspace
+packages, but new sites do not install them from npm. The forms package is an
+unreleased bundle source and is not implied by the currently recorded bundle
+release. The legacy extension npm
+packages are deprecated migration artifacts. A release channel is not an
+independent assessment: review, deployment
 evidence and an accessibility assessment are still pending
 ([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)). Their status
 files say exactly what is built: [auth](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/IMPLEMENTATION-STATUS.md),
@@ -104,33 +107,40 @@ Each rung's YAML is valid on every rung above it.
 6. **Your own look.** A shared `presentation` (catalogue and theme variables)
    restyles auth and admin together; the `ui` extension adds the template kit,
    project copy, template and stylesheet overrides for kit-rendered pages.
+7. **Bounded data and forms.** The `store` extension supplies declared durable
+   collections; the `forms` extension supplies declared browser form flows over
+   the shared UI kit. Both are trusted operator extensions, not core YAML
+   handlers. Add `auth: true` where a flow or collection is per-account.
 
 Stored short links previously sat here as a native `link` route; that handler
 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 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
+Rungs 1 to 3 need only the core package. Rungs 4 to 7 need a verified extension
+bundle installed into an explicit operator host, once its source package appears
+in a selected catalog. Auth and admin additionally need the Node/SQLite runtime
+their packages document; forms declares Node, AWS and Vercel targets, while store
+is currently Node-only. 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),
+[store](https://github.com/jimhoyd-com/urlcode/blob/main/packages/store/README.md), [forms](https://github.com/jimhoyd-com/urlcode/blob/main/packages/forms/README.md)) for the
 exact requirement.
 
 ### The composition contract
 
-An extended project starts from the current stable packages and one command.
-`--save-exact` records the concrete versions selected from the independent
-`latest` channels:
+An extended project starts from core and an immutable bundle release. The
+release is an explicit operator choice; use the current verified tag from
+[package and channel alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md):
 
 ```sh
-npm install --save-exact @jimhoyd/urlcode@latest @jimhoyd/urlcode-ui@latest @jimhoyd/urlcode-auth@latest @jimhoyd/urlcode-admin@latest
-urlcode init my-site --with ui,auth,admin
+npm install @jimhoyd/urlcode
+npx urlcode init my-site --with ui,auth,admin --bundle-release extension-bundles@v…
 ```
 
-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.
+This produces a manifest with core only and a bundle lockfile for extensions.
+`scripts/pack-sources.mjs` remains available to review reproducible source
+inputs. Three files make an extended project. Nothing else is discovered by
+convention.
 
 ```
 site/
@@ -202,34 +212,32 @@ package behavior.
 A signed declarative artifact is a separate, optional authoring input, not a
 fifth way to compose executable behavior. A project may lock an attested
 schema/example bundle and expose it through MCP `get_extension_artifacts` and
-`get_extension_artifact`; the npm package and operator host remain the only
-executable extension path. See [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts).
+`get_extension_artifact`; the verified executable bundle and explicit operator
+host remain the executable extension path. See [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts).
 
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
 ```
 
-`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
-package is missing or two fragments collide (the contract is documented under
+`urlcode init <dir> --with ui,auth,admin --bundle-release
+extension-bundles@v…` writes this layout in one step. It verifies and locks the
+named GitHub Release bundles, calls each verified module's `scaffold` export,
+and merges fragments into `app/urlcode.yaml`, one
+explicit `host.mjs` and one `README.md`, refusing before writing a site when a
+bundle is missing or two fragments collide (the contract is documented under
 [scaffolding](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#scaffolding-with-init---with)). `urlcode-auth init`
 and `urlcode-admin init` write the same layout for a single package; `urlcode-auth bootstrap` creates the first
 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`,
+The presentation tooling composes the same way, by naming logical extensions
+rather than npm dependencies. The UI bundle is the kit until the locked auth
+and admin bundles add their namespaces, 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.
+extension template is checked against the shipped view model. `urlcode init
+--with --bundle-release` writes the release pin into the generated README.
 
 ### Rules an agent must follow
 
@@ -314,6 +322,13 @@ needed schema, example or README. Context is a summary with the
 constraints and exact commands, not a schema dump, and it never hides a
 capability limit: ask `capabilities NAME` before promising a feature.
 
+When a goal spans routes, persistence or extensions, the next bounded query can
+be `urlcode plan-feature "goal" --project DIR --json` (MCP `plan_feature`). It
+matches only the current compiled project, capability catalog, bundled recipes,
+locked inert artifacts and registrations already available to the session. Read
+its operator prerequisites and explicit gaps as constraints, not as permission
+to select packages, storage, keys or grants in project YAML.
+
 The complete catalogs (`urlcode capabilities`, `recipes list`), the compact
 [llms.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms.txt) index and the generated [llms-full.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms-full.txt)
 stay available as deliberate fallback and reference, not as the opening move.
@@ -508,12 +523,12 @@ this project's own redirects — cheaper than this table or the recipe catalog.
 |---|---|---|
 | Fixed redirect (301/302/303/307/308, 302 default) | `redirect: {url, status}` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
 | Parameterized path redirect (`/users/{id}` to `/profiles/{id}`) | `{name}` placeholder in `redirect.url` naming a declared path parameter | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
-| Fixed-depth suffix redirect (`/legacy/a/b` to `/modern/a/b`) | one route per depth, one placeholder per segment | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Root-relative redirect (`/users/{id}` to `/profiles/{id}`) | `redirect.url: /profiles/{id}`: one leading slash, path only, `{name}` placeholders | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Wildcard/suffix redirect (`/legacy/**` to `/modern/{**}`, any depth) | terminal `/**` route key with a literal prefix, `{**}` in the destination path; redirect only, not static or Cloudflare | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
 | Redirect that preserves query keys | `redirect.query.pass` (explicit allowlist) or `query.map` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
 | Redirect that keeps the method/body (POST) | `methods` plus `status: 307` or `308` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
 | 404 for unmatched paths | `site.notFound` (a project-relative `.html` file) | [site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md) |
-| Wildcard/suffix redirect (`/legacy/*` to `/modern/*`, any depth) — **gap** | not expressible; terminal `/*` and `{rest...}` are refused on `redirect` | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md) |
-| Host-based, scheme-based or relative-URL redirect — **gap** | not expressible; destination must be a literal absolute `https://host/path` | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md) |
+| Host-based or scheme-based redirect — **gap** | not expressible; destination is a literal absolute `https://host/path` or a root-relative path | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md) |
 | Security headers (CSP, HSTS, frame and referrer policy) | `policies.security: {headers: oshp}` or `policies.profile: hardened` | [security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/security.md) |
 | Cache headers on a page, download or static mount | `cacheControl`: `no-cache` (default), `no-store`, `public, max-age=3600` or `public, max-age=31536000, immutable`; nothing else validates | [assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/assets.md) |
 | A cache strategy on any route | `policies.cache` | [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md) |
@@ -537,8 +552,9 @@ Which handler serves the response:
 Data persistence has no native handler. The operator-installed `store` extension
 serves declared collections as a CRUD API, and `urlcode recipes search "crud store
 persist"` finds the `store-crud` recipe. It needs the operator to install
-`@jimhoyd/urlcode-store` (on npm) and a host file. `init --with
-ui,auth,store` scaffolds one from the published packages; a no-auth
+an attested executable bundle and a host file. `init --with
+ui,auth,store --bundle-release extension-bundles@v…` scaffolds the supported
+npm-free form; a no-auth
 `--with store` needs `--ack store:public-write`, which only a core release after the
 store's first publication has, so say so rather than promising it. Report anything beyond that recipe (filtering, sorting, per-record
 ownership, a database) as a gap. `urlcode context` lists the same built-ins so
@@ -757,7 +773,7 @@ programmatic compatibility analysis and provider verification limits.
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-GUIDE.md
 
 <!-- urlcode-current-version:start -->
-This guide targets URLCode 0.4.8. Start with the function example below,
+This guide targets URLCode 0.5.5. Start with the function example below,
 then add only the fields your route needs. The authoritative machine-readable
 shape is [JSON Schema](https://github.com/jimhoyd-com/urlcode/blob/main/schemas/urlcode.schema.json); semantic rules are in the
 [specification](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPECIFICATION.md). Unsupported fields fail validation.
@@ -898,6 +914,7 @@ schema-valid combinations activate successfully.
 | `routes.*.env.* (option 1).value` | string | yes | — |
 | `routes.*.env.* (option 2)` | object | no | unknown keys rejected |
 | `routes.*.env.* (option 2).env` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.env.* (option 2).default` | string | no | — |
 | `routes.*.secrets` | object | no | — |
 | `routes.*.secrets.*` | object | no | unknown keys rejected |
 | `routes.*.secrets.*.secret` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
@@ -1327,7 +1344,8 @@ Keys are absolute case-sensitive paths. Trailing slashes are significant.
 Parameters occupy whole segments, e.g. `/p/{id}`, with distinct identifier names.
 Each parameter matches exactly one nonempty segment, never across `/`; it is not
 greedy. No regex paths, client-controlled host dispatch or dot segments. Only static directory mounts
-support a terminal `/*` wildcard with an otherwise literal path. Route keys cannot contain
+support a terminal `/*` wildcard with an otherwise literal path; a `redirect` alone supports a
+terminal `/**` (one or more remaining segments, at least a one-segment literal prefix, see [route matching](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ROUTING.md)). Route keys cannot contain
 percent encoding, spaces, backslashes or query strings. Path length is limited
 to 2,048 characters and 32 segments. `/_urlcode` is reserved.
 
@@ -1466,7 +1484,9 @@ Unknown query keys are ignored unless explicitly passed by a redirect.
 ### Redirects
 
 `redirect.url` is an absolute HTTP(S) URL with literal scheme/host and no embedded
-credentials or whitespace/control characters. `{pathInput}` placeholders are
+credentials or whitespace/control characters, or a root-relative path (one leading `/`, never
+`//`, no dot segments) that answers a path-only `Location`. On a `/**` route `{**}` is the captured
+suffix, once, each segment encoded. `{pathInput}` placeholders are
 allowed only in the destination pathname and encoded as single components.
 No environment/secret interpolation. Status defaults to 302; allowed values are
 301, 302, 303, 307 and 308.
@@ -1590,12 +1610,17 @@ parity for a `sandbox: true` route; a trusted route has no such restriction.
 
 Context contains `inputs.path/query/header`, `args`, `env`, `secrets`. Arguments
 may be scalar literals, input references, `{env: alias}` or `{secret: alias}`.
-Bindings use `{value: "literal"}`, `{env: EXTERNAL_NAME}` or `{secret: logical_name}`.
-Literal non-secret values need no grant. Every external environment or secret
-binding is denied unless an operator policy grants that exact name to the route
-and matches the SHA-256 of the current configuration/source snapshot.
-A project cannot grant itself capabilities. See [policy setup](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md).
-Missing bindings also reject activation. Inspection parses source without running it.
+Bindings use `{value: "literal"}`, `{env: EXTERNAL_NAME}`,
+`{value: "default", env: EXTERNAL_NAME}` or `{secret: logical_name}`. The
+combined form resolves to the process environment variable when set and
+non-empty, else `value`; it needs the same operator grant as `{env: ...}`
+alone. Literal non-secret values need no grant. Every external environment or
+secret binding is denied unless an operator policy grants that exact name to
+the route and matches the SHA-256 of the current configuration/source
+snapshot. A project cannot grant itself capabilities. See
+[policy setup](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md). Missing bindings reject activation
+(the combined form always resolves, via its default). Inspection parses
+source without running it.
 
 Development may read `.env.local`; process values win. Serving never reads it.
 Dotenv supports single-line NAME=value, paired single/double quotes, blank lines
@@ -1709,6 +1734,7 @@ not part of the route key.
 | `/go` | `/go`, `/go?campaign=spring` | `/Go`, `/go/`, `/go/extra` |
 | `/r/{code}` | `/r/abc`, `/r/123` | `/r/`, `/r/abc/extra` |
 | `/r/{code}/details` | `/r/abc/details` | `/r/abc/other/details` |
+| `/legacy/**` with a `redirect` handler | `/legacy/a`, `/legacy/a/b/c` | `/legacy`, `/legacy/`, `/legacy/a//b` |
 | `/assets/*` with a `static` handler | Files under `/assets/`, including `/assets/css/site.css` | `/assets`, `/assets-other/site.css` |
 
 A `{parameter}` captures exactly one nonempty path segment. It is **not greedy**:
@@ -1721,8 +1747,16 @@ path. It covers the remaining nested file path; it is not a named capture or a
 regex operator. Matching a mount does not guarantee a response file exists:
 missing files return 404. It is not a catch-all for functions or redirects.
 
+A `redirect` handler alone supports a terminal `/**` after a literal prefix (never bare `/**`, never
+with a `{parameter}`). It matches one or more remaining segments, and `{**}` in `redirect.url` is
+those segments, each percent-encoded and joined by `/`, usable once and only in the destination
+path. Empty segments, `.`/`..`, encoded slashes and captures over 1,024 characters do not match.
+Exact and `{parameter}` routes always win over it, so `/legacy/keep/{id}` can carve an exception out
+of `/legacy/**`. It is refused on static hosting (S3 redirects match one path) and on Cloudflare
+until the Worker table supports suffix matching, and it cannot share a prefix with a `static` mount.
+
 No regex routes, greedy parameters, optional segments, partial-segment parameters,
-`**` globs, or regex constraints inside `{code}` are implemented. Characters such
+other `**` globs, or regex constraints inside `{code}` are implemented. Characters such
 as `.` and `+` have no regex meaning in a literal path. Do not paste a regex into
 a route key: some regex-looking text is legal literal text, while unsupported
 syntax may fail validation. Parameter-schema `pattern` is also unsupported.
@@ -2821,7 +2855,7 @@ Extensions are trusted operator modules, separate from a project's own
 `function`/`middleware` code. Auth
 and admin implementations live in `urlcode-auth` and `urlcode-admin`; the runtime
 supplies only the generic integration contract. No project file can import a host
-extension or choose its npm package.
+extension, choose a bundle release, or choose an npm package.
 
 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
@@ -2833,6 +2867,13 @@ The `store` extension is the data-owning counterpart: it serves declared,
 bounded collections as a CRUD API from an operator-owned directory. See
 [data store](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STORE.md).
 
+The `forms` extension is the browser-flow counterpart: it renders bounded
+declared fields through the `ui` kit, validates URL-encoded submissions with
+its host-supplied CSRF secret, and redirects a successful submission to a
+fixed confirmation page. It is a trusted operator extension, needs `ui`, and
+may be mounted with `auth: true`; its optional `onSubmit` hook is trusted
+project code rather than a sandbox bridge. See the [forms package](https://github.com/jimhoyd-com/urlcode/blob/main/packages/forms/README.md).
+
 A project declares versioned configuration and exclusive route mounts:
 
 ```yaml
@@ -3217,29 +3258,24 @@ Assembly rules, in the resolved order:
 
 #### 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.
+`init --with --bundle-release extension-bundles@v…` writes a private
+`<directory>/package.json` pinning the running core and an extension bundle
+lockfile naming the verified archives. It does not add extension npm
+dependencies. Before anything is written, the selected catalog checks every
+required extension and core compatibility; a missing requirement or incompatible
+bundle 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.
+`package-lock.json` until you run `npm install` in it yourself for core, which
+the command and generated README both state as the next step. Bundle
+reproducibility comes from the committed lockfile and frozen cache, not npm.
 
 - `--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.
+- `--pin <package>=<specifier>` is only for reviewed local source development.
+  New first-party extension installs use the signed bundle release instead.
 
 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
@@ -3260,9 +3296,8 @@ extension artifact for tooling that understands its declared format. It is not
 a Node module and cannot activate an extension, run a hook, replace a trusted
 operator host, or grant a route any authority.
 
-Install an artifact only from its immutable `extensions@v…` GitHub Release.
-For example, after the first release is published, its inert store configuration
-schema snapshot can be installed with:
+Install an artifact only from its immutable `extensions@v…` GitHub Release. The
+published inert store configuration schema snapshot can be installed with:
 
 ```sh
 urlcode extension-artifacts install store-schema --artifact-release extensions@v1.0.0 --project app
@@ -3310,6 +3345,71 @@ not the `@jimhoyd/urlcode-store` implementation. Installing it does not install
 or activate that package. Its README names the separate executable and operator
 requirements.
 
+### Signed executable extension bundles
+
+Official executable extensions are delivered through a separate, immutable
+`extension-bundles@v…` GitHub Release namespace;
+it is intentionally disjoint from the permanently data-only `extensions@v…`
+artifact channel above. A bundle is a bounded, frozen Node module tree produced
+from reviewed first-party source, not a general extension marketplace and not
+a project dependency resolver.
+
+An operator explicitly installs one named bundle from an immutable release:
+
+```sh
+urlcode extension-bundles install store \
+  --bundle-release extension-bundles@v1.0.0 --project app
+```
+
+For a new composed site, `init --with` can perform that verified installation
+before it writes the route project. This is the npm-free extension path: the
+generated `package.json`, when requested, pins URLCode core only; the generated
+host loads only the names recorded in the bundle lockfile.
+
+```sh
+urlcode init site --with ui,auth,admin \
+  --bundle-release extension-bundles@v1.0.0
+```
+
+`init` verifies each requested bundle in a temporary operator staging root,
+obtains each scaffold from that verified module tree, then writes the cache and
+`urlcode.extension-bundles.lock.json` into the new site. It never resolves an
+extension package from npm in this mode. A failed verification or scaffold
+refusal leaves no site directory behind. The release tag is still an explicit
+operator choice; YAML cannot supply it.
+
+The command verifies attestations for both the catalog and selected archive
+against the requested tag and dedicated workflow, rejects self-hosted runners,
+checks the catalog's commit, filename and SHA-256, and extracts only regular
+files in the signed module tree. It writes
+`urlcode.extension-bundles.lock.json` and keeps the frozen bytes under
+`app/.urlcode/extension-bundles/<sha256>/`. There is no automatic discovery,
+installation, update, or fallback to npm. `inspect` reads the committed lock;
+a modified cache or an incompatible core version refuses before import.
+
+Executable bundles are **trusted operator code**, exactly like a hand-written
+operator host module. Project YAML cannot choose a bundle, name a release,
+trigger a download, or grant a bundle authority. An operator host explicitly
+loads a locked entry by name, then chooses which returned registration to pass
+to `createRuntime`:
+
+```js
+import { loadExtensionBundle } from '@jimhoyd/urlcode/extension-bundles';
+
+const { storeExtension } = await loadExtensionBundle('/absolute/site/app', 'store');
+export default { extensions: [storeExtension({ directory: '/srv/site-data', projectSha256: process.env.PROJECT_SHA256 })] };
+```
+
+This does not make bundle code sandboxed and does not alter a route that
+declares `sandbox: true`; those remain distinct execution modes. The signed
+bundle path is the supported distribution for first-party executable
+extensions. The legacy `@jimhoyd/urlcode-ui`, `@jimhoyd/urlcode-auth`,
+`@jimhoyd/urlcode-admin`, and `@jimhoyd/urlcode-store` npm packages are
+deprecated migration artifacts: existing projects may retain their locked
+copies, but new projects must use a verified bundle release. Their npm
+retention status is not a promise that they are available or supported for new
+installs.
+
 ---
 
 # Composing a site from ui, auth and admin
@@ -3320,10 +3420,16 @@ 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
+npm install @jimhoyd/urlcode
+npx urlcode init site --with ui,auth,admin --bundle-release extension-bundles@v…
 ```
 
+Use the immutable bundle release recorded in [package and channel
+alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md). This creates a site whose npm manifest pins
+core only; UI, auth and admin are verified, locked GitHub Release bundles.
+The legacy extension npm packages are deprecated migration artifacts. New sites
+obtain extensions from the verified bundle release.
+
 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:
 
@@ -3501,9 +3607,10 @@ not run it. With the packages named:
   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.
+`urlcode init <directory> --with ui,auth,admin --bundle-release
+extension-bundles@v…` writes these commands into the generated README with the
+verified bundle release pinned. The operator names the logical extensions; it
+does not add extension npm dependencies.
 
 Run the extension's published `fastChecks` while editing. Theme and copy changes
 need no framework build. Template and CSS checks load only the UI kit and named