@jimhoyd/urlcode 0.4.7 → 0.5.0

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.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`.
@@ -15,112 +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)
 
-## Declarative-first default
+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.
 
-> 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 |
+| Shape | Supported? | Use |
 |---|---|---|
-| 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`.
-- [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.7",
+  "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",
@@ -89,7 +93,8 @@
     "test": "node --conditions=development --test test/*.test.ts",
     "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 && npm run release:check",
+    "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",
@@ -108,6 +113,8 @@
     "docs:plugin": "node scripts/generate-claude-plugin.ts",
     "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",
@@ -119,6 +126,7 @@
     "release:run": "node scripts/release-run.ts",
     "release:peers": "node scripts/release.ts peers",
     "release:check": "node scripts/release.ts check && node scripts/release-prepare.ts --check",
+    "rehearse:release": "node --conditions=development --test test/release-rehearsal.test.ts",
     "ci:history": "node scripts/ci-history.ts",
     "ci:report": "node scripts/ci-report.ts",
     "test:workspace-integration": "node --test test/workspace-scaffold.integration.ts",

package/recipes/redirect/README.md

@@ -1,7 +1,21 @@
-# Permanent documentation redirect
+# Redirects: fixed, parameterized, query-preserving and 404
 
 Run `urlcode validate --local --project .` and `urlcode serve --project .`.
-`/docs?campaign=launch&private=discarded` redirects to
-`https://example.com/documentation?campaign=launch` with status 301.
-Replace the example destination before deploying. Incoming query parameters are
-not forwarded unless explicitly allowlisted.
+
+- `/docs?campaign=launch&private=discarded` redirects (301) to
+  `https://example.com/documentation?campaign=launch`. Only the declared
+  `campaign` key is forwarded; everything else, including `private`, is
+  dropped. Replace the example destination before deploying.
+- `/users/{id}` redirects (308, method- and body-preserving) to
+  `https://example.com/profiles/{id}`, substituting the declared path
+  parameter into the destination.
+- Any other path, such as `/missing` or `/users/42/extra`, answers the
+  runtime's default 404. `DELETE /docs` answers 405 (only GET/HEAD match by
+  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 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/redirect/recipe.yaml

@@ -1,25 +1,27 @@
 id: redirect
-description: Permanent redirect that forwards only an allowlisted query key.
-tags: [redirect, permanent, "301", query, passthrough, documentation, native]
+description: Fixed, parameterized and query-preserving redirects, and the default 404 for everything else.
+tags: [redirect, permanent, "301", "308", parameterized, query, passthrough, "404", documentation, native]
 complexity: starter
-capabilities: [enabled, methods, redirect]
-targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: compatible}
-routes: 1
+capabilities: [enabled, methods, parameters, redirect]
+targets: {self-hosted: compatible, aws: compatible, vercel: compatible, cloudflare: compatible, static: refused}
+routes: 2
 inputs:
   - name: destination
     file: urlcode.yaml
-    description: Replace https://example.com/documentation with the real target.
+    description: Replace https://example.com/documentation and https://example.com/profiles with the real targets.
   - name: query.pass
     file: urlcode.yaml
-    description: The query keys forwarded to the destination; everything else is dropped.
+    description: The query keys forwarded to the /docs destination; everything else is dropped.
 files: [urlcode.yaml, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
   commands:
     - urlcode validate --local --project .
     - urlcode test --project .
-    - urlcode audit --project . --expect-routes 1
+    - urlcode audit --project . --expect-routes 2
 behavior:
   - GET /docs?campaign=launch&private=x answers 301 to https://example.com/documentation?campaign=launch
-  - HEAD answers the same status with an empty body
-  - unknown paths answer 404
+  - HEAD /docs answers the same status with an empty body
+  - DELETE /docs answers 405
+  - GET /users/42 answers 308 (method- and body-preserving) to https://example.com/profiles/42
+  - unknown paths, including /users/42/extra and /missing, answer the runtime's default 404

package/recipes/redirect/tests/requests.json

@@ -12,8 +12,30 @@
     "status": 301,
     "expectBody": ""
   },
+  {
+    "path": "/users/42",
+    "status": 308,
+    "expectHeaders": {
+      "location": "https://example.com/profiles/42"
+    }
+  },
+  {
+    "path": "/users/42/extra",
+    "status": 404
+  },
+  {
+    "path": "/users/42",
+    "method": "HEAD",
+    "status": 308,
+    "expectBody": ""
+  },
   {
     "path": "/missing",
     "status": 404
+  },
+  {
+    "path": "/docs",
+    "method": "DELETE",
+    "status": 405
   }
 ]

package/recipes/redirect/urlcode.yaml

@@ -1,9 +1,19 @@
 version: "1"
 routes:
   /docs:
-    description: Move documentation and preserve only the declared campaign key.
+    description: Permanent move, forwarding only the declared campaign key.
     redirect:
       url: https://example.com/documentation
       status: 301
       query:
         pass: [campaign]
+  /users/{id}:
+    description: Parameterized redirect; the id segment carries straight through.
+    parameters:
+      - name: id
+        in: path
+        required: true
+        schema: {type: string, minLength: 1, maxLength: 64}
+    redirect:
+      url: https://example.com/profiles/{id}
+      status: 308

package/skills/urlcode/SKILL.md

@@ -34,6 +34,8 @@ When the MCP server was started with an operator host file, `get_extensions`
 returns installed extension configuration/policy schemas, declared project
 hook contracts, supported authoring surfaces and fast checks. Otherwise use `urlcode extensions --project DIR --host-file
 ABSOLUTE_HOST --json` when the operator has supplied that host file.
+If the project commits `urlcode.extensions.lock.json`, call `get_extension_artifacts`, then `get_extension_artifact` for only the locked schema, example or README needed; without MCP, run `urlcode extension-artifacts inspect --project DIR --json` before reading its cache.
+These are verified, inert authoring inputs, not proof of an installed executable extension. Fetch or update one only when the user requests that project change and names an immutable `extensions@v…` release.
 Without the server, run the CLI equivalents and read only the output:
 
 ```sh

package/starters/default/AGENTS.md

@@ -15,14 +15,14 @@ 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
 
 When present, `.mcp.json` registers the read-only `urlcode mcp` server; prefer its
 tools (also `get_manifest`) to reading documents. Inspect `get_extensions` before
-replacing extension behavior. `--allow-authoring` is an operator opt-in; never add it.
+replacing extension behavior. `--allow-authoring` is an operator opt-in; never add it. For a committed artifact lock, use `get_extension_artifacts`/`get_extension_artifact`; they expose verified inert data and never activate an extension.
 
 ## What the runtime provides (this version)
 
@@ -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