@jimhoyd/urlcode 0.5.5 → 0.5.8

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 61,239 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 61,970 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.5.5`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.8`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
 > 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;
@@ -114,8 +114,10 @@ Each rung's YAML is valid on every rung above it.
 
 Stored short links previously sat here as a native `link` route; that handler
 was removed from core. A `urlcode-dynamic-link` package owned them the same way
-`auth`/`admin` own their mounts, but it has been retired and unpublished; no
-package occupies this rung today.
+`auth`/`admin` own their mounts, but it has been retired and unpublished. It has
+no direct successor; a project that wants stored short links declares a
+collection through the `store` extension above (see [docs/STORE.md](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STORE.md))
+rather than a native `link` route.
 
 Rungs 1 to 3 need only the core package. Rungs 4 to 7 need a verified extension
 bundle installed into an explicit operator host, once its source package appears
@@ -364,6 +366,11 @@ The root [llms.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms.txt) i
 reading order for agents that want complete context in one fetch. It is a convenience,
 not a runtime protocol or a guarantee that AI clients automatically consume it.
 The generated reference is checked against the schema in `npm run verify`.
+[URLCode AI](https://urlcode.ai/) is the optional hosted companion for shared
+skills and LLM tooling. It complements the project-local MCP server; see
+[hosted AI MCP setup](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md#optional-hosted-ai-mcp) for its authenticated
+remote connection details. Its machine-readable entry point is
+[`https://urlcode.ai/llms.txt`](https://urlcode.ai/llms.txt).
 
 Follow [organization and readability practices](https://github.com/jimhoyd-com/urlcode/blob/main/docs/BEST-PRACTICES.md): preserve local
 conventions, use clear names, keep middleware focused and avoid needless layers.
@@ -439,7 +446,7 @@ urlcode benchmark --project ./my-links --requests 100 --concurrency 2
 ```
 
 Use the intentional actual count, not always 2. Runtime checkout users can replace
-`urlcode` with `node src/cli.ts`. Template users can use the equivalent npm scripts.
+`urlcode` with `node packages/core/src/cli.ts`. Template users can use the equivalent npm scripts.
 External bindings require an already reviewed policy; add `--policy` where needed.
 The benchmark operates locally; it is not a load test of an external deployment.
 
@@ -733,6 +740,10 @@ the operator, never by tool arguments; `--allow-authoring` on the operator's
 command line adds project-confined route, recipe, scaffold and runner tools.
 `urlcode init` writes `.mcp.json` so Claude Code and Codex register the read-only
 server for the project ([registering the server](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md#registering-the-server)).
+The optional hosted URLCode AI MCP is a separate authenticated connection for
+shared skills and LLM tools; it does not replace the local project server. Its
+endpoint and credential-handling requirements are in
+[hosted AI MCP setup](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md#optional-hosted-ai-mcp).
 Inspection is not activation/deployment readiness: real grants, asset snapshots
 and service availability still need normal runtime checks. Provider conformance replay is local evidence; only
 explicit live [deployment observations](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROVIDER-VERIFICATION.md) test ingress.
@@ -773,7 +784,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.5.5. Start with the function example below,
+This guide targets URLCode 0.5.8. 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.
@@ -788,15 +799,16 @@ From the runtime checkout:
 
 ```sh
 npm ci
-node src/cli.ts validate --project examples/cookbook
-node src/cli.ts test --project examples/cookbook
-node src/cli.ts audit --project examples/cookbook --expect-routes 40
-node src/cli.ts dev --project examples/cookbook
+node packages/core/src/cli.ts validate --project examples/cookbook
+node packages/core/src/cli.ts test --project examples/cookbook
+node packages/core/src/cli.ts audit --project examples/cookbook --expect-routes 40
+node packages/core/src/cli.ts dev --project examples/cookbook
 ```
 
 The cookbook is a larger learning project. The normal `urlcode init ../my-links`
-remains a small two-route starter. For an independent application with a pinned
-runtime dependency, clone [urlcode-template](https://github.com/jimhoyd-com/urlcode-template).
+creates a bare zero-route scaffold; add only the routes the application needs.
+For an independent application with a pinned runtime dependency, clone
+[urlcode-template](https://github.com/jimhoyd-com/urlcode-template).
 
 ### Pages
 
@@ -1920,10 +1932,18 @@ values into header literals. Header configuration applies to handler responses,
 including declared error statuses, but not runtime validation/errors (400, 404,
 405, 413, 415, 500, etc.). Defaults remain `no-store`, `nosniff` and a request ID.
 Header policy is bounded to 64 keys/16 KiB; merged function headers remain bounded.
+A header repeated in the result the runtime writes (from a policy, or from a
+handler result that carries more than one pair for the same name) is sent as
+separate wire lines, the same as a declared `Set-Cookie` list; it is never
+collapsed to only its last value.
 
 Framing, hop-by-hop headers, Location, Allow, range/cache validators,
 Content-Encoding, X-Request-ID and X-Content-Type-Options are reserved to the
-runtime/handler. Configure redirect URLs/status on `redirect`; asset content type,
+runtime/handler. The runtime frames every response the same way on every host:
+Content-Length is the UTF-8 byte length of the body it sends, whatever length a
+handler states. Only a HEAD answer carries a stated length, the one GET would
+send, and no body. The self-hosted and Vercel writers also make Node refuse a
+body that differs from the stated length. Configure redirect URLs/status on `redirect`; asset content type,
 cache and disposition on its own handler. Asset metadata cannot be overridden by
 `response.headers`. On functions/declared responses, Content-Type may be configured;
 JSON declarations require a JSON type. No response header secret interpolation.
@@ -2393,9 +2413,11 @@ cannot enforce`; the Cloudflare build reports
 build time and carried in the Worker artifact; the Worker has no filesystem and
 no Node imports, so only modules free of both qualify. The Worker's client
 identity is the platform's `cf-connecting-ip`; the serverless adapters use the
-platform-set source address (`sourceIp` on Lambda, the leftmost
-`X-Forwarded-For` entry the platform writes on Vercel). None of these read a
-forwarded header a client could have set.
+platform-set source address (`sourceIp` on Lambda, Vercel's own
+`X-Vercel-Forwarded-For` — Vercel's documented copy of the client IP that
+survives even when a project puts another proxy in front of Vercel, unlike
+plain `X-Forwarded-For`, which that outer proxy can overwrite before Vercel
+ever sees it). None of these read a forwarded header a client could have set.
 
 The cross-request state a policy keeps (throttle counters, the origin cache) is
 per runtime instance on every target, never shared between replicas or
@@ -2760,6 +2782,11 @@ portable scalar header contract. Upstream redirects are returned as responses;
 Location is forwarded only if explicitly selected and is never fetched. Headers
 nominated by an incoming or upstream Connection field are removed even if selected.
 Header names are normalized to lowercase; array-valued upstream fields are omitted.
+A proxy route reads incoming headers from the same credential-free projection a
+trusted function receives: a header an installed plugin or extension declares
+as a credential is withheld before `requestHeaders` selection runs, even when a
+project's own `requestHeaders` names it explicitly, so a route cannot forward a
+credential header upstream by declaring it.
 An encoded request body requires explicitly selecting its Content-Encoding
 header; literal header injection cannot change or replace that coding. Bodies
 remain raw bytes, including content encoding; select Content-Encoding when
@@ -3673,9 +3700,9 @@ navigation or labels to an auth/admin view without editing either package.
 
 | Hook | Input | Returns | Called |
 |---|---|---|---|
-| `beforeRoleChange` | `{accountId, currentRoles, requestedRoles, actorId, reason}` | `{allow: boolean, reason?}` | Before roles are applied, after the administrator's permission check. A veto means the auth service is never asked. |
+| `beforeRoleChange` | `{accountId, currentRoles, requestedRoles, actorId, reason}` | `{allow: boolean, reason?}` | Before roles are applied, after the administrator's permission check, on every path that assigns roles: `/users/roles`, bulk role assignment through `/account-operations`, and a role-change support case's creation and approval. A veto means the auth service is never asked; for a bulk assignment it runs once per affected account before anything is staged. |
 | `onRegistrationApproved` | `{requestId, accountId, email, actorId, reason}` | ignored | After a registration request is approved. |
-| `onAccountStatusChanged` | `{accountId, status, actorId, reason}` | ignored | After an account is locked or unlocked. |
+| `onAccountStatusChanged` | `{accountId, status, actorId, reason}` | ignored | After an account is locked or unlocked, on every path: `/users/status`, `/users/bulk` (once per affected account), and an approved lock/unlock support case. |
 
 #### Verdicts and failure
 
@@ -3816,6 +3843,10 @@ into it; only the default for routes that declare neither option has changed.
 - A fresh guest heap/module state per invocation prevents state crossing requests.
 - 32 MiB guest heap, 512 KiB stack, source/input/output/header limits, bounded
   concurrency, guest interruption and an independent worker termination deadline.
+- The guest's result is recorded where guest code cannot rewrite it, and the
+  host checks its shape before trusting it. A result that states a body length
+  for any method other than HEAD is invalid and answers 502; the runtime frames
+  the response by the bytes it sends ([responses](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md#responses)).
 - External bindings are denied by default. Project YAML cannot self-authorize.
   Operator grants are exact-name, route-scoped and pinned to configuration/source.
 

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.5.5`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.8`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
 > 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;
@@ -21,9 +21,16 @@ grants. Unsupported features fail with the route named; nothing degrades silentl
 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.
+2. After installing `@jimhoyd/urlcode`, run `npx --no --package @jimhoyd/urlcode urlcode init .` (it works in a directory holding only `package.json`, `package-lock.json`, `node_modules` or `.git` and preserves existing package metadata). It writes a bare agent-ready scaffold: `urlcode.yaml`, a minimal 404 fixture, `AGENTS.md`, local `.mcp.json`, and project CI. 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.
+4. Hosted skills and LLM assistance are optional: connect a compatible HTTP MCP
+   client to `https://mcp.urlcode.ai/mcp` with
+   `Authorization: Bearer <URLCODE_AI_TOKEN>`. Keep `urlcode mcp` registered
+   for project-aware inspection and validation, and store the hosted token in
+   the client's secret facility rather than in project files. Start with the
+   hosted [agent guide](https://urlcode.ai/llms.txt), then see
+   [hosted AI MCP setup](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md#optional-hosted-ai-mcp).
 
 | Shape | Supported? | Use |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode",
-  "version": "0.5.5",
+  "version": "0.5.8",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [
@@ -75,6 +75,7 @@
   "files": [
     ".claude/skills",
     "dist",
+    "!dist/scripts",
     "schemas",
     "data",
     "starters",
@@ -99,22 +100,22 @@
     "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",
+    "check:code": "node scripts/check.ts && node scripts/check-core-boundaries.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 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",
-    "serve": "node src/cli.ts serve --project starters/default",
-    "validate": "node src/cli.ts validate --local --project starters/default",
-    "test:project": "node src/cli.ts test --project starters/default",
-    "init": "node src/cli.ts init",
-    "doctor": "node src/cli.ts doctor",
-    "routes": "node src/cli.ts routes --project starters/default",
-    "audit:routes": "node src/cli.ts audit --project starters/default",
-    "benchmark:project": "node src/cli.ts benchmark --project starters/default",
+    "dev": "node packages/core/src/cli.ts dev --project starters/default",
+    "serve": "node packages/core/src/cli.ts serve --project starters/default",
+    "validate": "node packages/core/src/cli.ts validate --local --project starters/default",
+    "test:project": "node packages/core/src/cli.ts test --project starters/default",
+    "init": "node packages/core/src/cli.ts init",
+    "doctor": "node packages/core/src/cli.ts doctor",
+    "routes": "node packages/core/src/cli.ts routes --project starters/default",
+    "audit:routes": "node packages/core/src/cli.ts audit --project starters/default",
+    "benchmark:project": "node packages/core/src/cli.ts benchmark --project starters/default",
     "docs:reference": "node scripts/generate-yaml-reference.ts",
     "docs:plugin": "node scripts/generate-claude-plugin.ts",
     "docs:llms": "node scripts/build-llms-full.ts",
@@ -155,9 +156,9 @@
     "@changesets/cli": "3.0.3",
     "@eslint/js": "10.0.1",
     "@types/mime-types": "3.0.1",
-    "@types/node": "26.5.1",
+    "@types/node": "26.6.2",
     "@types/semver": "7.8.0",
-    "eslint": "10.10.0",
+    "eslint": "10.11.0",
     "globals": "17.12.0",
     "semver": "7.8.5",
     "typescript": "6.0.3",

package/skills/urlcode/SKILL.md

@@ -12,24 +12,23 @@ A URLCode project declares URL behavior in YAML; the installed runtime serves it
 > Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
 
 Check installed primitives, YAML configuration, policies, extensions and recipes/templates before writing custom code. Keep it focused and report the gap; never invent fields or bypass target limits or operator grants. Source checkouts have `docs/PROJECT-DIRECTION.md`; npm installations have it in `llms-full.txt`.
-
 ## 1. Recognize the project
 
+- No `urlcode.yaml` yet? `npm install @jimhoyd/urlcode` (scoped; no unscoped `urlcode` package exists), then `npx urlcode init .`.
 - The root has `urlcode.yaml` with `version: "1"`. Included route files are
-  listed under `includes`; functions, middleware and assets are referenced from
-  the project root.
+  listed under `includes`; functions, middleware and assets are project-relative.
 - Read the project's `AGENTS.md` first if present; it lists the handlers,
   policies and commands this runtime version supports.
 - Find the runtime: `urlcode` on the PATH, or
   `node node_modules/@jimhoyd/urlcode/dist/cli.js`, or
-  `node /path/to/urlcode/src/cli.ts` for a source checkout. Use one form for
+  `node /path/to/urlcode/packages/core/src/cli.ts` for a source checkout. Use one form for
   every command below.
-
 ## 2. Retrieve the minimum, do not read everything
 
 **First step: one bounded query.** MCP `get_context` when the `urlcode` server is registered, otherwise `urlcode context --project DIR` (add `--budget N` to cap it). It returns a compact summary, constraints and exact commands, never a schema dump. Then retrieve only what the task needs: `capabilities NAME`/`get_capability` (its limits), `get_schema`, `recipes search`/`search_recipes`, `explain`, and `get_extensions` when an operator host file exists. The bare `urlcode capabilities` and `recipes list` catalogs, `llms.txt` and `llms-full.txt` are deliberate fallback/reference, not the opening move.
 
 If the project carries `.mcp.json` (written by `urlcode init`) and your client has the `urlcode` server, prefer its tools: `get_context` (project summary, constraints, exact commands), `get_capability` and `get_schema` (one capability or YAML fragment), `search_recipes`, `search_examples`, `explain` (a route's effective behavior) and `get_manifest`. For framework discovery, use `list_skills` before `get_skill`, `search_docs` for a short package-owned excerpt, and `get_example` for one runnable example. Use `validate_yaml` for pasted YAML syntax/schema feedback only; use `validate` for the actual project. The server is read-only; `--allow-authoring` is an operator opt-in you never add yourself.
+[URLCode AI](https://urlcode.ai/) is an optional, separate hosted service for shared skills and LLM tooling. Its remote MCP supplements this local project server; never replace `.mcp.json` or put its bearer token in project files. Its machine-readable entry point is `https://urlcode.ai/llms.txt`; connection details belong to the MCP client's secret facility and are documented in the URLCode tooling guide.
 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
@@ -118,8 +117,9 @@ urlcode audit --project DIR --expect-routes N
 ```
 
 Add fixtures to `tests/requests.json` for each new route: positive and negative
-cases, every active method, `HEAD`. Update `N` deliberately when routes are
-added or removed, and update any `--expect-routes` in the project's README,
+cases, every active method, `HEAD`. `N` is declared routes plus one per active
+`site.*` convention; an audit mismatch reports the declared/generated split. Update it
+deliberately when routes are added or removed, and update any `--expect-routes` in the project's README,
 Makefile or CI workflow to match. A failing validation names the route; fix
 the declaration rather than working around it.
 

package/starters/default/.github/workflows/urlcode.yml

@@ -19,5 +19,6 @@ jobs:
       # Pin to a release tag or commit of the runtime you depend on.
       - uses: jimhoyd-com/urlcode/action@main
         with:
-          expect-routes: 2 # update when adding or removing routes
+          expect-routes: 0 # update when adding or removing routes
+          allow-empty-project: true # remove after adding the first active route
           compliance: baseline

package/starters/default/AGENTS.md

@@ -22,7 +22,7 @@ static serving and authentication. Read this file before changing anything.
 
 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. For a committed artifact lock, use `get_extension_artifacts`/`get_extension_artifact`; they expose verified inert data and never activate an extension.
+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. [URLCode AI](https://urlcode.ai/) is a separate optional hosted service for shared skills and LLM tooling; its remote MCP never replaces this local project server, and its credential belongs only in a client secret facility, never project files. Its machine-readable entry point is `https://urlcode.ai/llms.txt`.
 
 ## What the runtime provides (this version)
 
@@ -56,10 +56,10 @@ record the reason in `sandboxReason`. Try `redirect` (relative or `/**`) or `res
 ```sh
 urlcode validate --local
 urlcode test
-urlcode audit --expect-routes 2
+urlcode audit --expect-routes 0
 ```
 
-Run all three after every change, updating the route count deliberately and adding `tests/requests.json` fixtures for every new route (positive/negative, every active method, HEAD). No global install: use `node /path/to/urlcode/src/cli.ts`.
+With no active routes, this initial audit intentionally exits nonzero with `no-active-routes`. Add the first route and its fixture, then make the audit pass; remove `allow-empty-project: true` from the generated GitHub workflow at that point. `N` counts declared routes plus one route for each active `site.*` convention; an audit mismatch reports the declared/generated split. Update it deliberately and add `tests/requests.json` fixtures for every new route (positive/negative, every active method, HEAD). No global install: use `node /path/to/urlcode/packages/core/src/cli.ts`.
 
 ## Feedback
 

package/starters/default/Makefile

@@ -1,6 +1,6 @@
 .DEFAULT_GOAL := help
 
-# Install the runtime separately, or override: URLCODE='node /path/to/urlcode/src/cli.js'
+# Install the runtime separately, or override: URLCODE='node /path/to/urlcode/dist/cli.js'
 URLCODE ?= urlcode
 HOST ?= 127.0.0.1
 PORT ?= 3000

package/starters/default/README.md

@@ -1,29 +1,31 @@
 # Your URLCode project
 
-One starter: a URL that runs your function, and a regular redirect.
-Created with `urlcode init ../my-links`. No template choice is needed.
+This is a bare, agent-ready URLCode scaffold. It starts with no routes so your
+application's YAML and tests describe only the behavior you intend to ship. Its
+single fixture proves the empty project returns 404.
 
 ```sh
 urlcode dev
 # In another terminal:
 urlcode test
-urlcode audit --expect-routes 2
-urlcode benchmark --requests 1000 --concurrency 2
 ```
 
-Visit http://127.0.0.1:3000/hello/Ada or http://127.0.0.1:3000/go.
-`urlcode.yaml` loads `routes/functions.yaml` and `routes/marketing/links.yaml`.
-Organize those files however you like; references are relative to the project root.
-The function route uses `middleware/headers.mjs` to add a response header around
-`await next()`. Edit or reuse it on other routes as needed.
-GET/HEAD, redirect 302 and no-store defaults keep YAML short. Valid edits reload.
+`urlcode audit --expect-routes 0` intentionally reports `no-active-routes` until
+you add the first route. The included GitHub workflow permits only that initial
+audit result; remove `allow-empty-project: true` after adding a route.
+
+Start with the local MCP `get_context` tool (or `urlcode context --project .`),
+then add the smallest declarative route or custom code the task requires. Keep
+`tests/requests.json` aligned with every route you add and update the audit
+count deliberately. `AGENTS.md` explains the workflow and points to the
+optional hosted shared tooling at https://urlcode.ai/llms.txt.
 
 This app uses the runtime you installed separately (compatible with 0.1.0).
-Without a global install, invoke `node /path/to/urlcode/src/cli.ts` instead of
-`urlcode`. Optional Make shortcuts accept `URLCODE='node /path/to/urlcode/src/cli.ts'`.
+Without a global install, invoke `node /path/to/urlcode/packages/core/src/cli.ts` instead of
+`urlcode`. Optional Make shortcuts accept `URLCODE='node /path/to/urlcode/packages/core/src/cli.ts'`.
 For a cloneable project with a pinned npm runtime dependency, use
 [urlcode-template](https://github.com/jimhoyd-com/urlcode-template). Both start
-with the same two route examples. No runtime fork or provider account is needed.
+with the same bare scaffold. No runtime fork or provider account is needed.
 
 Keep this app in your own Git repository. Secrets stay in ignored `.env.local`
 or provider environment values, with external operator policy for function grants.

package/starters/default/tests/requests.json

@@ -1,56 +1,6 @@
 [
-  {
-    "path": "/hello/Ada",
-    "status": 200,
-    "expectBody": "{\"message\":\"Hello, Ada!\"}",
-    "expectHeaders": {
-      "x-powered-by": "URLCode",
-      "cache-control": "no-store",
-      "x-example-middleware": "active"
-    }
-  },
-  {
-    "path": "/hello/Ada",
-    "method": "HEAD",
-    "status": 200,
-    "expectBody": "",
-    "expectHeaders": {
-      "x-example-middleware": "active"
-    }
-  },
-  {
-    "path": "/go",
-    "status": 302,
-    "expectHeaders": {
-      "location": "https://example.com/"
-    }
-  },
-  {
-    "path": "/go",
-    "method": "POST",
-    "status": 405,
-    "expectHeaders": {
-      "allow": "GET, HEAD"
-    }
-  },
   {
     "path": "/missing",
     "status": 404
-  },
-  {
-    "path": "/hello/Ada",
-    "method": "POST",
-    "status": 405,
-    "expectHeaders": {
-      "allow": "GET, HEAD"
-    }
-  },
-  {
-    "path": "/hello/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "status": 400
-  },
-  {
-    "path": "/hello/%ZZ",
-    "status": 400
   }
 ]

package/starters/default/urlcode.yaml

@@ -1,7 +1,4 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/jimhoyd-com/urlcode/669632fb4f188f293a0f622847f87ee019c0627f/schemas/urlcode.schema.json
-# Organize files however you like; list their paths from this project root.
+# Start with no routes. Add only the files and routes your application needs.
 version: "1"
-includes:
-  - routes/functions.yaml
-  - routes/marketing/links.yaml
 routes: {}

package/dist/scripts/operational-drills.js

@@ -1,33 +0,0 @@
-// Disposable local proof, never a claim about the production deployment.
-import assert from 'node:assert/strict';
-import {mkdtemp,mkdir,writeFile,rm} from 'node:fs/promises';
-import {tmpdir} from 'node:os';
-import {join} from 'node:path';
-import {startServer} from '../server.js';
-                                             
-
-const seconds=Number(process.env.URLCODE_SOAK_SECONDS||5);
-assert(Number.isInteger(seconds)&&seconds>=1&&seconds<=3600,'Soak must be 1–3600 seconds');
-const directory=await mkdtemp(join(tmpdir(),'urlcode-drills-')),project=join(directory,'app');
-let app                  ;
-try {
- await mkdir(project);
- const config='version: "1"\nroutes:\n  /go:\n    redirect: {url: "https://example.com/v1"}\n  /function:\n    function: {source: f.mjs}\n';
- await writeFile(join(project,'urlcode.yaml'),config);
- await writeFile(join(project,'f.mjs'),'export default () => new Response("isolated");');
- app=await startServer({project,port:0,log:()=>{}});
- const server=app;
- const get=async(path        )=>{const r=await fetch(`http://127.0.0.1:${server.address.port}${path}`,{redirect:'manual'});const body=await r.text();return {status:r.status,location:r.headers.get('location'),body};};
- const start=performance.now(),samples          =[];let requests=0;
- while(performance.now()-start<seconds*1000){
-   const before=performance.now();const responses=await Promise.all(['/go','/function'].map(get));
-   assert.deepEqual(responses.map(r=>r.status),[302,200]);assert.equal(responses[1]?.body,'isolated');
-   samples.push(performance.now()-before);requests+=2;
- }
- await writeFile(join(project,'urlcode.yaml'),'invalid: configuration');assert.equal(await app.reload(),false);assert.equal((await get('/go')).location,'https://example.com/v1');
- await writeFile(join(project,'urlcode.yaml'),config.replace('/v1','/v2'));assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v2');
- await writeFile(join(project,'urlcode.yaml'),config);assert.equal(await app.reload(),true);assert.equal((await get('/go')).location,'https://example.com/v1');
- await app.close();app=undefined;
- samples.sort((a,b)=>a-b);
- console.log(JSON.stringify({event:'local-operational-proof',seconds,requests,batchP99Ms:samples[Math.floor(samples.length*.99)],rssBytes:process.memoryUsage().rss,checks:['mixed HTTP load','invalid reload preserves last-good','configuration rollback'],deploymentProof:false}));
-} finally {await app?.close();await rm(directory,{recursive:true,force:true});}

package/starters/default/functions/hello.mjs

@@ -1,3 +0,0 @@
-export default function hello(request, { args }) {
-  return Response.json({ message: `Hello, ${args.name}!` });
-}

package/starters/default/middleware/headers.mjs

@@ -1,6 +0,0 @@
-// Reusable logic around a route: run downstream, then add a response header.
-export default async function headers(request, context, next) {
-  const response = await next();
-  response.headers.set('x-example-middleware', 'active');
-  return response;
-}

package/starters/default/routes/functions.yaml

@@ -1,20 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/jimhoyd-com/urlcode/669632fb4f188f293a0f622847f87ee019c0627f/schemas/urlcode.schema.json
-# File locations do not change route paths. GET/HEAD are the default methods.
-version: "1"
-routes:
-  # Your code runs when this URL is requested.
-  /hello/{name}:
-    parameters:
-      - name: name
-        in: path
-        required: true
-        schema: {type: string, minLength: 1, maxLength: 80}
-    middleware:
-      - source: middleware/headers.mjs
-    function:
-      source: functions/hello.mjs
-      args:
-        name: {from: path, name: name}
-    response:
-      headers:
-        X-Powered-By: URLCode

package/starters/default/routes/marketing/links.yaml

@@ -1,7 +0,0 @@
-# yaml-language-server: $schema=https://raw.githubusercontent.com/jimhoyd-com/urlcode/669632fb4f188f293a0f622847f87ee019c0627f/schemas/urlcode.schema.json
-version: "1"
-routes:
-  # A regular redirect needs no custom code.
-  /go:
-    redirect:
-      url: https://example.com

package/starters/page/README.md

@@ -1,14 +0,0 @@
-# Your URLCode page
-
-The smallest project: one route that serves `public/index.html`.
-Created with `urlcode init <dir> --template page`.
-
-```sh
-urlcode validate --local
-urlcode test
-urlcode dev   # http://127.0.0.1:3000/
-```
-
-Edit `public/index.html`. Add more pages, a `static` directory, downloads,
-redirects or functions as routes in `urlcode.yaml` (see docs/ASSETS.md in the
-URLCode repository). Keep `tests/requests.json` in step with the routes.

package/starters/page/public/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Hello, URLCode</title>
-</head>
-<body>
-<h1>Hello, URLCode</h1>
-<p>This page is served by a page route in urlcode.yaml.</p>
-</body>
-</html>

package/starters/page/tests/requests.json

@@ -1,17 +0,0 @@
-[
-  {
-    "path": "/",
-    "status": 200,
-    "expectBody": "<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>Hello, URLCode</title>\n</head>\n<body>\n<h1>Hello, URLCode</h1>\n<p>This page is served by a page route in urlcode.yaml.</p>\n</body>\n</html>\n"
-  },
-  {
-    "path": "/",
-    "method": "HEAD",
-    "status": 200,
-    "expectBody": ""
-  },
-  {
-    "path": "/missing",
-    "status": 404
-  }
-]

package/starters/page/urlcode.yaml

@@ -1,6 +0,0 @@
-version: "1"
-routes:
-  /:
-    description: The home page, served from a file. Add routes beside it as the project grows.
-    page:
-      file: public/index.html