@jimhoyd/urlcode 0.4.7 → 0.5.0

package/dist/types/extension-artifacts.d.ts

@@ -0,0 +1,87 @@
+/** Offline, declarative extension bundles. These are deliberately not Node packages. */
+export declare const ARTIFACT_REPOSITORY = "jimhoyd-com/urlcode";
+export declare const ARTIFACT_WORKFLOW = "jimhoyd-com/urlcode/.github/workflows/extension-artifacts.yml";
+export interface ArtifactEntry {
+    name: string;
+    version: string;
+    asset: string;
+    sha256: string;
+    kind: 'declarative';
+}
+export interface Catalog {
+    format: 1;
+    tag: string;
+    commit: string;
+    artifacts: ArtifactEntry[];
+    revoked: {
+        sha256: string;
+        reason: string;
+    }[];
+}
+export interface LockedArtifact extends ArtifactEntry {
+    catalog: {
+        tag: string;
+        commit: string;
+    };
+}
+export interface ExtensionLock {
+    format: 1;
+    artifacts: LockedArtifact[];
+}
+/** Parse an untrusted catalog only after its GitHub attestation was verified by the caller. */
+export declare function parseCatalog(bytes: Uint8Array, requestedTag: string): Catalog;
+export interface TarFile {
+    path: string;
+    bytes: Uint8Array;
+}
+export interface ArchiveLimits {
+    archive: number;
+    expanded: number;
+    files: number;
+    file: number;
+    label: string;
+}
+/** A minimal tar reader: only regular files are accepted, before any write occurs. */
+export declare function readBoundedTgz(source: Uint8Array, limits: ArchiveLimits): TarFile[];
+export declare function extractArtifact(bytes: Uint8Array, entry: ArtifactEntry, destination: string): Promise<void>;
+export declare function readLock(project: string): Promise<ExtensionLock>;
+export declare function writeLock(project: string, lock: ExtensionLock): Promise<void>;
+export declare function cachePath(project: string, sha256: string): string;
+export interface ReleaseAsset {
+    name: string;
+    url: string;
+}
+export interface ArtifactTransport {
+    release(tag: string): Promise<ReleaseAsset[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+/** The default transport accepts only GitHub Release asset URLs and verifies every downloaded subject. */
+export declare const githubTransport: ArtifactTransport;
+export declare function resolveCatalog(release: string, transport?: ArtifactTransport): Promise<{
+    catalog: Catalog;
+    assets: ReleaseAsset[];
+}>;
+export declare function installArtifact(project: string, release: string, artifactName: string, transport?: ArtifactTransport): Promise<ExtensionLock>;
+export declare function inspectArtifacts(project: string): Promise<{
+    lock: ExtensionLock;
+    cached: string[];
+    missing: string[];
+    invalid: string[];
+}>;
+/** Read-only inventory for authoring tools. Paths come from the verified archive, never from an arbitrary filesystem argument. */
+export declare function describeArtifactCache(project: string): Promise<{
+    format: 1;
+    artifacts: (LockedArtifact & {
+        status: 'cached' | 'missing' | 'invalid';
+        files: string[];
+    })[];
+}>;
+/** Return one bounded text/JSON member from a verified cached artifact for MCP/agent consumers. */
+export declare function readArtifactMember(project: string, artifactName: string, path: string): Promise<{
+    format: 1;
+    artifact: LockedArtifact;
+    path: string;
+    mediaType: 'application/json' | 'text/markdown';
+    content: unknown;
+}>;

package/dist/types/extension-bundles.d.ts

@@ -0,0 +1,49 @@
+/** Verified, executable first-party bundles. Unlike extension artifacts, these are trusted operator code. */
+export declare const BUNDLE_REPOSITORY = "jimhoyd-com/urlcode";
+export declare const BUNDLE_WORKFLOW = "jimhoyd-com/urlcode/.github/workflows/extension-bundles.yml";
+export interface BundleEntry {
+    name: string;
+    version: string;
+    asset: string;
+    sha256: string;
+    entry: string;
+}
+export interface BundleCatalog {
+    format: 1;
+    tag: string;
+    commit: string;
+    coreVersion: string;
+    bundles: BundleEntry[];
+    revoked: {
+        sha256: string;
+        reason: string;
+    }[];
+}
+export interface LockedBundle extends BundleEntry {
+    catalog: {
+        tag: string;
+        commit: string;
+    };
+    coreVersion: string;
+}
+export interface BundleLock {
+    format: 1;
+    bundles: LockedBundle[];
+}
+export interface BundleTransport {
+    release(tag: string): Promise<{
+        name: string;
+        url: string;
+    }[]>;
+    download(url: string): Promise<Uint8Array>;
+    attest(path: string, release: string): Promise<void>;
+}
+/** Parse only a catalog whose attestation was already verified against the requested immutable tag. */
+export declare function parseBundleCatalog(bytes: Uint8Array, requested: string): BundleCatalog;
+export declare function extractBundle(bytes: Uint8Array, item: Pick<LockedBundle, 'name' | 'version' | 'entry' | 'sha256' | 'coreVersion'>, destination: string): Promise<void>;
+export declare function bundleCachePath(project: string, sha256: string): string;
+export declare function readBundleLock(project: string): Promise<BundleLock>;
+export declare const githubBundleTransport: BundleTransport;
+export declare function installBundle(project: string, release: string, bundleName: string, transport?: BundleTransport): Promise<BundleLock>;
+/** Explicit host-only loader. It never reads project YAML, downloads, updates, or discovers code. */
+export declare function loadExtensionBundle(project: string, bundleName: string): Promise<Record<string, unknown>>;

package/dist/types/extensions.d.ts

@@ -185,6 +185,8 @@ export interface ScaffoldRequest {
     hostFile: string;
     /** Every extension name being scaffolded together, including this one, in a canonical (sorted) order that is independent of the `--with` spelling. */
     names: readonly string[];
+    /** `npm` resolves extension packages from the operator's install; `bundle` resolves only already-verified, locked release bundles. */
+    distribution?: 'npm' | 'bundle';
     /**
      * Operator acknowledgements from repeated `--ack <extension>:<id>` flags, sorted and de-duplicated; empty when none. Core treats
      * them as opaque strings and never invents one. An extension reads only the ones qualified with its own name. To require one, throw
@@ -224,6 +226,8 @@ export interface ScaffoldResult {
     hostSetup: string[];
     hostEntries: string[];
     hostClose?: string[];
+    /** Named exports core may bind from this extension's already-verified executable bundle. Required for bundle distribution; never a project-controlled module reference. */
+    hostBundleExports?: string[];
     /** Files written relative to `directory` with their modes; never inside the project, never overwriting. */
     files: ScaffoldFile[];
     /** Markdown appended to README.md under a heading core adds; the numbered steps merged in the resolved order. */

package/dist/types/functions.d.ts

@@ -36,8 +36,12 @@ export interface FunctionWorkerData {
     dependencies: Record<string, string[]>;
     entries: [string, string][];
 }
+/** `route.pattern` is the route key that matched, so one module can serve several routes without reading `request.url`. */
 export type FunctionContext = RequestContext & {
     args?: Record<string, ParameterValue>;
+    route?: {
+        pattern: string;
+    };
 };
 export interface FunctionWorkerRequest {
     id: string;

package/dist/types/index.d.ts

@@ -18,8 +18,8 @@ export { buildTypeScriptProject } from './typescript-authoring.ts';
 export type { TypeScriptBuildReport } from './typescript-authoring.ts';
 export { importBulkProject } from './bulk.ts';
 export type { BulkFormat, BulkFilePlan, BulkImportReport } from './bulk.ts';
-export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens } from './tooling.ts';
-export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection } from './tooling.ts';
+export { inspectProject, validateProject, explainRoute, explainProject, previewImport, previewExport, getCapability, getSchemaFragment, schemaPathNames, inspectExtensions, describeExtensions, buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './tooling.ts';
+export type { InspectOptions, RouteExplanation, RouteMiss, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport, CapabilityEntry, CapabilityUsage, SchemaFragment, ExtensionInspection, ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './tooling.ts';
 export { buildManifest, renderManifest, MANIFEST_SCHEMA_VERSION } from './manifest.ts';
 export type { Manifest, ManifestRoute, ManifestModule, RecipeProvenance } from './manifest.ts';
 export { serveMcp } from './mcp.ts';
@@ -40,3 +40,5 @@ 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';
+export { installBundle, loadExtensionBundle, readBundleLock, parseBundleCatalog } from './extension-bundles.ts';
+export type { BundleCatalog, BundleEntry, BundleLock, LockedBundle, BundleTransport } from './extension-bundles.ts';

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

@@ -1,5 +1,6 @@
 import type { ScaffoldResult } from './extensions.ts';
 import type { DependencyPin } from './project-dependencies.ts';
+import { type BundleTransport } from './extension-bundles.ts';
 export interface InitWithOptions {
     cwd?: string | undefined;
     /** Default true: record exact pins for core, the named extensions and their declared peers. */
@@ -8,6 +9,10 @@ export interface InitWithOptions {
     pins?: ReadonlyMap<string, string> | undefined;
     /** `--ack <extension>:<id>`, repeatable: opaque qualified acknowledgements handed to every scaffold. Core refuses one that no scaffold consumed. */
     acknowledgements?: readonly string[] | undefined;
+    /** Immutable signed release used instead of resolving executable extension packages from npm. */
+    bundleRelease?: string | undefined;
+    /** Test-only transport injection; production uses GitHub attestation verification. */
+    bundleTransport?: BundleTransport | undefined;
 }
 export interface InitWithResult {
     directory: string;
@@ -30,4 +35,4 @@ export declare function orderScaffolds(results: readonly ScaffoldResult[]): Scaf
  * `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, requested: readonly string[], { cwd, manifest, pins, acknowledgements }?: InitWithOptions): Promise<InitWithResult>;
+export declare function initProjectWith(destination: string, requested: readonly string[], { cwd, manifest, pins, acknowledgements, bundleRelease, bundleTransport }?: InitWithOptions): Promise<InitWithResult>;

package/dist/types/match.d.ts

@@ -37,6 +37,7 @@ export interface MatchableRoute {
     pattern: string;
     parts: string[];
     prefix?: string;
+    wildcard?: boolean;
     extension?: string;
     parameters: CompiledParameter[];
     env: Record<string, string>;

package/dist/types/site.d.ts

@@ -8,4 +8,6 @@ type SiteKey = keyof SiteConfig;
 export declare const generatedPaths: Readonly<Record<SiteKey, string>>;
 export declare function expandSite(document: ProjectDocument, root: string, { origin, log, routes }?: SiteOptions): Promise<Record<string, RouteConfig>>;
 export declare function applySite(loaded: LoadedDocument, options?: SiteOptions): Promise<Record<string, RouteConfig>>;
+export declare const notFoundInlineLimit = 65536;
+export declare function inlineNotFound(loaded: LoadedDocument): Promise<boolean>;
 export {};

package/dist/types/tooling.d.ts

@@ -10,8 +10,8 @@ export type { CapabilityEntry, CapabilityUsage } from './capability-query.ts';
 export { getSchemaFragment, schemaPathNames } from './schema-query.ts';
 export type { SchemaFragment } from './schema-query.ts';
 export { listRecipes, showRecipe, searchRecipes, listExamples, searchExamples };
-export { buildContext, renderContext, estimateTokens, documentationTokens } from './context.ts';
-export type { ContextOptions, ProjectContext, ContextSection } from './context.ts';
+export { buildContext, renderContext, estimateTokens, documentationTokens, buildTaskContext, renderTaskContext, contextTasks } from './context.ts';
+export type { ContextOptions, ProjectContext, ContextSection, ContextTask, TaskContext, TaskShape } from './context.ts';
 export type { RouteExplanation, ExplainedHandler, ExplainedCache, ExplainedExtensionRequirement, ExtensionProvider, TargetSupport } from './explain.ts';
 /** `extensions` are operator registrations from a host file; explain reports whether each requirement has a provider. Nothing is activated. */
 export interface InspectOptions {

package/dist/types/types.d.ts

@@ -264,6 +264,7 @@ export interface CompiledRoute extends Omit<RouteConfig, 'methods' | 'parameters
     reply?: Reply;
     expiresAt?: number;
     prefix?: string;
+    wildcard?: boolean;
     middleware: CompiledMiddleware[];
     function?: CompiledFunction;
     respond?: RespondSpec;

package/dist/types.js

@@ -127,7 +127,7 @@
                                                                                                                                                                             
                                                                                             
                                                                                                 
-                                                                                                                 
+                                                                                                                                     
                                                                 
                                                                                              
                                                                                   

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 57,753 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 60,557 tokens (estimate: characters / 4). -->
 
 <!-- urlcode-current-version:start -->
 # URLCode
@@ -7,7 +7,7 @@
 > A portable runtime for programmable URL behavior, and the framework that grows
 > from it: routes in YAML, functions and middleware, then accounts, administration and
 > stored links as operator-installed extensions. Stable project format
-> `version: "1"`. Core is Apache-2.0; this revision is `0.4.7`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.0`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
 > auth, admin and ui extension packages in this repository are versioned at the same
 > revision; confirm what is published with `npm run release:status`.
@@ -18,9 +18,6 @@ or fetch inside a `sandbox: true` function, regex routes, database access,
 global middleware, YAML interpolation, or packages named in YAML. Secrets need external revision-pinned
 grants. Unsupported features fail with the route named; nothing degrades silently.
 
-Agents that explicitly want the complete consolidated reference in one fetch should read
-[llms-full.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms-full.txt), generated from the documents below (about 50k tokens, estimated).
-
 ## Contents
 
 1. [The URLCode framework](#the-urlcode-framework)
@@ -199,15 +196,23 @@ and the MCP `get_extensions` tool report those surfaces and their fast checks,
 so people and agents can discover the supported path instead of replacing
 package behavior.
 
+A signed declarative artifact is a separate, optional authoring input, not a
+fifth way to compose executable behavior. A project may lock an attested
+schema/example bundle and expose it through MCP `get_extension_artifacts` and
+`get_extension_artifact`; the npm package and operator host remain the only
+executable extension path. See [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts).
+
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
 ```
 
-`urlcode init <dir> --with ui,auth,admin` writes this layout in one step: it
-resolves each installed `@jimhoyd/urlcode-<name>` from the current directory,
-calls its `scaffold` export and merges the fragments into `app/urlcode.yaml`,
-one `host.mjs` and one `README.md`, refusing before writing anything when a
-package is missing or two fragments collide (the contract is documented under
+`urlcode init <dir> --with ui,auth,admin` writes this layout in one step: by
+default it resolves each installed `@jimhoyd/urlcode-<name>` from the current
+directory; with `--bundle-release extension-bundles@v…` it verifies and locks
+the named GitHub Release bundles instead. In either mode it calls the verified
+module's `scaffold` export and merges fragments into `app/urlcode.yaml`, one
+explicit `host.mjs` and one `README.md`, refusing before writing a site when a
+package/bundle is missing or two fragments collide (the contract is documented under
 [scaffolding](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#scaffolding-with-init---with)). `urlcode-auth init`
 and `urlcode-admin init` write the same layout for a single package; `urlcode-auth bootstrap` creates the first
 administrator from JSON on stdin. `inspectExtensionRevision(project)` prints
@@ -301,7 +306,10 @@ Make the first retrieval one bounded query: the MCP tool `get_context` when the
 `urlcode capabilities NAME` (MCP `get_capability`) for one capability's limits,
 `get_schema` for one YAML fragment, `urlcode recipes search TEXT`
 (`search_recipes`), `explain` for a route's effective behavior and, when the
-operator supplies a host file, `get_extensions`. Context is a summary with the
+operator supplies a host file, `get_extensions`. If the project has a committed
+`urlcode.extensions.lock.json`, use `get_extension_artifacts` to verify and
+inventory its inert data and `get_extension_artifact` to retrieve only the
+needed schema, example or README. Context is a summary with the
 constraints and exact commands, not a schema dump, and it never hides a
 capability limit: ask `capabilities NAME` before promising a feature.
 
@@ -356,7 +364,15 @@ teaches how to retrieve the minimum reference through `urlcode capabilities`,
 the documentation whole. For a host-composed application, `get_extensions`
 adds each extension's schemas, hooks, supported authoring surfaces and fast
 checks. Agents should use those surfaces before generating replacement package
-behavior. Neither file replaces the schema; both defer to it.
+behavior. A committed artifact lock is a separate offline authoring input:
+`get_extension_artifacts` validates its cache and lists allowlisted files;
+`get_extension_artifact` reads one bounded JSON or Markdown member from its
+verified archive. The CLI fallback is `urlcode extension-artifacts inspect
+--project DIR --json`. An artifact never installs or activates an npm package,
+registers a host extension or grants authority. Agents must not fetch or update
+one unless the user explicitly requests that project change and names the
+immutable `extensions@v…` release. Neither guide nor artifact replaces the
+runtime schema; all defer to the pinned implementation.
 
 Treat core, installed extensions and product UI as one application with
 different owners. Keep auth/admin security and workflow behavior package-owned;
@@ -482,8 +498,21 @@ Before writing a function, check whether a declarative feature already covers th
 need. Security headers are the usual miss: a project that declares nothing sends
 only the runtime's defaults (`nosniff`, `no-store`, a request ID).
 
+Building only redirects? `urlcode context --project DIR --task redirects` (MCP
+`get_context {"task":"redirects"}`) is a bounded, redirect-only call: every row
+below with the exact YAML, the two gaps with their exact validation error, and
+this project's own redirects — cheaper than this table or the recipe catalog.
+
 | I need | Declare | Reference |
 |---|---|---|
+| Fixed redirect (301/302/303/307/308, 302 default) | `redirect: {url, status}` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Parameterized path redirect (`/users/{id}` to `/profiles/{id}`) | `{name}` placeholder in `redirect.url` naming a declared path parameter | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Root-relative redirect (`/users/{id}` to `/profiles/{id}`) | `redirect.url: /profiles/{id}`: one leading slash, path only, `{name}` placeholders | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Wildcard/suffix redirect (`/legacy/**` to `/modern/{**}`, any depth) | terminal `/**` route key with a literal prefix, `{**}` in the destination path; redirect only, not static or Cloudflare | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Redirect that preserves query keys | `redirect.query.pass` (explicit allowlist) or `query.map` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| Redirect that keeps the method/body (POST) | `methods` plus `status: 307` or `308` | [redirects](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/redirects.md) |
+| 404 for unmatched paths | `site.notFound` (a project-relative `.html` file) | [site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md) |
+| Host-based or scheme-based redirect — **gap** | not expressible; destination is a literal absolute `https://host/path` or a root-relative path | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md) |
 | Security headers (CSP, HSTS, frame and referrer policy) | `policies.security: {headers: oshp}` or `policies.profile: hardened` | [security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/security.md) |
 | Cache headers on a page, download or static mount | `cacheControl`: `no-cache` (default), `no-store`, `public, max-age=3600` or `public, max-age=31536000, immutable`; nothing else validates | [assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/assets.md) |
 | A cache strategy on any route | `policies.cache` | [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md) |
@@ -507,8 +536,9 @@ Which handler serves the response:
 Data persistence has no native handler. The operator-installed `store` extension
 serves declared collections as a CRUD API, and `urlcode recipes search "crud store
 persist"` finds the `store-crud` recipe. It needs the operator to install
-`@jimhoyd/urlcode-store` (on npm) and a host file. `init --with
-ui,auth,store` scaffolds one from the published packages; a no-auth
+`@jimhoyd/urlcode-store` package or an attested executable bundle and a host
+file. `init --with ui,auth,store --bundle-release extension-bundles@v…`
+scaffolds the npm-free bundle form; a no-auth
 `--with store` needs `--ack store:public-write`, which only a core release after the
 store's first publication has, so say so rather than promising it. Report anything beyond that recipe (filtering, sorting, per-record
 ownership, a database) as a gap. `urlcode context` lists the same built-ins so
@@ -727,7 +757,7 @@ programmatic compatibility analysis and provider verification limits.
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-GUIDE.md
 
 <!-- urlcode-current-version:start -->
-This guide targets URLCode 0.4.7. Start with the function example below,
+This guide targets URLCode 0.5.0. Start with the function example below,
 then add only the fields your route needs. The authoritative machine-readable
 shape is [JSON Schema](https://github.com/jimhoyd-com/urlcode/blob/main/schemas/urlcode.schema.json); semantic rules are in the
 [specification](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPECIFICATION.md). Unsupported fields fail validation.
@@ -1297,7 +1327,8 @@ Keys are absolute case-sensitive paths. Trailing slashes are significant.
 Parameters occupy whole segments, e.g. `/p/{id}`, with distinct identifier names.
 Each parameter matches exactly one nonempty segment, never across `/`; it is not
 greedy. No regex paths, client-controlled host dispatch or dot segments. Only static directory mounts
-support a terminal `/*` wildcard with an otherwise literal path. Route keys cannot contain
+support a terminal `/*` wildcard with an otherwise literal path; a `redirect` alone supports a
+terminal `/**` (one or more remaining segments, at least a one-segment literal prefix, see [route matching](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ROUTING.md)). Route keys cannot contain
 percent encoding, spaces, backslashes or query strings. Path length is limited
 to 2,048 characters and 32 segments. `/_urlcode` is reserved.
 
@@ -1436,7 +1467,9 @@ Unknown query keys are ignored unless explicitly passed by a redirect.
 ### Redirects
 
 `redirect.url` is an absolute HTTP(S) URL with literal scheme/host and no embedded
-credentials or whitespace/control characters. `{pathInput}` placeholders are
+credentials or whitespace/control characters, or a root-relative path (one leading `/`, never
+`//`, no dot segments) that answers a path-only `Location`. On a `/**` route `{**}` is the captured
+suffix, once, each segment encoded. `{pathInput}` placeholders are
 allowed only in the destination pathname and encoded as single components.
 No environment/secret interpolation. Status defaults to 302; allowed values are
 301, 302, 303, 307 and 308.
@@ -1679,6 +1712,7 @@ not part of the route key.
 | `/go` | `/go`, `/go?campaign=spring` | `/Go`, `/go/`, `/go/extra` |
 | `/r/{code}` | `/r/abc`, `/r/123` | `/r/`, `/r/abc/extra` |
 | `/r/{code}/details` | `/r/abc/details` | `/r/abc/other/details` |
+| `/legacy/**` with a `redirect` handler | `/legacy/a`, `/legacy/a/b/c` | `/legacy`, `/legacy/`, `/legacy/a//b` |
 | `/assets/*` with a `static` handler | Files under `/assets/`, including `/assets/css/site.css` | `/assets`, `/assets-other/site.css` |
 
 A `{parameter}` captures exactly one nonempty path segment. It is **not greedy**:
@@ -1691,8 +1725,16 @@ path. It covers the remaining nested file path; it is not a named capture or a
 regex operator. Matching a mount does not guarantee a response file exists:
 missing files return 404. It is not a catch-all for functions or redirects.
 
+A `redirect` handler alone supports a terminal `/**` after a literal prefix (never bare `/**`, never
+with a `{parameter}`). It matches one or more remaining segments, and `{**}` in `redirect.url` is
+those segments, each percent-encoded and joined by `/`, usable once and only in the destination
+path. Empty segments, `.`/`..`, encoded slashes and captures over 1,024 characters do not match.
+Exact and `{parameter}` routes always win over it, so `/legacy/keep/{id}` can carve an exception out
+of `/legacy/**`. It is refused on static hosting (S3 redirects match one path) and on Cloudflare
+until the Worker table supports suffix matching, and it cannot share a prefix with a `static` mount.
+
 No regex routes, greedy parameters, optional segments, partial-segment parameters,
-`**` globs, or regex constraints inside `{code}` are implemented. Characters such
+other `**` globs, or regex constraints inside `{code}` are implemented. Characters such
 as `.` and `+` have no regex meaning in a literal path. Do not paste a regex into
 a route key: some regex-looking text is legal literal text, while unsupported
 syntax may fail validation. Parameter-schema `pattern` is also unsupported.
@@ -2551,15 +2593,19 @@ as the not-found page instead. The page answers every unknown URL, so it cannot
 
 `urlcode build --target static` writes it as the object `404.html` (see
 [static hosting](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STATIC.md)); point the host's error document at that key.
-Cloudflare refuses it like any `page` route (no asset binding); the Worker
-has no per-request fallback page, so use the platform's own 404 asset there.
+Cloudflare inlines it: the page is small, singular and static, so the build
+reads it (64 KiB cap, must decode as UTF-8) and carries it in the artifact as a
+`respond` route at `/404.html`, answering the same status, headers and method
+rules as every other target. See [`docs/CLOUDFLARE.md`](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CLOUDFLARE.md#site-notfound-is-inlined).
+`favicon` and `llms` stay refused there like any other `page` route (no asset
+binding).
 
 ### Per-target support
 
-| Target | `robots`, `sitemap`, `securityTxt` (`respond`) | `favicon`, `llms`, `notFound` (`page`) |
-| --- | --- | --- |
-| self-hosted, Vercel, AWS | served | served |
-| Cloudflare | compiled into the artifact (`build --origin` for absolute URLs) | refused at build time like any `page` route: the target has no asset binding; serve them from the platform's static assets |
+| Target | `robots`, `sitemap`, `securityTxt` (`respond`) | `favicon`, `llms` (`page`) | `notFound` |
+| --- | --- | --- | --- |
+| self-hosted, Vercel, AWS | served | served | served |
+| Cloudflare | compiled into the artifact (`build --origin` for absolute URLs) | refused at build time like any `page` route: the target has no asset binding; serve them from the platform's static assets | inlined into the artifact (64 KiB cap, UTF-8) |
 
 ### Not in this release
 
@@ -3218,6 +3264,124 @@ Serving the result is the usual explicit host binding:
 urlcode validate --project app --host-file "$PWD/host.mjs" --origin https://site.example
 ```
 
+### Signed declarative artifacts
+
+Core remains the npm-distributed runtime. The workspace extensions are not an
+alternate npm channel. A release can additionally carry a small, **data-only**
+extension artifact for tooling that understands its declared format. It is not
+a Node module and cannot activate an extension, run a hook, replace a trusted
+operator host, or grant a route any authority.
+
+Install an artifact only from its immutable `extensions@v…` GitHub Release. The
+published inert store configuration schema snapshot can be installed with:
+
+```sh
+urlcode extension-artifacts install store-schema --artifact-release extensions@v1.0.0 --project app
+urlcode extension-artifacts update store-schema --artifact-release extensions@v1.1.0 --project app
+urlcode extension-artifacts inspect --project app
+```
+
+The command downloads the signed `extensions-catalog.json`, verifies its
+GitHub attestation against the dedicated artifact workflow in
+`jimhoyd-com/urlcode` and the exact requested tag ref, then verifies the selected
+`.tgz` the same way. Self-hosted-runner attestations are refused. The catalog
+pins its release tag, source commit, filename and SHA-256; a catalog revocation
+refuses installation. `gh` with support for attestation source-ref verification
+is therefore a required local dependency for this command.
+
+The resulting `urlcode.extensions.lock.json` is the reproducibility boundary:
+commit it with the project. Every locked artifact records its own catalog tag
+and source commit, so updating one artifact cannot silently relabel another as
+coming from a newer release. Extracted files live under
+`app/.urlcode/extensions/<sha256>/` and are checked before extraction. Archives
+are size- and file-count-bounded, reject links and traversal, and may contain
+only `extension.json`, JSON configuration/schema data, and an optional README.
+Any JavaScript, package manifest, install hook, native module, or unknown file
+causes refusal. `inspect` re-hashes the cached archive and every extracted file,
+reporting an entry as missing or invalid rather than trusting its directory
+name. Updates are never automatic: review a newer immutable release and run
+`update` explicitly.
+
+Agent tooling can consume a committed lock without gaining write or execution
+authority. MCP `get_extension_artifacts` validates the lock and cache and lists
+the signed member paths; `get_extension_artifact {name, path}` returns one
+verified, bounded JSON or Markdown member directly from the cached archive.
+The CLI fallback is `urlcode extension-artifacts inspect --project app --json`.
+Neither MCP tool performs a network request, installs or updates an artifact,
+loads a host file, or activates code. A missing or modified cache is reported
+as missing/invalid and its contents are not returned.
+
+This does not relax the existing host boundary. `--host-file` is still the only
+way to load trusted operator extension code, and artifact files are never
+imported by `serve`, `validate`, `init --with`, or the runtime.
+
+Artifact versions are independent from npm package versions. The initial
+`store-schema` artifact is a reviewed configuration-schema snapshot and example,
+not the `@jimhoyd/urlcode-store` implementation. Installing it does not install
+or activate that package. Its README names the separate executable and operator
+requirements.
+
+### Signed executable extension bundles
+
+Official executable extensions are migrating away from consumer npm installs.
+They use a separate, immutable `extension-bundles@v…` GitHub Release namespace;
+it is intentionally disjoint from the permanently data-only `extensions@v…`
+artifact channel above. A bundle is a bounded, frozen Node module tree produced
+from reviewed first-party source, not a general extension marketplace and not
+a project dependency resolver.
+
+An operator explicitly installs one named bundle from an immutable release:
+
+```sh
+urlcode extension-bundles install store \
+  --bundle-release extension-bundles@v1.0.0 --project app
+```
+
+For a new composed site, `init --with` can perform that verified installation
+before it writes the route project. This is the npm-free extension path: the
+generated `package.json`, when requested, pins URLCode core only; the generated
+host loads only the names recorded in the bundle lockfile.
+
+```sh
+urlcode init site --with ui,auth,admin \
+  --bundle-release extension-bundles@v1.0.0
+```
+
+`init` verifies each requested bundle in a temporary operator staging root,
+obtains each scaffold from that verified module tree, then writes the cache and
+`urlcode.extension-bundles.lock.json` into the new site. It never resolves an
+extension package from npm in this mode. A failed verification or scaffold
+refusal leaves no site directory behind. The release tag is still an explicit
+operator choice; YAML cannot supply it.
+
+The command verifies attestations for both the catalog and selected archive
+against the requested tag and dedicated workflow, rejects self-hosted runners,
+checks the catalog's commit, filename and SHA-256, and extracts only regular
+files in the signed module tree. It writes
+`urlcode.extension-bundles.lock.json` and keeps the frozen bytes under
+`app/.urlcode/extension-bundles/<sha256>/`. There is no automatic discovery,
+installation, update, or fallback to npm. `inspect` reads the committed lock;
+a modified cache or an incompatible core version refuses before import.
+
+Executable bundles are **trusted operator code**, exactly like a hand-written
+operator host module. Project YAML cannot choose a bundle, name a release,
+trigger a download, or grant a bundle authority. An operator host explicitly
+loads a locked entry by name, then chooses which returned registration to pass
+to `createRuntime`:
+
+```js
+import { loadExtensionBundle } from '@jimhoyd/urlcode/extension-bundles';
+
+const { storeExtension } = await loadExtensionBundle('/absolute/site/app', 'store');
+export default { extensions: [storeExtension({ directory: '/srv/site-data', projectSha256: process.env.PROJECT_SHA256 })] };
+```
+
+This does not make bundle code sandboxed and does not alter a route that
+declares `sandbox: true`; those remain distinct execution modes. npm packages
+remain the migration fallback until the first signed bundle release and the
+fresh composed consumer flow have been released and proven. Do not unpublish a
+package merely because its data-only artifact exists.
+
 ---
 
 # Composing a site from ui, auth and admin