@jimhoyd/urlcode 0.5.6 → 0.5.9

package/dist/vercel.js

@@ -12,6 +12,17 @@ import { assert, HttpError } from './errors.js';
 
 const platformOrigins = ['VERCEL_PROJECT_PRODUCTION_URL','VERCEL_URL','VERCEL_BRANCH_URL'];
 
+// `x-forwarded-for` is documented as overwritten (not appended to) by
+// Vercel's edge, but only when Vercel itself is the client-facing proxy; a
+// project's own proxy in front of Vercel can still set it before Vercel ever
+// sees the request. `x-vercel-forwarded-for` is Vercel's own copy of the same
+// value and is the header Vercel's docs say to prefer for exactly that reason
+// (https://vercel.com/docs/headers/request-headers#x-vercel-forwarded-for).
+// Exported so the adapter's client-IP resolution can be verified directly.
+export function forwardedClient(headers         , headerCounts                        )                     {
+  return headerCounts['x-vercel-forwarded-for'] === 1 ? (headers.get('x-vercel-forwarded-for') ?? '').split(',')[0]?.trim() || undefined : undefined;
+}
+
 function readBody(req                 , limit        )                  {
   if (req.headers['content-length'] && Number(req.headers['content-length']) > limit) return Promise.reject(new HttpError(413,'Request body too large'));
   return new Promise((resolve,reject) => {
@@ -49,9 +60,7 @@ export function createVercelHandler({ project = process.cwd(), origin, environme
       }
       const limit = Math.min(maxBodyBytes, runtime.requestLimit(target) ?? maxBodyBytes);
       const body = await readBody(req,limit);
-      // The platform terminates TLS and sets the forwarded header itself, so
-      // its leftmost entry is the client; the socket peer is the platform.
-      const forwarded = headerCounts['x-forwarded-for'] === 1 ? (headers.get('x-forwarded-for') ?? '').split(',')[0]?.trim() : undefined;
+      const forwarded = forwardedClient(headers, headerCounts);
       const publicOrigin = resolveOrigin(origin,environment,platformOrigins) ?? 'http://localhost';
       const result = await runtime.handle({ target, method, headers, headerCounts, body,
         origin: publicOrigin, client: forwarded || req.socket?.remoteAddress });

package/dist/verify-deployment.js

@@ -3,6 +3,7 @@ import { request, Agent } from 'node:http';
 import { request as secureRequest, Agent as SecureAgent } from 'node:https';
 import { randomBytes } from 'node:crypto';
 import { assert } from './errors.js';
+import { isRecord } from './object-guards.js';
 import { createRuntime } from './runtime.js';
                                                    
 import { benchmarkTarget, hit, readFixtures, runFixtures, isStepsFixture, probeAgent } from './readiness.js';
@@ -26,7 +27,7 @@ import { lists as bundledAgents } from '../data/agents/index.js';
 // snapshot would; it says nothing about the host, the proxy or the network.
                                                 
                                        
-                                                                                                                                                                    
+                                                                                                                                                             
                                                                                                                                               
                                                                             
                                                                                                                                                       
@@ -46,32 +47,49 @@ const MAX_REQUESTS = 10000;
 const BODY_LIMIT = 1048576;
 const SNIPPET = 200;
 const siteTypes                         = { 'site.robots': 'text/plain', 'site.sitemap': 'application/xml', 'site.securityTxt': 'text/plain', 'site.llms': 'text/plain', 'site.notFound': 'text/html' };
-const isRecord = (value         )                                   => value !== null && typeof value === 'object' && !Array.isArray(value);
 const snippet = (body        )         => body.length > SNIPPET ? `${body.length} bytes: ${body.subarray(0, SNIPPET).toString('utf8')}` : body.toString('utf8');
 const tlsCode = /CERT|TLS|SSL|SELF_SIGNED/;
 
 // One request, one answer. Bodies are read up to 1 MiB and never logged
 // beyond the snippet a failing assertion carries. Redirects are not followed
 // and a transport error is reported as text, never thrown.
+//
+// `timeout` on a Node request/response is an *idle* timer: it only fires
+// once a socket has gone quiet, so a deployment that drips one byte just
+// under that interval keeps resetting it and can hold this probe open
+// indefinitely. A single wall-clock deadline covering the whole request
+// (connect through body) closes that gap. Past `BODY_LIMIT` the response is
+// destroyed rather than left to keep streaming into a discard loop: this
+// probe only ever needs a bounded snippet, never the rest of an oversized
+// or endless body.
 function probe(target                 , { path, method = 'GET', headers = {} }       , agent       , timeoutMs        )                  {
   return new Promise(resolve => {
-    const fail = (error         ) => {
+    let settled = false;
+    const finish = (answer        )       => { if (settled) return; settled = true; clearTimeout(deadline); resolve(answer); };
+    const fail = (error         )       => {
       const code = isRecord(error) && typeof error.code === 'string' ? error.code : error instanceof Error ? error.message : 'transport';
-      resolve({ status: 0, headers: {}, body: Buffer.alloc(0), error: code });
+      finish({ status: 0, headers: {}, body: Buffer.alloc(0), error: code });
     };
     let req                           ;
+    const deadline = setTimeout(() => { req?.destroy(new Error('timeout')); }, timeoutMs);
     try {
       const options                 = { host: target.hostname, port: target.port, path, method, agent, timeout: timeoutMs,
         headers: { host: target.hostname, 'user-agent': probeAgent, 'accept-encoding': 'identity', ...headers } };
       req = (target.protocol === 'https:' ? secureRequest : request)(options, (res                 ) => {
+        const out                         = {};
+        for (const [key, value] of Object.entries(res.headers)) if (value !== undefined) out[key] = Array.isArray(value) ? value.join(', ') : value;
         const chunks           = []; let size = 0;
-        res.on('data', (chunk        ) => { if (size < BODY_LIMIT) chunks.push(chunk); size += chunk.length; });
-        res.on('error', fail);
-        res.on('end', () => {
-          const out                         = {};
-          for (const [key, value] of Object.entries(res.headers)) if (value !== undefined) out[key] = Array.isArray(value) ? value.join(', ') : value;
-          resolve({ status: res.statusCode ?? 0, headers: out, body: Buffer.concat(chunks) });
+        const done = ()       => finish({ status: res.statusCode ?? 0, headers: out, body: Buffer.concat(chunks) });
+        res.on('data', (chunk        ) => {
+          if (size < BODY_LIMIT) chunks.push(chunk);
+          size += chunk.length;
+          if (size > BODY_LIMIT) res.destroy();
         });
+        res.on('error', fail);
+        res.on('end', done);
+        // A body cut off by the BODY_LIMIT destroy() above ends here, not on
+        // 'end'; the snippet already collected is still a valid answer.
+        res.on('close', () => { if (!settled) done(); });
       });
       req.on('error', fail); req.on('timeout', () => req?.destroy(new Error('timeout'))); req.end();
     } catch (error) { req?.destroy(); fail(error); }
@@ -148,7 +166,7 @@ export async function verifyDeployment(project        , { target, origin, expect
     const parse = (answer        )                                      => { try { const json          = JSON.parse(answer.body.toString('utf8')); return isRecord(json) ? json : undefined; } catch { return undefined; } };
     const healthJson = parse(health);
     check(health.status === 200 && healthJson?.status === 'ok' && typeof healthJson.version === 'string' && typeof healthJson.routes === 'number',
-      { check: 'probes', severity: 'high', message: '/_urlcode/health must answer 200 with {status:"ok",version,routes}', expected: '200', observed: `${health.status} ${snippet(health.body)}` });
+      { check: 'probes', severity: 'high', message: '/_urlcode/health must answer 200 with {status:"ok",version,routes}; start the target with --health-details (or --metrics) if it currently answers {status} only', expected: '200', observed: `${health.status} ${snippet(health.body)}` });
     const ready = await send({ path: '/_urlcode/ready' }), readyJson = parse(ready);
     check(ready.status === 200 && readyJson?.status === 'ok', { check: 'probes', severity: 'high', message: '/_urlcode/ready must answer 200 (the deployment reports itself degraded or is not URLCode)', expected: '200', observed: `${ready.status} ${snippet(ready.body)}` });
     if (typeof readyJson?.version === 'string') version.observed = readyJson.version;

package/docs/AI-AUTHORING.md

@@ -63,6 +63,11 @@ The root [llms.txt](../llms.txt) is a compact discovery index; the generated
 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](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](BEST-PRACTICES.md): preserve local
 conventions, use clear names, keep middleware focused and avoid needless layers.
@@ -432,6 +437,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](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](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](PROVIDER-VERIFICATION.md) test ingress.

package/docs/FUNCTION-SECURITY.md

@@ -82,6 +82,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](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/docs/README.md

@@ -8,7 +8,7 @@ Use documentation from the same pinned revision as your runtime.
 | Understand what URLCode does | [Framework](FRAMEWORK.md) |
 | Build my first project | [Installation](INSTALL.md), then [YAML guide](YAML-GUIDE.md) |
 | Build a site with UI, accounts and admin | [Composing a site](COMPOSING-A-SITE.md) |
-| Have an AI author a project | [AI authoring](AI-AUTHORING.md), [agent index](../llms.txt) |
+| Have an AI author a project | [AI authoring](AI-AUTHORING.md), [agent index](../llms.txt), [hosted agent guide](https://urlcode.ai/llms.txt) |
 | Deploy and operate a project | [Operations](OPERATIONS.md) |
 | Contribute to URLCode | [Contributing](../CONTRIBUTING.md), [local development](LOCAL-DEVELOPMENT.md) |
 
@@ -26,7 +26,7 @@ The [specification](SPECIFICATION.md) owns implemented semantics; the
 | Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
 | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
 | Run examples | [Executable cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
-| Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
+| Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [hosted agent guide](https://urlcode.ai/llms.txt), [SDK and read-only MCP](TOOLING.md) |
 | Reuse code around routes | [Middleware](MIDDLEWARE.md), [middleware examples](MIDDLEWARE-EXAMPLES.md) |
 | Handle secrets and decide what to sandbox | [Function security](FUNCTION-SECURITY.md) |
 | Author guest functions in TypeScript | [Build-time guest transpilation](TYPESCRIPT-AUTHORING.md) |

package/docs/TOOLING.md

@@ -281,6 +281,14 @@ documentation and example tools read only a fixed package-owned manifest; no
 tool argument names an arbitrary local path or remote URL. The CLI equivalent of `search_docs` is
 `urlcode docs search TEXT [--json]`, which returns the same at most three bounded excerpts. `validate_yaml` checks supplied
 YAML syntax and schema only, while `validate` compiles the selected local project.
+The `list_skills`, `get_skill`, `search_docs`, `get_example`, `validate_yaml` and
+`explain_error` tools are thin wrappers over `@jimhoyd/urlcode/agent-context`
+(`listSkills`, `getSkill`, `searchDocs`, `getExample`, `validateYaml`,
+`explainError`), a public package export — not an internal detail of this
+server. A host building its own MCP server, or any other agent-tooling
+integration, can import that module directly instead of reimplementing this
+behavior or reaching into `dist/agent-context.js`; see
+[TypeScript](TYPESCRIPT.md).
 `get_extension_artifacts` validates the project-selected
 `urlcode.extensions.lock.json` and cache, then returns artifact metadata,
 status and allowlisted member paths. `get_extension_artifact` accepts only a
@@ -330,7 +338,7 @@ choices added by hand, never by `init` or by an agent.
 
 - **Claude Code** reads `.mcp.json` in the project directory as a project-scoped
   server and asks for approval on first use. A project that pins the runtime in its
-  `package.json` (`--template redirects`, `--with`, `--manifest`) gets
+  `package.json` (`--with`, `--manifest`) gets
   `"command": "npx"` with `--no --package @jimhoyd/urlcode urlcode mcp ...`, which runs the
   installed copy and never fetches (do not use a bare `npx urlcode`: that names an unrelated
   registry package). A project without one keeps the bare `urlcode` command for a global
@@ -354,6 +362,32 @@ The generated `AGENTS.md` and the packaged skill tell agents to prefer
 `get_manifest` when the server is registered and to fall back to the matching
 CLI commands otherwise.
 
+## Optional hosted AI MCP
+
+The local `urlcode mcp` server remains the project-aware URLCode integration:
+it reads the selected checkout, validates its configuration and never needs a
+network credential. Do not replace its generated `.mcp.json` entry with a
+hosted service.
+
+[URLCode AI](https://urlcode.ai/) is a separate, opt-in hosted service for
+shared skills and LLM-assisted work. A client that supports authenticated HTTP
+MCP can add it as a second server with these connection details:
+
+- URL: `https://mcp.urlcode.ai/mcp`
+- request header: `Authorization: Bearer <URLCODE_AI_TOKEN>`
+
+Store `URLCODE_AI_TOKEN` in the MCP client's secret or environment-variable
+facility. Do not put a literal bearer token in `.mcp.json`, `urlcode.yaml`, a
+checked-in client configuration, or a shell history. Each client has its own
+remote-server configuration syntax, so configure that endpoint explicitly in
+the client rather than asking `urlcode init` to generate it.
+
+The hosted tools are not a proxy for this local server: they do not receive the
+project root and do not replace local `get_context`, validation, manifest,
+extension-artifact or authoring tools. Keep the local server registered for
+framework- and project-specific work; add the hosted server only where its
+shared skill catalog or LLM tools are useful.
+
 ## Authoring mode
 
 `urlcode mcp --allow-authoring --project DIR` adds six tools to the twenty-two read

package/examples/assets/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/examples/compliance/rules.mjs

@@ -1,7 +1,7 @@
 // Operator compliance rules for `urlcode audit --compliance-rules`.
-// Runnable against the cookbook from the runtime checkout:
+// Runnable against the cookbook from the runtime checkout (after `npm run build`):
 //
-//   node src/cli.js audit --project examples/cookbook \
+//   node dist/cli.js audit --project examples/cookbook \
 //     --compliance baseline --compliance-rules "$PWD/examples/compliance/rules.mjs" --compliance-warn
 //
 // The file must sit outside the audited project (it is trusted host code, the

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,257 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.6`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.9`. `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.
@@ -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.6. Start with the function example below,
+This guide targets URLCode 0.5.9. 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.
@@ -795,8 +806,9 @@ 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.6`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.9`. `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.6",
+  "version": "0.5.9",
   "description": "Portable runtime for programmable URL behavior",
   "type": "module",
   "workspaces": [
@@ -25,6 +25,10 @@
       "types": "./dist/types/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./agent-context": {
+      "types": "./dist/types/agent-context.d.ts",
+      "default": "./dist/agent-context.js"
+    },
     "./aws": {
       "types": "./dist/types/aws.d.ts",
       "default": "./dist/aws.js"
@@ -75,6 +79,7 @@
   "files": [
     ".claude/skills",
     "dist",
+    "!dist/scripts",
     "schemas",
     "data",
     "starters",
@@ -155,9 +160,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/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/packages/core/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/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.