@jimhoyd/urlcode 0.4.1 → 0.4.2

package/docs/RELEASE-READINESS.md

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

package/docs/RELEASE-SECURITY.md

@@ -78,8 +78,12 @@ any version tag, then creates one at a time and waits for successful publication
 and consumer-facing registry installability before releasing dependents. Shared publication concurrency avoids cross-version races.
 The active immutable-tag rule blocks release tag updates/deletions with no
 bypass actors; its configuration is in `.github/rulesets/release-tags.json`. No automation needs permission to bypass main checks or approve
-its own PR. A repository-scoped GitHub App is the preferred eventual automation
-identity; a narrowly scoped fine-grained PAT can support a maintainer script.
+its own PR. Manual package/all release workflows share the coordinator and need
+`RELEASE_AUTOMATION_TOKEN` because events created by the ordinary `GITHUB_TOKEN`
+do not trigger tag publishers. A repository-scoped GitHub App is preferred. A
+fine-grained PAT may select only `urlcode` and `urlcode-template`, with Contents,
+Pull requests and Actions read/write plus Checks read. Neither identity needs
+ruleset bypass, administration, npm secrets or review approval.
 
 ## Remaining validation
 

package/docs/SPIKE-DEFAULT-TRUST-MODEL.md

@@ -174,19 +174,15 @@ with `add_repo` before treating it as settled.
   settles this explicitly: a hook a project names in an extension's own YAML
   config (`urlcode-auth`'s `onSignUp`/`beforeRegister`/`onDelete` and the
   like) is first-party project code in the same category as any
-  `function`/`middleware` route, trusted and in-process by default, with the
-  same per-hook `sandbox: true` opt-in. No hardwired always-sandboxed case
-  for lifecycle hooks specifically. Trusted execution of such a hook needs no
-  core primitive — an extension's own `activate()` already has
-  `ExtensionActivation.root` and can `import()` the project's module
-  directly. The isolated half of that opt-in previously had no equivalent:
-  core's trusted/sandboxed dispatch was wired to route dispatch only, not
-  exposed to extensions. `@jimhoyd/urlcode/sandbox`'s `SandboxPool` (see
-  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md), [TYPESCRIPT.md](TYPESCRIPT.md))
-  closes that: the same worker/QuickJS engine `FunctionPool` already used for
-  route dispatch, generalized to explicit `{source, export}` entries/targets
-  instead of `FunctionRoute`, with no second engine and no "trusted" mode
-  exported alongside it.
+  `function`/`middleware` route and runs trusted and in-process. Core now owns
+  the shared extension-hook primitive: it validates hook references, imports
+  them during activation, enforces the extension-published input/output JSON
+  Schemas, reports those contracts to authoring tools, and includes hook entry
+  files in the project revision. Hook sandboxing is not part of this first
+  contract; `sandbox: true` is rejected during activation instead of silently
+  running trusted. A later sandbox contract must define its serialization and
+  capability boundary before it can reuse the worker/QuickJS path described in
+  [FUNCTION-SECURITY.md](FUNCTION-SECURITY.md).
 
 ## Recommended sequencing
 

package/docs/TOOLING.md

@@ -52,7 +52,7 @@ The tooling API consolidates authoring operations without starting a runtime:
 - `listRecipes()` and `showRecipe(name)` expose the fixed bundled recipe catalog.
 - `inspectExtensions({project, hostFile?})` reports each operator-registered
   extension's name, contract version, targets, credential headers, configuration
-  and policy JSON Schemas, whether the project declares it, whether its revision
+  and policy JSON Schemas, machine-readable project hook contracts, whether the project declares it, whether its revision
   pin matches and where routes mount or require it, plus the project's declared
   names. With `hostFile` it executes that trusted operator module under the
   `--host-file` rules (absolute path, outside the project) and releases it

package/docs/VERSION-ALIGNMENT.md

@@ -26,6 +26,14 @@ must match its manifest. `npm run release:check` rejects stale lockfile versions
 Unreleased source changes do not require moving a published tag or pretending a
 new package has already shipped.
 
+Manual GitHub Actions releases can select `core`, `ui`, `auth`, `admin`, or
+`all`. A single-package release updates only that package's manifest, lock entry,
+changelog and relevant Changesets; core also owns its duplicated CLI/MCP/plugin
+version metadata and downstream starter update. The all-packages action aligns
+every manifest and advances internal peer floors together. Changesets that name
+packages across the selected boundary must be released together rather than
+partially consumed.
+
 The `0.4.1` release is an explicit stable release decision for core, UI, auth
 and admin. Publication moves each package's npm `latest` channel to `0.4.1`, in
 core → UI → auth → admin order, after its release checks pass. A prepared

package/docs/archive/2026-09-20/OPEN-DECISIONS-COMPLETED.md

@@ -0,0 +1,116 @@
+# Historical record
+
+Archived 2026-09-20 from [open decisions](../../OPEN-DECISIONS.md), which was
+reconciled against its issues that day (#242). These sections record completed
+work and dated observations exactly as they stood on 2026-09-19 (core `db375bf`
+and the package sources of that date); they are not current instructions and
+their version numbers, dist-tags, commits and pins are not current. Versions
+and channels: [version alignment](../../VERSION-ALIGNMENT.md) and
+`npm run release:status`. Archiving does not declare any security, deployment,
+recovery or provider check performed. The live middleware decision remains in
+open decisions.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+<!-- local-links: historical-file -->
+
+## 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.
+
+## 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](../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](../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.

package/docs/archive/README.md

@@ -20,6 +20,7 @@ Archived on 2026-09-19 after checking the current code:
 | [Usability review](2026-09-19/USABILITY-REVIEW.md) | Predates trusted execution and retired packages | New benchmark observations |
 | [Management security](2026-09-19/MANAGEMENT-SECURITY.md) | Describes the removed core link-management API | No current core replacement |
 | [Lambda compile spike](2026-09-19/SPIKE-LAMBDA-COMPILE.md) | Proposal declined 2026-09-19 in favour of one Node deployment per project | Open decisions; AWS and Vercel guides |
+| [Completed decisions (2026-09-20)](2026-09-20/OPEN-DECISIONS-COMPLETED.md) | Closed questions, the completed monorepo migration and the 2026-09-19 source baseline, moved out of open decisions (#242) | Current open decisions and release readiness |
 
 Open proposals stay outside the archive with their status stated at the top.
 The accepted trust-by-default decision remains directly linked from the current

package/llms-full.txt

@@ -1,5 +1,5 @@
 <!-- Generated by scripts/build-llms-full.ts (npm run docs:llms). Do not edit; edit the source documents. -->
-<!-- Consolidated URLCode authoring reference: 16 documents, about 52,663 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 52,118 tokens (estimate: characters / 4). -->
 
 # URLCode
 
@@ -540,9 +540,10 @@ either `true` or `false`) or `sandbox: true` is enough to silence it.
 
 The same judgment call applies to a project-level lifecycle hook an
 extension invokes (`onSignUp`, `beforeRegister` and the like) — it is
-first-party project code with the same trusted-by-default rule and the same
-`sandbox: true` opt-in as any `function`/`middleware` route, no special
-case. See [EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks).
+first-party project code with the same trusted-by-default rule as a
+`function`/`middleware` route. Extension hook contract v1 is trusted-only;
+`sandbox: true` is rejected rather than silently ignored. See
+[EXTENSIONS.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks).
 
 Guest TypeScript needs `build-typescript --project SOURCE --out NEW_DIRECTORY`
 before serving. Only the emitted `.js`/`.mjs` executes, in QuickJS for a
@@ -561,7 +562,7 @@ origin grants pinned to the project revision. These are self-hosted features;
 providers refuse them. Signals are bounded best effort with drops, no retries
 or persistence. Never turn a user request into an implicit network grant.
 
-Before using a feature, ask `urlcode capabilities <name>` for its constraints, grants and target support and `urlcode schema <path>` for only that YAML fragment (MCP: `get_capability`, `get_schema`), instead of guessing.
+Before using a feature, ask `urlcode capabilities <name>` for its constraints, grants and target support and `urlcode schema <path>` for only that YAML fragment (MCP: `get_capability`, `get_schema`), instead of guessing. For an installed extension, use `urlcode extensions --host-file ... --json` or MCP `get_extensions`; its hook contracts include the accepted names, purpose and input/output schemas. Prefer extension configuration and UI copy/templates/theme/CSS, then a declared project hook, and only then a new extension or fork.
 The [tooling SDK and stdio MCP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md) inspect, validate, explain and preview
 without guest execution, environment reads or writes. Run `urlcode explain /route`
 to check effective methods, policies and cache outcome, and `urlcode manifest`
@@ -2702,29 +2703,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](https://github.com/jimhoyd-com/urlcode/blob/main/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:
@@ -2740,76 +2730,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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md) and
-  [TYPESCRIPT.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/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
@@ -2818,6 +2783,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
@@ -3162,15 +3128,24 @@ extensions:
         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` remains each package's own config, but core supplies the reference
+schema, trusted loader and machine-readable hook contract. `get_extensions`
+reports those contracts, so an agent can discover accepted names, purpose and
+input/output shapes without guessing from prose.
 
 Hooks are first-party project code and run **trusted and in-process**, the
 same default `function` and `middleware` routes have
-([FUNCTION-SECURITY.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/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.
+([FUNCTION-SECURITY.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)). Extension hook contract v1 is
+trusted-only; `sandbox: true` is rejected loudly at activation.
+
+#### `@jimhoyd/urlcode-ui`
+
+| Hook | Input | Returns | Called |
+|---|---|---|---|
+| `transformView` | `{template, view}` | the view object to render | Synchronously before each public `ui.kit.render()` or `ui.kit.page()` call. Use it only when theme, copy, templates and CSS cannot express the change. |
+
+For example, `transformView: ./hooks/ui-view.mjs` can add project-computed
+navigation or labels to an auth/admin view without editing either package.
 
 #### `@jimhoyd/urlcode-auth`
 
@@ -3338,14 +3313,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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks)
-and [TYPESCRIPT.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#project-level-lifecycle-hooks).
 
 ### What the trusted default can and can't do
 

package/llms.txt

@@ -66,7 +66,7 @@ fields or bypass target limits or operator grants. See [the design principle](do
 - [Interchange](docs/INTERCHANGE.md), [bulk import](docs/BULK.md), [recipes](docs/RECIPES.md) (`urlcode recipes search`, `examples search`), [TypeScript guests](docs/TYPESCRIPT-AUTHORING.md).
 
 ## Extensions (accounts, administration, presentation)
-- [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, `extension` mounts, `policies.extensions`, the operator host file, `@jimhoyd/urlcode/extensions`. Project-level lifecycle hooks run trusted via plain `import()`, or sandboxed via `@jimhoyd/urlcode/sandbox`'s `SandboxPool`.
+- [Extensions](docs/EXTENSIONS.md): `extensions.<name>` blocks, mounts, policies, operator registration, the shared trusted hook primitive and its machine-readable hook contracts. UI/auth/admin project hooks run trusted in-process; contract v1 rejects `sandbox: true`.
 - [Composing a site](docs/COMPOSING-A-SITE.md): what `urlcode init site --with ui,auth,admin` wires, which `--with` combinations are supported, the presentation override paths under `ui/`, and per-package lifecycle hook input, verdict, timing and failure semantics. Separates declarative configuration, project functions and the TypeScript a new extension needs.
 - [urlcode-auth](packages/auth): npm: @jimhoyd/urlcode-auth; accounts, sessions, MFA, roles, account page; its own llms.txt. Lives in this repository as a workspace package.
 - [urlcode-admin](packages/admin): npm: @jimhoyd/urlcode-admin; users, sessions, roles, audit, cases; its own llms.txt. Lives in this repository as a workspace package.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [

package/packaging/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "urlcode",
   "description": "Authoring and operating URLCode projects: the implemented YAML contract, capability limits, deployment and verification commands for the pinned runtime revision.",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "author": {
     "name": "jimhoyd-com",
     "url": "https://github.com/jimhoyd-com"

package/packaging/claude-plugin/skills/urlcode-authoring/SKILL.md

@@ -30,6 +30,11 @@ Start with `urlcode context --project <dir> --budget 4000`, then retrieve the
 capability, schema fragment, recipe or example relevant to the change. Use the
 read-only MCP equivalents when available. `llms.txt` is the index; read the
 matching task guide from `docs/` when a query needs more explanation.
+When the project has an operator host file, inspect `urlcode extensions
+--project <dir> --host-file <absolute-file> --json` (MCP: `get_extensions`)
+before writing extension configuration or project hooks. The report is the
+machine-readable source for config/policy schemas and hook names, purposes and
+input/output schemas.
 `docs/SPECIFICATION.md` and `schemas/urlcode.schema.json` resolve contract
 questions. Archived plans are historical, not valid YAML guidance.
 
@@ -49,6 +54,11 @@ questions. Archived plans are historical, not valid YAML guidance.
 - Create every referenced module, page and asset **before** validating. All
   source paths resolve from the project root. Trusted modules can import Node built-ins and npm packages;
   only `sandbox: true` modules are restricted to the relative snapshotted graph.
+- Customize installed extensions in this order: declarative configuration;
+  `urlcode-ui` copy, theme, template and CSS overrides; a hook declared by the
+  extension; a new extension only when the installed contract cannot express
+  the behavior. Extension hooks run trusted in-process and reject `sandbox:
+  true` in contract v1.
 - Write exact response fixtures for success and failure, covering every active
   method, middleware behavior, HEAD, and any range or cache semantics.
 - Follow `docs/BEST-PRACTICES.md` for layout and readability as the project grows.