@jimhoyd/urlcode 0.4.1 → 0.4.6

package/.claude/skills/urlcode-authoring/SKILL.md

@@ -18,7 +18,9 @@ is to author only what the pinned revision implements and then prove it.
 Check the installed version's primitives, YAML configuration, policies, supported
 extensions and recipes/templates before writing a custom function or middleware.
 Keep necessary custom code focused and report the capability gap; never invent
-fields or bypass target limits or operator grants. See `docs/PROJECT-DIRECTION.md` in the installed runtime.
+fields or bypass target limits or operator grants. In a source checkout, see
+`docs/PROJECT-DIRECTION.md`; in an npm installation, search the matching heading
+in `llms-full.txt`.
 
 ## Read the contract before writing YAML
 
@@ -26,12 +28,25 @@ Documentation, schema and runtime must come from the **same revision**. Read fro
 the project's installed runtime (`node_modules/@jimhoyd/urlcode/`) or the
 checkout you are working in — never from memory of another version.
 
-Start with `urlcode context --project <dir> --budget 4000`, then retrieve the
-capability, schema fragment, recipe or example relevant to the change. Use the
-read-only MCP equivalents when available. `llms.txt` is the index; read the
-matching task guide from `docs/` when a query needs more explanation.
-`docs/SPECIFICATION.md` and `schemas/urlcode.schema.json` resolve contract
-questions. Archived plans are historical, not valid YAML guidance.
+Make one bounded query first: MCP `get_context` when the `urlcode` server is
+registered, otherwise `urlcode context --project <dir>` (add `--budget 4000`
+when the project is large). It is a compact summary, constraints and exact
+commands, not a schema dump. Then retrieve only what the change needs:
+`urlcode capabilities NAME` (`get_capability`, for its limits), `get_schema`,
+`recipes search TEXT` (`search_recipes`), `explain` and, when the operator
+supplies a host file, `get_extensions`. Bare `urlcode capabilities`, `recipes
+list`, the compact `llms.txt` index and `llms-full.txt` remain deliberate
+fallback/reference: in a source checkout read the matching task guide from
+`docs/`; in an npm installation search the heading in `llms-full.txt`.
+When the project has an operator host file, inspect `urlcode extensions
+--project <dir> --host-file <absolute-file> --json` (MCP: `get_extensions`)
+before writing extension configuration or project hooks. The report is the
+machine-readable source for config/policy schemas, hook contracts, supported
+project-owned authoring surfaces and fast checks.
+The `SPECIFICATION` section of `llms-full.txt` and
+`schemas/urlcode.schema.json` resolve contract questions in an installed
+package. A source checkout also has `docs/SPECIFICATION.md`. Archived plans are
+historical, not valid YAML guidance.
 
 ## Workflow
 
@@ -49,6 +64,24 @@ questions. Archived plans are historical, not valid YAML guidance.
 - Create every referenced module, page and asset **before** validating. All
   source paths resolve from the project root. Trusted modules can import Node built-ins and npm packages;
   only `sandbox: true` modules are restricted to the relative snapshotted graph.
+- Treat core, installed extensions and product UI as one application with
+  different owners. Follow an extension's published `authoring` surfaces in
+  this order: configuration; theme and copy; component or template override;
+  project CSS; declared trusted hook. Keep auth/admin security and workflow
+  behavior in their packages and keep only the product-specific difference in
+  the project. Build a new extension only for a reusable capability the
+  installed contracts cannot express. Extension hooks run trusted in-process
+  and reject `sandbox: true` in contract v1.
+- When a React frontend has `components.json`, follow the installed official
+  shadcn/ui skill for component discovery, composition, accessibility and
+  semantic Tailwind styling. Start with `shadcn info --json`, then use its
+  `shadcn docs`/`search` flow or configured MCP registry before generating a
+  component. Do not put React components in URLCode's server template renderer
+  merely because it uses shadcn-compatible tokens.
+- Run the extension's published `fastChecks` while iterating, then the full
+  project checks before handoff. Theme and copy changes should not rebuild the
+  framework packages. Full workspace/package checks may take several minutes;
+  give them enough time to finish instead of repeatedly rebuilding.
 - Write exact response fixtures for success and failure, covering every active
   method, middleware behavior, HEAD, and any range or cache semantics.
 - Follow `docs/BEST-PRACTICES.md` for layout and readability as the project grows.
@@ -108,6 +141,26 @@ runtime checkout, substitute `node src/cli.ts` for `urlcode`; in a project made
 from `urlcode-template`, the equivalent npm scripts work. External bindings
 require an already reviewed policy — add `--policy` where needed.
 
+## Feedback after a real attempt
+
+After a task, give feedback only when a real attempt exposed one of these:
+
+- a **capability gap**: a requirement the current contract cannot express;
+- a **repeated-workaround**: custom code recreating framework plumbing likely
+  to recur across applications;
+- a **documentation/discovery gap**: the supported path was hard to find or
+  distinguish from an unsupported one; or
+- a **suspected defect**: observed behavior contradicts the installed contract
+  or its fixture.
+
+Produce a compact draft, not an issue: category, installed runtime/target,
+sanitized route or YAML fragment, the exact validation/test observation, the
+smallest expected behavior, and a proposed fixture. Do not include secrets,
+customer URLs, raw source, or one-off product logic. Search existing URLCode
+issues first and name a likely duplicate when found. You may propose a new
+issue or comment, but never create or update a GitHub issue without the user's
+explicit approval.
+
 ## Boundaries
 
 - Keep secrets out of source, examples and Git. Request named bindings, but

package/.claude/skills/urlcode-operations/SKILL.md

@@ -18,6 +18,10 @@ another version.
 
 ## Read before advising
 
+In a source checkout, use the `docs/` paths below. In an npm installation,
+search the same document headings in `llms-full.txt`; the archive deliberately
+does not duplicate the repository's authored documentation tree.
+
 1. `docs/OPERATIONS.md` — process and container deployment, shutdown, exposure.
 2. `docs/DEPLOYMENT-CHECKS.md` — `verify-deployment`: what it checks against a
    live target and what it deliberately does not.

package/README.md

@@ -53,19 +53,22 @@ application by adding YAML; the operator wires trusted packages in one host
 file outside the project. The full map, the composition contract and the rules
 an AI agent must follow are in [the framework](docs/FRAMEWORK.md).
 
-| Package | Adds | Status |
+| Package | Adds | Stable npm channel |
 |---|---|---|
-| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, provider adapters, extension contract | `0.4.1` stable release target, Apache-2.0 |
-| [urlcode-ui](packages/ui) (in this repository) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.4.1` stable release target; review pending |
-| [urlcode-auth](packages/auth) (in this repository) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.4.1` stable release target; review pending |
-| [urlcode-admin](packages/admin) (in this repository) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.4.1` stable release target; review pending |
-
-This release aligns all four packages at `0.4.1`, with publication to npm's
-`latest` channel in the order core → ui → auth → admin. The table describes
-the release target; confirm publication with `npm run release:status` before
-installing it. Matching numbers do not establish a permanent fixed-version
-policy. Peer ranges, channel rules and generated application pins are documented
-in [package and channel alignment](docs/VERSION-ALIGNMENT.md).
+| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, provider adapters, extension contract | [![npm stable version](https://img.shields.io/npm/v/%40jimhoyd%2Furlcode?label=stable)](https://www.npmjs.com/package/@jimhoyd/urlcode) |
+| [urlcode-ui](packages/ui) (in this repository) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | [![npm stable version](https://img.shields.io/npm/v/%40jimhoyd%2Furlcode-ui?label=stable)](https://www.npmjs.com/package/@jimhoyd/urlcode-ui) |
+| [urlcode-auth](packages/auth) (in this repository) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | [![npm stable version](https://img.shields.io/npm/v/%40jimhoyd%2Furlcode-auth?label=stable)](https://www.npmjs.com/package/@jimhoyd/urlcode-auth) |
+| [urlcode-admin](packages/admin) (in this repository) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | [![npm stable version](https://img.shields.io/npm/v/%40jimhoyd%2Furlcode-admin?label=stable)](https://www.npmjs.com/package/@jimhoyd/urlcode-admin) |
+
+The badges report each package's live npm `latest` channel, which is the stable
+version of that package. Stability is independent: matching version numbers are
+not required. Releases created by the current [GitHub release
+publisher](https://github.com/jimhoyd-com/urlcode/releases) show the exact
+four-package combination tested together, its declared peer
+requirements and a copyable exact-version install command; the signed
+`train.json` asset is the machine-readable receipt. Peer ranges, channel rules
+and generated application pins are documented in [package and channel
+alignment](docs/VERSION-ALIGNMENT.md).
 
 `urlcode-dynamic-link` and `urlcode-short` were published once as
 `0.1.0-alpha.1` and have since been retired: both were unpublished from npm and
@@ -106,7 +109,8 @@ it. Cross-repository acceptance is tracked in
 
 ## Status
 
-The `0.4.1` release line brings core, UI, auth and admin to matching stable
+<!-- urlcode-current-version:start -->
+The `0.4.6` release line brings core, UI, auth and admin to matching stable
 versions. A stable version selects the npm `latest` channel; it does not close
 the review and deployment evidence gaps below. `0.4.0-alpha.1`
 added the extension contract, capabilities and provider conformance, strict
@@ -118,6 +122,7 @@ opt-in, and removed the native `link:`/`dynamicLinks:` YAML shape. That is a
 behaviour change for existing projects with no YAML edit; read
 [the roadmap entry](ROADMAP.md) before upgrading. Use the schema and docs from
 the runtime revision you run.
+<!-- urlcode-current-version:end -->
 The [roadmap](ROADMAP.md) separates implemented from planned, and
 [release readiness](docs/RELEASE-READINESS.md) records what is proven and
 what is not: provider deployments, soak and independent security review
@@ -178,8 +183,7 @@ SQLite build requirement, unverified from this repository.
 ## Try it
 
 ```sh
-# After the 0.4.1 release has been published:
-npm install --global @jimhoyd/urlcode@0.4.1
+npm install --global @jimhoyd/urlcode@latest
 urlcode init my-urls && cd my-urls
 urlcode dev
 ```

package/SECURITY.md

@@ -57,6 +57,8 @@ confirmed issues use private coordination and a public advisory when appropriate
 Bind loopback by default; protect public deployments with HTTPS, rate limits,
 network controls and restricted operational endpoints. See [operations](docs/OPERATIONS.md).
 
-See the [internal security reviews](docs/SECURITY-AUDIT.md) — most recently
-2026-09-17 — for fixed findings and remaining gates. Use a current reviewed commit: the shared 0.3.0
-version label alone does not identify which hardening patches are present.
+Use a current reviewed commit: the shared 0.3.0 version label alone does not
+identify which hardening patches are present. Internal source-review details are
+maintainer material, not an independent assessment; the public security model,
+reporting path and outstanding assessment gate are the authoritative claims on
+this page and in [the sandbox review](docs/SANDBOX-REVIEW.md).

package/dist/BUILD-MANIFEST.json

@@ -2,19 +2,21 @@
   "node": "v26.9.0",
   "files": {
     "dist/adapters.js": "a7153ec52f2ed7e0cdd8ed7d433504815f402ec53b2b1c3d38d0cf0e2fcf6509",
+    "dist/agent-context.js": "1e4e9c7b85d155c06d99d8b70f625bd7ab31330a0207aef6ed1803243b759611",
     "dist/agent-lists.js": "35ab484198897501d011cb6cc00b5a6787192e19df29c97646e8c118fcc19eef",
-    "dist/agents-guide.js": "0b19909aee3f8a1039c34c43ff58116ec1bc3f1875e3dbc34b3b01655273201c",
+    "dist/agents-guide.js": "14684bf514cabbe7c9bb1ad6b6b2c479f8aaf3feb299b64655fd9fba218268d6",
     "dist/assets.js": "0833b093d2fe457ce68281110dc07d47914992753607741c13b339d92c76cf5c",
     "dist/authoring-files.js": "ad32814f9ae9c549c6247396f982aa700d13a293cc0a589609eccc68f8965550",
-    "dist/authoring.js": "5fe1e871ff216ef1f7d2f490f74397b81b1de4edfe31cdb6115907296aa1c652",
+    "dist/authoring.js": "bb3d4e7c6c982c4a1985a7663f960d05a08459d935e2609d404f4001b7ea767f",
     "dist/aws.js": "7d8e3a97b4f6dbefbd68da058f05192469d1efcaed5458b284863ebe462e060e",
-    "dist/build-cloudflare.js": "af4f49ad45287d7c4105bb84b1592b5b8e76c930f7159505338298f7c5fd5651",
+    "dist/body-schema.js": "0227ef8cf2b380e3ef65a358533aa0e0f4a119c94e63747b8eb03fe65a6b9193",
+    "dist/build-cloudflare.js": "e552dbf3c08036f02b0e5eb4bfd1309229bbba41d021ac15051e3f6fb165d8b4",
     "dist/build-static.js": "fe01ef4fcc66d83d8be7a787538b55974e84fd3d7c89e26f0a2f1a152762d565",
     "dist/bulk.js": "aac88d422bd9a7a341a421fb4e29ff5580b28d39250b7f1f5315ba20ae92da8a",
-    "dist/capabilities.js": "28dba05b3851b8b12b3c1b809af87b732f84d601c737afe9225abe429886e691",
+    "dist/capabilities.js": "bb98f5bbf54cc4e82fa197f999a621ad815273176f02692c35566886e2bb8777",
     "dist/capability-query.js": "9f68bc94901451d7b9ecdd3aee8c3376dca7f0b890e31d8205306cf8120dea86",
     "dist/catalog.js": "c378ef9bfd63b940790f6975f7db54557c2459722b65a7c170b97df24184bc52",
-    "dist/cli.js": "45b8adaae66a46e7b05067f1ced488b9dd7ccff8d15ba71e858459d76f5ddbb8",
+    "dist/cli.js": "c155fc50b1750dd0eda78ec3860f8855f6726e563d6d28632a6e54891e09b768",
     "dist/client-address.js": "9d0d01466aab23124330605c5a0e0f981f87c897858acfad909f546a63df165b",
     "dist/cloudflare.js": "17b43b0a6b6a0ef8a893415c989e4ae3976d97cc966adbf897b785f9adc472e3",
     "dist/compliance-rules/baseline.js": "6296dea6bcb9f9bb80ed6ed5ab2f456e7f74e6de2be5d2d98ca8c983fb4df3ab",
@@ -24,63 +26,64 @@
     "dist/compliance.js": "29a18da3cefea94802ac7d817d1ab4e3674abd5c3ac4ef893cb8b01c6a23fb61",
     "dist/conditions.js": "ff25e97da550a3bdd80af55522045669438aa31a77d2bc83ad602bcefdee0475",
     "dist/config-worker.js": "bc2170d60c35f8d5de227cbfc4c5067dc61d7cbc5b98aed88e68a11797072da5",
-    "dist/config.js": "8a0fde242b4658c522031a15d89daed25f8b77761f5c4204f295d5e311ac8ff7",
-    "dist/context.js": "549a53e4738b9c20a1ec55614027f758026fb5860bf4ac962ce22d7029e48df0",
+    "dist/config.js": "33c8d1f80aa7f1ce25eab12644f6cbef961a897b72b1585d4bfa6424985f0d16",
+    "dist/context.js": "f0de473b1e13649b0778fe2d5e7a65d4d6ac82614b47a1f86b453b73a85cb166",
     "dist/ecosystem-cli.js": "1e71bacd53d6fa8c7857cfcce3c3012ce054771a434b78d1f39e892e32642edd",
     "dist/egress.js": "2ae29fe2cb4590fd2f715abe6817db47fed2f50dd31f37946ecf42eafbb0dd9e",
-    "dist/errors.js": "a908e66496afebbdd632a8c159a6e14d23f8f38798a0b4342ca122f2511c6cde",
-    "dist/examples.js": "89ae2b764a688fe52acfb9b94d3d262d7742401ebd0ef10c9ebfc76edfa5631c",
+    "dist/errors.js": "fef26eb834dd61b8b5f587eb7ab265d216122d182545f0a1c5b19c20840dffb0",
+    "dist/examples.js": "8523799797d2530fe48ec5e96c34970bdba03c49afb31fdaab6a9c162a17dfa9",
     "dist/explain-cli.js": "f0f8f3b5046430d03c6abb629b38651c9c734b03456040735ce9d7e582b2bcd5",
     "dist/explain.js": "7fb632036cc68280701dd512c74d27d6e0f97b4848e9024b284d7c5393b35eb5",
-    "dist/extensions.js": "0506ec6289fa0582399d8c6d27727ffeb629bd442264248c921c63cc5b46ff01",
+    "dist/extensions.js": "966441cca677b0d88683d29d89d36c61cf487ae2b70d94eaa0c71c50730a4212",
     "dist/function-sources.js": "16fad4abc81c7ee07b6cbcef2d23a9fc50e97a17cb4dde1db53469bbb555c96f",
     "dist/function-worker.js": "35771790ada4e1b36d447d4967a5e6cf0b543f32944e4c904f5fbf8998e824a5",
     "dist/functions.js": "0f09d1bd27eb655ceb5900a4a5e2b760d2028b02cb637a6a89a4eb5940828008",
     "dist/guest-api.js": "49aec9ed72733ad119e63bcfcee18158dcc8ceb951e1823b8947f6407ff24afc",
     "dist/header-validation.js": "465181dbb08ff05f52defdd29fda025c0c64589bf319fa87fa6d3ab4b68216d5",
-    "dist/http-policy.js": "4cb187642269078ddf3460a3f1813dc57878a616a6f8132ef8f8d3b4b91ebb56",
-    "dist/http-response.js": "62f5da2e08bfe7ecff07464a49aaf910aa55770308a59118be9372390c2df9a1",
+    "dist/http-policy.js": "393a6383bdf9e05597c98721b3a4c4207a9bbe359883babcbfa06b696c70f56c",
+    "dist/http-response.js": "565826d1ece4bd30dfc1150c75800acec1fef584f732e964409aa92958fc8550",
     "dist/index.js": "8d7532ae0a31f9439ebb62e7b01a2748aee00f350262ff55d1226121d206c1ed",
-    "dist/init-with.js": "bf43b3aa4b421e9a31c5227e6afdf4956aba70d836ffddde96176a772d79e09b",
+    "dist/init-with.js": "0d2dccb83f0ad53181c6f5c95a4c663ce06ee9a1fa9074facac9a1aee7599a96",
     "dist/interchange-cli.js": "35bd70ba8077af5c3e39404ff0e5d28707632090a59a90645141252449fd3f04",
     "dist/interchange.js": "26789420af33344d9a08c00fe6b2708aa71994224df527b3075295be2151611e",
     "dist/logging.js": "8ec57fea26983aa071b05fe15d680d6550b03488101163ed9666da674118cf31",
     "dist/manifest.js": "83eed0d59621039ef364cf6e7b54c5bd47e0d8cf0a5abe7b07344bfc1db56ed8",
     "dist/match.js": "53ebcc2cda529a8d07fb83f8cb69a1446036ffc1641af3c4bd45a55851bded28",
     "dist/mcp-authoring.js": "1183a56c5decb99ecb67a5da7bd91d1b494bc17a2965051aa63c4a7e291462b5",
-    "dist/mcp.js": "484c03cdf81f94116ec973feb70754298f8b1d5b3b42561969f8cce26b3c97c2",
+    "dist/mcp.js": "28e6b98a394ae330d4310abc89e0e5a5210d2b892c9ecb3ac97345e765e584f8",
     "dist/observability.js": "f4b1ab496f051fe3ef2ed36b2b2e469c63a8940700e2df852e6ff2d9cccdd5ae",
     "dist/operator-host.js": "e3dac9d43a83beb775202b4ab9eeeba7ac63cebfc5dcc669be38d825be587bd0",
+    "dist/pattern-guard.js": "6f157ced99666a89ca5af1418f5a14568d850985042dea309bf9ec0c19dbaca5",
     "dist/plugins.js": "a61aa933cd9e1b41020b86fae78aa3a7f45f5313124aa11b50cb57898722385e",
     "dist/policies/agents.js": "c1dbc1e90339f472eeeb2372f7f4637f59a5d210797ea680ac8120a02aa20c10",
     "dist/policies/cache.js": "d08184e50b0ecb7331b29e4145aaefacb23b64ddaf3555d579743762f90c1629",
     "dist/policies/compression.js": "800f3ae3b1a4c1fe58c3d9908364ea9d78f655ff50c7f7589f584378e7f194b0",
-    "dist/policies/security.js": "2b3bfdf82140156fea4b162adc28ee43ccd85c402fb200680dbb8d8706417420",
+    "dist/policies/security.js": "c68d39f5fa2d7d16f5bfb3dcff2ac71428cc41814970eecf8b931debd40c0f3e",
     "dist/policies/throttle.js": "bbb0cb1c24cf70d0a1ac32fc0618efb6c44e5b5d42564842f9c585ff7e501603",
     "dist/policies.js": "3750a7032ec7326aa544f4808683ad9eb91d4f2c5afe79904420cd8a355710a9",
-    "dist/policy.js": "33c527008fafe4af18243ba668d069517c20659150f9f1d1a5a1d076e8724f89",
+    "dist/policy.js": "2da95b3f1f77249b1e9f399a06b88909b68594fdbc958176075e91ff23104a7c",
     "dist/prerender.js": "6210999e848ab86c87f265943960ef63716896da7a40e248221a6a30425c56b8",
     "dist/project-dependencies.js": "b43a8f3125f62d38f0e71237b7813a785ef0613a83fcdec3fa8314f33758a534",
-    "dist/project-tests.js": "445eaa139d2f1a2534369cfdeef081ef518de03218a467e7c5c2059caf840270",
+    "dist/project-tests.js": "63562978411ee94a69dcf45d4d47e84fba009d8654ac421c2a02a418cd80b4db",
     "dist/provider-verification.js": "ffcf9f05e8cb5f71ea46a97e279e8a613fdfdf9435ab02bd57af11e2680a9107",
     "dist/proxy.js": "34107e59ac0dbbea090efa3cf5badf3226c5302ba25e8f8ff9b2b5596ed80e50",
-    "dist/readiness.js": "90b54bc0cf60dd155d05789a1aad767bd67483d5fa6064ae8b1143f8cf9e06b2",
-    "dist/recipes.js": "11853f23e63c3c65c5bed03a278cde0349d28c9fa23266c9907a2df318bb5fc3",
+    "dist/readiness.js": "2b67bc86c0c73528f3f798b6a0ee1bd5aec5ac6f4a0998c45443c903a622af4f",
+    "dist/recipes.js": "7af62ea9f612c82ea21e97e9d14451f05e0b509d6e420fb99fec96b22e3533f1",
     "dist/route-diff.js": "8d71d50d332ffaaed588656bd32aa36763260d1ad87bb62d7ea1c8fb23383969",
-    "dist/router.js": "cf831025d5ed6778d1d6a0e541177799794e76766c82084ded81d3e87317ca1e",
-    "dist/runtime.js": "2346d4630d178ee52caa7a94d4289f9b16f4b8ee467070b39fdd05742ed4513f",
+    "dist/router.js": "b2b26409321c5d119ac54793efe6bb6a2f9bbf2f36db251c68337c25b9d836b9",
+    "dist/runtime.js": "e36153ab250b566ea778584a447ce603cf283274d9f8ac54a22aa9969c2284e8",
     "dist/sandbox.js": "c88c5aa5dd95b4f55f1ba62da7969ad66dbd97c30f72e5b5f2817a2098ac1c65",
-    "dist/scaffold.js": "3ef243aceca7ddf2780aa2c8c04ae17edd07682d3a418fd5d65ba00f5c762f14",
+    "dist/scaffold.js": "0f936cabd20b609c7ebfebd7895710ce6c30882c3088a2356ac75bb4e0d10c55",
     "dist/schema-query.js": "bfd1844acd8d54ac361115191fcfbaf828a67e223b9ec6e9c22f158761af149b",
-    "dist/server.js": "d878bc8f0d6a05f8fd25997cace3150e2ff4d44ee9c8f4b5530e29601e164be1",
+    "dist/server.js": "165b66fc4ed3b8e7c46ae4402ef66a5bc988c0910fb3e11556b040781e09d03c",
     "dist/signals.js": "b55e54efc8fb6703e08f2a1e808ec8e011bda67738db8ceadf1b248f695795be",
-    "dist/site.js": "c40a06a6f9e2d6d3bea94727783c115fed4309bb0190787f58434eed64cbde84",
-    "dist/tooling.js": "7409db98422325cd4181d073d645ea57debca0e54cb151123474b85f4d4ed7dc",
+    "dist/site.js": "38176ac4d1970ebf73e3f96094f39900724ce96b29d6de892b8baae01e183aa5",
+    "dist/tooling.js": "3d2848aba0a374ef980328c6924d4b314c53094efc2cc94638f1a58b726f8161",
     "dist/trusted-functions.js": "f3800c75f45ce90faf85ba6664398ad9031c5a9ac51d5ce42bdcff08a497d48e",
-    "dist/types.js": "2fe7664dbb5695ec72114197abde72de4031df9c3b211740eacefa68e9b21844",
-    "dist/typescript-authoring.js": "2e98498a15bdbb76f36fbee84afb7c42ca95bbf80a2e6dd4040147f3b1642a29",
+    "dist/types.js": "827f1afde90d19715e79500515ecaa80f5b65ce552f0ef24d2fc561ef77e6e40",
+    "dist/typescript-authoring.js": "df3d9c82e6b545cae5caae04c443ed4d2feae96def5e5cde250c0a90d83ae98c",
     "dist/vercel.js": "a0da20c095d0c7fa8f579ed4dd5951e7a34191f8a72a57c5e782c9eab39f6f08",
-    "dist/verify-deployment.js": "0c2e68f3cf258a364728c801411df5284343bc01b75a64fe275ff84e397e998b",
+    "dist/verify-deployment.js": "2d3b6301b70684abfccea669f7901afda7fae9d9d66902809ecdef65f22aea16",
     "dist/scripts/operational-drills.js": "c26c406d28013cc554b25a5b6bf8baf4e71d5e67e50d866fae546f538a192317"
   }
 }

package/dist/agent-context.js

@@ -0,0 +1,82 @@
+import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {parseYaml,validateDocument} from './config.js';
+import {listExamples} from './examples.js';
+
+/**
+ * Fixed, package-owned agent material. This is intentionally a manifest rather
+ * than an arbitrary file reader: MCP clients cannot use it to enumerate or
+ * exfiltrate a local project.
+ */
+const packageRoot=fileURLToPath(new URL('../',import.meta.url));
+const docs=[
+  {id:'llms',title:'URLCode agent index',file:'llms.txt',summary:'Compact map of the framework, its declarative primitives and the minimum reference to load next.'},
+  {id:'authoring',title:'AI authoring',file:'docs/AI-AUTHORING.md',summary:'Declarative-first authoring workflow, retrieval order and framework constraints.'},
+  {id:'yaml-reference',title:'YAML reference',file:'docs/YAML-REFERENCE.md',summary:'Generated inventory of accepted URLCode YAML fields.'},
+  {id:'tooling',title:'Tooling and local MCP',file:'docs/TOOLING.md',summary:'Bounded local project inspection, validation and MCP tool behavior.'},
+  {id:'security',title:'Function security',file:'docs/FUNCTION-SECURITY.md',summary:'Trusted versus sandboxed function behavior, bindings and operator grants.'},
+]         ;
+const skills=[
+  {name:'urlcode',description:'Author URLCode projects declaratively, retrieve only the required contract, and validate the result.',file:'skills/urlcode/SKILL.md'},
+]         ;
+const maxExcerpt=1800;
+
+function terms(query       )          {return [...new Set(query.toLowerCase().split(/[^a-z0-9]+/).filter(term=>term.length>1))].slice(0,16);}
+function excerpt(text       , query       )        {
+  const words=terms(query),lower=text.toLowerCase();
+  const positions=words.map(word=>lower.indexOf(word)).filter(position=>position>=0);
+  const start=Math.max(0,(positions.length?Math.min(...positions):0)-300);
+  return text.slice(start,start+maxExcerpt);
+}
+async function content(file       )                 {return readFile(packageRoot+file,'utf8');}
+
+export function listSkills() {return skills.map(({name,description})=>({name,description}));}
+export async function getSkill(name       ) {
+  const skill=skills.find(candidate=>candidate.name===name);
+  if(!skill)throw new Error('Unknown bundled skill');
+  return {name:skill.name,description:skill.description,content:await content(skill.file)};
+}
+
+/** Deterministic lexical search over a deliberately small, agent-facing corpus. */
+export async function searchDocs(query       ) {
+  const words=terms(query);
+  if(!words.length)throw new Error('Search text must contain a word');
+  const hits=(await Promise.all(docs.map(async doc=>{
+    const text=await content(doc.file),haystack=`${doc.title} ${doc.summary} ${text}`.toLowerCase();
+    const matched=words.filter(word=>haystack.includes(word));
+    return {doc,text,matched,score:matched.length};
+  }))).filter(hit=>hit.score>0).sort((a,b)=>b.score-a.score||a.doc.id.localeCompare(b.doc.id)).slice(0,3);
+  return {query,results:hits.map(({doc,text,matched})=>({id:doc.id,title:doc.title,summary:doc.summary,matched,excerpt:excerpt(text,query)}))};
+}
+
+/** Returns the two smallest high-value files of a fixed packaged example. */
+export async function getExample(name       ) {
+  const example=(await listExamples()).find(candidate=>candidate.name===name);
+  if(!example)throw new Error('Unknown bundled example');
+  const files=example.files.filter(file=>file==='urlcode.yaml'||file==='README.md');
+  const content                      =Object.create(null);
+  for(const file of files)content[file]=await readFile(`${packageRoot}examples/${name}/${file}`,'utf8');
+  return {metadata:example,content};
+}
+
+/** Validates only supplied YAML syntax and the versioned document schema. It never resolves includes or reads source files. */
+export function validateYaml(text       ) {
+  try {
+    const document=validateDocument(parseYaml(text));
+    return {valid:true,scope:'syntax-and-schema-only',version:document.version,routeCount:Object.keys(document.routes).length};
+  }catch(error){
+    return {valid:false,scope:'syntax-and-schema-only',error:error instanceof Error?error.message:'Invalid URLCode YAML'};
+  }
+}
+
+/** Short deterministic remediation for common validator output; no model call or project read occurs. */
+export function explainError(error       ) {
+  const lower=error.toLowerCase();
+  let guidance='Use validate_yaml for YAML syntax/schema feedback, then use local validate for project files, includes and route semantics.';
+  if(lower.includes('duplicate yaml')||lower.includes('duplicate key'))guidance='Give every mapping key one value. URLCode rejects duplicate YAML keys rather than choosing one silently.';
+  else if(lower.includes('aliases')||lower.includes('anchors')||lower.includes('explicit tags'))guidance='Rewrite YAML anchors, aliases and tags as ordinary repeated YAML values; URLCode accepts a JSON-compatible YAML subset.';
+  else if(lower.includes('invalid configuration at'))guidance='The named location does not match the versioned URLCode schema. Ask get_schema for that field or get_capability for the handler before editing it.';
+  else if(lower.includes('project file')||lower.includes('referenced'))guidance='This needs local project validation: confirm the referenced path is project-relative, exists, and is allowed by the selected route type.';
+  else if(lower.includes('sandbox'))guidance='Sandboxed routes cannot use Node or network APIs. Prefer a declarative handler or proxy; otherwise remove sandboxing only after a deliberate trust review.';
+  return {guidance,nextTools:['get_schema','get_capability','validate']};
+}

package/dist/agents-guide.js

@@ -33,53 +33,55 @@ export function renderAgentsGuide({ routes }                    )         {
   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.
+installed runtime supplies routing, validation, middleware wiring, policies,
+static serving and authentication. 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.
+   referenced code and \`tests/requests.json\`. Preserve unrelated routes.
+2. Make one bounded query first: MCP \`get_context\` when the \`urlcode\` server is
+   registered, else \`urlcode context --project DIR\` (add \`--budget N\` to cap
+   it). It returns a compact summary, constraints and exact commands.
+3. Then retrieve only what the task needs: \`capabilities NAME\`/\`get_capability\`
+   (limits; \`--target NAME\` before promising a provider), \`get_schema\`,
+   \`recipes search TEXT\`/\`search_recipes\` then \`recipes add NAME --out DIR\`,
+   \`explain\` and, with an operator host file, \`get_extensions\`. Bare
+   \`capabilities\` and \`recipes list\` are complete catalogs: fallback, not step one.
 4. Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement. Check supported extensions and recipes first; explain any capability gap.
 
-## Ask the runtime through MCP first
+## MCP
 
-When present, \`${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.
+When present, \`${mcpConfigFile}\` 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.
 
 ## What the runtime provides (this version)
 
 - Handlers, exactly one per route: ${handlers.map(name => `\`${name}\``).join(', ')}.
 - Ordered \`middleware\` around any handler, declared in YAML, trusted by default.
-- Validated inputs: \`parameters\`, \`request.body\` and \`methods\` on the route;
-  functions receive validated \`args\`, never raw user input.
+- Validated route \`parameters\`, \`request.body\`, \`methods\` and function \`args\`.
 - 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; a missing one is a report, not an
-invitation to reimplement it.
+Never recreate these in a function; report a missing capability.
+
+## Build one application
+
+Treat routes, extensions and UI as one application with different owners. Use
+published surfaces in order: configuration/theme/copy, smallest template, CSS,
+then a declared hook. Keep auth/admin security and workflows package-owned; add
+an extension only for a reusable missing capability. Use the official shadcn/ui
+skill only in a React frontend with \`components.json\`; start with \`shadcn info
+--json\`. Do not put React components in the server renderer.
 
 ## Functions and middleware are trusted by default; sandbox is opt-in
 
-A route's \`function\`/\`middleware\` runs trusted, in-process, with full
-Node/filesystem/\`fetch\` access, given only declared \`args\`/\`env\`/\`secrets\`. Add
-\`sandbox: true\` when that code warrants isolation (unreviewed code, a sensitive
-secret, complex logic) — not merely for untrusted input, which both modes share.
-A \`sandbox: true\` route gets a text/JSON subset only: use \`proxy\`/a binding, and
-say why in \`sandboxReason\`.
+A \`function\`/\`middleware\` is trusted, in-process Node with only declared
+\`args\`/\`env\`/\`secrets\`. Add \`sandbox: true\` for code needing isolation, not
+merely untrusted input. The sandbox is text/JSON-only; use \`proxy\`/a binding and
+record the reason in \`sandboxReason\`.
 
 ## Checks that count as evidence
 
@@ -89,25 +91,23 @@ urlcode test
 urlcode audit --expect-routes ${routes}
 \`\`\`
 
-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\`.
+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\`.
+
+## Feedback
+
+After a real attempt, draft evidence-backed feedback: category, sanitized YAML, observed validation/test result, expected behavior and fixture. Ignore one-off product logic; search existing URLCode issues first; never publish or comment without the user's explicit approval.
 
 ## 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.
+- Report unsupported requirements; a field the exact schema rejects does not exist.
+- Never create operator grants. Request a named binding; the operator grants it
+  outside the project, pinned to the revision.
+- Keep keys, tokens and credentials out of project files and commit messages.
 - Protect a route with \`auth: true\`/\`auth: { role: admin }\` where an \`auth\`
   extension is declared; \`cache\` likewise expands to \`policies.cache\`.
-- 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.
+- Local checks are not deployment, soak or independent security evidence.
 
-The installed package ships an agent skill with the same loop at
-\`${skillPath}\` inside \`@jimhoyd/urlcode\` (for example
-\`node_modules/@jimhoyd/urlcode/${skillPath}\`).
+The installed package ships the same loop at \`${skillPath}\` inside
+\`@jimhoyd/urlcode\` (for example \`node_modules/@jimhoyd/urlcode/${skillPath}\`).
 `;
 }

package/dist/authoring.js

@@ -18,18 +18,28 @@ import { renderPackageManifest } from './project-dependencies.js';
                                                                                                             
      
                                        
+                                                                                                                           
+                                            
  
-export async function initProject(destination        , { manifest }              = {})                  {
+export async function initProject(destination        , { manifest, template = 'default' }              = {})                  {
   const target = resolve(destination);
   await mkdir(dirname(target), { recursive: true });
   // Reserve destination before copying; never merge into existing user files.
   await mkdir(target);
   try {
-    const source = fileURLToPath(new URL('../starters/default/', import.meta.url));
+    const source = fileURLToPath(new URL(`../starters/${template === 'page' ? 'page' : 'default'}/`, import.meta.url));
     for (const file of await readdir(source)) {
       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 });
     }
+    if (template === 'page') {
+      await loadDocument(target);
+      if (manifest) {
+        const pkg = await open(join(target,'package.json'), 'wx', 0o644);
+        try { await pkg.writeFile(renderPackageManifest(target, manifest)); } finally { await pkg.close(); }
+      }
+      return target;
+    }
     // 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.