@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.1

package/dist/BUILD-MANIFEST.json

@@ -1,60 +1,90 @@
 {
-  "node": "v26.8.2",
+  "node": "v26.9.0",
   "files": {
-    "dist/adapters.js": "40e5c2d0ff4be8b11752418f063a9e79e29e31b6a64c92a19a514f182268133c",
-    "dist/agent-lists.js": "fa1e87b928bf7178d7e910584018ef330a164be834156a8728f8d33ed7353211",
+    "dist/adapters.js": "a7153ec52f2ed7e0cdd8ed7d433504815f402ec53b2b1c3d38d0cf0e2fcf6509",
+    "dist/agent-lists.js": "35ab484198897501d011cb6cc00b5a6787192e19df29c97646e8c118fcc19eef",
+    "dist/agents-guide.js": "9cecc60690fe91e1f09a5298273c1d918428f114b5abb11f40f37f341668309c",
     "dist/assets.js": "0833b093d2fe457ce68281110dc07d47914992753607741c13b339d92c76cf5c",
-    "dist/authoring.js": "99c3fe70df840ccc2a57b887b6b5886998a1155e848c3b6804a89bd1e257b05b",
-    "dist/aws.js": "1384e417de68404b5f1f35ee8a9148271b6efa0965a64e458d7bbda0234cc564",
-    "dist/build-cloudflare.js": "65af88384795bd7a4e2374c2cd9e5be174e3ffd4142f705723a3f5115a28eb27",
-    "dist/cli.js": "4cb9a0a6d85ac4b101b72cd71dbdb3ca17c8ab1d064986f9923e4a5254b8b7a9",
-    "dist/client-address.js": "292b86165def33247b05ef619e15245b70765522c8d9dc0ca4fac6e22e531de8",
+    "dist/authoring-files.js": "ad32814f9ae9c549c6247396f982aa700d13a293cc0a589609eccc68f8965550",
+    "dist/authoring.js": "ec5240e8686c124f4601229b45f89ce112d9eeb9d35e3059fe55e93056c45209",
+    "dist/aws.js": "7d8e3a97b4f6dbefbd68da058f05192469d1efcaed5458b284863ebe462e060e",
+    "dist/build-cloudflare.js": "af4f49ad45287d7c4105bb84b1592b5b8e76c930f7159505338298f7c5fd5651",
+    "dist/bulk.js": "aac88d422bd9a7a341a421fb4e29ff5580b28d39250b7f1f5315ba20ae92da8a",
+    "dist/capabilities.js": "c1e28c7de676c3b43c154d6f767749a1b34df78a64c58b5c23ad95339f964608",
+    "dist/capability-query.js": "850525d542aeeaeb4f89397ac57c6f89daad3fe3fa02ecb0332ea9f75d140b32",
+    "dist/catalog.js": "ab1c01c9296cc277d2bd4fd682aeb053656a7d9f91c61974f4b78feea0211de8",
+    "dist/cli.js": "4cba007ed3666fdfdf9fc676de1e346ab8196e3907dc2541eeb3e59842d9891a",
+    "dist/client-address.js": "9d0d01466aab23124330605c5a0e0f981f87c897858acfad909f546a63df165b",
     "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
-    "dist/compliance-rules/baseline.js": "6746ed9717fcbc414d4892ec54afca74496dcc725f2c80d417e382c190294811",
-    "dist/compliance-rules/privacy.js": "fe8330fd4c5068645e5c41db389fd190d7423e822397bf3938ca48d275bd449c",
+    "dist/compliance-rules/baseline.js": "0a0c03d932f30797c4837c78c6b64ca6bb88f2ca947eb7f6adf5fdcdd280616d",
+    "dist/compliance-rules/privacy.js": "0e4d12106cf777299a7d30451f53c7b996f202fe53d7e1047b69f5df2a74a53d",
     "dist/compliance-rules/shared.js": "595a7ee3a5af8c52197c5c9cbf09f4289a234e52b7a198afdd498be9be8d28a1",
-    "dist/compliance-rules/strict.js": "937b55f4574eb5ca9f238b1a9658b089d006372328da35a329e4359719e6c3d0",
+    "dist/compliance-rules/strict.js": "73ee13c2f893acf20cc3d44bf054e58c1474dec52eafe0cf2ce7f4eb96a3bc53",
     "dist/compliance.js": "e956dc89b0b729fed7031297b8d7554141110334e670edf5cedc3d052a8fb3e4",
+    "dist/conditions.js": "ff25e97da550a3bdd80af55522045669438aa31a77d2bc83ad602bcefdee0475",
     "dist/config-worker.js": "bc2170d60c35f8d5de227cbfc4c5067dc61d7cbc5b98aed88e68a11797072da5",
-    "dist/config.js": "d0e0d100f3f97d3cefd17d898dddea463773092569a7cd7c3384bd547847659f",
+    "dist/config.js": "8efc2cfc24e9a958770d73aa8464d18c81d7a9a1d2398398cd9cc2776e639127",
+    "dist/context.js": "a6b0278b4fd478175f43b1ef5ae640ce6e0782c906c6fd2c7d1aebaf5a31c918",
+    "dist/ecosystem-cli.js": "1e71bacd53d6fa8c7857cfcce3c3012ce054771a434b78d1f39e892e32642edd",
+    "dist/egress.js": "2ae29fe2cb4590fd2f715abe6817db47fed2f50dd31f37946ecf42eafbb0dd9e",
     "dist/errors.js": "a908e66496afebbdd632a8c159a6e14d23f8f38798a0b4342ca122f2511c6cde",
-    "dist/function-sources.js": "48b470fbdcef2ad2c83e61a6476d5499210d0937b72518ae01fb2b9225b0e16b",
+    "dist/examples.js": "8de9917a82fb04e44a3182d57c6a95cc730feb8b22a37d54b9b3c4177aa83111",
+    "dist/explain-cli.js": "c5414e9627f428f0d8efa4e4f3f89951ea10a6b3fe1d7f633e48f71a792406d2",
+    "dist/explain.js": "5dd271b699c9b852fbaa4db271d9a370fe98fca43b1d0ac018de0c0b047bf7b8",
+    "dist/extensions.js": "7402ff86017fca83a0e08a50b402bc428056566d63511aa84d609e252dc456e8",
+    "dist/function-sources.js": "f6e8bdd9d4ef728b44c6e1f08c601b11fc4ad3e0c104dacf4fea0b71874ea4e7",
     "dist/function-worker.js": "3f5bad4f1b5cb812924c2dcc73ece6f816cf6aac26cd471fd1030dcfbf009c3b",
     "dist/functions.js": "6b1e5d4a3f8db17d4e5df261b98ed15f5f0c5e5507a6fc0f472e9f94ed2b6090",
     "dist/guest-api.js": "bc2501496a6ef9fd20dddb606fbc6fd557d534dd075e7ad38406248b230013ed",
     "dist/header-validation.js": "465181dbb08ff05f52defdd29fda025c0c64589bf319fa87fa6d3ab4b68216d5",
     "dist/http-policy.js": "4cb187642269078ddf3460a3f1813dc57878a616a6f8132ef8f8d3b4b91ebb56",
     "dist/http-response.js": "5fc3bb9eb932a3fd2fbc72c361416a5f1439b8bf45b2be37baca1c6446abf40c",
-    "dist/index.js": "648878ef26cb3a8eb075a5ddd4d044022afe6cf5e5e38d1bd6ea418b82791371",
+    "dist/index.js": "53648d88b0db7d9168d2f212ea4a28b7fd3ead6238c99c0b8d7d41536274d6d4",
+    "dist/init-with.js": "8371f568867ebdc6ab8e9aa762234ae2aa015865f46aa901254528e20d69b791",
+    "dist/interchange-cli.js": "35bd70ba8077af5c3e39404ff0e5d28707632090a59a90645141252449fd3f04",
+    "dist/interchange.js": "26789420af33344d9a08c00fe6b2708aa71994224df527b3075295be2151611e",
     "dist/link-api.js": "0d1f2fb5ef8cd6fda7b071d3e08c53eb4b1c01d4003167af2f400949b70dea4f",
-    "dist/link-cli.js": "5f45e62a6b935112cabfcd12691a5ebc01d9c87f92e4befb655380d9e752323b",
+    "dist/link-cli.js": "c4e2121a3e66f33c640832a7cb362a6a1db8b6d91d55a4239ce38ba0ced67b22",
     "dist/link-events.js": "502a6038a538fa43094a9ba9c7546f504b4a1832a1377f26ca8cb69c2326670e",
     "dist/link-records.js": "ef67a58cd107db0c3ac1c0ffd7b32817553606cf69bb3002da4ca0138c272f69",
     "dist/link-store-worker.js": "0080452bbada2154b923449cd14596579bde94ad5f8dab94ecc84aa0d59c089b",
     "dist/link-store.js": "526cdbe1b917cc7a74fb6edbbf13717d823ace5b5d6a5f89bc91438056a10b37",
     "dist/logging.js": "8ec57fea26983aa071b05fe15d680d6550b03488101163ed9666da674118cf31",
-    "dist/management-policy.js": "ad573627de0e9f9b5368d701966468f391f53d64d2a82bfd8083bca412b01721",
-    "dist/match.js": "a0935ee5a3c68d85c268abbdcecd30a7ebd68e37bbecb68136479b1f94fc3705",
-    "dist/observability.js": "28a446ad867329e58cbccb9215a343a390e8599dad6a31c1db0e702d3df67e27",
-    "dist/plugins.js": "c228ec42cd727f259193fe905ae247f9fba34f695dd1364d8e3ee6683262da7c",
-    "dist/policies/agents.js": "761920214db2ada60733743541f134928ba1d2f0bc763660bd0d1112a725c887",
+    "dist/management-policy.js": "bd5563da52c53ace71b01daed0d2a492baeb3f26f5ec5ee1b0981c2b88df9ffa",
+    "dist/manifest.js": "d4f58f936febbabf09ec1706baae7c1cb186dcd8a3d29b5725dad5b6eaf43a3f",
+    "dist/match.js": "53ebcc2cda529a8d07fb83f8cb69a1446036ffc1641af3c4bd45a55851bded28",
+    "dist/mcp-authoring.js": "5030f52ef9c7ebc7b97305fcce687eb0a0d6164e34fda87f8278135a1e6f3d65",
+    "dist/mcp.js": "ac96c5a094d7cc88cf16d1d1e3c23f45773729fe28855f921581badb2b95eb89",
+    "dist/observability.js": "13a22b9e34cf8da3739856eeada8522fb6c43765386cae07c6aa0981447fcb83",
+    "dist/operator-host.js": "e3dac9d43a83beb775202b4ab9eeeba7ac63cebfc5dcc669be38d825be587bd0",
+    "dist/plugins.js": "a61aa933cd9e1b41020b86fae78aa3a7f45f5313124aa11b50cb57898722385e",
+    "dist/policies/agents.js": "c1dbc1e90339f472eeeb2372f7f4637f59a5d210797ea680ac8120a02aa20c10",
     "dist/policies/cache.js": "ef16d7e592526c29f865b2693faa2c8afbea41c6526687563dffcb13a77fc1f7",
-    "dist/policies/compression.js": "d342c6db4a9bee63b62b35654dde28fa163bfd82510bb85331bb9b072f856781",
-    "dist/policies/security.js": "119fb37bd0e994ddabf3feacbc52d481c8e8c65b0ac6b71c8d3533b8c3e2cedb",
+    "dist/policies/compression.js": "800f3ae3b1a4c1fe58c3d9908364ea9d78f655ff50c7f7589f584378e7f194b0",
+    "dist/policies/security.js": "2b3bfdf82140156fea4b162adc28ee43ccd85c402fb200680dbb8d8706417420",
     "dist/policies/throttle.js": "bbb0cb1c24cf70d0a1ac32fc0618efb6c44e5b5d42564842f9c585ff7e501603",
-    "dist/policies.js": "e3f48ad730d1d7b1435bff2f2bd7091e24a0c46dd0e1393d53337d64e3a7d83d",
-    "dist/policy.js": "280f94593c9e376726e2b3d34f4c1e9817802d67134bd6a2d1afe466244b3fdc",
-    "dist/prerender.js": "f568e2773be6fe67b547739f609c0287f429451ab31187f48ffe4560df3f877b",
-    "dist/project-tests.js": "91aa9c22d9f40efb0c5318b7a05b4aee753fc1ab591fe90e8d94f24fa60697f5",
-    "dist/readiness.js": "64eedecc9405db253e2bd39819c7f5640c6017f13cf23d2a193656dda095ca45",
-    "dist/router.js": "a102132362177bb8690bde11ce2b6ea9719a79601a25165d5d36dc736b1b888b",
-    "dist/runtime.js": "1d22cdb83703e0fc15da63d28b02fbd419051894063cb2fde5072b186c98ec62",
+    "dist/policies.js": "23fa019b7bf1cdedcc5f7772d2f157e4b381a554bce9e84594c2be4a0f8f76b8",
+    "dist/policy.js": "8285ed144ba42fd34e926e526cd4dcf60d5ab3668adf4f0b797f074ebd5243ce",
+    "dist/prerender.js": "0386ea2411e00b9563b5349133f1d723947b01f837fa92d4c61a699c9cfb5cdb",
+    "dist/project-tests.js": "225761d36bbe7e185c49c10c0334e579caf7d98647c9941faa4b0ea6406522fa",
+    "dist/provider-verification.js": "ffcf9f05e8cb5f71ea46a97e279e8a613fdfdf9435ab02bd57af11e2680a9107",
+    "dist/proxy.js": "34107e59ac0dbbea090efa3cf5badf3226c5302ba25e8f8ff9b2b5596ed80e50",
+    "dist/readiness.js": "d419b09a83dc8e6790be7c91ba4e1a2a5cf9b141577c98bd24e99a3609553649",
+    "dist/recipes.js": "11853f23e63c3c65c5bed03a278cde0349d28c9fa23266c9907a2df318bb5fc3",
+    "dist/route-diff.js": "eebac076a886ddfb2bf5b97ea09d81f888e7bb0063d482eddb8e5fef9acea107",
+    "dist/router.js": "4315585232561c1737e579a2cbd990596d337b37565dd449bcb1bbaa6abbfb13",
+    "dist/runtime.js": "f6f1bfa320a427423d66be845de3368552b1f4cca4a28136b913ac26fb9d6169",
     "dist/scaffold.js": "9dd30112e070ec554bd7cae1ca0a8b03642632be57411ba76a72972f4ba49b3e",
+    "dist/schema-query.js": "bfd1844acd8d54ac361115191fcfbaf828a67e223b9ec6e9c22f158761af149b",
     "dist/server.js": "d8c78d1695b3c11328f3f983281fba78c2aca6a66cf755b39ecf4ec2ec4b6f29",
-    "dist/site.js": "f34b023c9bcd403d38b8a2bf4d8ba184e0ff00cbd98405b49c68747466d995cd",
+    "dist/signals.js": "b55e54efc8fb6703e08f2a1e808ec8e011bda67738db8ceadf1b248f695795be",
+    "dist/site.js": "c40a06a6f9e2d6d3bea94727783c115fed4309bb0190787f58434eed64cbde84",
     "dist/sqlite-version.js": "a3a08d99064bd0f35847e288027e00a516efdd61c675bfbbe7726e3aa900f0d1",
-    "dist/types.js": "96650efc60f2400b7b1a6622798f0f42d43f451fa5bf18a93d06482feb2e0283",
-    "dist/vercel.js": "76092b83e4d80e29541589682e00237701a3d3f096a8045fa2cf104b6d1b6725",
+    "dist/tooling.js": "eaf9aa49df17b5ab3bc538976b2849fac52b5ca779b6e814fd7ca592ecd757b7",
+    "dist/types.js": "8579202bf322e542969bbd9e5b98774963b12ac69bdf362eebfcb068de2d5421",
+    "dist/typescript-authoring.js": "156c617c2cbf992c299dbbbd5398500f0f30d1c90df8630509036da4ffd7cae9",
+    "dist/vercel.js": "a0da20c095d0c7fa8f579ed4dd5951e7a34191f8a72a57c5e782c9eab39f6f08",
+    "dist/verify-deployment.js": "cac5d10ea18ae5f699df0eb0a5229837297c7627b47e65140f053820cae2414d",
     "dist/scripts/operational-drills.js": "b7e9448279c59ee9de62023055a9ff5c7a60bcceed4c33d023edc612f5575af9"
   }
 }

package/dist/adapters.js

@@ -1,19 +1,12 @@
+                                                        
 import { createRuntime } from './runtime.js';
                                                                         
 import { validatePolicy } from './policy.js';
 import { ConfigError } from './errors.js';
-                                             
 
 /** The subset of process.env a hosted adapter reads. */
                                                              
-                                                                                                          
-
-// Handlers a stateless per-request invocation cannot honour. Functions and
-// middleware need worker threads and the WASM engine on every cold start;
-// stored links need a durable writable file that instances share. Adapters
-// refuse them identically, so a project's supported surface does not depend on
-// which provider is serving it.
-const unsupported                                     = { function:'isolated functions', link:'stored live links' };
+                                                                                                                                                                
 
 export function readPolicyFromEnvironment(environment             )                             {
   if (!environment.URLCODE_POLICY) return undefined;
@@ -27,20 +20,8 @@ export function readPolicyFromEnvironment(environment             )
 
 // Activates a project for a native-handler-only host, refusing the whole
 // deployment rather than letting individual routes fail at request time.
-export async function activateNativeOnly(project        , environment             , { target = 'node', plugins }                    = {})                   {
-  const runtime = await createRuntime(project, { permissions: readPolicyFromEnvironment(environment), environment, target, plugins });
-  const refused = runtime.testPlan().inventory.flatMap(route => {
-    const reason = route.handler === undefined ? undefined : unsupported[route.handler];
-    return [
-      ...(reason ? [`${route.path} uses ${reason}`] : []),
-      ...(route.middleware ? [`${route.path} declares middleware`] : []),
-    ];
-  });
-  if (refused.length) {
-    await runtime.close();
-    throw new ConfigError(`This adapter serves native handlers only: ${refused.join('; ')}`);
-  }
-  return runtime;
+export async function activateNativeOnly(project        , environment             , { target, plugins, extensions, origin }                   )                   {
+  return createRuntime(project, { permissions: readPolicyFromEnvironment(environment), environment, target, plugins, extensions, origin });
 }
 
 // Caches a successful activation for the life of the instance. A failure is not

package/dist/agent-lists.js

@@ -10,7 +10,7 @@ import { isListFile, isBundled, validatePattern } from './policies/agents.js';
 //
 // A list file is the schema data/agents/*.json uses: either an array of
 // entries or `{ entries: [...] }`, each entry `{ name?, pattern, ... }`.
-export const MAX_LIST_ENTRIES = 4096;
+const MAX_LIST_ENTRIES = 4096;
 
 function listPath(root        , reference        , routePattern        )         {
   assert(isListFile(reference) && !isAbsolute(reference), `${routePattern}: policies.agents list ${JSON.stringify(reference)} must be a project-relative path ending in .json`);

package/dist/agents-guide.js

@@ -0,0 +1,113 @@
+import { getCapabilities } from './capabilities.js';
+                                                        
+import { registry } from './policies.js';
+import { generatedPaths } from './site.js';
+import { assert } from './errors.js';
+
+/** Where the packaged agent skill lives, relative to the installed @jimhoyd/urlcode package. */
+export const skillPath = 'skills/urlcode/SKILL.md';
+/** The MCP registration file `urlcode init` writes beside the project (Claude Code and Codex read this shape). */
+export const mcpConfigFile = '.mcp.json';
+/**
+ * Renders `.mcp.json` registering the read-only `urlcode mcp` server for the project at `project`, relative
+ * to the file. `--allow-authoring` is deliberately absent: the operator adds it by hand when they want it.
+ */
+export function renderMcpConfig(project = '.')         {
+  assert(/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(project) && !project.split('/').includes('..'), 'MCP project path must be a relative path without ..');
+  return JSON.stringify({ mcpServers: { urlcode: { command: 'urlcode', args: ['mcp', '--project', project] } } }, null, 2) + '\n';
+}
+const handlerNames                            = ['redirect','respond','page','static','download','function','link','proxy','conditional','extension'];
+
+/**
+ * The application-level AGENTS.md written by `urlcode init`. Built from the
+ * installed runtime's capability catalog, so it names only the handlers,
+ * policies and site keys this version implements. Under 80 lines by design.
+ */
+export function renderAgentsGuide({ routes }                    )         {
+  assert(Number.isInteger(routes) && routes >= 0 && routes <= 100000, 'Route count must be a non-negative integer');
+  const catalog = getCapabilities('self-hosted');
+  const native = new Set(catalog.capabilities.filter(row => row.targets['self-hosted']?.support === 'native').map(row => row.capability));
+  const handlers = handlerNames.filter(name => native.has(name));
+  const policies = Object.keys(registry).filter(name => native.has(`policies.${name}`                  ));
+  const site = Object.entries(generatedPaths).map(([key, path]) => `\`${key}\` (${path})`);
+  return `# Working on this project
+
+This project uses URLCode: URL behavior is declared in \`urlcode.yaml\`, and the
+installed \`@jimhoyd/urlcode\` runtime serves it. There is no framework code to
+write for routing, validation, middleware wiring, policies, static serving or
+authentication; the runtime provides them. Read this file before changing anything.
+
+## Before writing code
+
+1. Inspect \`urlcode.yaml\` first, then every file its \`includes\` list names,
+   the referenced functions, middleware and \`tests/requests.json\`. Preserve the
+   existing organization and every route you were not asked to change.
+2. Run \`urlcode capabilities\` to see what this runtime version implements and
+   which targets support it; \`urlcode capabilities --target NAME\` before
+   promising any provider deployment.
+3. Run \`urlcode recipes list\` and \`urlcode recipes show NAME\` before writing a
+   route from scratch. If a recipe covers the need, add it with
+   \`urlcode recipes add NAME --out DIR\` and adapt the copy.
+4. Prefer YAML over code. Prefer native handlers over functions.
+
+## Ask the runtime through MCP first
+
+\`${mcpConfigFile}\` registers the read-only \`urlcode mcp\` server. When it is
+available, prefer its tools over reading documents: \`get_context\`,
+\`get_capability\`, \`get_schema\`, \`search_recipes\`, \`explain\`, \`get_manifest\`.
+The CLI equivalents are the fallback: \`urlcode context\`, \`urlcode capabilities NAME\`,
+\`urlcode schema PATH\`, \`urlcode recipes search TEXT\`, \`urlcode explain PATH\`,
+\`urlcode manifest\`. \`--allow-authoring\` is an operator opt-in; never add it yourself.
+
+## What the runtime provides (this version)
+
+- Handlers, exactly one per route: ${handlers.map(name => `\`${name}\``).join(', ')}.
+- Ordered \`middleware\` around any handler, declared in YAML, run in the sandbox.
+- Validated inputs: \`parameters\`, \`request.body\` and \`methods\` on the route;
+  functions receive validated \`args\`, never raw user input.
+- Policies, host-enforced and off by default: ${policies.map(name => `\`${name}\``).join(', ')}.
+- Site conventions under \`site\`, each generating one native route: ${site.join(', ')}.
+- Bindings: named \`env\` and \`secrets\` references resolved by the operator, never values in YAML.
+
+Never recreate any of these in a function. If a requirement seems to need one
+of them and it is missing, that is a report, not an invitation to reimplement.
+
+## Functions and middleware are sandboxed
+
+Guest code runs in an isolated JavaScript engine with a fresh heap per call.
+It sees a text/JSON \`Request\`/\`Response\` subset, validated \`args\` and granted
+\`env\`. There is no \`fetch\`, no Node API, no filesystem, no timers and no
+imports outside the project. Do not write code that needs them; declare a
+\`proxy\` route or a binding instead and say why.
+
+## Checks that count as evidence
+
+\`\`\`sh
+urlcode validate --local
+urlcode test
+urlcode audit --expect-routes ${routes}
+\`\`\`
+
+Run all three after every change. Update the expected route count deliberately
+when you add or remove a route, and add fixtures to \`tests/requests.json\` for
+every new route (positive and negative cases, every active method, HEAD).
+Without a global install, invoke \`node /path/to/urlcode/src/cli.ts\` instead of \`urlcode\`.
+
+## Rules
+
+- Report unsupported requirements instead of inventing fields. The schema is
+  exact; a field the validator rejects does not exist. Say what is missing.
+- Never create or approve operator grants. Request a named binding in YAML and
+  stop; the operator grants it outside this project, pinned to the revision.
+- Secrets stay out of the project: no keys, tokens or credentials in YAML,
+  functions, fixtures, \`.env\` files that are not ignored, or commit messages.
+- Authentication is host processing: declare \`auth\` on the route, never build
+  login forms, sessions or password checks in functions.
+- Validation, tests and the audit are the evidence. Local checks are not a
+  deployment, a soak test or a security review; do not claim otherwise.
+
+The installed package ships an agent skill with the same loop at
+\`${skillPath}\` inside \`@jimhoyd/urlcode\` (for example
+\`node_modules/@jimhoyd/urlcode/${skillPath}\`).
+`;
+}

package/dist/authoring-files.js

@@ -0,0 +1,60 @@
+import {lstat,realpath,open,mkdir,rm,rename} from 'node:fs/promises';
+import {resolve,join,dirname,basename,parse} from 'node:path';
+import {assert} from './errors.js';
+
+/** Authoring output never copies hidden state, package hooks, or credential files. */
+export function authoringPath(path        )         {
+  const parts=path.split('/');
+  assert(path.length>0 && path.length<=1024 && parts.length<=32 && parts.every(part=>
+    part && !part.startsWith('.') && !/[. ]$/.test(part) && !/^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part) && !/[\\:*?"<>|\u0000-\u001f\u007f]/u.test(part) &&
+    !/^(?:node_modules|package(?:-lock)?\.json|.*\.(?:pem|key|p12|pfx|env))$/i.test(part)), 'Authoring paths must be safe non-sensitive project-relative paths');
+  return path;
+}
+export async function authoringFile(root        ,path        ,directory=false)                  {
+  authoringPath(path);let file=root;
+  for(const [index,part] of path.split('/').entries()){
+    file=join(file,part);const info=await lstat(file);
+    assert(!info.isSymbolicLink(),'Authoring through symlinks is forbidden');
+    assert(index<path.split('/').length-1 || directory ? info.isDirectory() : info.isFile() && info.nlink===1,'Authoring requires ordinary files and directories');
+  }
+  return file;
+}
+export async function readAuthoringFile(root        ,path        ,limit        )                  {
+  const file=await authoringFile(root,path),handle=await open(file,'r');
+  try {
+    const info=await handle.stat();assert(info.isFile() && info.nlink===1 && info.size<=limit,'Authoring source size limit exceeded');
+    const bytes=Buffer.alloc(info.size+1);let offset=0;
+    while(offset<bytes.length){const read=await handle.read(bytes,offset,bytes.length-offset,null);if(!read.bytesRead)break;offset+=read.bytesRead;}
+    assert(offset<=info.size,'Authoring source changed during read');return bytes.subarray(0,offset);
+  }finally{await handle.close();}
+}
+/** Reserve a fresh directory exclusively, then publish the entry config last.
+ * Failed writes remove only the directory created by this invocation. No existing
+ * directory (even an empty one) is accepted; consumers see no activatable project
+ * until every dependency has been written. Callers must own the output parent.
+ */
+export async function publishAuthoringProject(output        ,files                                   ,dryRun=false)                  {
+  assert(files.has('urlcode.yaml'),'Authoring output requires urlcode.yaml');
+  assert(files.size<=10000,'Authoring file limit exceeded');
+  const paths=new Set        ();
+  for(const path of files.keys()){
+    authoringPath(path);const key=path.toLowerCase();assert(!paths.has(key),'Conflicting authoring output paths');paths.add(key);
+  }
+  for(const path of paths){let parent=dirname(path);while(parent!=='.'){assert(!paths.has(parent),'Authoring file/directory conflict');parent=dirname(parent);}}
+  const target=resolve(output),parent=dirname(target);assert(target!==parse(target).root,'Invalid authoring output');
+  assert(!(await lstat(parent)).isSymbolicLink(),'Authoring output parent must not be a symlink');
+  const destination=join(await realpath(parent),basename(target));
+  let exists=false;try{await lstat(destination);exists=true;}catch(error){if(!(error instanceof Error && 'code' in error && error.code==='ENOENT'))throw error;}
+  assert(!exists,'Authoring output already exists');
+  if(dryRun)return destination;
+  await mkdir(destination,{mode:0o700});
+  try {
+    const entries=[...files].sort(([a],[b])=>a==='urlcode.yaml'?1:b==='urlcode.yaml'?-1:a.localeCompare(b));
+    for(const [path,content] of entries){
+      const file=join(destination,path==='urlcode.yaml'?'.urlcode.yaml.pending':path);await mkdir(dirname(file),{recursive:true,mode:0o700});
+      const handle=await open(file,'wx',0o600);try{await handle.writeFile(content);await handle.sync();}finally{await handle.close();}
+      if(path==='urlcode.yaml')await rename(file,join(destination,'urlcode.yaml'));
+    }
+    return destination;
+  }catch(error){await rm(destination,{recursive:true,force:true});throw error;}
+}

package/dist/authoring.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { parseDocument } from 'yaml';
 import { loadDocument, validateDocument } from './config.js';
+import { renderAgentsGuide, renderMcpConfig, mcpConfigFile } from './agents-guide.js';
 import { compileRoutes } from './router.js';
 import { prepareFunctionSnapshot, requestedPermissions } from './policy.js';
 import { assert } from './errors.js';
@@ -17,9 +18,18 @@ export async function initProject(destination        )                  {
   try {
     const source = fileURLToPath(new URL('../starters/default/', import.meta.url));
     for (const file of await readdir(source)) {
-      if (file === '.gitignore') continue;
+      if (file === '.gitignore' || file === 'AGENTS.md' || file === mcpConfigFile) continue;
       await cp(join(source,file), join(target,file === 'gitignore.template' ? '.gitignore' : file), { recursive: true, force: false, errorOnExist: true });
     }
+    // AGENTS.md is generated from the installed runtime's capability catalog so
+    // it names only what this version implements; the starter carries a
+    // committed copy for clones, kept identical by test.
+    const routes = Object.keys((await loadDocument(target)).routes).length;
+    const guide = await open(join(target,'AGENTS.md'), 'wx', 0o644);
+    try { await guide.writeFile(renderAgentsGuide({ routes })); } finally { await guide.close(); }
+    // .mcp.json registers the read-only server for repository-aware agents; the starter carries the same bytes.
+    const mcp = await open(join(target,mcpConfigFile), 'wx', 0o644);
+    try { await mcp.writeFile(renderMcpConfig('.')); } finally { await mcp.close(); }
   } catch (error) { await rm(target, { recursive: true, force: true }); throw error; }
   return target;
 }

package/dist/aws.js

@@ -1,3 +1,4 @@
+                                                        
 import { randomUUID } from 'node:crypto';
 import { activateNativeOnly, lazyRuntime, resolveOrigin } from './adapters.js';
                                                  
@@ -6,7 +7,7 @@ import { prepareResponse, errorResponse } from './http-response.js';
                                                      
 import { assert, ConfigError, HttpError } from './errors.js';
 
-                                                                                                                                                                                                                 
+                                                                                                                                                                                                                                                           
 /** A Lambda payload format 2.0 event, as far as this adapter reads it. */
                               
                                                                                    
@@ -64,9 +65,9 @@ function requestBody(event             , limit        )         {
 // Builds a Lambda handler for payload format 2.0. The runtime is created once
 // per execution environment and reused across warm invocations.
 export function createLambdaHandler({ project = process.cwd(), origin, environment = process.env,
-  maxBodyBytes = 1048576, plugins }                       = {})                {
+  maxBodyBytes = 1048576, plugins, extensions }                       = {})                {
   assert(Number.isInteger(maxBodyBytes) && maxBodyBytes >= 1 && maxBodyBytes <= 16777216, 'Request limit must be 1–16777216 bytes');
-  const ready = lazyRuntime(() => activateNativeOnly(project, environment, { target: 'aws', plugins }));
+  const ready = lazyRuntime(() => activateNativeOnly(project, environment, { target: 'aws', plugins, extensions, origin:resolveOrigin(origin,environment,platformOrigins) }));
 
   return async function handler(raw) {
     const requestId = randomUUID();

package/dist/build-cloudflare.js

@@ -1,3 +1,4 @@
+import { analyzeProjectCapabilities, analyzeCompiledCapabilities, assertTargetCompatibility } from './capabilities.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import Ajv from 'ajv/dist/2020.js';
@@ -8,23 +9,12 @@ import { assert } from './errors.js';
 import { effectivePolicies, registry } from './policies.js';
 import { resolveLists } from './agent-lists.js';
 import { applySite } from './site.js';
+import { buildManifest, renderManifest, manifestPath } from './manifest.js';
                                                                                   
                                                                                      
 
                                                                                                                 
-                                                                                                                 
-
-// Handlers this target cannot serve, and why. Declarative routes only in this
-// slice: assets need a platform binding rather than an inline copy, and the
-// sandbox needs facilities the platform does not provide.
-const unsupported = {
-  function:'isolated functions need worker threads and the WASM engine',
-  link:'stored live links need a durable writable store',
-  page:'pages need a static-asset binding',
-  static:'static directories need a static-asset binding',
-  download:'downloads need a static-asset binding',
-}         ;
-const unsupportedHandlers = ['function','link','page','static','download']                                                         ;
+                                                                                                                                   
 
 // The artifact is this runtime's build output, not a published contract: the
 // format may change with any release, and the runtime refuses a version it does
@@ -80,24 +70,21 @@ export async function buildCloudflare(project        , { out = 'dist/cloudflare'
   // Generated site routes are built like declared ones; the ones that need
   // an origin get it from --origin, exactly as the server does.
   await applySite(loaded, { origin, log });
+  assertTargetCompatibility(analyzeProjectCapabilities(loaded, 'cloudflare'));
   // No bindings are resolved: a build artifact must never carry a secret, and
   // this target has no per-request operator policy to pin one to.
   const compiled = await compileRoutes(loaded, {}, {}, undefined);
   const routes = [...compiled.exact.values(), ...[...compiled.byLength.values()].flat(), ...compiled.mounts];
 
-  const refused           = [];
+  assertTargetCompatibility(analyzeCompiledCapabilities(loaded.document, compiled, 'cloudflare'));
   for (const route of routes) {
-    for (const handler of unsupportedHandlers) {
-      if (route[handler]) refused.push(`${route.pattern}: ${unsupported[handler]}`);
-    }
-    if (route.middleware?.length) refused.push(`${route.pattern}: middleware needs the sandbox`);
     const policies                    = effectivePolicies(loaded.document, route);
     for (const name of Object.keys(policies)) {
       assert(isPolicyName(name), `Unknown policy "${name}"`);
       const support = policyModule(name).targets(policies[name]).cloudflare;
       // The platform provides it: accepted and dropped, never carried.
       if (support === 'delegated') { delete policies[name]; continue; }
-      if (!compilablePolicies.has(name) || support !== 'compiled') refused.push(`${route.pattern}: policies.${name} cannot be compiled for this target`);
+      assert(compilablePolicies.has(name) && support === 'compiled', `${route.pattern}: policies.${name} cannot be compiled for this target`);
     }
     // Project-relative agent lists are read here, once, so the artifact
     // carries the patterns and the Worker never needs a filesystem.
@@ -109,11 +96,7 @@ export async function buildCloudflare(project        , { out = 'dist/cloudflare'
     // evaluates a configuration the runtime would have rejected.
     for (const name of Object.keys(policies)) if (isPolicyName(name) && compilablePolicies.has(name)) await policyModule(name).compile(policies[name], { route, shared: {}, target: 'cloudflare', document: loaded.document, root: loaded.root });
     if (Object.keys(policies).length) route.compiledPolicies = policies; else delete route.compiledPolicies;
-    if (Object.keys(route.env).length || Object.keys(route.secrets).length) {
-      refused.push(`${route.pattern}: env and secret bindings would have to be baked into the artifact`);
-    }
   }
-  assert(!refused.length, `This target serves declarative routes only:\n  ${refused.join('\n  ')}`);
   assert(routes.length, 'No routes to build');
 
   const ajv = new Ajv.default({ code:{ source:true, esm:true }, strict:false, allErrors:false });
@@ -159,6 +142,10 @@ import * as validators from './validators.js';
 
 export default { fetch: createFetchHandler(artifact, validators) };
 `);
+  // The semantic manifest travels with the artifact so a reviewer can read
+  // what was built without the project checkout (docs/TOOLING.md).
+  const manifest = manifestPath(out);
+  await writeFile(manifest, renderManifest(await buildManifest(project, origin === undefined ? {} : { origin })));
   return { out, format:FORMAT, version:loaded.version, routes:serialised.length,
-    validators:Object.keys(validators).length };
+    validators:Object.keys(validators).length, manifest };
 }

package/dist/bulk.js

@@ -0,0 +1,37 @@
+import {createHash} from 'node:crypto';
+import {stringify} from 'yaml';
+import {importRoutes} from './interchange.js';
+                                                           
+import {publishAuthoringProject} from './authoring-files.js';
+import {assert} from './errors.js';
+
+                                           
+                                                                                                    
+                                   
+                                                                                                     
+                                                                                 
+ 
+/** Import ordinary redirect rows into small, portable include files. There is no
+ * merge mode: duplicate rules and existing output directories are refused. */
+export async function importBulkProject(text        ,format            ,output        ,{dryRun=false,source='<input>'}                                                        ={})                            {
+  assert(['csv','json','yaml'].includes(format),'Bulk input must be csv, json or yaml');
+  assert(source.length<=1024 && !/[\u0000-\u001f\u007f]/u.test(source),'Invalid bulk provenance source name');
+  const provenance={name:source,format,sha256:createHash('sha256').update(text).digest('hex')};
+  const converted=await importRoutes({text,format,source});
+  const report                  ={ok:converted.ok,dryRun,routeCount:converted.routeCount,diagnostics:converted.diagnostics,files:[],source:provenance};
+  if(!converted.ok || !converted.document)return report;
+  const files=new Map               (),entries=Object.entries(converted.document.routes),includes          =[];
+  // 100 includes at the 100,000-route cap; each parser AST stays small without
+  // changing the configuration worker heap, wall deadline or include limits.
+  for(let offset=0;offset<entries.length;offset+=1000){
+    const group=entries.slice(offset,offset+1000),path=`routes/redirects-${String(includes.length+1).padStart(3,'0')}.yaml`;
+    includes.push(path);files.set(path,stringify({version:'1',routes:Object.fromEntries(group)}));
+    report.files.push({path,routeCount:group.length,firstPath:group[0] [0],lastPath:group.at(-1) [0]});
+  }
+  files.set('urlcode.yaml',stringify({version:'1',...(includes.length?{includes}:{}),routes:{}}));
+  report.files.unshift({path:'urlcode.yaml',routeCount:0});
+  const metadata={version:1,source:provenance,routeCount:report.routeCount,files:report.files};
+  files.set('provenance.json',JSON.stringify(metadata,null,2)+'\n');report.files.push({path:'provenance.json',routeCount:0});
+  report.output=await publishAuthoringProject(output,files,dryRun);
+  return report;
+}