@jimhoyd/urlcode 0.4.8 → 0.5.5

package/llms.txt

@@ -4,10 +4,11 @@
 > 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.5`. `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`.
+> auth, admin, ui and store workspace packages are bundle sources. New sites install
+> core from npm and verified executable extensions from an immutable GitHub Release;
+> see package and channel alignment for the supported release pair.
 <!-- urlcode-current-version:end -->
 
 Use the schema and docs from the runtime revision you run. Do not assume Node
@@ -15,132 +16,76 @@ 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 `npx --no --package @jimhoyd/urlcode urlcode context --project DIR` (MCP `get_context`). For redirect-only work run
+   `npx --no --package @jimhoyd/urlcode 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. After installing `@jimhoyd/urlcode`, run `npx --no --package @jimhoyd/urlcode urlcode init . --template redirects` (it works in a directory holding only `package.json`, `package-lock.json`, `node_modules` or `.git`, and merges `scripts.start` into your `package.json`): yaml, 404 page, `npm start` honoring `PORT`, fixtures. Otherwise write `urlcode.yaml`, then run `npx --no --package @jimhoyd/urlcode urlcode validate --local --project DIR` and `npx --no --package @jimhoyd/urlcode urlcode test`. `--no` refuses a registry fetch, so it always uses the installed scoped runtime.
+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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROJECT-DIRECTION.md#design-principle-declarative-first)).
+
+| I need | Use |
+|---|---|
+| Security headers | `policies.security` ([security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/security.md)) |
+| Cache headers / cache strategy | `cacheControl` / `policies.cache` ([assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/assets.md), [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md)) |
+| Body size, content type, JSON check | `request.body` ([HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/POLICIES.md)) |
+| Fixed JSON/text/headers | `respond` and `response.headers` |
+| robots.txt, sitemap, favicon, security.txt | top-level `site` ([site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md)) |
+| Sign-in, roles, protected routes | `extensions.auth`, then `auth: true` ([extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md)) |
+| Persistence | operator-installed store extension, recipe `store-crud`; a database, filtering and per-record ownership beyond it are gaps |
+| Stored short links (create, redirect, click count) | operator-installed store extension's `shortLinks` capability: a collection `key`, an HTTP(S) `destination` field, one `increments` counter, and a public `/go`-style redirect mount; no function needed (`urlcode docs search "shortLinks"`, MCP `search_docs`) |
+
+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 });
+```
+
+Function handler shape: a module whose `export default` is `(request, { args, env, route })` and returns a
+`Response` (or a promise of one). `args` holds the route's declared path inputs; the string form
+`function: functions/hello.mjs` and the long form `function: {source: ...}` both bind every declared path input
+(write `args: {}` to bind none). `sandbox: true` is a separate route option. `route.pattern` is the matched pattern; `env` holds route-scoped values only.
+Search the docs with bounded output using `npx --no --package @jimhoyd/urlcode urlcode docs search "TEXT"` (MCP `search_docs`)
+rather than grepping llms-full.txt.
+
+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](https://github.com/jimhoyd-com/urlcode/blob/main/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](https://github.com/jimhoyd-com/urlcode/blob/main/docs/AI-AUTHORING.md), [YAML guide](https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-GUIDE.md), [field reference](https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-REFERENCE.md), [JSON Schema](schemas/urlcode.schema.json), [semantics](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPECIFICATION.md), [cookbook](examples/cookbook/README.md), [recipes](https://github.com/jimhoyd-com/urlcode/blob/main/docs/RECIPES.md).
+- Skills: [authoring](.claude/skills/urlcode-authoring/SKILL.md), [operations](.claude/skills/urlcode-operations/SKILL.md).
+- Routes and handlers: [routing](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ROUTING.md), [HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md), [middleware](https://github.com/jimhoyd-com/urlcode/blob/main/docs/MIDDLEWARE.md), [assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ASSETS.md), [conditions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CONDITIONS.md), [egress](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EGRESS.md), [prerender](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PRERENDER.md), [site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md), [organization](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ORGANIZATION.md).
+- Extensions: [extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md) (including [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts); MCP `get_extension_artifacts`), [composing a site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/COMPOSING-A-SITE.md), [package and channel alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md). New first-party executable extension installs use an attested `extension-bundles@v…` GitHub Release and an explicit host; do not add deprecated extension npm packages to a new project. [urlcode-auth](https://github.com/jimhoyd-com/urlcode/tree/main/packages/auth), [urlcode-admin](https://github.com/jimhoyd-com/urlcode/tree/main/packages/admin), [urlcode-ui](https://github.com/jimhoyd-com/urlcode/tree/main/packages/ui), [urlcode-store](https://github.com/jimhoyd-com/urlcode/tree/main/packages/store), and [urlcode-forms](https://github.com/jimhoyd-com/urlcode/tree/main/packages/forms) are workspace bundle sources. Per-route middleware is native core (`middleware:` array), not a retired extension; core has no native `link` handler, but the store extension's `shortLinks` capability covers create, invalid-destination, redirect, missing-code and click-count for stored short links without a function — declare it under `extensions.store.config.shortLinks` (`urlcode docs search "shortLinks"`, MCP `search_docs`). Only report a gap for stored-link needs beyond that (custom redirect status, non-HTTP(S) destinations, per-record ownership).
+- Tooling: [tooling and MCP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md), [TypeScript](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TYPESCRIPT.md), [capabilities](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CAPABILITIES.md), [plugins](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PLUGINS.md), [interchange](https://github.com/jimhoyd-com/urlcode/blob/main/docs/INTERCHANGE.md), [bulk import](https://github.com/jimhoyd-com/urlcode/blob/main/docs/BULK.md).
+- Operations: [operations](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPERATIONS.md), [install](https://github.com/jimhoyd-com/urlcode/blob/main/docs/INSTALL.md), [deployment checks](https://github.com/jimhoyd-com/urlcode/blob/main/docs/DEPLOYMENT-CHECKS.md), [readiness](https://github.com/jimhoyd-com/urlcode/blob/main/docs/READINESS.md), [capacity](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CAPACITY.md), [resilience](https://github.com/jimhoyd-com/urlcode/blob/main/docs/RESILIENCE.md), [observability](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OBSERVABILITY.md), [Vercel](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERCEL.md), [AWS](https://github.com/jimhoyd-com/urlcode/blob/main/docs/AWS.md), [Cloudflare](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CLOUDFLARE.md), [static hosting](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STATIC.md), [release readiness](https://github.com/jimhoyd-com/urlcode/blob/main/docs/RELEASE-READINESS.md), [roadmap](https://github.com/jimhoyd-com/urlcode/blob/main/ROADMAP.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.4.8",
+  "version": "0.5.5",
   "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",
@@ -81,19 +85,25 @@
     "llms-full.txt",
     "NOTICE",
     "recipes",
-    "skills"
+    "skills",
+    "docs/AI-AUTHORING.md",
+    "docs/YAML-REFERENCE.md",
+    "docs/TOOLING.md",
+    "docs/FUNCTION-SECURITY.md"
   ],
   "scripts": {
     "build": "node --disable-warning=ExperimentalWarning scripts/build.ts",
+    "prepare": "node --disable-warning=ExperimentalWarning scripts/build.ts --quiet",
     "typecheck": "tsc -p tsconfig.json",
     "test": "node --conditions=development --test test/*.test.ts",
+    "test:shard": "node --conditions=development --test",
     "lint": "eslint .",
     "check": "npm run check:code && npm run check:docs",
     "check:code": "node scripts/check.ts && node scripts/check-release-tags.ts && node scripts/check-workspace-links.ts && node scripts/check-issue-labels.ts && npm run release:check",
     "test:workerd": "node scripts/workerd-parity.ts",
     "verify": "npm run lint && npm run typecheck && npm run check && npm run build && npm test && npm run verify:workspaces",
     "workspace:styles": "npm run styles --workspace @jimhoyd/urlcode-ui",
-    "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run verify --workspace @jimhoyd/urlcode-store && npm run audit:packages && npm run test:workspace-integration",
+    "verify:workspaces": "npm run verify --workspace @jimhoyd/urlcode-ui && npm run verify --workspace @jimhoyd/urlcode-auth && npm run verify --workspace @jimhoyd/urlcode-admin && npm run verify --workspace @jimhoyd/urlcode-store && npm run verify --workspace @jimhoyd/urlcode-forms && npm run audit:packages && npm run test:workspace-integration",
     "audit:packages": "node scripts/package-audit.ts --all",
     "test:package": "npm run build && npm run test:package:built",
     "dev": "node src/cli.ts dev --project starters/default",
@@ -110,6 +120,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/recipes/store-crud/README.md

@@ -1,8 +1,8 @@
 # Store CRUD
 
 `/api/todos/*` is a persistent JSON CRUD API. The project declares one
-collection and its mount; the operator-installed `store` extension
-(`@jimhoyd/urlcode-store`) serves it and keeps the data in the operator's
+collection and its mount; the operator-installed `store` extension serves it
+from a verified bundle and keeps the data in the operator's
 directory. There is no handler code. Full contract, limits and guarantees:
 [docs/STORE.md](../../docs/STORE.md).
 
@@ -10,20 +10,19 @@ directory. There is no handler code. Full contract, limits and guarantees:
 
 The store is not core and does not activate on its own.
 
-- The operator installs `@jimhoyd/urlcode-store` next to `@jimhoyd/urlcode`
-  and registers it in a host file kept outside the project.
-- The package is on npm (`@jimhoyd/urlcode-store`).
-  `urlcode init --with ui,auth,store` scaffolds a protected site from the
-  published packages. A no-auth `init --with store` needs `--ack store:public-write`,
-  which the core published at the store's first release does not have, so write the host file below by hand until a
-  newer core is released.
+- The operator selects the signed `store` bundle release and registers it in a
+  host file kept outside the project.
+- `urlcode init --with ui,auth,store --bundle-release extension-bundles@v…`
+  scaffolds a protected site from verified bundles. A no-auth `init --with
+  store` needs `--ack store:public-write`.
 - The data directory must be outside the project. It is single-writer: one
   server process per directory.
 
 ```js
 // /operator/host.mjs -- trusted operator code, never part of the project
 import {inspectExtensionRevision} from '@jimhoyd/urlcode/extensions';
-import {storeExtension} from '@jimhoyd/urlcode-store';
+import {loadExtensionBundle} from '@jimhoyd/urlcode/extension-bundles';
+const {storeExtension} = await loadExtensionBundle(process.env.URLCODE_PROJECT, 'store');
 const projectSha256 = await inspectExtensionRevision(process.env.URLCODE_PROJECT);
 export default {extensions: [storeExtension({directory: '/operator/data/store', projectSha256})]};
 ```

package/recipes/store-crud/recipe.yaml

@@ -7,7 +7,7 @@ targets: {self-hosted: conditional, cloudflare: refused, aws: conditional, verce
 routes: 1
 services:
   - name: store extension
-    description: An operator host file registering storeExtension from @jimhoyd/urlcode-store, with a data directory outside the project. The operator installs the package; `urlcode init --with ui,auth,store` scaffolds a protected host, and the README shows a hand-written one.
+    description: An operator host file registering the verified store bundle, with a data directory outside the project. `urlcode init --with ui,auth,store --bundle-release extension-bundles@v…` scaffolds a protected host, and the README shows a hand-written one.
 grants:
   - kind: extension
     description: The registration pins projectSha256 to this exact revision; editing a collection or the mount needs operator review and a new pin.

package/schemas/urlcode.schema.json

@@ -703,6 +703,9 @@
                   "env": {
                     "type": "string",
                     "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+                  },
+                  "default": {
+                    "type": "string"
                   }
                 },
                 "required": [

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