@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.2

package/docs/OPEN-DECISIONS.md

@@ -1,6 +1,7 @@
 # Decisions to align
 
-Reviewed 2026-09-19 against core `db375bf` and the current public package sources.
+Last reconciled 2026-09-20 against open and closed issues (#242); the source
+review it began from is dated 2026-09-19 (core `db375bf`, now archived).
 This is the maintainer's decision list, not a second implementation backlog.
 The [roadmap](../ROADMAP.md) gives sequence and the [archive](archive/README.md)
 keeps earlier discussions. Recommendations below are not accepted decisions.
@@ -33,27 +34,51 @@ keeps earlier discussions. Recommendations below are not accepted decisions.
 |---|---|---|
 | Where does work status live? | Several old plans repeated issues and continued calling delivered work unfinished. | Issues for actionable status, this short roadmap for sequence, archive for completed proposals. Preserve evidence gaps when archiving. |
 | Expand into business applications now? | No collection handler or proposed business suite is implemented; the model-backed benchmark evidence is missing. | Measure existing tasks and record repeated application plumbing before selecting a collection/CMS/forms project. Retired short-link products stay retired. [Proposal](SPIKE-BUSINESS-SUITE.md). |
-| Which provider execution model next? | AWS/Vercel still reject function/middleware despite the trusted default. | Decide demand first, then compare one Node deployment per project against one Lambda per route. Do not promise either today. [Proposal](SPIKE-LAMBDA-COMPILE.md). |
-| Fold extension schemas into retrieved context? | `urlcode extensions` and the MCP `get_extensions` query return the registered configuration and policy schemas, but `src/context.ts:113` reports `extensions` as names only, so an author writing `extensions.<name>.config` or `policies.extensions.<name>` must run the separate operator-authorized query first. | Decide from retrieval and task evidence, not preference: the existing small-task harness can measure whether folding schemas into bounded context improves authoring. Keep the token budget bounded and never auto-load a project-selected host file. This is a discovery improvement, not a defect in the existing query. |
-| Retire the UI primitive fallback? | Auth and admin use the kit when supplied, and retain tested primitive rendering without it. | Keep both until an explicit compatibility/deprecation decision; adoption is already implemented. |
+| Fold extension schemas into retrieved context? ([#174](https://github.com/jimhoyd-com/urlcode/issues/174), open) | `urlcode extensions` and the MCP `get_extensions` query return the registered configuration and policy schemas, but `src/context.ts:113` reports `extensions` as names only, so an author writing `extensions.<name>.config` or `policies.extensions.<name>` must run the separate operator-authorized query first. | Decide from retrieval and task evidence, not preference: the existing small-task harness can measure whether folding schemas into bounded context improves authoring. Keep the token budget bounded and never auto-load a project-selected host file. This is a discovery improvement, not a defect in the existing query. |
+| Build the tested-image promotion path? ([#233](https://github.com/jimhoyd-com/urlcode/issues/233), open) | [Design and an inert invariant helper](CONTAINER-PROMOTION.md) are merged. `release.yml` still rebuilds from source when `PUBLISH_CONTAINER` is true, and a retry accepts an existing `:VERSION` on its `revision` label alone. Live GHCR state and whether GHCR preserves an OCI digest through `skopeo`/`crane` are unverified. | The reason is integrity (tested bytes are the shipped bytes), not speed: CI's image build took about 12 seconds, so a cross-run build cache is not justified and should not be added. Recommendation: do not implement while publication is off and GHCR is uninspected. First grant `read:packages` and inspect historical labels and digests; then land a candidate-side image build behind an operator input, inspect one real candidate, and only then change the publisher. Not changed here. |
+| Keep the POST-plus-`request.body` sandbox advisory? | `src/readiness.ts` nudges any code-running route that accepts POST with a declared `request.body` and declares neither `sandbox: true` nor `sandboxReason`. It is advisory only: never fails `audit`, never changes `ready`. | The nudge keys on request *shape* while [AI authoring](AI-AUTHORING.md) tells authors to decide on *code* trust, so it can read as "untrusted input implies sandbox" -- the reasoning that guidance explicitly rejects. It still has value as a prompt to record a decision. Recommendation: keep the trigger, restate the message as a request to record the trust decision (`sandbox: true` or `sandboxReason`) rather than as a suggestion that this route may need isolation. Not changed here; #196 was a docs/tooling alignment pass. |
 
 The broader [AI benchmark proposal](SPIKE-AI-FRAMEWORK-BENCHMARK.md) also needs a
 chosen application, model-run budget and execution authorization. The existing
 small-task harness can supply evidence without committing to that larger study.
 
-## Closed questions removed from the active list
+## Accepted: one Node deployment per project
 
-- Publishing convention is recorded in [version alignment](VERSION-ALIGNMENT.md):
-  publishable manifests on main, releases through reviewed tags/workflows.
-- Core `0.4.0-alpha.2` and current extension releases exist; publishing that
-  already-shipped version is not a next step.
-- Auth/admin kit adoption and shared form helpers are implemented in their code.
-- The template pins `0.4.0-alpha.2`. Its skill differences were read against that
-  pin: omitted handlers and advice about the removed management API are stale,
-  not intentional older-version behavior.
-- The guidance checks run through `npm run check` inside `verify`; a regex check
-  is not a schema validator for every example. Extending its coverage is tracked
-  separately, not a reason to weaken review or bypass required checks.
+**Decided 2026-09-19.** Projects that use `function` or `middleware` deploy as
+**one trusted Node process** — a container or a VM running the project as it
+runs locally. That is the supported execution model, and it needs no new work:
+it is what the runtime already does.
+
+**Per-route Lambda compilation is not pursued.** The alternative on the table
+was a build step emitting one Lambda per `function` route
+([the proposal](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md)). It is declined for now, on three
+grounds the proposal itself states:
+
+1. It would replace the sandbox guarantee rather than preserve it, and lose the
+   fresh-per-invocation state that `sandbox: true` currently guarantees.
+2. It would make this project the author of generated IAM roles — a
+   security-critical output it has never owned.
+3. It would trade an honest refusal for a larger claim nobody has deployed.
+
+Against that, a single Node deployment supports every route type today with no
+compiler, no generated infrastructure and no second isolation story to document.
+
+**What follows from this decision:**
+
+- AWS and Vercel continue to refuse `function` and `middleware` at activation,
+  naming the route (`src/capabilities.ts`, `activateNativeOnly` in
+  `src/adapters.ts`). That refusal is now a **deliberate position**, not a gap
+  awaiting an adapter. Documentation should say so rather than implying the
+  support is coming.
+- Serverless targets remain first-class for the declarative route types they can
+  actually serve; nothing about static or native-only deployment changes.
+- [SPIKE-LAMBDA-COMPILE.md](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md) is kept as the analysis
+  behind this decision, not as a plan. Reopen it only on evidence of real demand
+  for URLCode `function` routes specifically on AWS serverless — the proposal's
+  own §6 already scopes what a first attempt would be.
+
+This decision is about the *execution model*, not about AWS. Deploying the Node
+process to AWS (ECS, EC2, App Runner) is an operator choice this fully supports.
 
 ## Accepted: per-package release tags
 
@@ -99,86 +124,26 @@ reasoning above is the kind of prose that rots as soon as `auth` and `admin`
 arrive, which is the whole argument this repository makes for enforcing checks
 over documented intent.
 
-## Done: the monorepo migration is complete
-
-**Closed 2026-09-19.** `urlcode-ui`, `urlcode-auth` and `urlcode-admin` are
-workspace packages under `packages/`, and all three have been released from
-this repository — `@jimhoyd/urlcode-ui@0.1.0-alpha.6`,
-`@jimhoyd/urlcode-auth@0.1.0-alpha.6`, `@jimhoyd/urlcode-admin@0.1.0-alpha.4`,
-each on `alpha` with `latest` deliberately held behind. Core's dist-tags are
-unchanged. The three source repositories are gone; their history survives only
-as verified `git bundle`s, because the repository allows squash merges only and
-the imported commits did not survive onto `main`.
-
-The operational runbook is [DEVELOPMENT-PIPELINE.md](DEVELOPMENT-PIPELINE.md)
-and [RELEASE-SECURITY.md](RELEASE-SECURITY.md). The plan itself is archived at
-[archive/2026-09-19/SPIKE-MONOREPO.md](archive/2026-09-19/SPIKE-MONOREPO.md),
-whose closing note records what the plan got wrong — chiefly that its
-strongest argument, the reach of the enforcing checks, only became true after
-both checkers were changed to discover workspace packages.
-
-The section below is kept for the middleware decision it records, which is
-still the reason there is no `packages/middleware`.
-
-## Accepted: monorepo first — middleware withdrawn rather than consolidated
-
-The maintainer confirmed that monorepo work is starting now. The earlier
-recommendation to keep repositories separate for now is superseded.
-
-**Reversed 2026-09-19: the middleware half of this decision no longer applies.**
-This section used to say "move middleware into the monorepo as its own package
-first, preserving its existing API and behavior," and explicitly: "do not
-unpublish or retire the middleware package as part of the initial move."
-That instruction was overtaken. `@jimhoyd/urlcode-middleware` has been
-**unpublished** from npm at `0.1.0-alpha.2` and `jimhoyd-com/urlcode-middleware`
-**deleted** — the package was withdrawn outright instead of migrated, so there
-is no `packages/middleware` to create and no subsequent fold-into-core step.
-The reversal is recorded here rather than deleted because the instruction it
-replaces was explicit, and a reader who remembers it should be able to see that
-it was changed deliberately and not simply forgotten.
-
-Nothing was lost in capability terms: per-route middleware is **native to
-core** via the `middleware:` array ([MIDDLEWARE.md](MIDDLEWARE.md)), and the
-deleted package only ever offered the same behavior through the extension
-seam. Trust remains the default and explicit sandbox choices keep their
-meaning. The generic extension wrapping hook (`ExtensionInstance.middleware`,
-`RuntimeExtension.cacheSensitive`) stays in core's contract for other
-extensions — it is no longer exercised by any shipped package, which is worth
-knowing before it is assumed to be covered. Static targets continue rejecting
-request-time middleware because there is no server to run it.
-
-Migration scope is therefore **core, auth, admin and UI**. Template and the
-distribution tap stay outside that package move. The observed stale peer pins
-and checkout-limited guidance checks strengthen the case for shared
-verification: carry those checks across the new package paths, since merely
-moving files does not prove every generated skill is covered. The cleanup PRs
-that superseded the earlier zero-open-PR survey have since merged, and a fresh
-survey again reports zero open pull requests across all four in-scope
-repositories — re-run it per repository immediately before that repository
-moves rather than trusting this line.
-
-The [archived monorepo plan](archive/2026-09-19/SPIKE-MONOREPO.md) records
-migration context.
-[Issue 172](https://github.com/jimhoyd-com/urlcode/issues/172), which tracked
-"consolidate middleware into core after moving it into the monorepo," is
-**moot and still open** — there is nothing left to consolidate. It should be
-closed with a pointer to this section. Migration starting is not a claim that
-it has landed.
-
-## Source review baseline
-
-| Repository | Reviewed commit | Code checked |
-|---|---|---|
-| core | `db375bf` | Runtime dispatch, schema normalization, capabilities, static compiler, prerender, MCP and resource generators |
-| auth | `71957dd` | Lifecycle hooks, UI rendering and shared helper imports |
-| admin | `f3b4882` | UI rendering, auth-service integration and shared helper imports |
-| UI | `0e96f7f` | Shared forms, kit/host exports and copied core contract |
-| ~~middleware~~ | `f201f4b` | Extension wrapping, per-entry sandbox dispatch and scaffolding — **repository deleted 2026-09-19; this baseline is unreachable except through the local `urlcode-middleware.bundle`** |
-| template | `4e09e50` | Exact core pin, generated guide and both vendored skills |
-
-The Homebrew tap (`73eaaef`) still selects stable core `0.3.0`; its old trust
-behavior belongs to that pin and must not be rewritten as alpha.2 behavior.
-The other organization tap and Scoop bucket contain Gitroll, not URLCode.
-The deleted documentation repository is historical context, not a second source
-of current contracts; its former GitHub links no longer resolve. This review is targeted source inspection, not an audit of
-every execution path or an independent security assessment.
+## Completed work (archived)
+
+Closed questions, the completed monorepo migration (ui, auth and admin are
+workspace packages; released from this repository) and the 2026-09-19 source
+review baseline live in
+[archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md](archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md).
+The migration plan is [archived](archive/2026-09-19/SPIKE-MONOREPO.md). Versions
+and channels are in [version alignment](VERSION-ALIGNMENT.md) and
+`npm run release:status`, not here.
+
+## Accepted: middleware withdrawn rather than consolidated
+
+**Decided 2026-09-19.** `@jimhoyd/urlcode-middleware` was unpublished and its
+repository deleted; there is no `packages/middleware` and nothing to fold into
+core afterward (#172, closed as moot). Per-route middleware is native to core
+via the `middleware:` array ([MIDDLEWARE.md](MIDDLEWARE.md)). The generic
+extension wrapping hook (`ExtensionInstance.middleware`,
+`RuntimeExtension.cacheSensitive`) stays in core's contract for other extensions
+but is no longer exercised by any shipped package, so do not assume it is
+covered. Static targets keep rejecting request-time middleware. The earlier
+instruction to move middleware into the monorepo first was overtaken; its full
+text is retained in the archived record.
+

package/docs/READINESS.md

@@ -10,9 +10,10 @@ urlcode audit --project ../my-links --expect-routes 2
 urlcode benchmark --project ../my-links --requests 1000 --concurrency 2 --max-p95-ms 50
 ```
 
-All three activate/validate the project with the same isolated runtime and use
-local environment loading like `test`. Pass an external `--policy` for explicitly
-authorized bindings. No destination redirects are followed, credentials are not
+All three activate/validate the project with the same runtime that serves it --
+each route in its own declared trust mode, trusted in-process unless it declares
+`sandbox: true` -- and use local environment loading like `test`. Pass an
+external `--policy` for explicitly authorized bindings. No destination redirects are followed, credentials are not
 printed, and no remote load-test target is accepted.
 
 ## Inventory and count reconciliation
@@ -81,7 +82,10 @@ parameter patterns still need explicit negative fixtures to exercise them.
 
 `ready: true` requires a nonempty active project, matching expected count (when
 supplied), zero failed checks and no uncovered active route/method combinations.
-It means this local gate passed, not that all branches, parameter values or assets
+When `ready` is false, `notReadyReasons` lists each failed condition:
+`no-active-routes`, `route-count-mismatch`, `failed-checks` and
+`uncovered-route-methods` (see `uncovered` for the pairs). `unassertedCases` never
+affects `ready`. It means this local gate passed, not that all branches, parameter values or assets
 have independent business assertions. Function routes intentionally serving only
 errors cannot satisfy normal-response coverage in this release. Time-dependent
 expiry is evaluated at audit start; avoid running a gate exactly at expiry.

package/docs/README.md

@@ -1,10 +1,20 @@
 # URLCode documentation
 
-Start with [the framework](FRAMEWORK.md): the four packages, the ladder from
-redirects to a full application, the composition contract and the rules an AI
-agent must follow. [Project direction](PROJECT-DIRECTION.md) states the
-boundary and the license. Use documentation pinned to your runtime revision;
-`version: "1"` is the stable project-format contract for this release line.
+Choose a starting point, then use the topic directory below when you need detail.
+Use documentation from the same pinned revision as your runtime.
+
+| I want to… | Start here |
+|---|---|
+| Understand what URLCode does | [Framework](FRAMEWORK.md) |
+| Build my first project | [Installation](INSTALL.md), then [YAML guide](YAML-GUIDE.md) |
+| Build a site with UI, accounts and admin | [Composing a site](COMPOSING-A-SITE.md) |
+| Have an AI author a project | [AI authoring](AI-AUTHORING.md), [agent index](../llms.txt) |
+| Deploy and operate a project | [Operations](OPERATIONS.md) |
+| Contribute to URLCode | [Contributing](../CONTRIBUTING.md), [local development](LOCAL-DEVELOPMENT.md) |
+
+The [specification](SPECIFICATION.md) owns implemented semantics; the
+[generated field reference](YAML-REFERENCE.md) lists accepted fields.
+[Project direction](PROJECT-DIRECTION.md) explains the product boundary.
 
 ## Author a project
 
@@ -13,11 +23,9 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Install the CLI | [Installation](INSTALL.md) |
 | Write YAML with examples | [YAML guide and recipes](YAML-GUIDE.md) |
 | Look up every accepted field | [Generated field reference](YAML-REFERENCE.md), [JSON Schema](../schemas/urlcode.schema.json) |
-| Let an AI build routes | [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt) |
 | Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
-| Run examples | [25-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
 | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
-| Run examples | [40-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
+| Run examples | [Executable cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
 | Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
 | Reuse code around routes | [Middleware](MIDDLEWARE.md), [middleware examples](MIDDLEWARE-EXAMPLES.md) |
 | Handle secrets and decide what to sandbox | [Function security](FUNCTION-SECURITY.md) |
@@ -39,11 +47,10 @@ boundary and the license. Use documentation pinned to your runtime revision;
 
 | Goal | Start here |
 |---|---|
-| Add accounts, sign-in and protected routes | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth#readme) |
-| Manage users, sessions, roles and audit | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin#readme) |
+| Add accounts, sign-in and protected routes | [urlcode-auth](../packages/auth#readme), [auth security](../packages/auth/SECURITY.md) |
+| Manage users, sessions, roles and audit | [urlcode-admin](../packages/admin#readme) |
 | Restyle every extension page and translate copy | [urlcode-ui](../packages/ui#readme), [ui contract](../packages/ui/CONTRACT.md) |
 | Write or install a versioned extension | [Extensions](EXTENSIONS.md), [example fixture](../examples/extensions/README.md) |
-| Follow implementation of the auth, admin and UI extensions | [Extension implementation sequence](archive/2026-09-19/EXTENSION-IMPLEMENTATION.md) |
 | Know which core version an extension package supports, and how it says so | [Core version alignment](VERSION-ALIGNMENT.md) |
 | Add host behavior in operator code | [Plugins](PLUGINS.md) |
 | Use the API from TypeScript | [TypeScript: shipped declarations, exports, build and fidelity](TYPESCRIPT.md) |
@@ -59,7 +66,6 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Review security findings and gaps | [Internal security audit](SECURITY-AUDIT.md) |
 | Assess release readiness | [Evidence and open gates](RELEASE-READINESS.md) |
 | See unfinished work | [Roadmap](../ROADMAP.md) |
-| Read the design for compiling function routes into per-route Lambdas | [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) |
 | Verify a running deployment matches the project | [Deployment checks](DEPLOYMENT-CHECKS.md) |
 | Inspect target support | [Capabilities and normalized representation](CAPABILITIES.md) |
 | Deploy to Vercel, AWS Lambda or Cloudflare Workers | [Vercel](VERCEL.md), [AWS](AWS.md), [Cloudflare](CLOUDFLARE.md), [provider verification evidence](PROVIDER-VERIFICATION.md) |
@@ -79,7 +85,6 @@ in the guides above and the [specification](SPECIFICATION.md).
 - [Version alignment](VERSION-ALIGNMENT.md) and [release security](RELEASE-SECURITY.md)
   describe peer compatibility and publication.
 - Open proposals: [middleware layering](SPIKE-CORE-LAYERING.md),
-  [Lambda compilation](SPIKE-LAMBDA-COMPILE.md),
   [agent benchmark](SPIKE-AI-FRAMEWORK-BENCHMARK.md), and
   [business suite](SPIKE-BUSINESS-SUITE.md). None is an implementation promise.
 - [Historical plans and reviews](archive/README.md) are archived separately.

package/docs/RELEASE-0.4.1.md

@@ -0,0 +1,73 @@
+# URLCode 0.4.1
+
+Core, UI, auth and admin share this explicitly selected stable version. This does not enable permanent fixed versioning. Internal peer minimums advance to this version; install the coordinated set together.
+
+```sh
+npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
+```
+
+This coordinated release moves core, UI, auth and admin from `0.4.0-alpha.3` to stable `0.4.1`. It makes the reviewed monorepo release line available through npm `latest` and keeps the four packages' peer minimums aligned.
+
+The runtime retains its existing trust model: project functions and middleware run trusted in Node by default; routes declaring `sandbox: true` retain QuickJS/WASM isolation. The stable label is a distribution decision, not an independent security assessment or hostile multi-tenant readiness claim.
+
+Release preparation now supports an explicit exit from alpha. Publication promotes the exact signed candidate archives, pins their manifest digest in immutable tags, checks actual npm installability, and updates the standalone starter to the published core version. Historical alpha versions and tags remain unchanged.
+
+### admin-kit-only-console.md
+
+**Breaking:** the console renders only through the urlcode-ui kit. `ui` is now a
+required option of `adminExtension` and of `createAdministrationRuntime`'s
+`admin` block, which is itself no longer optional.
+
+`@jimhoyd/urlcode-ui` was already a required peer dependency, so nothing new has
+to be installed. What changed is that the `ui` *extension* must now be supplied
+and active: the primitive render path — the same `admin/*` templates rendered
+through the shared primitives inside a console shell admin built itself — is
+gone, along with the `RenderPath` seam, the `activeKit()` helper, the
+`ScreenOptions.shell.sidebar` markup and `src/admin-presentation.ts`. The kit
+builds the sidebar, page header and skip target from the `nav` items and account
+`menu` admin supplies, so the console shell has one representation instead of
+two. `ScreenOptions.preferences` is gone too: the kit layout now renders through
+the same resolved presentation as the body, so the document's `lang` matches the
+copy on the page.
+
+Activation refuses up front, rather than failing per request in production, when
+
+- `ui` is missing,
+- `ui` is supplied but not active yet — declare `ui` before `admin` under
+  `extensions` in `urlcode.yaml`, since the runtime activates in declaration
+  order, and mount its assets route, or
+- the kit was built without `adminUiTemplates`.
+
+To migrate, build the extension with admin's templates and pass it:
+
+```js
+const ui = createUiExtension({projectSha256, projectRoot, sources: [authCatalogue], extensions: [authUiTemplates, adminUiTemplates]});
+adminExtension({service, csrfKey, projectSha256, ui});
+```
+
+Scaffolding emits that wiring for you: `scaffold()`, `initAdministration` and
+`urlcode init --with ui,auth,admin` compose the kit and register the admin
+templates with it. `ui` is now required, and must come before `admin`; the
+scaffold refuses otherwise before writing anything.
+
+### auth-kit-only-render.md
+
+Breaking: the `ui` extension is now required. Every account screen renders through the `urlcode-ui` kit; the shared-primitive fallback is gone. `authExtension({ui, ...})` refuses activation when `ui` is absent or when the runtime has not activated it, naming the missing piece instead of failing per request. Declare `ui` before `auth` in `urlcode.yaml` (with its asset route) and list `ui.registration` before `authExtension` in the host: the runtime activates extensions in the order `urlcode.yaml` declares them. `@jimhoyd/urlcode-ui` was already a required peer dependency, so nothing new needs installing; what changes is that the extension must be supplied and active. `ScreenOptions.ui` is no longer optional and `screenObserver` no longer reports a render path.
+
+Scaffolding composes the kit for you: `urlcode init --with ui,auth` and the standalone `initAuthentication` now write a project whose `urlcode.yaml` declares `ui` first and whose host passes it to `authExtension`. The scaffold refuses when `ui` is missing, or ordered after `auth`, before anything is written.
+
+### auth-store-startup-diagnostics.md
+
+Report which startup phase an auth store worker reached when its 15-second bound elapses, and reject at once when the worker fails or exits before reporting readiness instead of waiting the bound out. The status and code are unchanged; the detail is attached as the error's cause for operator logs and never reaches a response.
+
+### pin-generated-site-dependencies.md
+
+`urlcode-auth init` now writes a `package.json` that pins this package and each declared peer at the exact version installed beside it, instead of a manifest with no dependencies at all; `initAuthentication` returns those pins and names any peer it could not resolve. Nothing is installed: running `npm install` in the generated directory to produce a lockfile stays the operator's explicit step, and no upgrade command exists.
+
+### ui-scaffold-peer-registration.md
+
+The scaffold wires kit-rendering peers into the host it generates. `scaffold()` reads the composed `names` and emits `createUiExtension({..., sources: [authCatalogue], extensions: [authUiTemplates, adminUiTemplates]})`, importing each peer it needs, so `urlcode init --with ui,auth,admin` produces a project that activates. Previously it always wrote `sources: []` and no `extensions`, which left auth and admin without their copy and templates. `ui` alone still registers nothing and imports no peer.
+
+Name `ui` first: the runtime activates extensions in the order `urlcode.yaml` declares them, core writes that file in `--with` order, and auth and admin both refuse to activate before the kit is active.
+
+Publish to the npm `latest` channel in core → UI → auth → admin order after exact-commit CI and candidate verification. Existing tags and the `alpha` channel stay unchanged; this stable release advances `latest`. Changesets prerelease mode is exited. Update the standalone starter's exact core pin after registry installability is verified. This preparation is not evidence of publication or an independent security assessment.

package/docs/RELEASE-0.4.2.md

@@ -0,0 +1,30 @@
+# URLCode 0.4.2
+
+Core, UI, auth and admin share this explicitly selected stable version. Independent package versioning remains enabled.
+
+```sh
+npm install --save-exact @jimhoyd/urlcode@0.4.2 @jimhoyd/urlcode-ui@0.4.2 @jimhoyd/urlcode-auth@0.4.2 @jimhoyd/urlcode-admin@0.4.2
+```
+
+### admin-copy-project-override.md
+
+Project translations of `adminUi.*` ids in `ui/copy/<locale>.json` now reach the admin console.
+
+In a composed site the console copy source is built with `createAdminPresentation({ base: kit.presentation })`, and the admin ids were resolved only from the bundled English, so a project's `adminUi.*` entries were silently ignored. When a base presentation is given, an admin id the base resolves for the request's locale now wins; otherwise the bundled admin English still answers. Hosts that pass no `base` and hosts that supply their own presentation are unchanged.
+
+### ui-styles-once-per-verify.md
+
+Compile Tailwind once per `npm run verify`.
+
+No API change and no change to the generated stylesheet. `verify` used to run
+`typecheck` then `build`, and each of those runs `styles`, so
+`scripts/build-styles.mjs` compiled the same minified CSS twice per
+verification. `verify` now runs `styles` once and then the compiler-only
+`typecheck:tsc` and `build:tsc` scripts. `typecheck` and `build` are unchanged
+from a caller's point of view: each still runs `styles` first, so either one
+works on its own from a fresh checkout.
+
+Nothing is cached and nothing is skipped because an output already exists; the
+single run is unconditional, so a source change is still picked up.
+
+Publish to the npm `latest` channel only after exact-commit CI and candidate verification. Existing tags and the `alpha` channel stay unchanged. Update the standalone starter after core registry installability is verified. This preparation is not evidence of publication or an independent security assessment.

package/docs/RELEASE-READINESS.md

@@ -1,13 +1,14 @@
 # Release readiness
 
-Status: `0.4.0-alpha.2` (`package.json`) alpha of the extension contract and
-agent tooling on top of the `0.3.0` self-hosted release; `0.4.0-alpha.1` is the
-most recent alpha actually published; the npm dist-tags for `@jimhoyd/urlcode`
-were `latest` = `0.3.0` and `alpha` = `0.4.0-alpha.1` when checked against the
-registry on 2026-09-19, so the repository's `0.4.0-alpha.2` is unpublished (see
-"Packaging" below). Production approval remains specific to
-the workload and deployment environment.
-This register describes the current public runtime, not future promises.
+Status: this register records evidence and open gates for the public runtime.
+It deliberately carries no current version table: the manifests are the version
+authority, [VERSION-ALIGNMENT.md](VERSION-ALIGNMENT.md) explains channels and
+ownership, and `npm run release:status` reads live registry and tag state. A
+stable release is a packaging fact. It is not production approval and does not
+perform any gate under "Gates before production approval" below; neither does a
+passing CI run. Production approval remains specific to the workload and
+deployment environment. Registry channels and deployments were not re-checked
+when this register was reconciled on 2026-09-20 (#242).
 Use the contract and docs from the same pinned commit as your installed runtime.
 
 ## What is aligned
@@ -41,7 +42,34 @@ deferred to the post-merge run.
 | Worker replacement | Repeated guest deadlines shed load and the pool returns to service after backoff, rather than latching off for the life of the process | Bounded by the configured worker count; no cross-process load balancing |
 | Shutdown | New work rejects; repeated close shares completion | Existing deadlines can still fail during shutdown |
 | Activation/recovery | Invalid reload retains last-good snapshot; corrupt revision metadata rejects activation | No deployment orchestration |
-| Packaging | Packed installation and starter examples tested; sensitive files excluded | `0.3.0` and `0.4.0-alpha.1` are published to npm as `@jimhoyd/urlcode` (`latest` and `alpha` dist-tags respectively; dist-tags verified against the npm registry on 2026-09-19, when the repository stood at the unpublished `0.4.0-alpha.2`). Published extension packages on the same date: `@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`, `@jimhoyd/urlcode-ui@0.1.0-alpha.4`. (`@jimhoyd/urlcode-short@0.1.0-alpha.1`, `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1` and `@jimhoyd/urlcode-middleware@0.1.0-alpha.2` were also published on that date, then retired and unpublished later the same day; all three repositories were deleted. Middleware's withdrawal removed no capability — per-route middleware is native to core.) Observed in passing on that date: auth's dist-tags were split — `alpha` at `0.1.0-alpha.2` while `latest` lagged at `0.1.0-alpha.1`, so a plain `npm install @jimhoyd/urlcode-auth` resolved a build below admin's declared floor. That is resolved: auth and admin both read `latest` = `alpha` = `0.1.0-alpha.3`. `@jimhoyd/urlcode-ui` now carries a split of its own — `alpha` = `0.1.0-alpha.6`, `latest` = `0.1.0-alpha.5` — which is deliberate rather than drift, and safe only because admin's ui floor is exactly `>=0.1.0-alpha.5`. See [VERSION-ALIGNMENT.md](VERSION-ALIGNMENT.md). GitHub Releases attach a Homebrew formula (`urlcode.rb`) for manual copy into a tap, not an automated Homebrew Core/tap publish. No provider adapter guarantee. |
+| Packaging | Packed installation and starter examples tested; sensitive files excluded | Published versions and channels: see VERSION-ALIGNMENT.md and `release:status`; this row asserts none. Dated registry observations are kept under "Dated packaging observations" below. GitHub Releases attach a Homebrew formula (`urlcode.rb`) for manual copy into a tap, not an automated Homebrew Core/tap publish. No provider adapter guarantee. |
+
+## Dated packaging observations
+
+Kept as observed; each is true only of its date and none is current status.
+Use `npm run release:status` for the present.
+
+- **2026-09-19, registry check.** `@jimhoyd/urlcode` had `latest` = `0.3.0` and
+  `alpha` = `0.4.0-alpha.1`; the repository then stood at `0.4.0-alpha.2`, which
+  was unpublished. Published extension packages that day:
+  `@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`,
+  `@jimhoyd/urlcode-ui@0.1.0-alpha.4`.
+- **2026-09-19, retired packages.** `@jimhoyd/urlcode-short@0.1.0-alpha.1`,
+  `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1` and
+  `@jimhoyd/urlcode-middleware@0.1.0-alpha.2` were published that day, then
+  retired and unpublished later the same day; all three repositories were
+  deleted. Middleware's withdrawal removed no capability: per-route middleware
+  is native to core.
+- **2026-09-19, observed in passing.** auth's dist-tags were split (`alpha` at
+  `0.1.0-alpha.2`, `latest` at `0.1.0-alpha.1`), so a plain install resolved a
+  build below admin's declared floor.
+- **Later 2026-09-19 or after (the source did not date these; treat as
+  superseded).** auth and admin both read `latest` = `alpha` =
+  `0.1.0-alpha.3`, resolving the split above; `@jimhoyd/urlcode-ui` carried a
+  deliberate `alpha` = `0.1.0-alpha.6` / `latest` = `0.1.0-alpha.5` split, safe
+  only because admin's ui floor was exactly `>=0.1.0-alpha.5`. The stable
+  `0.4.1` alignment described in [VERSION-ALIGNMENT.md](VERSION-ALIGNMENT.md)
+  postdates these.
 
 `npm run check:downstream-skills` is a manual, advisory report worth running
 before a release: it diffs core's `.claude/skills/` copies against copies
@@ -80,7 +108,8 @@ benchmark into a universal throughput claim.
    extension needs its own backup/restore drill; core has no durable store.
 4. Alerting and ownership for sustained errors, latency, readiness, dropped logs,
    disk space, restarts and backups. Pick service objectives for the actual app.
-5. Stable-release support commitments before packaging/public reuse claims.
+5. Stable-release support commitments before packaging/public reuse claims;
+   a stable release exists, but that does not by itself record such commitments.
    Private security reporting and the current support baseline are documented in
    SECURITY.md.
 
@@ -88,7 +117,7 @@ License selection is resolved: URLCode is released under the Apache License 2.0,
 `package.json` declares it, and the repository carries the full license text.
 The remaining gates above are engineering and operational, not legal.
 
-The unreleased next-phase source now includes strict bulk/provider interchange,
+The next-phase source (shipped in the alpha releases; see the archived plan) includes strict bulk/provider interchange,
 local recipes, TypeScript authoring, bounded self-hosted proxy/signals and read-only
 MCP. Local AWS/Vercel/Cloudflare adapter tests and deployment probe tooling exist,
 but actual provider deployments remain unverified. Node process/container hosting

package/docs/RELEASE-SECURITY.md

@@ -18,16 +18,18 @@ means a successful nightly or manual `ci.yml` run across every supported OS/Node
 combination; the compact push/PR matrix alone does not authorize publication. Package manifests,
 lockfile versions and tag names must agree. Published peer floors must exist and
 extension tests must resolve the published packages, not workspace source.
-The manual core candidate and tagged core release use the same preparation
-script with the digest-pinned Node image from Dockerfile. Locked dependencies,
+The candidate builds all package archives once using the digest-pinned Node
+image from Dockerfile; publishers promote those exact signed bytes. The builder
+installs Git from Debian for repository-fixture tests; Git is a test dependency,
+not an addition to the runtime image or npm package. Locked dependencies,
 verification, runtime audit, package installation tests and local drills precede
 packing. Build commands in that container receive no GitHub token.
 
 The candidate workflow stores artifacts without publishing. A tagged release
 publishes npm only when `PUBLISH_NPM=true` and core images only when
-`PUBLISH_CONTAINER=true`. Preparation retains original artifacts for 90 days
-before publication so reruns of the same run reuse them. Manual candidates retain
-their existing 30-day retention. Keep independent last-good artifacts and
+`PUBLISH_CONTAINER=true`. Candidate and release artifacts are retained for 90 days, and each package
+GitHub release stores the complete signed candidate bundle. Retries verify and
+reuse original retained or durable bytes; missing originals fail closed. Keep independent last-good artifacts and
 rehearse deployment rollback; Actions retention is not an archival guarantee.
 
 ## Identity and provenance
@@ -39,9 +41,12 @@ requires a reviewed registry trust migration. Successful preparation does not
 prove the registry-side identity permits direct publication.
 
 `actions/attest` signs the candidate files with GitHub OIDC/Sigstore provenance.
-Core includes its package archive, dependency SBOM, build manifest, checksums,
-and, for a release, Homebrew formula. Extensions include their archive and
-checksums. The core manifest records source SHA, lockfile hash, Node and
+The candidate bundle includes all four archives, dependency SBOM, build manifest,
+train metadata, checksums and Homebrew formula. Each publisher retains that
+bundle and publishes only its selected npm archive. New annotated version tags
+pin the candidate run ID and signed-manifest SHA256. The run ID is also bound
+into the manifest; the digest prevents another attempt of that run from
+substituting different artifacts. The core manifest records source SHA, lockfile hash, Node and
 TypeScript versions and emitted-file hashes. `dist/` is built, never committed.
 
 Verify an artifact with `gh attestation verify <tarball> --repo
@@ -59,18 +64,26 @@ identical SHA-512 integrity. GitHub assets are compared and missing assets added
 existing unequal assets are never clobbered. Transient registry errors fail
 closed rather than count as an unpublished version.
 
-Alpha versions use npm/GHCR `alpha` and GitHub prerelease classification. New
-GitHub releases are not automatically promoted to GitHub `latest`. Mutable npm
+Alpha versions use npm/GHCR `alpha` and GitHub prerelease classification.
+Explicit stable versions use npm `latest` and normal GitHub releases. Only the
+stable core release advances GitHub `latest`, so the core installer cannot pick
+an extension release. Stable preparation removes Changesets prerelease mode;
+existing alpha artifacts, tags and channel pointers remain unchanged. Mutable npm
 and container channels cannot regress to an older version. Existing core image
 versions are reused only with matching source labels; unlabeled historical
 images require a reviewed migration rather than an inferred identity.
 
-The coordinator creates one package tag at a time and waits for success before
-releasing dependents. Shared publication concurrency avoids cross-version races.
+The coordinator verifies candidate availability and provenance before creating
+any version tag, then creates one at a time and waits for successful publication
+and consumer-facing registry installability before releasing dependents. Shared publication concurrency avoids cross-version races.
 The active immutable-tag rule blocks release tag updates/deletions with no
 bypass actors; its configuration is in `.github/rulesets/release-tags.json`. No automation needs permission to bypass main checks or approve
-its own PR. A repository-scoped GitHub App is the preferred eventual automation
-identity; a narrowly scoped fine-grained PAT can support a maintainer script.
+its own PR. Manual package/all release workflows share the coordinator and need
+`RELEASE_AUTOMATION_TOKEN` because events created by the ordinary `GITHUB_TOKEN`
+do not trigger tag publishers. A repository-scoped GitHub App is preferred. A
+fine-grained PAT may select only `urlcode` and `urlcode-template`, with Contents,
+Pull requests and Actions read/write plus Checks read. Neither identity needs
+ruleset bypass, administration, npm secrets or review approval.
 
 ## Remaining validation
 
@@ -79,3 +92,9 @@ publish path, OIDC trust for every package, tag protection, GHCR behavior and
 partial-failure recovery must be verified on an authorized release; local tests
 and workflow inspection cannot prove them. The release helpers do not alter
 historical npm channels, GitHub flags, tags or registry artifacts.
+
+The coordinated `.3` release proved the existing OIDC identities, but exposed
+missing-artifact retry behavior tracked in #223. New workflows fail closed or
+recover verified durable bytes; old immutable tags retain their original
+workflow code. The new promotion path still needs a future explicitly authorized
+release rehearsal; implementing it does not publish a new version.

package/docs/SPECIFICATION.md

@@ -202,7 +202,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](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,

package/docs/SPIKE-CORE-LAYERING.md

@@ -35,7 +35,7 @@ either is blocked on the other.
 Core's job is to stay the smallest thing that is still a complete product on
 its own: YAML routing (`redirect`/`respond`/`page`/`static`/`download`) plus
 `function`, the one primitive with an actual serverless story
-([`SPIKE-LAMBDA-COMPILE.md`](SPIKE-LAMBDA-COMPILE.md) — compile each `function`
+([`SPIKE-LAMBDA-COMPILE.md`](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md) — compile each `function`
 route to its own Lambda, the pattern `src/build-cloudflare.ts` already uses).
 That base alone serves static and dynamic content and deploys anywhere
 (`docs/FRAMEWORK.md` layer 1–3). Everything past that — accounts, admin,