@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

package/docs/COMPOSING-A-SITE.md

@@ -0,0 +1,278 @@
+# Composing a site from ui, auth and admin
+
+One command produces a site that already has accounts, an administration
+console and a presentation kit wired together:
+
+```sh
+npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
+urlcode init site --with ui,auth,admin
+```
+
+This page is the map of what you may then change, and with which tool. It
+covers three different activities that are easy to confuse:
+
+| You want to | Use | Code? |
+|---|---|---|
+| Change what an extension is configured to do | the `config` block in `app/urlcode.yaml` | none |
+| Change how its screens look or read | files under `<site>/ui/` | none (templates are data) |
+| Run your own logic at one of its lifecycle points | a project function named from that `config` | first-party project JavaScript |
+| Add a capability none of the three provides | a new extension package | TypeScript against the runtime contract |
+
+Work down that list, not up. The [declarative-first
+principle](PROJECT-DIRECTION.md#design-principle-declarative-first) applies
+here as much as it does to routes: reach for the next row only when the one
+above it cannot express the requirement.
+
+## What `--with ui,auth,admin` generates
+
+- `site/app/` — the route project: `urlcode.yaml` with an `extensions` block
+  per package, and `routes/extensions.yaml` holding `/assets/ui/*`,
+  `/account/*`, `/private` and `/admin/*`.
+- `site/host.mjs` — the operator host module, the one place that holds code.
+  It builds the kit with `createUiExtension`, passes the returned object into
+  `authExtension` and `adminExtension`, and lists `ui.registration` first.
+- `site/ui/` — `copy/`, `templates/` and `extra.css`, the project's
+  presentation overrides, beside the host and **outside** `app/`.
+- `site/operator-service.mjs`, `site/data/` — auth's operator service and its
+  private key material, mode `0600`.
+- `site/README.md` — the merged next steps, environment table and the project
+  revision to review and pin.
+
+Nothing about that wiring is manual any more. The generated host registers
+`authCatalogue` as a copy source and both `authUiTemplates` and
+`adminUiTemplates` as template namespaces, because auth and admin render only
+through the kit and refuse to activate without their own templates present.
+
+### Supported combinations
+
+`--with` order is the activation order, and the kit must be active before
+anything that renders through it.
+
+| `--with` | Result |
+|---|---|
+| `ui` | Kit only; the host wires no peer catalogue or templates. |
+| `ui,auth` | Accounts on `/account/*`, rendered through the kit. |
+| `ui,auth,admin` | The full composition above. |
+| `auth` or `auth,admin` | Refused: the scaffold names the missing `ui`. |
+| `auth,admin,ui` | Refused: `ui` must come before the extensions it renders. |
+| `admin` without `auth` | Refused: admin reuses auth's service, CSRF key and revision. |
+
+Every refusal happens before anything is written, and leaves no directory
+behind. There is no auth-without-ui or admin-without-ui configuration in this
+revision: the UI primitive fallback was retired, so the kit is the only render
+path (see [OPEN-DECISIONS.md](OPEN-DECISIONS.md)).
+
+## Declarative configuration
+
+Each package owns one `extensions.<name>` block. The block itself is core
+schema (`version` plus `config`); what may go inside `config` is the
+package's own JSON Schema, which you can print rather than guess:
+
+```sh
+urlcode extensions --project ./site/app --host-file "$PWD/site/host.mjs" --json
+```
+
+The same report is the MCP tool `get_extensions`, and it is the authoritative
+answer for both the configuration schema and the per-route policy schema. The
+generated site starts from something like this:
+
+```yaml
+version: "1"
+extensions:
+  ui:
+    version: "1"
+    config:
+      theme:
+        name: My Site
+      languages: [en]
+      copy: ui/copy
+      templates: ui/templates
+      stylesheet: ui/extra.css
+  auth:
+    version: "1"
+    config:
+      registration: "off"
+  admin:
+    version: "1"
+    config: {}
+```
+
+Routes mount an extension, and policies require one:
+
+```yaml
+routes:
+  /assets/ui/*:
+    extension: ui
+    methods: [GET, HEAD]
+  /account/*:
+    extension: auth
+    methods: [GET, HEAD, POST]
+  /admin/*:
+    extension: admin
+    methods: [GET, HEAD, POST]
+  /private:
+    respond:
+      text: Signed in
+    policies:
+      extensions:
+        auth: {}
+```
+
+See [EXTENSIONS.md](EXTENSIONS.md) for the `auth` route short form, extension
+middleware, and the host-file trust boundary.
+
+## Presentation overrides
+
+The `ui` config's `copy`, `templates` and `stylesheet` paths point at the
+project's own directories. Nothing here forks a package.
+
+| Override | File | Effect |
+|---|---|---|
+| Wording and translation | `ui/copy/<locale>.json` | Replaces catalogue ids, including ids the auth and admin packages own. Listed in `languages`. |
+| A whole screen | `ui/templates/<name>.html` | Shadows a kit or extension template of that name, for example `ui/templates/auth/sign-in.html` or `ui/templates/admin/dashboard.html`. |
+| Styling | `ui/extra.css` | Appended after the kit stylesheet; `{file, replace: true}` replaces it instead. |
+| Colours, logo, favicon, radius, font | the `theme` block | Declarative; no file needed. |
+
+A template is data in the kit's own language. It cannot add a script, change
+what a form validates, or change what a page sends in headers — so an override
+cannot weaken the screen it restyles. Stylesheets containing `@import`,
+`script`, `javascript:` or `expression(` are refused.
+
+Names, coverage and what the runtime will actually load:
+
+```sh
+npx urlcode-ui list --project ./site --extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin
+npx urlcode-ui doctor --project ./site --extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin --copy ui/copy --templates ui/templates --stylesheet ui/extra.css
+npx urlcode-ui eject auth/sign-in --out ./site/ui/templates --project ./site --extensions @jimhoyd/urlcode-auth
+npx urlcode-ui copy --missing fr --project ./site --extensions @jimhoyd/urlcode-auth --copy ui/copy --languages en,fr
+```
+
+`eject` copies the shipped source so an override starts from what ships and
+never overwrites an existing file. `ui/` lives outside `app/`, so editing copy
+or templates does **not** change the project revision and does not require
+re-pinning `PROJECT_SHA256`.
+
+**Name the packages that ship the other namespaces.** `urlcode-ui` is this
+kit alone until `--extensions` names them. Each package is resolved from
+`--project` with Node package resolution and imported for the namespace it
+exports; one that is not installed there is skipped with a note, so the
+command still runs. The site's `host.mjs` is never read: it builds services
+and reads secrets at its top level, and a read-only `list` or `doctor` must
+not run it. With the packages named:
+
+- `list` shows the `auth/*` and `admin/*` names beside the kit's own, each
+  with its origin, and `eject auth/sign-in` copies the shipped source.
+- `doctor` reports an `expected` view model for an extension template, so its
+  `behind` flag tells you when an override of one has fallen behind what
+  ships. Its `extensions` field names the namespaces the report covers, so a
+  report built without a peer is visible as such.
+- `preview auth/sign-in` renders the extension's own sample view model.
+- `copy --missing` skeletons cover the auth ids the account screens use.
+  Admin-owned `adminUi.*` ids are deliberately not offered: admin composes
+  its catalogue onto the kit's presentation rather than registering it there,
+  and those translations do not currently reach the console
+  ([#227](https://github.com/jimhoyd-com/urlcode/issues/227)).
+
+`urlcode init <directory> --with ui,auth,admin` writes these commands into the
+generated README with the flag already set. `@jimhoyd/urlcode-ui` depends on
+neither peer; the operator names them.
+
+Overrides of extension templates and of extension-owned catalogue ids reach
+the rendered screens, which is what the regression test below asserts.
+
+## Project functions: lifecycle hooks
+
+A hook is your own function, named from the extension's `config`, that the
+extension calls at a lifecycle point it defines. It uses the same source shape
+a `function` route uses — a bare path, or `{source, export}` — resolved
+relative to the route project.
+
+```yaml
+extensions:
+  auth:
+    version: "1"
+    config:
+      registration: open
+      hooks:
+        beforeRegister:
+          source: ./hooks/registration-rule.mjs
+          export: default
+        onSignUp: ./hooks/on-signup.mjs
+```
+
+`hooks` is not a core schema key. It is each package's own config, validated
+by that package's schema before `activate()`, which is why `get_extensions` is
+the place to check what a given version accepts.
+
+Hooks are first-party project code and run **trusted and in-process**, the
+same default `function` and `middleware` routes have
+([FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)). Neither package implements
+sandboxed hook execution yet; `sandbox: true` on a hook is rejected loudly at
+activation rather than accepted and silently run trusted.
+
+### `@jimhoyd/urlcode-auth`
+
+| Hook | Input | Returns | Called |
+|---|---|---|---|
+| `beforeRegister` | `{email, profile?}` | `{allow: boolean, reason?}` | Before an account is created, on `POST /account/register` and on `POST /account/signup/begin`. |
+| `onSignUp` | `{accountId, email}` | ignored | After a genuinely new account is created — on `/account/register`, and on `/account/signup/complete` only when that completion created an account rather than signing an existing one in. |
+| `onDelete` | `{accountId, email}` | ignored | After the account owner's own deletion is scheduled. Not on an administrator-initiated deletion, and not on the background purge when the grace period ends. |
+
+### `@jimhoyd/urlcode-admin`
+
+| Hook | Input | Returns | Called |
+|---|---|---|---|
+| `beforeRoleChange` | `{accountId, currentRoles, requestedRoles, actorId, reason}` | `{allow: boolean, reason?}` | Before roles are applied, after the administrator's permission check. A veto means the auth service is never asked. |
+| `onRegistrationApproved` | `{requestId, accountId, email, actorId, reason}` | ignored | After a registration request is approved. |
+| `onAccountStatusChanged` | `{accountId, status, actorId, reason}` | ignored | After an account is locked or unlocked. |
+
+### Verdicts and failure
+
+- **A veto is explicit.** A pre-action hook allows only by returning
+  `allow: true`. `allow: false`, or no verdict at all, rejects the operation
+  with `403` and the hook's own `reason`, or a generic message when it gave
+  none. Nothing is written. A hook that *throws* has not returned a verdict:
+  the operation is still refused, but as a generic `500`, so return a verdict
+  rather than throwing when you mean to deny.
+- **Broken hooks fail at activation, not at the first request.** A missing
+  module, a source path escaping the project, an export that is not a
+  function, or `sandbox: true` all throw while the extension activates, naming
+  the hook. The site does not start.
+- **A post-action hook cannot undo anything.** `onSignUp`,
+  `onDelete`, `onRegistrationApproved` and `onAccountStatusChanged` run after
+  the operation has committed. Throwing from one replaces the success response
+  with a `500` while the account, approval or status change stands. There is
+  no retry and no rollback. Keep them non-throwing: catch your own errors and
+  queue the work instead of failing the request.
+- **A hook's message is not a channel to the browser.** Only a pre-action
+  `reason` is shown. An uncaught error surfaces as a generic failure.
+- **An edited hook needs a restart.** Activation re-imports the hook's entry
+  module, so a reload picks up an edit to that file — but modules it imports
+  stay on Node's module cache, exactly as for trusted route functions.
+
+## TypeScript: implementing a new extension
+
+Only write an extension when a capability is genuinely absent — not to
+customize one of the three above. An extension is an operator-installed
+package whose host object core activates; it is named in `host.mjs`, never
+in YAML. The contract, the activation inputs, `ExtensionActivation.root`,
+credential headers and the `projectSha256` pin are in
+[EXTENSIONS.md](EXTENSIONS.md) and [TYPESCRIPT.md](TYPESCRIPT.md); the
+`scaffold` export that makes a package work with `init --with` is in
+[EXTENSIONS.md](EXTENSIONS.md#scaffolding-with-init---with).
+
+If its screens should be themeable the same way auth's and admin's are, it
+also exports a template namespace (and, if it ships English wording, a
+catalogue) for a host to pass to `createUiExtension`. That is what makes
+`ui/templates/<yourname>/<screen>.html` work in a consumer project without a
+fork.
+
+## What this page does not claim
+
+The composition, the refusals and the override path are exercised by
+`test/workspace-scaffold.integration.ts`, which runs `init --with` against the
+built packages, drops a template and a copy catalogue into the generated
+`ui/` directory and asserts both reach a rendered auth screen and a rendered
+admin screen. That runs in-process against the generated host: no HTTP
+listener, TLS proxy, browser or deployed site is exercised, and no published
+npm tarball is checked against this checkout.

package/docs/DEVELOPMENT-PIPELINE.md

@@ -0,0 +1,270 @@
+# Development and release pipeline
+
+The repository uses npm workspaces, independent package versions, and Changesets
+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 and main pushes
+
+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`, `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.
+
+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
+check names (`verify-complete`, `container`) and CodeQL enforcement are preserved.
+The repository ruleset currently does not require a branch to be up to date;
+release publication separately requires verification of the exact main commit.
+
+```sh
+npm run check:docs                 # prose checks without the runtime suite
+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
+npm run test:package              # builds and installs a real archive
+```
+
+CI uses `test:package:built` only after building in that same job. Core tests and
+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 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 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
+# 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
+```
+
+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.
+
+## 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
+```
+
+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)
+
+## 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
+
+Auth/admin tests register resources with their package-local `test/cleanup.ts`.
+Cleanup runs in reverse acquisition order: close servers and SQLite services
+before deleting temporary directories, including services reopened by a test.
+Every registered callback is attempted even if another closer throws, and the
+combined error fails the test. Register each closer as soon as its resource opens.
+The suites use a five-minute test-file timeout so a stuck fixture is diagnosed
+before the CI job limit. Node applies this limit to whole test files too; the
+large auth-core file legitimately exceeds two minutes on Windows Node 22.
+Windows regression coverage runs on Node 24 for platform-sensitive PRs and
+main; nightly/manual runs cover Node 22/24/26.
+
+Failed auth service initialization also waits for its SQLite worker to terminate
+before rejecting. Callers can clean up or retry after a rejected open without
+racing a remaining database handle; configuration identity failures still fail
+closed with the same error code.

package/docs/EXTENSIONS.md

@@ -6,10 +6,11 @@ and admin implementations live in `urlcode-auth` and `urlcode-admin`; the runtim
 supplies only the generic integration contract. No project file can import a host
 extension or choose its npm package.
 
-Stored short links are moving out of core this way too: a future
-`urlcode-dynamic-link` package (mount-based, like `auth`/`admin`, not yet
-published) will own the durable link store, its CLI and management API. Core
-no longer has a native `link` handler or a `dynamicLinks` project flag.
+Stored short links moved out of core this way too: a `urlcode-dynamic-link`
+package (mount-based, like `auth`/`admin`) owned the durable link store, its CLI
+and management API. That package has since been retired and unpublished, so no
+supported stored-link extension ships today. Core no longer has a native `link`
+handler or a `dynamicLinks` project flag.
 
 A project declares versioned configuration and exclusive route mounts:
 
@@ -192,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
@@ -256,7 +257,16 @@ each half of a hook's `sandbox: true` opt-in has its own answer:
   or provided: this is ordinary first-party project code, and the
   extension's own `activate()` already has `ExtensionActivation.root` to
   resolve the hook's `source` against and can `import()` it directly, the
-  same way any trusted `function`/`middleware` route does.
+  same way any trusted `function`/`middleware` route does. Do that import
+  with a per-activation cache-busting query, the way core's own trusted
+  route activation does (`src/trusted-functions.ts`): Node's ESM loader
+  caches a resolved module forever by URL, so a plain `import()` of the
+  unchanged file URL makes a second activation in the same process keep
+  serving the hook code that was on disk at the first one
+  (jimhoyd-com/urlcode#198). Only the hook's **entry** module is refreshed
+  this way — modules the hook itself imports stay on Node's module cache,
+  the same limitation the trusted route path has, so a change to a hook's
+  own dependency still needs a process restart.
 - **Sandboxed (`sandbox: true`).** `@jimhoyd/urlcode/sandbox` exports
   `SandboxPool`, the same QuickJS/worker-thread engine that backs a
   sandboxed `function`/`middleware` route — the identical module-allowlist
@@ -326,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
@@ -391,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