@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.1

package/docs/DEVELOPMENT-PIPELINE.md

@@ -5,24 +5,51 @@ for UI, auth and admin. Core remains at the repository root and is explicitly
 included in the shared release inventory. Moving it is not required to use the
 same release checks and coordinator.
 
-## Pull requests
+## Pull requests and main pushes
 
-Every PR starts `verify`. A complete Git diff selects one of two lanes:
+Every PR and every push to main starts `verify`. A complete Git diff selects one
+of two lanes:
 
-- **Prose:** root project Markdown, `docs/**/*.md`, `llms.txt` and
-  `llms-full.txt` changes run guidance/generated-resource checks, runtime audit,
-  and the required container job. CodeQL retains its repository policy.
-- **Full:** all other changes, mixed changes, empty/unavailable diffs and main
-  pushes run static checks once and core and workspace suites separately. Both
-  suites retain Linux on Node 22/24/26. Main adds Windows/macOS on Node 24.
-  PRs add those platform legs for runtime, CLI, SQLite, fixture, dependency,
-  workflow and unknown changes; known UI presentation-only changes omit them. Package, action,
-  cookbook, reproducibility and operational checks retain their coverage.
+- **Prose:** root project Markdown, `docs/**/*.md`, `llms.txt`, `llms-full.txt`,
+  `benchmarks/agent/README.md`, `benchmarks/results/README.md` and each
+  package's `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` and `GOVERNANCE.md` run
+  guidance/generated-resource checks, runtime audit, and the required container
+  job. CodeQL retains its repository policy.
+- **Full:** all other changes, mixed changes, and empty, unclassifiable or
+  unavailable diffs run static checks once and core and workspace suites
+  separately. Both suites retain Linux on Node 22/24/26. Main adds
+  Windows/macOS on Node 24. PRs add those platform legs for runtime, CLI,
+  SQLite, fixture, dependency, workflow and unknown changes; known UI
+  presentation-only changes omit them. Package, action, cookbook,
+  reproducibility and operational checks retain their coverage.
 
-The prose allowlist is deliberately narrow. Package documentation, skills,
-starters, examples, schemas, manifests and workflow changes select full checks.
-A rename from source into docs also selects full checks. No required workflow
-uses `paths-ignore`.
+A pull request is classified against its merge base; a push to main is
+classified tip to tip from the event's `before`/`after` SHAs, so a force-push or
+rewritten history is measured by what actually moved. Classification fails
+closed: a missing, malformed or all-zero SHA (branch creation or deletion), and
+history this checkout cannot read, select full verification. Scheduled and
+manually dispatched runs are never classified from paths at all, so exact-SHA
+release coverage cannot silently become a docs-only run.
+
+The prose allowlist is deliberately narrow, and it is a list of reviewed,
+non-executable contributor prose rather than "every Markdown file". Skills,
+starters, recipes, examples, schemas, manifests, workflows, benchmark prompts,
+tasks, answers and acceptance notes, and any package document that ships inside
+a published tarball or is read by an agent surface (`README.md`, `SECURITY.md`,
+`CONTRACT.md`, `THREAT-MODEL.md`, `IMPLEMENTATION-STATUS.md`, `AGENTS.md`,
+`CHANGELOG.md`) select full checks. Anything feeding a generator stays in the
+code lane. A rename from source into docs also selects full checks, because the
+diff is read without rename detection and shows both paths. Every prose path is
+still covered by the always-run `docs` job, which walks all authored Markdown.
+No required workflow uses `paths-ignore`.
+
+The always-run `docs` job runs `npm run check:docs`; in the full lane the
+`static` job runs `npm run check:code`, which is the rest of `npm run check`.
+The two together are exactly `npm run check`, which stays complete for local
+use. This removes a duplicated dependency install plus seven repeated checks on
+the same commit, not meaningful wall time: the sampled documentation checking
+was about two seconds. Job names, lane selection and `verify-complete`
+dependencies are unchanged.
 
 `verify-complete` accepts only the results specified by the successful plan.
 Failed, canceled, missing or unexpectedly skipped work fails the gate. Required
@@ -32,7 +59,8 @@ release publication separately requires verification of the exact main commit.
 
 ```sh
 npm run check:docs                 # prose checks without the runtime suite
-npm run ci:plan -- BASE_SHA HEAD_SHA
+npm run check:code                 # everything in `check` except the prose checks
+npm run ci:plan -- BASE_SHA HEAD_SHA # previews as a pull request outside Actions
 npm run ci:report -- RUN_ID         # read GitHub job/step durations
 npm run ci:history -- 100 2026-09-19 # group historical timing samples
 npm run verify                    # full local validation remains available
@@ -43,123 +71,184 @@ CI uses `test:package:built` only after building in that same job. Core tests an
 workspace tests run in separate jobs to shorten their serial critical path;
 this increases job setup overhead and needs monitoring for runner queue pressure.
 After building all three extensions, the workspace job also runs the real
-`init --with auth,admin,ui` scaffold integration. Missing workspace outputs fail
+`init --with ui,auth,admin` scaffold integration. Missing workspace outputs fail
 instead of silently skipping an absent external checkout.
 The [audit](CI-RELEASE-AUDIT-2026-09-19.md) records the previous timings.
-The [follow-up measurements](CI-FOLLOWUP-2026-09-19.md) record the first compact
-main result and explain why the new lanes still need 20 organic runs each.
-
-## Version and release ownership
-
-A feature PR records release intent in a Changeset for a changed workspace
-package. Review dependency/peer changes explicitly. Keep pre-mode enabled until
-an explicit decision to leave alpha. Do not force all packages to one version.
-Core version bumps remain explicit in the release PR, including its CLI banner.
-`release:check` verifies every manifest against its lockfile entry and checks the
-alpha-mode policy. Existing CLI tests catch core banner/version disagreement.
-
-A release PR collects version/changelog and lockfile changes together. Ordinary
-unreleased development does not move existing version tags or npm versions.
-Use the exact release commit after its full platform checks have passed. Routine
-main builds use five OS/Node combinations per suite (ten jobs total), rather
-than the full nine per suite (eighteen). Nightly runs at 07:17 UTC and manual
-runs retain all three operating systems on all three Node versions. Before a
-release, run `gh workflow run ci.yml --ref main` and wait for that exact commit's
-full run to succeed. A successful compact main run alone cannot authorize a
-release. Main pushes do not cancel scheduled/manual verification.
-
-Inspect release state:
+The [follow-up measurements](CI-FOLLOWUP-2026-09-19.md) record early compact-main observations; issue #185 contains the later decision
+and current sample sizes.
+
+## Version preparation and release ownership
+
+Core remains at the repository root. Independent extension versions remain
+supported; a coordinated version is an explicit maintainer choice, not a
+permanent fixed-version policy. An explicitly selected stable version exits
+Changesets alpha pre-mode; subsequent stable patches stay out of pre-mode. Feature PRs record workspace release intent in
+Changesets; core release notes remain an explicit maintainer responsibility.
+
+`release:check` checks manifest/lock versions and peer ranges, CLI and MCP
+versions, generated plugin metadata, local peer compatibility, and channel policy.
+The preparation helper updates these together, adds release notes and extension
+changelogs, and records the version decision. Pending Changesets must be
+explicitly consumed; they are archived under `.changeset/pre/` and their summaries
+included in the release notes. Review the resulting diff and peer minimums.
 
 ```sh
-npm run release:status   # registry channels, peer compatibility, remote tag SHAs
-npm run release:plan     # read-only JSON inventory, including root core
-npm run release:run      # read-only ordered proposal at HEAD
+# Example only: choose the next intended version before executing.
+npm run release:prepare -- --version 0.4.1 --consume-changesets
+# Apply local edits on a clean non-main branch; no remote writes or publication:
+npm run release:prepare -- --version 0.4.1 --consume-changesets --execute
 ```
 
-All three commands require network access; none publish. `release:run` selects
-unpublished manifest versions and releases already tagged at HEAD (for resuming
-partial completion). Its order is core, UI, auth, admin, skipping other already
-published versions. Plan fields come from package manifests, not copied versions
-in another config file.
+An optional `--notes PATH` adds reviewed maintainer notes. Dry runs do not change
+files. Preparation rejects downgrades, reused local tags, dirty checkouts and
+stale plans. A stable target removes `.changeset/pre.json`, publishes to npm
+`latest`, and leaves the historical `alpha` pointer unchanged. Alpha targets
+require existing alpha mode; the helper never silently re-enters prerelease mode.
+It does not invoke a permanent Changesets fixed-version policy.
 
-Once the release itself is authorized, from a clean checkout of that exact SHA:
+## One-command release and resume
+
+Inspect without writing:
+
+```sh
+npm run release:status  # registry channels, peer compatibility, tag SHAs
+npm run release:plan    # manifest-derived inventory
+npm run release:run     # ordered states at this checkout: pending/resume/unchanged
+npm run release:run -- --version 0.4.1 --consume-changesets
+```
+
+For an explicitly authorized coordinated release:
+
+```sh
+npm run release:run -- --version 0.4.1 --consume-changesets --execute
+```
+
+`--execute` authorizes the entire sequence: create the release branch/PR, wait
+for checks and merge, run the release gates, create version tags, publish, verify
+an installed consumer, and create/check/merge the starter update. It never
+approves a review or bypasses a required check. A required human review still
+blocks merging. No write or publication occurs without `--execute`.
+
+The coordinator works in a temporary clone and prints its location. It prepares
+`codex/release-VERSION`, or resumes the existing PR/branch after checking its
+versions and receipt. It checks out the actual merged SHA and reinstalls that
+commit's locked dependencies. Repeating the command discovers existing PRs,
+gates, tags and workflow state rather than creating another version. Temporary
+release clones are retained for diagnosis and can be removed after completion.
+
+For an independently prepared release PR already merged to main, use a clean
+checkout of its exact commit:
 
 ```sh
 npm run release:run -- --execute
 ```
 
-This opt-in command creates missing tags through GitHub, refuses an existing tag
-at a different commit, and waits for each package's tag-triggered release before
-starting the next. It stops on failure or missing npm publication. Do not push
-all release tags at once: publication workflows share one concurrency group and
-GitHub may replace pending runs. The coordinator intentionally starts one at a
-time. It never merges a PR, bypasses checks, force-pushes or publishes locally.
-
-The coordinator needs `gh` authentication with repository Contents write and
-Actions read; reading checks also needs Checks read. It is intended for an
-authorized maintainer session or a repository-scoped GitHub App. A fine-grained
-PAT can serve a short-lived maintainer script with those permissions, but must
-have no ruleset bypass. The workflow `GITHUB_TOKEN` should not be used to create
-these trigger tags: its push events do not start another ordinary push workflow.
-For long-lived automation prefer a GitHub App; do not add a bypass to `main`.
+The coordinator creates `codex/release-validation/SHA` at the already-merged
+commit when gates are missing. An existing validation branch must name that
+exact SHA; it is never moved. This lets main advance without changing the release
+being tested. The branches remain as audit/resume references. It dispatches full
+`ci.yml` and `candidate.yml`, reuses existing successful runs, and waits for
+running ones. A failed gate stops with its run ID; diagnose it and rerun that
+exact run before resuming. Compact PR/main checks cannot replace the full
+OS/Node matrix or CodeQL on the selected commit.
+
+Before creating any version tags, it downloads and verifies the candidate bundle.
+A green run with missing artifacts does not authorize tags. New version tags are
+annotated with the source commit, chosen candidate run ID and the SHA256 of its
+signed manifest. The manifest binds every package and supporting asset by hash. Every package in a
+resumed train must select that same candidate. Neither a later candidate of the
+same source nor a newer main commit can silently replace the chosen bytes.
+A successful rerun of the same candidate ID cannot substitute a changed bundle: its
+manifest must still match the immutable checksum in the release tag.
+After tags exist, rerun package publishers rather than the pinned candidate run.
+If a later attempt of that candidate run fails, the coordinator stops even when
+an earlier attempt succeeded; it does not infer which attempt should be trusted.
+
+Publication is sequential: core → UI → auth → admin, skipping unchanged published
+versions. Each publisher must succeed and its version must be readable through
+npm's abbreviated install metadata, with a downloadable SHA512-verified tarball,
+before dependents begin. Bounded retries handle propagation, transport failures,
+429 and server errors; authentication and integrity failures stop immediately.
+Afterward, an external consumer with a fresh npm cache installs the four exact
+registry versions, checks its peer tree and imports, and generates the combined
+extension scaffold in dependency order (`ui,auth,admin`). The candidate archive
+smoke uses the same scaffold check before any package is published.
+
+The standalone starter helper updates the exact core pin, lockfile, matching
+schema/docs links and guide from the installed published core package, then runs
+validation/tests/audit/benchmark,
+and opens a resumable PR. The coordinator waits for checks and merges it, checking
+for a newer template pin immediately before merge. `--skip-template` explicitly
+leaves this follow-up to the maintainer. To run only that follow-up:
+
+```sh
+npm run release:template -- --version 0.4.1 --execute
+```
+
+That standalone helper opens a PR but does not merge it. All helpers stop on
+errors; rerun after diagnosis. A failed publisher is retried at most once per
+coordinator invocation and must pass the original-byte recovery checks below.
+
+The maintainer identity needs repository Contents, Actions and Pull requests
+write, plus Checks read, on the affected repositories. GitHub App installations
+should be scoped to URLCode and its template. No ruleset bypass or long-lived
+npm token is needed. The workflow `GITHUB_TOKEN` must not create the triggering
+version tags because its push events do not start ordinary push workflows.
 [GitHub App guidance](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/deciding-when-to-build-a-github-app)
 
-## Publication and recovery
-
-The four workflow filenames remain unchanged because npm trusted publishing
-names them. They call shared helpers for identity, preflight, peer installation,
-retry handling and publication. npm authentication remains OIDC; no npm token
-is introduced. Core candidate and release share `prepare-core-release.sh`.
-For an authorized release, first dispatch the manual `candidate.yml` workflow on
-the selected main commit. It extends the core candidate with UI/auth/admin
-archives and verifies all four together in an isolated temporary consumer:
-peer compatibility, installed versions, public imports and real scaffold
-composition. Its signed `train.json` records the proposed archives and integrity.
-A candidate does not publish, validate live providers or prove registry OIDC;
-release workflows still prepare and retain their own immutable retry artifacts.
-Extensions share `prepare-extension-release.sh` and test published peer floors.
-Auth/admin build in the workspace for packaging, then build and run their suites
-in a temporary copy outside the monorepo against exact registry peer floors.
-This preserves #184’s isolation fix; npm `--prefix` is not an isolation boundary.
-
-Preflight checks the checkout SHA, main ancestry, a successful exact-SHA full
-`ci.yml` nightly or explicit manual run, CodeQL, remote tag SHA, npm
-channel monotonicity and published peer floors. When a full run was canceled,
-run `verify` manually at the selected tag/ref, then rerun the failed release;
-never substitute another commit's passing run or move the tag.
-
-Prepared artifacts are retained for 90 days before publication. A rerun of the
-same workflow run restores those original bytes and skips preparation. npm
-versions already present must have identical SHA-512 integrity; existing GitHub
-assets must match byte for byte. Different bytes stop the release. An absent or
-expired artifact requires reconstruction that still passes these comparisons;
-if it cannot, diagnose and create a new version rather than overwrite history.
-
-GitHub release classification follows the manifest's prerelease status. New
-GitHub releases use `--latest=false`; stable latest promotion is a separate
-maintainer decision, avoiding accidental promotion by a package-level release.
-GHCR updates the derived channel (`alpha` for alphas, `latest` for stable) and
-preserves existing version images only when their source label matches. An
-existing image/channel without the required labels fails closed and needs a
-reviewed migration; this change does not silently relabel old images.
-
-Partial npm/GitHub/GHCR success is possible; those systems cannot be updated
-atomically. Rerun the original failed run, check its summary and then rerun the
-coordinator. A changed source commit requires a new version and tag. Failed
-OIDC configuration needs correction on npm, not tag deletion. A green dry run
-cannot prove registry-side OIDC trust; each package's first authorized publish
-must verify it.
-
-Historical tags, GitHub release flags and npm channels are not retroactively
-rewritten by these scripts. Use `release:status` to inspect them. The active [Immutable release tags rule](https://github.com/jimhoyd-com/urlcode/rules/23712319)
-prohibits update/deletion of `v*` and `@jimhoyd/urlcode-*@*` tags, permits
-creation, and has no bypass actors. Its reviewed configuration is tracked in
-`.github/rulesets/release-tags.json`. Main protection is unchanged.
-
-During the September 19 alignment, GitHub releases `v0.4.0-alpha.1` and
-`v0.4.0-alpha.2` were explicitly marked as prereleases and GitHub latest was
-restored to `v0.3.0`, matching npm. Their tags and artifact bytes were unchanged.
-Further performance and release-train validation is tracked in
+## Build once, publish verified bytes
+
+The four publisher filenames remain unchanged for npm trusted-publisher identity.
+The candidate builds in the digest-pinned environment, runs verification,
+packaging and local operational checks, packs all four packages, and tests an
+isolated combined consumer. The signed bundle contains all four archives,
+SBOM, Homebrew formula, source/build manifest, train identity and checksums.
+The manifest binds it to the candidate run as well as the commit.
+
+Publishers verify the selected candidate's workflow provenance, exact source SHA,
+run identity, manifest/package identities and hashes. They publish the selected
+package's existing archive without rebuilding it. Auth/admin still run isolated
+compatibility tests against their actual published peer floors; temporary test
+builds do not replace the promoted archive. This preserves the distinction
+between workspace compatibility and registry compatibility.
+
+Each package's GitHub release stores the complete signed bundle for durable
+recovery. Supporting sibling archives are candidate evidence: an independent
+package release does not imply every sibling archive was published to npm.
+Candidate and release Actions artifacts retain 90 days; retention is not an
+archival guarantee. Keep independent last-good copies for deployment rollback.
+
+## Recovery, immutable tags and channels
+
+A retry restores the original retained bundle, or recovers the complete verified
+bundle from that package's GitHub release. Missing, incomplete or unverifiable
+originals stop the retry. It never rebuilds archives or substitutes a new
+candidate. If publication stopped before a complete durable release existed and
+the retained artifact is gone, a new version may be required.
+
+Existing npm versions must match SHA512 integrity; existing GitHub assets must
+match byte for byte. Partial npm/GitHub/GHCR success is possible and cannot be
+made atomic. Fix registry identity/settings where appropriate and resume the
+original run. A source change requires a new version and tag. Never delete,
+recreate, move or force-push version tags.
+
+These recovery changes apply to releases made with the new workflows. They cannot
+change the immutable workflow source at `0.4.0-alpha.3` or repair that historical
+run by rerunning it. The missing-artifact behavior observed there is recorded in
+[issue #223](https://github.com/jimhoyd-com/urlcode/issues/223).
+
+npm uses OIDC with pinned npm 11.5.1. Alpha versions use npm/GHCR `alpha`, and
+GitHub prerelease classification with `--latest=false`. Existing `latest`
+pointers are not promoted by this flow. Core GHCR publication remains conditional
+on `PUBLISH_CONTAINER=true`; its existing version/channel identity guards remain.
+Historical GHCR verification is still a separate follow-up.
+
+The [Immutable release tags rule](https://github.com/jimhoyd-com/urlcode/rules/23712319)
+blocks updates/deletions of `v*` and `@jimhoyd/urlcode-*@*`, permits creation, and
+has no bypass actors. Main protection is unchanged. Source and artifact checks
+are not an independent security assessment, provider deployment or recovery
+proof. The next explicitly authorized new release must exercise the complete
+new promotion/recovery path. Progress and remaining work are recorded in
 [issue #185](https://github.com/jimhoyd-com/urlcode/issues/185).
 
 ### Windows fixture cleanup

package/docs/EXTENSIONS.md

@@ -193,7 +193,7 @@ project customizes an extension's *look* through `urlcode-ui`'s
 standard, or every extension author (and every project depending on one)
 either reinvents it or forks the extension. `urlcode-auth` and
 `urlcode-admin` independently hit this gap (auth/#35, admin/#32); auth's own
-[SPIKE-AUTH.md](https://github.com/jimhoyd-com/urlcode-auth/blob/main/docs/SPIKE-AUTH.md)
+[SPIKE-AUTH.md](../packages/auth/docs/SPIKE-AUTH.md)
 already scoped a shape for `onSignUp`/`beforeRegister`/`onDelete`.
 
 **The pattern.** An extension with lifecycle events an author judges worth
@@ -336,16 +336,15 @@ boundary, not a JavaScript sandbox or an independent security review.
 
 ## Scaffolding with `init --with`
 
-`urlcode init <directory> --with auth,admin` produces the layered site the
+`urlcode init <directory> --with ui,auth,admin` produces the layered site the
 [framework page](FRAMEWORK.md#the-composition-contract) describes in one
 command: the starter under `<directory>/app/`, one `host.mjs`, one `README.md`,
 and each extension's own operator files. Core never bundles or imports the
 extension packages at build time; at run time it resolves
 `@jimhoyd/urlcode-<name>` for each name with Node's package resolution from
-the invoking directory (so `npm install @jimhoyd/urlcode-auth` in that
-directory, from npm where the packages are published as `0.1.0-alpha.x`
-prereleases, is the normal path and what makes `--with auth` work), imports
-the package and calls its
+the invoking directory. Install a compatible package set there, as shown in
+[the framework guide](FRAMEWORK.md#the-composition-contract), before using
+`--with ui,auth`; UI must activate before auth. Core imports the package and calls its
 `scaffold` export with this request:
 
 ```ts
@@ -401,6 +400,37 @@ Assembly rules, in `--with` order:
   review the project and pin it explicitly; the host is generated to require
   the pin, never to compute it.
 
+### Recorded versions
+
+`init --with` also writes `<directory>/package.json`: a private manifest that
+pins, at exactly the version that was resolved, the running runtime, every
+extension named in `--with`, and every package those extensions declare in
+`peerDependencies` (so `@jimhoyd/urlcode-ui` is pinned for an `auth,admin` site
+although nobody named it). Before anything is written, the whole set is checked
+against every declared peer range; an incompatible combination or a missing
+required peer refuses and names it, leaving no directory behind.
+
+Nothing is installed. The generated site has no `node_modules` and no
+`package-lock.json` until you run `npm install` in it yourself, which the
+command and the generated README both state as the next step. Reproducibility
+comes from that install, not from generation.
+
+- `--no-manifest` generates the site without a `package.json`, for a site whose
+  dependencies are managed elsewhere. Plain `urlcode init` is unchanged and
+  still writes no manifest; add `--manifest` to pin the runtime for a
+  route-only project too.
+- `--pin <package>=<specifier>` records a specifier instead of the resolved
+  version, for local tarball or offline development
+  (`--pin @jimhoyd/urlcode-auth=file:/abs/urlcode-auth-0.1.0-alpha.6.tgz`). A
+  package installed from a local path or tarball is detected from npm's own
+  install record and pinned by that path without any flag; the README says so,
+  because such a pin only reproduces where that path exists.
+
+There is no upgrade command. Moving a generated project to newer versions today
+means editing its `package.json` and re-running `npm install` yourself; nothing
+in this runtime selects a newer tested set, shows the change, or updates a
+lockfile for you.
+
 Serving the result is the usual explicit host binding:
 
 ```sh

package/docs/FRAMEWORK.md

@@ -7,26 +7,26 @@ claim here is implemented in the linked repository; nothing is roadmap.
 
 ## Four packages, one project shape
 
-| Package | Repository | What it adds | How a project declares it |
+| Package | Source | What it adds | How a project declares it |
 |---|---|---|---|
-| `@jimhoyd/urlcode` | [urlcode](https://github.com/jimhoyd-com/urlcode) | The runtime: YAML routes, functions and middleware (trusted by default, `sandbox: true` opt-in), pages and assets, policies, site conventions, CLI, provider adapters, the extension contract | `urlcode.yaml` with `version: "1"` |
-| `@jimhoyd/urlcode-ui` | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, one stylesheet with light and dark, themes, translations, the `ui` extension that serves the kit's assets | `extensions.ui` plus an asset mount route |
-| `@jimhoyd/urlcode-auth` | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) | Accounts: password, passkeys, OpenID Connect, email codes, TOTP, recovery, sessions, roles, registration modes, account page, operator CLI | `extensions.auth` plus an `/account/*` mount and `policies.extensions.auth` on protected routes |
-| `@jimhoyd/urlcode-admin` | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
-
-The core is Apache-2.0 and released. The three extension packages are
-Apache-2.0 and published to npm as alphas (`@jimhoyd/urlcode-ui@0.1.0-alpha.4`,
-`@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`,
-on core `0.4.0-alpha.1`). An alpha on npm is a distribution channel, not an
-endorsement: the source is complete, but independent review, deployment
-evidence and an accessibility assessment are still pending
+| `@jimhoyd/urlcode` | this repository | The runtime: YAML routes, functions and middleware (trusted by default, `sandbox: true` opt-in), pages and assets, policies, site conventions, CLI, provider adapters, the extension contract | `urlcode.yaml` with `version: "1"` |
+| `@jimhoyd/urlcode-ui` | [`packages/ui`](../packages/ui) | Shared presentation: escaped templates, shadcn/ui partials, one stylesheet with light and dark, themes, translations, the `ui` extension that serves the kit's assets | `extensions.ui` plus an asset mount route |
+| `@jimhoyd/urlcode-auth` | [`packages/auth`](../packages/auth) | Accounts: password, passkeys, OpenID Connect, email codes, TOTP, recovery, sessions, roles, registration modes, account page, operator CLI | `extensions.auth` plus an `/account/*` mount and `policies.extensions.auth` on protected routes |
+| `@jimhoyd/urlcode-admin` | [`packages/admin`](../packages/admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
+
+All four are Apache-2.0. The `0.4.1` release line aligns their stable versions;
+check `npm run release:status` for publication progress. A stable npm channel is
+not an independent assessment: review, deployment evidence and an accessibility
+assessment are still pending
 ([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)). Their status
-files say exactly what is built: [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/IMPLEMENTATION-STATUS.md),
-[admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/IMPLEMENTATION-STATUS.md),
-[ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/IMPLEMENTATION-STATUS.md).
-Which core version each package supports, how it declares that, and the order
-in which a core change reaches the downstream repositories are recorded in
-[core version alignment](VERSION-ALIGNMENT.md).
+files say exactly what is built: [auth](../packages/auth/IMPLEMENTATION-STATUS.md),
+[admin](../packages/admin/IMPLEMENTATION-STATUS.md),
+[ui](../packages/ui/IMPLEMENTATION-STATUS.md).
+The current version of each package is its own manifest, and the peer ranges it
+declares are in that manifest too; do not read a version number out of this
+page. How versions, channels and release tags line up is recorded in
+[package and channel alignment](VERSION-ALIGNMENT.md), and `npm run
+release:status` reports the live registry and tag state.
 
 ## The ladder
 
@@ -43,8 +43,10 @@ Each rung's YAML is valid on every rung above it.
 3. **Functions and middleware.** `function` routes and ordered `middleware`
    in JavaScript, trusted and in-process by default; a route declaring
    `sandbox: true` runs isolated instead (QuickJS inside WebAssembly, fresh
-   heap per call, no Node, filesystem or network). Secrets reach a function
-   only through an operator grant pinned to the project revision.
+   heap per call, no Node, filesystem or network). The `env`/`secrets` the
+   runtime injects into a function come only from an operator grant pinned to
+   the project revision; the grant governs that injected context, not the
+   ambient Node environment trusted in-process code can reach on its own.
 4. **Accounts.** The `auth` extension: sign-in, registration, MFA, account
    page and protected routes. The operator installs it in a host file outside
    the project; YAML only declares the mount and configuration.
@@ -61,17 +63,19 @@ was removed from core. A `urlcode-dynamic-link` package owned them the same way
 package occupies this rung today.
 
 Rungs 1 to 3 need only the core package. Rungs 4 to 6 need the extension
-packages, installed from npm as `0.1.0-alpha.x` prereleases, and a Node host
-with a patched SQLite build; see each repository's README for the exact
-requirement.
+packages installed from npm and a Node host with a
+patched SQLite build; see each package's README ([auth](../packages/auth/README.md),
+[admin](../packages/admin/README.md), [ui](../packages/ui/README.md)) for the
+exact requirement.
 
 ## The composition contract
 
-An extended project starts with the packages and one command:
+After the aligned `0.4.1` packages are published, an extended project starts
+with the packages and one command:
 
 ```sh
-npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
-urlcode init my-site --with auth,admin
+npm install --save-exact @jimhoyd/urlcode@0.4.1 @jimhoyd/urlcode-ui@0.4.1 @jimhoyd/urlcode-auth@0.4.1 @jimhoyd/urlcode-admin@0.4.1
+urlcode init my-site --with ui,auth,admin
 ```
 
 Installing from npm is the normal path; `scripts/pack-sources.mjs` still builds
@@ -140,7 +144,7 @@ See each package README for its complete kit registration example.
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
 ```
 
-`urlcode init <dir> --with auth,admin` writes this layout in one step: it
+`urlcode init <dir> --with ui,auth,admin` writes this layout in one step: it
 resolves each installed `@jimhoyd/urlcode-<name>` from the current directory,
 calls its `scaffold` export and merges the fragments into `app/urlcode.yaml`,
 one `host.mjs` and one `README.md`, refusing before writing anything when a
@@ -151,6 +155,17 @@ administrator from JSON on stdin. `inspectExtensionRevision(project)` prints
 the SHA-256 that `projectSha256` must carry; changing extension YAML, policies
 or mounts changes the revision and needs an explicit operator reapproval.
 
+The presentation tooling composes the same way, by naming packages rather than
+depending on them. `urlcode-ui` is the kit alone until
+`--extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin` names the packages
+that ship the other namespaces: each is resolved from `--project` with Node
+package resolution and imported for the namespace it exports, so `list`,
+`doctor`, `eject`, `preview` and `copy --missing` cover the `auth/*` and
+`admin/*` templates and copy the host registers, and a project override of an
+extension template is checked against the shipped view model. A package that is
+not installed is skipped. `urlcode init --with` writes the commands with the
+flag already set; `@jimhoyd/urlcode-ui` still depends on neither peer.
+
 ## Rules an agent must follow
 
 These are the facts that keep generated projects valid. The full matrix is in
@@ -195,8 +210,8 @@ These are the facts that keep generated projects valid. The full matrix is in
 | Need | Read |
 |---|---|
 | Write or change routes | [YAML guide](YAML-GUIDE.md), [field reference](YAML-REFERENCE.md), [cookbook](../examples/cookbook/README.md) |
-| Add accounts | [auth README](https://github.com/jimhoyd-com/urlcode-auth#readme), [auth security](https://github.com/jimhoyd-com/urlcode-auth/blob/main/SECURITY.md) |
-| Add administration | [admin README](https://github.com/jimhoyd-com/urlcode-admin#readme) |
-| Restyle every page | [ui README](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
+| Add accounts | [auth README](../packages/auth/README.md), [auth security](../packages/auth/SECURITY.md) |
+| Add administration | [admin README](../packages/admin/README.md) |
+| Restyle every page | [ui README](../packages/ui/README.md), [ui contract](../packages/ui/CONTRACT.md) |
 | Write an extension | [extensions](EXTENSIONS.md), [extension model review](archive/2026-09-19/SPIKE-EXTENSION-MODEL.md) |
 | Run it | [operations](OPERATIONS.md), [install](INSTALL.md), [deployment checks](DEPLOYMENT-CHECKS.md) |