@jimhoyd/urlcode 0.4.1 → 0.4.2

package/docs/DEVELOPMENT-PIPELINE.md

@@ -82,7 +82,8 @@ and current sample sizes.
 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 alpha pre-mode when no package remains on alpha; 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
@@ -101,12 +102,41 @@ 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
+stale plans. A stable target removes `.changeset/pre.json` once no package
+remains on alpha, 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
+## GitHub Actions release buttons
+
+The Actions page exposes `release core`, `release UI`, `release auth`, `release
+admin` and `release all packages`. Each manual workflow accepts an exact stable
+or alpha version and whether to consume relevant pending Changesets. The four
+package workflows update and publish only their selected package. `release all
+packages` aligns and publishes the complete train in core → UI → auth → admin
+order. A Changeset spanning selected and unselected packages is rejected; use
+the all-packages workflow or split the change intentionally.
+
+All five buttons call the same serialized reusable workflow. It creates a
+release PR, waits for normal required checks, merges without bypass, runs the
+exact-commit full matrix and signed candidate, publishes the selected immutable
+tag, checks registry installability, and verifies the current four-package
+consumer combination. A core release also updates the standalone starter. The
+workflow is resumable: rerun the same button and version after repairing a
+failure. It reuses matching PRs, tags, candidates and successful publishers.
+
+Configure `RELEASE_AUTOMATION_TOKEN` as a repository Actions secret. Prefer a
+repository-scoped GitHub App token when available. A fine-grained PAT is also
+supported when it is limited to `urlcode` and `urlcode-template` with Contents,
+Pull requests and Actions read/write. The repositories are public, so the
+coordinator can inspect their check runs without an additional token
+permission. The token owner needs ordinary write access. Do not grant ruleset
+bypass, administration, approval or package-registry credentials; npm
+publishers continue to use their workflow OIDC identities. Dispatch from
+`main`.
+
+## One-command local release and resume
 
 Inspect without writing:
 
@@ -115,12 +145,14 @@ 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
+npm run release:run -- --version 0.4.2 --package auth --consume-changesets
 ```
 
 For an explicitly authorized coordinated release:
 
 ```sh
 npm run release:run -- --version 0.4.1 --consume-changesets --execute
+npm run release:run -- --version 0.4.2 --package auth --consume-changesets --execute
 ```
 
 `--execute` authorizes the entire sequence: create the release branch/PR, wait
@@ -241,7 +273,9 @@ 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.
+Historical GHCR verification is still a separate follow-up. Digest promotion of a
+tested image is design only, in [CONTAINER-PROMOTION.md](CONTAINER-PROMOTION.md);
+the publisher still builds from source.
 
 The [Immutable release tags rule](https://github.com/jimhoyd-com/urlcode/rules/23712319)
 blocks updates/deletions of `v*` and `@jimhoyd/urlcode-*@*`, permits creation, and

package/docs/EXTENSIONS.md

@@ -183,29 +183,18 @@ Node adapter conformance is not a live-provider deployment claim.
 
 ## Project-level lifecycle hooks
 
-`authorize` and `middleware` let core call *into* an extension. They do not
-let a project hand its own code *to* an extension to run at a defined point.
-That gap matters once an extension has meaningful lifecycle events —
-registration, deletion, an administrative action, a link resolution, and so
-on. Presentation already has a standard layering mechanism for this: a
-project customizes an extension's *look* through `urlcode-ui`'s
-`copy`/`extra.css`/`templates` without forking it. Behavior needs the same
-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](../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
-exposing should let the project name its own function in the extension's own
-`config`, using the same source shape `function`/`middleware` routes already
-use (a string path, or `{source, export, args}` — `schemas/urlcode.schema.json`),
-and add its own `sandbox` boolean next to it (below). The extension's own
-`activate()` reads that config, and its own runtime dispatch — not a new core
-primitive, an ordinary call the extension package makes with the request
-context it already has — invokes the named function at the lifecycle point
-it defines, with a typed input and a typed verdict the extension's own
-schema documents. For example, an auth-style extension might declare:
+Extensions expose project customization points through the core hook primitive.
+Each registration publishes `hooks`, a machine-readable list containing the
+hook name, whether it is a value-transforming `filter` or side-effect `action`,
+its description and its input/output JSON Schemas. The extension embeds
+`extensionHooksSchema(contracts)` in its configuration schema and calls
+`loadExtensionHooks(config.hooks, contracts, context)` during activation.
+Core then enforces the common source/export shape, project-root confinement,
+known names, eager module/export validation, input/output schemas and reload
+cache busting. Hook entry bytes participate in the project revision, so editing
+a hook invalidates the operator's extension pin.
+
+Projects select those declared hooks in the extension's own configuration:
 
 ```yaml
 extensions:
@@ -221,76 +210,51 @@ extensions:
 ```
 
 with `beforeRegister` called before an account is created, given a typed
-`{email, traits}`-shaped input and returning a typed verdict (`{allow: true}`
+`{email, profile?}` input and returning a typed verdict (`{allow: true}`
 or `{allow: false, reason}`), and `onSignUp` called after, for side effects
-such as provisioning a workspace. The exact hook names, input/verdict shapes
-and invocation points are the extension's own design — `hooks` is not a core
-schema key — but the source/export/sandbox shape, and the fact that this is
-project code the extension calls rather than an operator callback in
-`host.mjs`, should be consistent across extensions so an author who has
-learned one has learned the pattern.
-
-**Trust and execution mode.** Project-level lifecycle hooks are first-party
-project code, the same category as any `function`/`middleware` route, and
-follow the same trusted-by-default rule with no special case
-(docs/SPIKE-DEFAULT-TRUST-MODEL.md, [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md)):
-trusted, in-process execution by default; a project sets `sandbox: true` on
-a given hook to opt that hook into isolated QuickJS/WASM execution, exactly
-the mechanism `function`/`middleware` routes already use and for the same
-reason — the hook's own code, not the trustworthiness of whatever triggered
-it, is what calls for isolation (docs/AI-AUTHORING.md's "Deciding when a
-route needs `sandbox: true`"). This was raised as an open question — whether
-a lifecycle hook should always run sandboxed because it makes a
-security-relevant decision — and settled the other way: uniformity with the
-rest of the trust model was chosen over hardwiring isolation for lifecycle
-hooks specifically, the same "no special case" call already made between
-`function` and `middleware` trust. A `beforeRegister` hook enforcing "only
-`@acme.com` may register" is the project's own governance rule over its own
-signup flow; it is not more dangerous than any other route the project
-wrote, and does not get a different default.
-
-Core's own trusted/sandboxed dispatch (`TrustedFunctions`/`FunctionPool`,
-`src/runtime.ts`) is wired to route dispatch, not exposed to extensions — but
-each half of a hook's `sandbox: true` opt-in has its own answer:
-
-- **Trusted (the default, no `sandbox: true`).** No core primitive is needed
-  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. 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
-  walk, memory/stack limits, two-layer deadline enforcement, `maxBytes` and
-  response-shape validation, with no separate or weaker engine for
-  extensions. It takes an explicit list of `{source, export}` entries
-  (resolve a hook's `source` string with the re-exported `functionFile()`,
-  the same resolution/validation a native route's `source` gets) instead of
-  anything route/YAML-shaped, and `execute({entry, chain}, request, context)`
-  in place of a `FunctionRoute`. There is no "trusted" mode exported
-  alongside it — `SandboxPool` is only ever the isolated path; see
-  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md) and
-  [TYPESCRIPT.md](TYPESCRIPT.md) for the full contract.
-
-An extension honoring a hook's `sandbox: true` is expected to actually
-isolate that invocation through `SandboxPool` now that the primitive exists
-(or document plainly that it does not yet, rather than accepting the field
-and silently running it trusted) — say which, in the extension's own docs,
-so an author reading them is not misled about what opt-in exists.
+such as provisioning a workspace. Hook names and lifecycle timing remain the
+extension's domain, while their declaration, loading and discovery are shared.
+
+Hooks are first-party project code and run trusted in-process by default, with
+full Node access, like trusted `function` and `middleware` routes. Contract v1
+does not define an arbitrary-value sandbox hook protocol. A hook reference with
+`sandbox: true` is rejected during activation rather than silently run trusted.
+Only the entry module is refreshed during reactivation; its imported dependencies
+remain in Node's module cache until restart.
+
+The UI extension exposes `transformView`, a synchronous filter called before a
+named kit template renders. It receives `{template, view}` and returns the view
+model to render. Use copy, templates, theme and CSS for ordinary presentation
+changes; use this hook for project-specific computed view data that those
+declarative layers cannot express.
+
+## Building an extension
+
+An extension package should export a registration factory and, when it supports
+`urlcode init --with`, a side-effect-free `scaffold` function. The registration:
+
+1. Declares its logical name, contract version, supported targets, exact project
+   revision pin and strict configuration/policy schemas.
+2. Publishes every project hook through `hooks` and reuses
+   `extensionHooksSchema` plus `loadExtensionHooks`; it does not implement its
+   own path resolver or dynamic-import cache.
+3. Activates all configuration, files, services and hooks before serving a
+   request. Invalid or stale configuration fails activation.
+4. Returns `handle` for mounts and optionally `authorize`/`middleware` for route
+   policies. It closes resources it owns.
+5. Keeps credentials, storage and provider setup in the operator host. Project
+   YAML contains logical configuration and project-relative hook references.
+
+Consumers install the package, declare its YAML block and mounts/policies, and
+register it in `host.mjs`. They modify it through declared configuration,
+presentation layers and hooks. A fork is reserved for changing behavior the
+extension has not exposed; that is evidence for a new declarative field or hook.
+See [Composing a site](COMPOSING-A-SITE.md) for the complete ui/auth/admin example.
 
 ## Discovering schemas
 
 Each registration carries the JSON Schemas that validate its `config` block and
-its per-route policy requirements. `urlcode extensions` prints them together with
+its per-route policy requirements, plus its hook contracts. `urlcode extensions` prints them together with
 the project's own declarations so an author can see what a mount accepts:
 
 ```sh
@@ -299,6 +263,7 @@ urlcode extensions --project ./site --host-file /absolute/operator/host.mjs [--j
 
 For every registration in the host file it reports the name, contract version,
 targets, credential headers, configuration schema, policy schema (if any),
+declared hook names, kinds, descriptions and input/output schemas,
 whether the project declares it, whether its `projectSha256` matches the current
 revision, the routes that mount it and the routes whose policies require it.
 Declared names the host does not register are listed as unregistered. The command

package/docs/FUNCTION-SECURITY.md

@@ -93,14 +93,11 @@ machinery either way.
 
 This engine — worker spawning, the module-allowlist walk, the two-layer
 deadline, `maxBytes` and response-shape validation — is one implementation
-shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`,
-the public primitive an extension package uses to run a project-supplied hook
-through this exact isolation when the project's own config declares
-`sandbox: true` on it (see [EXTENSIONS.md](EXTENSIONS.md#project-level-lifecycle-hooks)
-and [TYPESCRIPT.md](TYPESCRIPT.md)). Every guarantee above applies identically
-through that entry point; there is no separate, weaker sandbox for extensions
-to reach for, and no "trusted" mode exported there — trusted execution needs
-no primitive at all (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+shared by route dispatch and by `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
+That public HTTP-shaped primitive remains available to extension authors, but
+project extension hooks use arbitrary typed values and contract v1 runs them
+trusted in-process; it rejects `sandbox: true` rather than claiming HTTP sandbox
+semantics apply to them. See [extensions](EXTENSIONS.md#project-level-lifecycle-hooks).
 
 ## What the trusted default can and can't do
 

package/docs/OPEN-DECISIONS.md

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

package/docs/READINESS.md

@@ -82,7 +82,10 @@ parameter patterns still need explicit negative fixtures to exercise them.
 
 `ready: true` requires a nonempty active project, matching expected count (when
 supplied), zero failed checks and no uncovered active route/method combinations.
-It means this local gate passed, not that all branches, parameter values or assets
+When `ready` is false, `notReadyReasons` lists each failed condition:
+`no-active-routes`, `route-count-mismatch`, `failed-checks` and
+`uncovered-route-methods` (see `uncovered` for the pairs). `unassertedCases` never
+affects `ready`. It means this local gate passed, not that all branches, parameter values or assets
 have independent business assertions. Function routes intentionally serving only
 errors cannot satisfy normal-response coverage in this release. Time-dependent
 expiry is evaluated at audit start; avoid running a gate exactly at expiry.

package/docs/README.md

@@ -1,10 +1,20 @@
 # URLCode documentation
 
-Start with [the framework](FRAMEWORK.md): the four packages, the ladder from
-redirects to a full application, the composition contract and the rules an AI
-agent must follow. [Project direction](PROJECT-DIRECTION.md) states the
-boundary and the license. Use documentation pinned to your runtime revision;
-`version: "1"` is the stable project-format contract for this release line.
+Choose a starting point, then use the topic directory below when you need detail.
+Use documentation from the same pinned revision as your runtime.
+
+| I want to… | Start here |
+|---|---|
+| Understand what URLCode does | [Framework](FRAMEWORK.md) |
+| Build my first project | [Installation](INSTALL.md), then [YAML guide](YAML-GUIDE.md) |
+| Build a site with UI, accounts and admin | [Composing a site](COMPOSING-A-SITE.md) |
+| Have an AI author a project | [AI authoring](AI-AUTHORING.md), [agent index](../llms.txt) |
+| Deploy and operate a project | [Operations](OPERATIONS.md) |
+| Contribute to URLCode | [Contributing](../CONTRIBUTING.md), [local development](LOCAL-DEVELOPMENT.md) |
+
+The [specification](SPECIFICATION.md) owns implemented semantics; the
+[generated field reference](YAML-REFERENCE.md) lists accepted fields.
+[Project direction](PROJECT-DIRECTION.md) explains the product boundary.
 
 ## Author a project
 
@@ -13,11 +23,9 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Install the CLI | [Installation](INSTALL.md) |
 | Write YAML with examples | [YAML guide and recipes](YAML-GUIDE.md) |
 | Look up every accepted field | [Generated field reference](YAML-REFERENCE.md), [JSON Schema](../schemas/urlcode.schema.json) |
-| Let an AI build routes | [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt) |
 | Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
-| Run examples | [25-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
 | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
-| Run examples | [40-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
+| Run examples | [Executable cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
 | Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
 | Reuse code around routes | [Middleware](MIDDLEWARE.md), [middleware examples](MIDDLEWARE-EXAMPLES.md) |
 | Handle secrets and decide what to sandbox | [Function security](FUNCTION-SECURITY.md) |
@@ -43,7 +51,6 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Manage users, sessions, roles and audit | [urlcode-admin](../packages/admin#readme) |
 | Restyle every extension page and translate copy | [urlcode-ui](../packages/ui#readme), [ui contract](../packages/ui/CONTRACT.md) |
 | Write or install a versioned extension | [Extensions](EXTENSIONS.md), [example fixture](../examples/extensions/README.md) |
-| Follow implementation of the auth, admin and UI extensions | [Extension implementation sequence](archive/2026-09-19/EXTENSION-IMPLEMENTATION.md) |
 | Know which core version an extension package supports, and how it says so | [Core version alignment](VERSION-ALIGNMENT.md) |
 | Add host behavior in operator code | [Plugins](PLUGINS.md) |
 | Use the API from TypeScript | [TypeScript: shipped declarations, exports, build and fidelity](TYPESCRIPT.md) |
@@ -59,7 +66,6 @@ boundary and the license. Use documentation pinned to your runtime revision;
 | Review security findings and gaps | [Internal security audit](SECURITY-AUDIT.md) |
 | Assess release readiness | [Evidence and open gates](RELEASE-READINESS.md) |
 | See unfinished work | [Roadmap](../ROADMAP.md) |
-| Read 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) |

package/docs/RELEASE-0.4.2.md

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