@jimhoyd/urlcode 0.4.0-alpha.3 → 0.4.2

package/dist/types/config.d.ts

@@ -1,4 +1,4 @@
-import type { AuthoredRouteConfig, LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
+import type { LoadedDocument, ProjectDocument, RouteConfig } from './types.ts';
 /** What config-worker.ts posts back: the loaded document, or the ConfigError message. */
 export type ConfigWorkerResult = {
     value: LoadedDocument;
@@ -17,14 +17,6 @@ export declare const SHORT_FORM_PATH_SCHEMA: {
     readonly minLength: 1;
     readonly maxLength: 128;
 };
-/**
- * Expands the YAML short forms into the canonical long form. `function: functions/x.mjs`
- * becomes `{source, args}` with an argument per `{param}` in the path, declaring any
- * parameter the route does not declare itself; a string middleware entry becomes `{source}`;
- * a route-level `cache` becomes `policies.cache` (refused alongside a direct `policies.cache`).
- * Everything downstream (routes, audit, the compiled table) sees only the long form.
- */
-export declare function normalizeRoute(pattern: string, route: AuthoredRouteConfig | RouteConfig): RouteConfig;
 export declare function safeFile(root: string, file: unknown): Promise<string>;
 export declare function loadDocument(project: string, { timeoutMs }?: {
     timeoutMs?: number;

package/dist/types/explain.d.ts

@@ -95,7 +95,6 @@ export interface ExplainOptions {
     projectSha256?: string | undefined;
     now?: number | undefined;
 }
-export declare function routeState(route: CompiledRoute, now: number): RouteState;
 /** Describe one compiled route. `chain` is the policy chain compiled for it, when the project declares policies. */
 export declare function explainCompiledRoute(loaded: LoadedDocument, route: CompiledRoute, chain: PolicyChain | undefined, options?: ExplainOptions): RouteExplanation;
 export declare function nearestRoutes(target: string, patterns: Iterable<string>, limit?: number): string[];

package/dist/types/extensions.d.ts

@@ -66,6 +66,62 @@ export interface ExtensionInstance {
 export interface ExtensionImmutableAssets {
     prefix: string;
 }
+export interface ExtensionHookReference {
+    source: string;
+    export?: string;
+    sandbox?: boolean;
+    sandboxReason?: string;
+}
+export type ExtensionHookConfig = string | ExtensionHookReference;
+export type ExtensionHookKind = 'filter' | 'action';
+/** Machine-readable contract for one project hook an extension exposes. */
+export interface ExtensionHookContract {
+    name: string;
+    kind: ExtensionHookKind;
+    description: string;
+    inputSchema: object;
+    outputSchema?: object;
+}
+export type LoadedExtensionHooks<T extends string = string> = Partial<Record<T, (input: unknown) => unknown>>;
+/** Shared schema for project hook references. Omission means trusted execution. */
+export declare const extensionHookReferenceSchema: {
+    readonly oneOf: readonly [{
+        readonly type: "string";
+        readonly minLength: 1;
+        readonly maxLength: 1024;
+    }, {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["source"];
+        readonly properties: {
+            readonly source: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1024;
+            };
+            readonly export: {
+                readonly type: "string";
+                readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+            };
+            readonly sandbox: {
+                readonly type: "boolean";
+            };
+            readonly sandboxReason: {
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 512;
+            };
+        };
+    }];
+};
+/** Builds the strict `config.hooks` schema from an extension's declared hook names. */
+export declare function extensionHooksSchema(contracts: readonly ExtensionHookContract[]): object;
+/**
+ * Loads project hooks once per activation. Project hooks are trusted first-party
+ * code by default, matching function/middleware routes. Sandboxed arbitrary-value
+ * hooks are not part of contract v1 and are refused rather than run trusted.
+ */
+export declare function loadExtensionHooks<T extends string>(config: Readonly<Record<string, unknown>> | undefined, contracts: readonly ExtensionHookContract[], context: Pick<ExtensionActivation, 'root'>): Promise<LoadedExtensionHooks<T>>;
 export interface RuntimeExtension {
     name: string;
     version: '1';
@@ -75,6 +131,8 @@ export interface RuntimeExtension {
     policySchema?: object;
     credentialHeaders?: string[];
     immutableAssets?: ExtensionImmutableAssets;
+    /** Project customization points, exposed by CLI/MCP for authors and agents. */
+    hooks?: readonly ExtensionHookContract[];
     /**
      * Reviewed, operator-declared cache sensitivity for `policies.extensions.<name>`
      * routes (never for an `extension:` mount, which is always treated as

package/dist/types/http-response.d.ts

@@ -32,7 +32,6 @@ export interface ResponseWriter {
     end(body?: ResponseBody): unknown;
     destroy(): unknown;
 }
-export declare const forbiddenHeaders: Set<string>;
 export declare function prepareResponse(result: HandlerResult, { requestId, method }: ResponseOptions): PreparedResponse;
 export declare function writeResponse(res: ResponseWriter, result: HandlerResult, options: ResponseOptions): number;
 export declare function errorResponse(error: unknown, { requestId, method, headers }: ResponseOptions & {

package/dist/types/index.d.ts

@@ -38,4 +38,5 @@ export { scaffoldProject } from './scaffold.ts';
 export type { ScaffoldReport, Unresolved as ScaffoldUnresolved } from './scaffold.ts';
 export { initProject, addRedirect } from './authoring.ts';
 export { initProjectWith } from './init-with.ts';
+export { collectDependencySet, renderPackageManifest, installSteps } from './project-dependencies.ts';
 export type { ScaffoldRequest, ScaffoldResult, ScaffoldFile } from './extensions.ts';

package/dist/types/init-with.d.ts

@@ -1,8 +1,10 @@
-import type { ScaffoldRequest, ScaffoldResult } from './extensions.ts';
-/** Directory names inside the generated site. The route project lives under `app/`; everything else is operator-owned. */
-export declare const PROJECT_DIRECTORY = "app", HOST_FILE = "host.mjs", ROUTES_FILE = "routes/extensions.yaml";
+import type { DependencyPin } from './project-dependencies.ts';
 export interface InitWithOptions {
     cwd?: string | undefined;
+    /** Default true: record exact pins for core, the named extensions and their declared peers. */
+    manifest?: boolean | undefined;
+    /** `--pin <package>=<specifier>` overrides, for local tarballs, checkouts and mirrors. */
+    pins?: ReadonlyMap<string, string> | undefined;
 }
 export interface InitWithResult {
     directory: string;
@@ -11,20 +13,12 @@ export interface InitWithResult {
     extensions: string[];
     projectSha256: string;
     nextSteps: string[];
+    dependencies: DependencyPin[];
 }
 export declare function parseWithNames(value: string): string[];
-export declare const packageName: (name: string) => string;
-/**
- * Resolves the extension package from the invoking directory (Node's package resolution with the default
- * conditions), imports it, and calls its `scaffold` export. Nothing is bundled; core never imports these packages
- * at build time. Refuses a missing package or a package without `scaffold` before anything is written.
- */
-export declare function loadScaffold(name: string, request: ScaffoldRequest, cwd: string): Promise<ScaffoldResult>;
-export declare function renderHost(names: readonly string[], results: readonly ScaffoldResult[]): string;
-export declare function renderReadme(directory: string, names: readonly string[], results: readonly ScaffoldResult[], starter: string, env: Record<string, string>, projectSha256: string): string;
 /**
  * `urlcode init <directory> --with a,b`: the starter under `app/`, every extension's fragments merged into one
  * `urlcode.yaml`, one `host.mjs`, one `README.md` and the extensions' own files. All packages are resolved and
  * their scaffolds computed before anything is written, so a refusal leaves no directory behind.
  */
-export declare function initProjectWith(destination: string, names: readonly string[], { cwd }?: InitWithOptions): Promise<InitWithResult>;
+export declare function initProjectWith(destination: string, names: readonly string[], { cwd, manifest, pins }?: InitWithOptions): Promise<InitWithResult>;

package/dist/types/manifest.d.ts

@@ -79,5 +79,4 @@ export interface Manifest {
 export declare function buildManifest(project: string, options?: InspectOptions): Promise<Manifest>;
 /** The manifest as `build` writes it: two-space JSON with a trailing newline. */
 export declare function renderManifest(manifest: Manifest): string;
-export declare const manifestFileName = "manifest.json";
 export declare function manifestPath(out: string): string;

package/dist/types/project-dependencies.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Exact dependency pins for a generated application.
+ *
+ * `urlcode init --with` resolves whatever `@jimhoyd/urlcode-<name>` packages are already installed beside the
+ * invoking directory. Without a manifest the generated site records nothing about which versions it was built
+ * against, so a later `npm install @jimhoyd/urlcode-auth` in that site can resolve a different set (#212). This
+ * module reads the versions that were actually resolved, validates the whole set against the packages' own
+ * declared `peerDependencies`, and renders a `package.json` pinning every one of them exactly.
+ *
+ * It never runs a package manager: generating a lockfile stays an explicit `npm install` the operator runs after
+ * reviewing the manifest. It also never imports an extension implementation -- only package metadata is read, by
+ * a name the caller supplied -- so core's generic extension boundary is unchanged.
+ */
+export declare const CORE_PACKAGE = "@jimhoyd/urlcode";
+interface Version {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: readonly (string | number)[];
+}
+export declare function parseVersion(value: string): Version | null;
+export declare function compareVersions(a: Version, b: Version): number;
+export declare function satisfiesRange(version: string, range: string, context?: string): boolean;
+export interface InstalledPackage {
+    name: string;
+    version: string;
+    directory: string;
+    peers: Record<string, string>;
+    optionalPeers: ReadonlySet<string>;
+    node: string | undefined;
+}
+/**
+ * Walks `node_modules` upwards from the invoking directory, exactly like Node's own resolution but reading the
+ * package's manifest rather than its entry point. Reading the manifest directly (instead of resolving the entry)
+ * means a package whose `exports` does not expose `./package.json` is still inspectable, and nothing in the
+ * package is loaded or executed.
+ */
+export declare function findInstalledPackage(name: string, from: string): Promise<InstalledPackage | null>;
+/** The version of the runtime executing this command; that is the version a generated site is pinned to. */
+export declare function runningCore(): Promise<InstalledPackage>;
+export interface DependencyPin {
+    name: string;
+    version: string;
+    specifier: string;
+    /** True when the specifier is a local path or tarball rather than a registry version. */
+    local: boolean;
+    /** `runtime` is core, `extension` was named in --with, `peer` was pulled in by a package's peerDependencies. */
+    role: 'runtime' | 'extension' | 'peer';
+}
+export interface DependencySet {
+    pins: DependencyPin[];
+    /** Exactly what goes into the generated `dependencies` block, sorted by name. */
+    dependencies: Record<string, string>;
+    /** Highest recognized `engines.node` floor across the set, or undefined when none was expressed as `>=x.y.z`. */
+    node: string | undefined;
+    /** True when any pin points at a local path or tarball. */
+    local: boolean;
+}
+export interface DependencyOptions {
+    cwd?: string | undefined;
+    /** `--pin <package>=<specifier>`: an operator-chosen specifier, for local tarballs and mirrors. */
+    overrides?: ReadonlyMap<string, string> | undefined;
+}
+export declare function parsePin(value: string): [string, string];
+/**
+ * Resolves core plus every named extension and their declared peers, then validates the whole set against every
+ * declared peer range before returning. Compatibility is judged as a set: a mismatch anywhere refuses, listing
+ * every mismatch rather than the first.
+ */
+export declare function collectDependencySet(names: readonly string[], packageNames: readonly string[], { cwd, overrides }?: DependencyOptions): Promise<DependencySet>;
+/** The generated manifest: private, module type, exact pins, and nothing that runs a package manager. */
+export declare function renderPackageManifest(directory: string, set: DependencySet): string;
+/**
+ * The install step is printed, never run: generating `package-lock.json` executes a package manager, which
+ * resolves and downloads code, so it stays the operator's explicit action after reviewing the manifest.
+ */
+export declare function installSteps(directory: string, set: DependencySet): string[];
+export {};

package/dist/types/readiness.d.ts

@@ -57,6 +57,9 @@ export interface AuditOptions {
 export interface AuditReport {
     elapsedMs: number;
     ready: boolean;
+    /** Empty when `ready`; otherwise one stable code per failed condition:
+     * `no-active-routes`, `route-count-mismatch`, `failed-checks`, `uncovered-route-methods`. */
+    notReadyReasons: string[];
     counts: {
         configured: number;
         active: number;

package/dist/types/tooling.d.ts

@@ -93,6 +93,7 @@ export interface ExtensionInspection {
         credentialHeaders: string[];
         schema: object;
         policySchema: object | null;
+        hooks: object[];
         declared: boolean;
         revisionPinned: boolean;
         mounts: string[];

package/dist/types/trusted-functions.d.ts

@@ -2,11 +2,9 @@ import type { FunctionRoute } from './function-sources.ts';
 import type { FunctionContext, FunctionResult } from './functions.ts';
 import type { GuestRequestPayload } from './guest-api.ts';
 import type { HandlerResult } from './http-response.ts';
-import type { LogFn } from './types.ts';
 export interface TrustedFunctionsOptions {
     timeoutMs?: number | undefined;
     maxBytes?: number | undefined;
-    log?: LogFn | undefined;
 }
 interface TrustedDefinition {
     source: string;
@@ -16,9 +14,8 @@ export type TrustedRoute = FunctionRoute<TrustedDefinition>;
 export declare class TrustedFunctions {
     timeoutMs: number;
     maxBytes: number;
-    log: LogFn;
     private readonly epoch;
-    constructor({ timeoutMs, maxBytes, log }?: TrustedFunctionsOptions);
+    constructor({ timeoutMs, maxBytes }?: TrustedFunctionsOptions);
     start(routes: TrustedRoute[]): Promise<this>;
     private loadExport;
     execute(route: TrustedRoute, request: GuestRequestPayload, context: FunctionContext, native: HandlerResult | undefined): Promise<FunctionResult>;

package/docs/AI-AUTHORING.md

@@ -25,7 +25,11 @@ fields or bypass target limits or operator grants. See [the design principle](PR
 6. [Readiness](READINESS.md), [capacity](CAPACITY.md), [DDoS/recovery](RESILIENCE.md).
 7. [The framework](FRAMEWORK.md) for accounts, administration and presentation:
    `extensions.<name>` blocks and `extension` mounts are the only YAML those
-   packages need; their configuration is documented in their own repositories.
+   packages need. [Composing a site](COMPOSING-A-SITE.md) is the map of what a
+   consumer may then change: the `config` each package accepts, the
+   presentation overrides under `ui/`, the project functions its lifecycle
+   hooks call, and when a requirement instead needs a new extension in
+   TypeScript.
 
 The root [llms.txt](../llms.txt) is a compact discovery index; the generated
 [llms-full.txt](../llms-full.txt) concatenates the authoring documents above in
@@ -269,9 +273,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](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](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
@@ -290,7 +295,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](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`

package/docs/AWS.md

@@ -11,6 +11,15 @@ self-hosted Node lifecycle, and a `sandbox: true` route would pay worker and
 WASM startup on every cold start. Both are refused at activation with the route
 named, never per request, trusted or sandboxed alike.
 
+That refusal is a settled position, not a gap awaiting an adapter: per-route
+Lambda compilation was considered and declined
+([the decision](OPEN-DECISIONS.md#accepted-one-node-deployment-per-project),
+[the analysis behind it](archive/2026-09-19/SPIKE-LAMBDA-COMPILE.md)). A project that uses
+`function` or `middleware` deploys instead as one trusted Node process — a
+container or a VM running the project as it runs locally — which supports every
+route type today. That process can run on AWS: ECS, EC2 and App Runner all
+serve it. The decision is about the execution model, not about avoiding AWS.
+
 A working project is in [`examples/aws/`](../examples/aws/).
 
 ## Set it up

package/docs/CI-FOLLOWUP-2026-09-19.md

@@ -68,7 +68,7 @@ extra shards would add setup and runner pressure.
   quality check or claim measured savings from a workflow with no prior runs.
 - The manual signed candidate builds all four tarballs and installs them together
   in a temporary consumer outside the workspace. It verifies the peer dependency
-  tree, installed versions, public imports, and `init --with auth,admin,ui`.
+  tree, installed versions, public imports, and `init --with ui,auth,admin`.
   `train.json` records package SHA-512 integrity and the source commit; the
   candidate manifest/checksums and provenance include the extension archives.
   Failure stops the candidate before attestation/upload. Nothing is published.

package/docs/CODEBASE-AUDIT-2026-09-20.md

@@ -1,3 +1,9 @@
+<!-- trust-model-prose: historical-file -->
+<!-- This report quotes the defective wording it is reporting -- including the
+     pre-trusted-default claims in finding 4 -- so the prose gate would read the
+     quotations as the guidance itself. The file is a dated review of one
+     commit and is not edited as the defects are fixed. -->
+
 # Codebase, tooling and documentation audit — 2026-09-20
 
 Reviewed commit: `bca8ac7` (core 0.4.0-alpha.2, auth 0.1.0-alpha.5,

package/docs/COMPOSING-A-SITE.md

@@ -0,0 +1,287 @@
+# 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` 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](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`
+
+| 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.