@jimhoyd/urlcode 0.4.8 → 0.5.0

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 59,492 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.8`. `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)
@@ -209,11 +206,13 @@ executable extension path. See [signed declarative artifacts](https://github.com
 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
@@ -508,12 +507,12 @@ this project's own redirects — cheaper than this table or the recipe catalog.
 |---|---|---|
 | 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) |
-| Fixed-depth suffix redirect (`/legacy/a/b` to `/modern/a/b`) | one route per depth, one placeholder per segment | [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) |
-| Wildcard/suffix redirect (`/legacy/*` to `/modern/*`, any depth) — **gap** | not expressible; terminal `/*` and `{rest...}` are refused on `redirect` | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.md) |
-| Host-based, scheme-based or relative-URL redirect — **gap** | not expressible; destination must be a literal absolute `https://host/path` | [open decision](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPEN-DECISIONS.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) |
@@ -537,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
@@ -757,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.8. 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.
@@ -1327,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.
 
@@ -1466,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.
@@ -1709,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**:
@@ -1721,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.
@@ -3260,9 +3272,8 @@ 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.
-For example, after the first release is published, its inert store configuration
-schema snapshot can be installed with:
+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
@@ -3310,6 +3321,67 @@ 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

package/llms.txt

@@ -4,7 +4,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.8`. `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`.
@@ -15,132 +15,68 @@ 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](llms-full.txt), generated from the documents below (about 50k tokens, estimated).
+## Start here (read only this section for a first attempt)
 
-## Building only redirects? Start here
-
-Run `urlcode context --project DIR --task redirects` (MCP `get_context {"task":"redirects"}`)
-first: one bounded call returning every supported shape below with exact YAML, the
-gaps with their exact validation error, and this project's own redirects — cheaper
-than reading this file or the recipe catalog. `urlcode recipes search redirect` and
-`urlcode recipes show redirect` give a runnable starting project.
+1. Run `urlcode context --project DIR` (MCP `get_context`). For redirect-only work run
+   `urlcode context --project DIR --task redirects`: supported shapes with exact YAML, gaps
+   with their exact validation error, a paste-ready `starter`, and this project's own redirects.
+2. For a new redirect-only project, `urlcode init DIR --template redirects` writes the tested starter (yaml, 404 page, `npm start` honoring `PORT`, fixtures). Otherwise write `urlcode.yaml`, then `urlcode validate --local --project DIR` and `urlcode test`.
+3. Do not read or grep [llms-full.txt](llms-full.txt) (about 60k tokens) for a routine task; it is the
+   deliberate fallback when the steps above do not answer the question.
 
 | Shape | Supported? | Use |
 |---|---|---|
-| Fixed redirect, any of 301/302/303/307/308 (302 default) | Yes | `redirect: {url, status}` — [redirects](docs/yaml/redirects.md) |
-| Parameterized path (`/users/{id}` to `/profiles/{id}`) | Yes | `{name}` placeholder in `redirect.url`, naming a declared path parameter |
-| Fixed-depth suffix (`/legacy/a/b` to `/modern/a/b`) | Yes, one route per depth | same as above with one placeholder per segment |
-| Query-string preservation | Yes, opt-in only | `redirect.query.pass` (explicit allowlist) / `query.map` |
-| Method-preserving redirect (keep POST body) | Yes | `methods` plus `status: 307` or `308` |
-| 404 for unmatched paths | Yes | `site.notFound` (a project-relative `.html` file) |
-| Wildcard/suffix redirect (`/legacy/*` to `/modern/*`, any depth) | No | terminal `/*` and `{rest...}` are refused on `redirect`; report the gap ([open decision](docs/OPEN-DECISIONS.md)) |
-| Host-based, scheme-based or relative-URL redirect | No | destination must be a literal absolute `https://host/path`; report the gap |
-
-## Declarative-first default
-
-> Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
-
-Check the installed version's primitives, YAML configuration, policies, supported
-extensions and recipes/templates before writing a custom function or middleware.
-Keep necessary custom code focused and report the capability gap; never invent
-fields or bypass target limits or operator grants. See [the design principle](docs/PROJECT-DIRECTION.md#design-principle-declarative-first).
-
-## Need X? Use this built-in first
-
-Route a task to the feature before writing code. Every row is off unless declared.
-
-| I need | Use | Where |
-|---|---|---|
-| Security headers (CSP, HSTS, nosniff, frame and referrer policy) | `policies.security` (`headers: oshp`, or `profile: hardened`) | [security](docs/policies/security.md), [policies](docs/POLICIES.md) |
-| Cache headers for a page, download or static folder | `cacheControl`, exactly one of `no-cache` (default), `no-store`, `public, max-age=3600`, `public, max-age=31536000, immutable` | [assets](docs/yaml/assets.md) |
-| Cache strategy or origin cache for any route | `policies.cache` | [cache](docs/policies/cache.md) |
-| Request body size, required body, content type, JSON syntax check | `request.body` (`maxBytes`, `required`, `contentTypes`, `format`); 413/415/400 | [HTTP](docs/HTTP.md) |
-| Restrict or allow HTTP methods | `methods` (default GET/HEAD); 405 with `Allow` | [HTTP](docs/HTTP.md) |
-| Rate limiting | `policies.throttle` | [throttle](docs/policies/throttle.md) |
-| Block bots or AI crawlers | `policies.agents`; `robots` via `site` | [agents](docs/policies/agents.md), [site](docs/SITE.md) |
-| Compression | `policies.compression` | [compression](docs/policies/compression.md) |
-| Fixed JSON, text or headers with no code | `respond` and `response.headers` | [HTTP](docs/HTTP.md) |
-| robots.txt, sitemap, favicon, security.txt | top-level `site` | [site](docs/SITE.md) |
-| Sign-in, roles, protected routes | `extensions.auth`, then `auth: true` on the route | [extensions](docs/EXTENSIONS.md) |
-
-Which handler serves the response:
-
-| The response is | Handler | Recipe |
-|---|---|---|
-| Fixed text or JSON | `respond` | `health-page` |
-| A short HTML snippet | `respond` `text` plus `response.headers` `Content-Type: text/html; charset=utf-8` | `docs/HTTP.md` |
-| One HTML file | `page` | `static-page` |
-| A directory of files | `static` | `static-plus-api` |
-| An attachment | `download` | `protected-download` |
-
-Persistence: core has no storage handler, but the operator-installed store extension serves declared collections as a CRUD API; `urlcode recipes search "crud store persist"` finds the `store-crud` recipe (operator installs the package; `init --with store` is not yet available from npm, #323). Gaps to report rather than invent: a database, filtering or per-record ownership beyond that recipe, CORS, and a native link store. `urlcode context`
-prints the same pointer for the project in front of you.
-
-After a real authoring attempt, draft feedback only for a capability gap,
-repeated workaround, documentation/discovery gap or suspected defect. Include
-the runtime/target, sanitized YAML, observed validation/test evidence, expected
-behavior and a proposed fixture. Search existing URLCode issues first. Never
-publish or comment on an issue without the user's explicit approval.
-
-## Authoring
-- [AI authoring contract](docs/AI-AUTHORING.md): workflow, capability matrix, checks.
-- [Authoring skill](.claude/skills/urlcode-authoring/SKILL.md): loadable authoring skill shipped with this revision; see [distribution](docs/AI-AUTHORING.md#agent-skills).
-- [Operations skill](.claude/skills/urlcode-operations/SKILL.md): loadable deployment/verification/resilience skill shipped with this revision.
-- [YAML guide](docs/YAML-GUIDE.md): recipes for all handlers and common options.
-- [JSON Schema](schemas/urlcode.schema.json): accepted fields and types.
-- [Field reference](docs/YAML-REFERENCE.md): generated exhaustive field inventory.
-- [Semantics](docs/SPECIFICATION.md): validation, defaults and sandbox API.
-- [Runnable cookbook](examples/cookbook/README.md): 25 routes with HTTP fixtures.
-- [Route matching](docs/ROUTING.md): precedence, non-greedy parameters, updates.
-- [Middleware](docs/MIDDLEWARE.md): next(), state, ordering and native body limits.
-- [Policies](docs/POLICIES.md): optional host-enforced `policies`/`profiles` keys, all off by default: `throttle`, `agents`, `security`, `compression`, `cache`; merge rules and per-target support.
-- [Plugins](docs/PLUGINS.md): host hook API operators pass in code; never named in YAML.
-- [TypeScript](docs/TYPESCRIPT.md): the package ships declarations for every export (`urlcode`, `@jimhoyd/urlcode/plugins`, `@jimhoyd/urlcode/policies`, `@jimhoyd/urlcode/observability`, `@jimhoyd/urlcode/compliance`, `@jimhoyd/urlcode/prerender`, `@jimhoyd/urlcode/sandbox`, `@jimhoyd/urlcode/aws`, `@jimhoyd/urlcode/vercel`, `@jimhoyd/urlcode/cloudflare`); the runtime source is TypeScript, `dist/` is its stripped JavaScript.
-- [HTTP](docs/HTTP.md): methods, request bodies and response headers.
-- [Assets](docs/ASSETS.md): pages, MIME, downloads, cache and ranges.
-- [Site conventions](docs/SITE.md): optional top-level `site` key, all off by default: `robots`, `sitemap`, `favicon`, `securityTxt`, `llms` generate native routes; declared routes win; absolute URLs need `--origin`.
-- [Prerendering](docs/PRERENDER.md): `@jimhoyd/urlcode/prerender` build helper and recipe; render function/middleware routes once into native page routes, no request-time guest code.
-- [Organization](docs/ORGANIZATION.md): entry point and included files.
-
-## Start here
-- [The framework](docs/FRAMEWORK.md): four packages, the ladder from redirects to a full app, the composition contract, the rules an agent must follow.
-- [AI authoring contract](docs/AI-AUTHORING.md): workflow, capability matrix, copyable task prompt, checks.
-- [JSON Schema](schemas/urlcode.schema.json) and [field reference](docs/YAML-REFERENCE.md): every accepted field.
-- [YAML guide](docs/YAML-GUIDE.md) and [runnable cookbook](examples/cookbook/README.md): recipes with HTTP fixtures.
-- [Semantics](docs/SPECIFICATION.md): validation, defaults, sandbox API.
-
-## Routes and handlers
-- [Routing](docs/ROUTING.md): exact and `{param}` paths, precedence, `/*` only on static and extension mounts.
-- [HTTP](docs/HTTP.md): methods, validated inputs, bodies, response headers, cookies.
-- [Function security](docs/FUNCTION-SECURITY.md): trusted and unsandboxed by default, `sandbox: true` QuickJS/WASM opt-in, Request/Response subset, operator grants.
-- [Middleware](docs/MIDDLEWARE.md) and [examples](docs/MIDDLEWARE-EXAMPLES.md): `next()`, state, ordering; also `urlcode recipes add middleware`.
-- [Assets](docs/ASSETS.md): pages, static, downloads, MIME, ranges. [Prerender](docs/PRERENDER.md): render once, no request-time code.
-- [Conditions](docs/CONDITIONS.md): exact predicates, disjoint redirect/respond cases, no-store.
-- [Egress](docs/EGRESS.md): bounded HTTPS proxy and best-effort signals behind operator grants; self-hosted only.
-- [Policies](docs/POLICIES.md): `throttle`, `agents`, `security`, `compression`, `cache`; all off unless declared. [Site](docs/SITE.md): robots, sitemap, favicon, security.txt, llms.txt.
-- [Organization](docs/ORGANIZATION.md), [best practices](docs/BEST-PRACTICES.md), [scaffolding](docs/SCAFFOLDING.md).
-- [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, 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`.
-- [Signed declarative artifacts](docs/EXTENSIONS.md#signed-declarative-artifacts): project-pinned, attested JSON/Markdown data for offline tooling. MCP `get_extension_artifacts` verifies/inventories a committed lock and `get_extension_artifact` reads one bounded member; neither installs or activates an npm extension.
-- [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.
-- [urlcode-ui](packages/ui): npm: @jimhoyd/urlcode-ui; escaped templates, shadcn/ui partials, themes, translations; its own llms.txt. Lives in this repository as a workspace package, not in a separate repository.
-- urlcode-middleware (retired): per-route middleware briefly lived here as an extension-seam alternative; the package was unpublished at 0.1.0-alpha.2 and its repository deleted. This is not a gap — per-route middleware is native to core via the `middleware:` array (docs/MIDDLEWARE.md); use that.
-- urlcode-dynamic-link (retired): stored short links briefly lived here as a mount-based extension; the package was unpublished and its repository deleted. Core has no native `link` handler and no supported extension provides stored links — report them as a gap.
-- [Plugins](docs/PLUGINS.md): host hook API in operator code, never named in YAML.
-
-## Tooling and API
-- [Tooling SDK and MCP](docs/TOOLING.md): `urlcode mcp`, read-only inspection, validation, conversion previews.
-- [TypeScript](docs/TYPESCRIPT.md): declarations for `@jimhoyd/urlcode` and its `/plugins`, `/policies`, `/observability`, `/compliance`, `/prerender`, `/extensions`, `/sandbox`, `/aws`, `/vercel`, `/cloudflare` entries.
-- [Capabilities](docs/CAPABILITIES.md): per-target support; `urlcode capabilities --target NAME`.
-
-## Operations
-- [Operations](docs/OPERATIONS.md), [install](docs/INSTALL.md), [deployment checks](docs/DEPLOYMENT-CHECKS.md), [CI action](docs/CI.md).
-- [Readiness](docs/READINESS.md), [capacity](docs/CAPACITY.md), [resilience](docs/RESILIENCE.md), [observability](docs/OBSERVABILITY.md).
-- [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md), [Cloudflare](docs/CLOUDFLARE.md): adapters with local conformance tests; no provider deployment verified yet.
-- [Static hosting](docs/STATIC.md): `urlcode build --target static` compiles redirects/pages/static/downloads to S3 + CloudFront objects and redirect metadata; no server, so function/middleware/extension/proxy/signals/conditions/parameters/bindings/policies are all refused; GitHub Pages is explicitly out of scope.
-- [Release readiness](docs/RELEASE-READINESS.md), [roadmap](ROADMAP.md): what is proven, what is planned.
+| Fixed redirect, 301/302/303/307/308 (302 default) | Yes | `redirect: {url, status}` |
+| Parameterized path (`/users/{id}` to `/profiles/{id}`) | Yes | `{name}` in `redirect.url`, naming a declared path parameter |
+| Root-relative destination (`/users/{id}` to `/profiles/{id}`) | Yes | `redirect.url: /profiles/{id}`: one leading slash, path only |
+| Wildcard suffix (`/legacy/**` to `/modern/{**}`, any depth) | Yes | terminal `/**` key with a literal prefix; `{**}` is the remaining segments (redirect only; not static or Cloudflare) |
+| Query-string preservation | Yes, opt-in | `redirect.query.pass` / `query.map` |
+| Method-preserving redirect | Yes | `methods` plus `status: 307` or `308` |
+| 404 for unmatched paths | Yes | `site.notFound` (project-relative `.html`) |
+| Host or scheme chosen from the request | No | destination is a literal absolute `https://` URL or a root-relative path; report the gap |
+
+## Declarative-first
+
+Use the highest-level declarative feature before writing a function or middleware. Custom code
+only when the framework cannot express the requirement; then report the gap. Never invent fields
+or bypass target limits or operator grants ([design principle](docs/PROJECT-DIRECTION.md#design-principle-declarative-first)).
+
+| I need | Use |
+|---|---|
+| Security headers | `policies.security` ([security](docs/policies/security.md)) |
+| Cache headers / cache strategy | `cacheControl` / `policies.cache` ([assets](docs/yaml/assets.md), [cache](docs/policies/cache.md)) |
+| Body size, content type, JSON check | `request.body` ([HTTP](docs/HTTP.md)) |
+| Restrict HTTP methods | `methods` (default GET/HEAD; 405 with `Allow`) |
+| Rate limiting, bot/AI-crawler blocking, compression | `policies.throttle`, `policies.agents`, `policies.compression` ([policies](docs/POLICIES.md)) |
+| Fixed JSON/text/headers | `respond` and `response.headers` |
+| robots.txt, sitemap, favicon, security.txt | top-level `site` ([site](docs/SITE.md)) |
+| Sign-in, roles, protected routes | `extensions.auth`, then `auth: true` ([extensions](docs/EXTENSIONS.md)) |
+| Persistence | operator-installed store extension, recipe `store-crud`; a database, filtering and per-record ownership beyond it are gaps |
+
+When only code can do it, one function serves one or more routes:
+
+```yaml
+  /hello/{name}:
+    function: functions/hello.mjs   # binds args.name; context.route.pattern is "/hello/{name}"
+```
+```js
+export default (request, { args, route }) => Response.json({ hello: args.name });
+```
+
+Handler for the response: fixed text or JSON is `respond`; one HTML file is `page`; a directory is
+`static`; an attachment is `download`; a short HTML snippet is `respond` `text` with a
+`Content-Type: text/html; charset=utf-8` header. Functions are trusted by default; add
+`sandbox: true` to opt a route in ([function security](docs/FUNCTION-SECURITY.md)).
+
+After a real attempt, draft feedback only for a capability gap, repeated workaround, documentation
+gap or suspected defect, with sanitized YAML and validation evidence. Search existing issues first;
+never publish or comment without the user's approval.
+
+## Reference (load one only when needed)
+
+- Authoring: [AI authoring contract](docs/AI-AUTHORING.md), [YAML guide](docs/YAML-GUIDE.md), [field reference](docs/YAML-REFERENCE.md), [JSON Schema](schemas/urlcode.schema.json), [semantics](docs/SPECIFICATION.md), [cookbook](examples/cookbook/README.md), [recipes](docs/RECIPES.md).
+- Skills: [authoring](.claude/skills/urlcode-authoring/SKILL.md), [operations](.claude/skills/urlcode-operations/SKILL.md).
+- Routes and handlers: [routing](docs/ROUTING.md), [HTTP](docs/HTTP.md), [middleware](docs/MIDDLEWARE.md), [assets](docs/ASSETS.md), [conditions](docs/CONDITIONS.md), [egress](docs/EGRESS.md), [prerender](docs/PRERENDER.md), [site](docs/SITE.md), [organization](docs/ORGANIZATION.md).
+- Extensions: [extensions](docs/EXTENSIONS.md) (including [signed declarative artifacts](docs/EXTENSIONS.md#signed-declarative-artifacts); MCP `get_extension_artifacts`), [composing a site](docs/COMPOSING-A-SITE.md), [urlcode-auth](packages/auth), [urlcode-admin](packages/admin), [urlcode-ui](packages/ui), each with its own llms.txt and in this repository as a workspace package. Per-route middleware is native core (`middleware:` array), not a retired extension; core has no native `link` handler and no supported extension provides stored links, so report them as a gap.
+- Tooling: [tooling and MCP](docs/TOOLING.md), [TypeScript](docs/TYPESCRIPT.md), [capabilities](docs/CAPABILITIES.md), [plugins](docs/PLUGINS.md), [interchange](docs/INTERCHANGE.md), [bulk import](docs/BULK.md).
+- Operations: [operations](docs/OPERATIONS.md), [install](docs/INSTALL.md), [deployment checks](docs/DEPLOYMENT-CHECKS.md), [readiness](docs/READINESS.md), [capacity](docs/CAPACITY.md), [resilience](docs/RESILIENCE.md), [observability](docs/OBSERVABILITY.md), [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md), [Cloudflare](docs/CLOUDFLARE.md), [static hosting](docs/STATIC.md), [release readiness](docs/RELEASE-READINESS.md), [roadmap](ROADMAP.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.8",
+  "version": "0.5.0",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [
@@ -62,6 +62,10 @@
       "types": "./dist/types/extensions.d.ts",
       "default": "./dist/extensions.js"
     },
+    "./extension-bundles": {
+      "types": "./dist/types/extension-bundles.d.ts",
+      "default": "./dist/extension-bundles.js"
+    },
     "./sandbox": {
       "types": "./dist/types/sandbox.d.ts",
       "default": "./dist/sandbox.js"
@@ -69,7 +73,7 @@
     "./package.json": "./package.json"
   },
   "files": [
-    ".claude",
+    ".claude/skills",
     "dist",
     "schemas",
     "data",
@@ -110,6 +114,7 @@
     "docs:llms": "node scripts/build-llms-full.ts",
     "docs:cookbook-index": "node scripts/build-cookbook-index.ts",
     "artifacts:prepare": "node --disable-warning=ExperimentalWarning scripts/prepare-extension-artifacts.ts",
+    "bundles:prepare": "node --disable-warning=ExperimentalWarning scripts/prepare-extension-bundles.ts",
     "check:downstream-skills": "node scripts/check-downstream-skill-drift.ts",
     "sync:agents": "node scripts/sync-agent-lists.ts",
     "check:docs": "node scripts/check-trust-model-prose.ts && node scripts/check-version-statements.ts && node scripts/check-local-links.ts && node scripts/check-guidance-claims.ts && node scripts/generate-yaml-reference.ts --check && node scripts/build-llms-full.ts --check && node scripts/build-cookbook-index.ts --check && node scripts/generate-claude-plugin.ts --check",

package/recipes/redirect/README.md

@@ -14,8 +14,8 @@ Run `urlcode validate --local --project .` and `urlcode serve --project .`.
   default). Add top-level `site: {notFound: 404.html}` for a custom 404 page
   instead of the plain default.
 
-For the shapes this recipe does not cover — a wildcard/suffix redirect that
-matches any depth (`/legacy/*`), or a host/scheme-based redirect — run
+For the shapes this recipe does not cover — a root-relative or `/**` suffix
+redirect, or a host/scheme-based redirect — run
 `urlcode context --project . --task redirects` (MCP `get_context
 {"task":"redirects"}`) for the exact supported alternative and the exact
 validation error, or see [docs/OPEN-DECISIONS.md](../../docs/OPEN-DECISIONS.md).

package/starters/default/AGENTS.md

@@ -15,7 +15,7 @@ static serving and authentication. Read this file before changing anything.
    (limits; `--target NAME` before promising a provider), `get_schema`,
    `recipes search TEXT`/`search_recipes` then `recipes add NAME --out DIR`,
    `explain` and, with an operator host file, `get_extensions`. Bare
-   `capabilities` and `recipes list` are complete catalogs: fallback, not step one.
+   `capabilities` and `recipes list` are complete catalogs: fallback, not step one. Do not read or grep `llms-full.txt` or the packaged docs for a routine task.
 4. Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement. Check supported extensions and recipes first; explain any capability gap.
 
 ## MCP
@@ -49,7 +49,7 @@ skill only in a React frontend with `components.json`; start with `shadcn info
 A `function`/`middleware` is trusted, in-process Node with only declared
 `args`/`env`/`secrets`. Add `sandbox: true` for code needing isolation, not
 merely untrusted input. The sandbox is text/JSON-only; use `proxy`/a binding and
-record the reason in `sandboxReason`.
+record the reason in `sandboxReason`. Try `redirect` (relative or `/**`) or `respond` first; a function gets `context.route.pattern`.
 
 ## Checks that count as evidence