@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.1

package/docs/INSTALL.md

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

package/docs/MIDDLEWARE.md

@@ -48,12 +48,18 @@ Every middleware and the function share the same request and context. Validated
 with a fresh `context.state` object for this chain. State never survives the
 request. Header edits are visible downstream; editing the request does not
 reroute it or change already validated inputs. Request bodies are single-use:
-reading one consumes it for downstream code. There is no `clone()` or streaming
-API; pass parsed data through `context.state` when needed.
+reading one consumes it for downstream code. On a `sandbox: true` route there is
+no `clone()` or streaming API at all, so pass parsed data through
+`context.state`; a trusted route receives Node's own `Request`/`Response` and so
+does have `clone()`, but passing parsed data through `context.state` keeps the
+chain portable between the two modes.
 
 Function responses support the existing text/JSON guest API. To transform their
-body, read it and return a new `Response`. Native redirect/respond/page/static/
-download bodies are opaque and cannot be read through `text()` or `json()`.
+body, read it and return a new `Response`. On a `sandbox: true` route, native
+redirect/respond/page/static/download bodies are opaque and cannot be read
+through `text()` or `json()`; a trusted chain receives them as an ordinary
+`Response` and can read them, so wrapping `respond: {text: hello}` and returning
+`HELLO` works there and fails in the guest.
 Returning the same native response preserves original bytes, including binary
 files, ranges and HEAD lengths. You may add headers, but cannot change its
 original status or existing native headers while preserving that body. To replace

package/docs/OPEN-DECISIONS.md

@@ -33,9 +33,8 @@ 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. |
+| 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
@@ -48,6 +47,10 @@ small-task harness can supply evidence without committing to that larger study.
 - 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 UI primitive fallback is retired, which settles the question this table
+  carried. Auth and admin now render every screen through the kit and refuse
+  activation without it (`packages/auth/src/auth.ts`: "there is no
+  shared-primitive fallback"), so "keep both" no longer describes the 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.
@@ -55,6 +58,44 @@ small-task harness can supply evidence without committing to that larger study.
   is not a schema validator for every example. Extending its coverage is tracked
   separately, not a reason to weaken review or bypass required checks.
 
+## Accepted: one Node deployment per project
+
+**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
 
 **Decided 2026-09-19.** Workspace packages under `packages/` release on
@@ -160,10 +201,9 @@ 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.
+"consolidate middleware into core after moving it into the monorepo," was
+**closed on 2026-09-19** as moot — there was nothing left to consolidate.
+Migration starting is not a claim that it has landed.
 
 ## Source review baseline
 

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

package/docs/README.md

@@ -39,8 +39,8 @@ 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) |
@@ -59,7 +59,7 @@ 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) |
+| Read why per-route Lambda compilation was declined | [Lambda compile spike (archived)](archive/2026-09-19/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 +79,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-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,14 +64,18 @@ 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
@@ -79,3 +88,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,

package/docs/STARTERS.md

@@ -36,18 +36,30 @@ on every push and pull request once the project is on GitHub.
 See [organization](ORGANIZATION.md) for choosing your own layout. Defaults allow
 GET/HEAD and use redirect 302; add configuration only when changing behavior.
 
+`urlcode init` writes no `package.json`: the route project is route-only, and its
+runtime may be installed globally, in a parent workspace or in a container. Add
+`--manifest` to also write one pinning the runtime at exactly the version that
+generated the project, then run `npm install` in it yourself to install that
+version and produce a lockfile. The CLI never runs a package manager, and no
+upgrade command exists — a pinned version changes when you edit the manifest.
+
 Initialization refuses an existing destination. Own the app in your own repository,
 keep secrets out of Git, and upgrade the runtime separately without regenerating
 application files. Add pages, downloads, more functions and business-specific
 features to this same project. Update tests and the expected route count as it grows.
 See [readiness](READINESS.md) and [security](FUNCTION-SECURITY.md).
 
-To start an extended site instead, install the extension packages from npm
-(`npm install @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin`, published as
-`0.1.0-alpha.x` prereleases) in the directory you run from and pass their names: `urlcode init ../my-site --with
-auth,admin` writes the same starter under `my-site/app/`, merges each package's
+To start an extended site instead, install the compatible core, UI, auth and
+admin set from npm in the directory you run from; the
+[framework guide](FRAMEWORK.md#the-composition-contract) provides the exact
+`0.4.1` command to use after publication. Pass UI first so its kit activates
+before auth: `urlcode init ../my-site --with ui,auth,admin` writes the same starter under `my-site/app/`, merges each package's
 routes and declarations into it, and generates one `host.mjs` and README beside
-it. The contract each package fulfils is in [extensions](EXTENSIONS.md#scaffolding-with-init---with).
+it, plus a `package.json` pinning the runtime, those packages and their declared
+peers at the versions it just resolved, validated together against every declared
+peer range. Installing them is your explicit `npm install` in that directory.
+The contract each package fulfils is in [extensions](EXTENSIONS.md#scaffolding-with-init---with),
+with `--no-manifest` and `--pin` in [recorded versions](EXTENSIONS.md#recorded-versions).
 
 Both paths carry an `AGENTS.md` for repository-aware assistants. `urlcode init`
 generates it from the installed runtime's capability catalog (the same source as

package/docs/TOOLING.md

@@ -81,10 +81,12 @@ network. Keys always appear in this order:
   `--host-file`, `host` counts the operator module's extensions and plugins
   without activating them.
 - `routes`: path, methods and handler per route, sorted by path.
-- `constraints`: a fixed list that holds for every project (no guest network,
-  no Node APIs, no regex routes, one handler per route, exact or `{param}`
-  path segments, subtree mounts only for static and extension routes, no YAML
-  interpolation, secrets by operator grant only), each with a value and a note.
+- `constraints`: a fixed list that holds for every project (network and Node
+  built-ins available to trusted code and withdrawn by `sandbox: true`, no
+  regex routes, one handler per route, exact or `{param}` path segments,
+  subtree mounts only for static and extension routes, no YAML interpolation,
+  injected `env`/`secrets` by operator grant only), each with a value and a
+  note spelling out how it differs between the two trust modes.
 - `targets`: for each capability target (or the one `--target`), which of this
   project's used features are supported, conditional, refused or unknown.
 - `commands`: the exact `validate`, `test`, `audit --expect-routes N` (N is

package/docs/VERCEL.md

@@ -7,7 +7,8 @@ that is the point of the project format.
 **This adapter serves native handlers only:** redirects, validated responses,
 pages, static assets and downloads. `function` and `middleware` routes are
 refused at activation, trusted or sandboxed alike, not per request, so a deployment cannot
-half-work. See [what is not supported](#what-this-adapter-does-not-do).
+half-work, and that is a settled position rather than a pending limitation. See
+[what is not supported](#what-this-adapter-does-not-do).
 
 A working project is in [`examples/vercel/`](../examples/vercel/).
 
@@ -71,13 +72,20 @@ and want it in generated URLs.
 
 | Not supported | Why |
 |---|---|
-| `function` routes | They need the self-hosted Node lifecycle; a `sandbox: true` route would additionally spawn worker threads and load the WASM engine on every cold start. Correctness is not the issue; predictable latency is, and it is unmeasured. |
+| `function` routes | They need the self-hosted Node lifecycle; a `sandbox: true` route would additionally spawn worker threads and load the WASM engine on every cold start. Correctness is not the issue; the execution model is — per-route compilation was considered and declined. |
 | Middleware | Runs in the same execution mode as the route's function, and is refused with it. |
 | `urlcode serve` operational endpoints | `/_urlcode/health` and `/_urlcode/ready` describe a long-lived process. Use Vercel's own observability. |
 
 Each refusal happens at activation with a message naming the route, so you find
 out on deploy rather than on a request.
 
+`function` and `middleware` are not coming to this adapter. The supported answer
+is to deploy the project as one trusted Node process — a container or a VM
+running the project as it runs locally — which supports every route type today,
+on any host you like including AWS (ECS, EC2, App Runner). See
+[the decision](OPEN-DECISIONS.md#accepted-one-node-deployment-per-project) and
+[the analysis behind it](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md).
+
 ## Operating it
 
 Every instance activates the project independently: parsing YAML, snapshotting

package/docs/VERSION-ALIGNMENT.md

@@ -26,18 +26,52 @@ must match its manifest. `npm run release:check` rejects stale lockfile versions
 Unreleased source changes do not require moving a published tag or pretending a
 new package has already shipped.
 
+The `0.4.1` release is an explicit stable release decision for core, UI, auth
+and admin. Publication moves each package's npm `latest` channel to `0.4.1`, in
+core → UI → auth → admin order, after its release checks pass. A prepared
+manifest or merged release PR does not prove registry publication: use
+`npm run release:status` to inspect the live result before installing the set.
+This alignment does not permanently couple package versions; subsequent
+releases can still select only the packages that changed.
+
 Alpha releases publish under `alpha`; they never automatically move npm
-`latest`. Core's historical `latest` remains the stable 0.3.0 baseline until an
-explicit stable release decision. Extensions have historical alpha versions on
-`latest`; subsequent alpha publication does not keep that channel in lockstep.
-Different channel values alone are not drift. Test the install combination you
-recommend against peer ranges; a bare install may select an older channel.
-`release:status` reports each declared peer floor and whether its current
-`latest` and `alpha` satisfy the range.
+`latest`. Stable publication does not move `alpha`, so the two channels can
+legitimately show different versions. Test the install combination you recommend
+against peer ranges. `release:status` reports each declared peer floor and
+whether its current `latest` and `alpha` satisfy the range.
+
+After all four `0.4.1` versions are published, install the aligned set with:
+
+```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
+```
+
+Bare package names resolve npm's current `latest`; exact application pins and a
+committed lockfile keep an existing application from changing on a new release.
+
+## Generated applications
+
+A generated application records its own versions. `urlcode init --with` writes a
+`package.json` pinning the running runtime, the named extensions and their
+declared peers at the exact versions resolved at generation time, after checking
+that set against every declared peer range; `urlcode init --manifest` does the
+same for a route-only project with the runtime alone; `urlcode-auth init` pins
+this package and its peers. Plain `urlcode init` stays route-only and writes no
+manifest, for projects whose runtime is managed elsewhere. Generation never runs
+a package manager: `package-lock.json` exists only after the operator runs
+`npm install` in the generated directory, and a pin taken from a local path or
+tarball reproduces only where that path exists.
+
+No upgrade command exists. A generated project moves to new versions by an
+operator editing its manifest and re-installing. The issue that asked for this
+(#212) describes a future command that would choose a tested compatible set,
+show the changes and require explicit alpha selection; nothing here implements
+that, and the pins above are only the groundwork it would need.
 
 The standalone `urlcode-template` is an external exact-version consumer: after a
 runtime release, update its dependency and starter through its own reviewed PR.
-It is not automatically released by the monorepo coordinator. The retired
+The coordinator prepares and checks that PR after registry installation succeeds;
+the template is a consumer update, not a fifth npm package. The retired
 `urlcode-docs`, `urlcode-middleware`, `urlcode-dynamic-link` and `urlcode-short`
 repositories are not release targets.
 

package/docs/archive/2026-09-19/ROADMAP.md

@@ -6,6 +6,7 @@ current instructions. See the [current roadmap](../../../ROADMAP.md),
 Remaining acceptance work is not declared complete by archiving this record.
 
 <!-- trust-model-prose: historical-file -->
+<!-- local-links: historical-file -->
 <!-- guidance-claims: ignore-file -->
 
 # Public roadmap

package/docs/archive/2026-09-19/SPIKE-EXTENSION-MODEL.md

@@ -6,6 +6,7 @@ current instructions. See the [current roadmap](../../../ROADMAP.md),
 Remaining acceptance work is not declared complete by archiving this record.
 
 <!-- trust-model-prose: historical-file -->
+<!-- local-links: historical-file -->
 <!-- guidance-claims: ignore-file -->
 
 # Review: the extension model, its precedents and its alignment