@jimhoyd/urlcode 0.5.0 → 0.5.6

package/examples/not-found/README.md

@@ -5,6 +5,6 @@ route, with status 404 and `text/html`. See
 [site conventions](../../docs/SITE.md#notfound--404html).
 
 ```sh
-node src/cli.ts test --project examples/not-found
-node src/cli.ts build --target static --project examples/not-found   # writes 404.html
+node packages/core/src/cli.ts test --project examples/not-found
+node packages/core/src/cli.ts build --target static --project examples/not-found   # writes 404.html
 ```

package/examples/not-found/example.yaml

@@ -9,9 +9,9 @@ files: [urlcode.yaml, public/index.html, public/404.html, tests/requests.json, R
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts validate --local --project examples/not-found
-    - node src/cli.ts test --project examples/not-found
-    - node src/cli.ts audit --project examples/not-found --expect-routes 2
+    - node packages/core/src/cli.ts validate --local --project examples/not-found
+    - node packages/core/src/cli.ts test --project examples/not-found
+    - node packages/core/src/cli.ts audit --project examples/not-found --expect-routes 2
 behavior:
   - an unmatched GET or HEAD is answered with the page and status 404
   - other methods keep the plain-text 404

package/examples/prerender/README.md

@@ -14,11 +14,11 @@ runs no code at all.
 From the runtime checkout:
 
 ```sh
-node src/cli.ts dev --project examples/prerender        # the dynamic source, live
-node src/cli.ts test --project examples/prerender       # 7 fixtures
+node packages/core/src/cli.ts dev --project examples/prerender        # the dynamic source, live
+node packages/core/src/cli.ts test --project examples/prerender       # 7 fixtures
 node examples/prerender/prerender.mjs examples/prerender /absolute/out
-node src/cli.ts test --project /absolute/out            # fixtures the build wrote
-node src/cli.ts audit --project /absolute/out --expect-routes 3
+node packages/core/src/cli.ts test --project /absolute/out            # fixtures the build wrote
+node packages/core/src/cli.ts audit --project /absolute/out --expect-routes 3
 ```
 
 The same three URLs answer identically before and after. The difference is what

package/examples/prerender/example.yaml

@@ -9,8 +9,8 @@ files: [urlcode.yaml, functions/page.mjs, middleware/template.mjs, prerender.mjs
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts test --project examples/prerender
+    - node packages/core/src/cli.ts test --project examples/prerender
     - node examples/prerender/prerender.mjs examples/prerender /absolute/out
-    - node src/cli.ts audit --project /absolute/out --expect-routes 3
+    - node packages/core/src/cli.ts audit --project /absolute/out --expect-routes 3
 behavior:
   - the rendered project serves the same bytes from native page routes with no sandbox on the request path

package/examples/provider-conformance/example.yaml

@@ -8,7 +8,7 @@ routes: 5
 files: [urlcode.yaml, README.md]
 tests:
   commands:
-    - node src/cli.ts validate --local --project examples/provider-conformance
-    - node src/cli.ts verify-provider --target self-hosted --origin https://owned-fixture.example
+    - node packages/core/src/cli.ts validate --local --project examples/provider-conformance
+    - node packages/core/src/cli.ts verify-provider --target self-hosted --origin https://owned-fixture.example
 behavior:
   - no functions, bindings, assets or policies, so every target activates it; never mix it into a real project

package/examples/shared-blocks/example.yaml

@@ -10,8 +10,8 @@ files: [urlcode.yaml, tests/requests.json, README.md]
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts validate --local --project examples/shared-blocks
-    - node src/cli.ts test --project examples/shared-blocks
-    - node src/cli.ts audit --project examples/shared-blocks --expect-routes 4
+    - node packages/core/src/cli.ts validate --local --project examples/shared-blocks
+    - node packages/core/src/cli.ts test --project examples/shared-blocks
+    - node packages/core/src/cli.ts audit --project examples/shared-blocks --expect-routes 4
 behavior:
   - a route's own request or response key replaces the shared block whole; nothing is deep merged

package/examples/vercel/example.yaml

@@ -12,8 +12,8 @@ files: [urlcode.yaml, api/index.js, vercel.json, public/index.html, public/notes
 tests:
   fixtures: tests/requests.json
   commands:
-    - node src/cli.ts validate --local --project examples/vercel
-    - node src/cli.ts test --project examples/vercel
-    - node src/cli.ts audit --project examples/vercel --expect-routes 5
+    - node packages/core/src/cli.ts validate --local --project examples/vercel
+    - node packages/core/src/cli.ts test --project examples/vercel
+    - node packages/core/src/cli.ts audit --project examples/vercel --expect-routes 5
 behavior:
   - every route is native, so the project activates on Vercel without the sandbox

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 60,557 tokens (estimate: characters / 4). -->
+<!-- Consolidated URLCode authoring reference: 16 documents, about 61,257 tokens (estimate: characters / 4). -->
 
 <!-- urlcode-current-version:start -->
 # URLCode
@@ -7,10 +7,11 @@
 > 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.0`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.6`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
-> auth, admin and ui extension packages in this repository are versioned at the same
-> revision; confirm what is published with `npm run release:status`.
+> 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;
+> see package and channel alignment for the supported release pair.
 <!-- urlcode-current-version:end -->
 
 Use the schema and docs from the runtime revision you run. Do not assume Node
@@ -43,12 +44,12 @@ grants. Unsupported features fail with the route named; nothing degrades silentl
 
 Source: https://github.com/jimhoyd-com/urlcode/blob/main/docs/FRAMEWORK.md
 
-One page for people and AI agents. It says what the four packages are, how a
+One page for people and AI agents. It says what the six workspace packages are, how a
 project grows from a handful of redirects into an application with accounts
 and an administration console, and which facts an agent must not guess. Every
 claim here is implemented in the linked repository; nothing is roadmap.
 
-### Four packages, one project shape
+### Six workspace packages, one project shape
 
 | Package | Source | What it adds | How a project declares it |
 |---|---|---|---|
@@ -56,12 +57,17 @@ claim here is implemented in the linked repository; nothing is roadmap.
 | `@jimhoyd/urlcode-ui` | [`packages/ui`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui) | Shared presentation: escaped templates, shadcn/ui partials, one stylesheet with light and dark, themes, translations, the `ui` extension that serves the kit's assets | `extensions.ui` plus an asset mount route |
 | `@jimhoyd/urlcode-auth` | [`packages/auth`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth) | Accounts: password, passkeys, OpenID Connect, email codes, TOTP, recovery, sessions, roles, registration modes, account page, operator CLI | `extensions.auth` plus an `/account/*` mount and `policies.extensions.auth` on protected routes |
 | `@jimhoyd/urlcode-admin` | [`packages/admin`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/admin) | Administration: users, sessions, roles, audit, registration approval, two-person cases, support impersonation, health | `extensions.admin` plus an `/admin/*` mount |
-
-All four are Apache-2.0. Each package's npm `latest` tag identifies its stable
-version. The current publisher records the exact four-package stack tested
-together on each new GitHub release and attaches the same information in signed
-`train.json` metadata.
-A stable npm channel is not an independent assessment: review, deployment
+| `@jimhoyd/urlcode-store` | [`packages/store`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/store) | Durable bounded JSON collections exposed as a typed CRUD API | `extensions.store` plus a protected collection mount |
+| `@jimhoyd/urlcode-forms` | [`packages/forms`](https://github.com/jimhoyd-com/urlcode/blob/main/packages/forms) | Bounded server-rendered form flows: escaped controls, admission, CSRF, validation and a fixed confirmation | `extensions.forms` plus a `GET, HEAD, POST` form mount; it composes with `ui` and optional `auth` |
+
+All six are Apache-2.0. Core is published through npm, GitHub Releases and
+Homebrew. The first-party executable extensions are published as signed,
+immutable GitHub Release bundles; their source remains in these workspace
+packages, but new sites do not install them from npm. The forms package is an
+unreleased bundle source and is not implied by the currently recorded bundle
+release. The legacy extension npm
+packages are deprecated migration artifacts. A release channel is not an
+independent assessment: review, deployment
 evidence and an accessibility assessment are still pending
 ([issue 58](https://github.com/jimhoyd-com/urlcode/issues/58)). Their status
 files say exactly what is built: [auth](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/IMPLEMENTATION-STATUS.md),
@@ -101,33 +107,40 @@ Each rung's YAML is valid on every rung above it.
 6. **Your own look.** A shared `presentation` (catalogue and theme variables)
    restyles auth and admin together; the `ui` extension adds the template kit,
    project copy, template and stylesheet overrides for kit-rendered pages.
+7. **Bounded data and forms.** The `store` extension supplies declared durable
+   collections; the `forms` extension supplies declared browser form flows over
+   the shared UI kit. Both are trusted operator extensions, not core YAML
+   handlers. Add `auth: true` where a flow or collection is per-account.
 
 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.
 
-Rungs 1 to 3 need only the core package. Rungs 4 to 6 need the extension
-packages installed from npm and a Node host with a
-patched SQLite build; see each package's README ([auth](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/README.md),
-[admin](https://github.com/jimhoyd-com/urlcode/blob/main/packages/admin/README.md), [ui](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui/README.md)) for the
+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
+in a selected catalog. Auth and admin additionally need the Node/SQLite runtime
+their packages document; forms declares Node, AWS and Vercel targets, while store
+is currently Node-only. See each package's README ([auth](https://github.com/jimhoyd-com/urlcode/blob/main/packages/auth/README.md),
+[admin](https://github.com/jimhoyd-com/urlcode/blob/main/packages/admin/README.md), [ui](https://github.com/jimhoyd-com/urlcode/blob/main/packages/ui/README.md),
+[store](https://github.com/jimhoyd-com/urlcode/blob/main/packages/store/README.md), [forms](https://github.com/jimhoyd-com/urlcode/blob/main/packages/forms/README.md)) for the
 exact requirement.
 
 ### The composition contract
 
-An extended project starts from the current stable packages and one command.
-`--save-exact` records the concrete versions selected from the independent
-`latest` channels:
+An extended project starts from core and an immutable bundle release. The
+release is an explicit operator choice; use the current verified tag from
+[package and channel alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md):
 
 ```sh
-npm install --save-exact @jimhoyd/urlcode@latest @jimhoyd/urlcode-ui@latest @jimhoyd/urlcode-auth@latest @jimhoyd/urlcode-admin@latest
-urlcode init my-site --with ui,auth,admin
+npm install @jimhoyd/urlcode
+npx urlcode init my-site --with ui,auth,admin --bundle-release extension-bundles@v…
 ```
 
-Installing from npm is the normal path; `scripts/pack-sources.mjs` still builds
-local tarballs from a reviewed checkout for operators who install only source
-they have read — one revision now covers core and every extension. Three files make an extended
-project. Nothing else is discovered by convention.
+This produces a manifest with core only and a bundle lockfile for extensions.
+`scripts/pack-sources.mjs` remains available to review reproducible source
+inputs. Three files make an extended project. Nothing else is discovered by
+convention.
 
 ```
 site/
@@ -199,36 +212,32 @@ package behavior.
 A signed declarative artifact is a separate, optional authoring input, not a
 fifth way to compose executable behavior. A project may lock an attested
 schema/example bundle and expose it through MCP `get_extension_artifacts` and
-`get_extension_artifact`; the npm package and operator host remain the only
-executable extension path. See [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts).
+`get_extension_artifact`; the verified executable bundle and explicit operator
+host remain the executable extension path. See [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts).
 
 ```sh
 urlcode serve --project /absolute/site --host-file /absolute/operator/host.mjs --origin https://site.example
 ```
 
-`urlcode init <dir> --with ui,auth,admin` writes this layout in one step: by
-default it resolves each installed `@jimhoyd/urlcode-<name>` from the current
-directory; with `--bundle-release extension-bundles@v…` it verifies and locks
-the named GitHub Release bundles instead. In either mode it calls the verified
-module's `scaffold` export and merges fragments into `app/urlcode.yaml`, one
+`urlcode init <dir> --with ui,auth,admin --bundle-release
+extension-bundles@v…` writes this layout in one step. It verifies and locks the
+named GitHub Release bundles, calls each verified module's `scaffold` export,
+and merges fragments into `app/urlcode.yaml`, one
 explicit `host.mjs` and one `README.md`, refusing before writing a site when a
-package/bundle is missing or two fragments collide (the contract is documented under
+bundle is missing or two fragments collide (the contract is documented under
 [scaffolding](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#scaffolding-with-init---with)). `urlcode-auth init`
 and `urlcode-admin init` write the same layout for a single package; `urlcode-auth bootstrap` creates the first
 administrator from JSON on stdin. `inspectExtensionRevision(project)` prints
 the SHA-256 that `projectSha256` must carry; changing extension YAML, policies
 or mounts changes the revision and needs an explicit operator reapproval.
 
-The presentation tooling composes the same way, by naming packages rather than
-depending on them. `urlcode-ui` is the kit alone until
-`--extensions @jimhoyd/urlcode-auth,@jimhoyd/urlcode-admin` names the packages
-that ship the other namespaces: each is resolved from `--project` with Node
-package resolution and imported for the namespace it exports, so `list`,
+The presentation tooling composes the same way, by naming logical extensions
+rather than npm dependencies. The UI bundle is the kit until the locked auth
+and admin bundles add their namespaces, so `list`,
 `doctor`, `eject`, `preview` and `copy --missing` cover the `auth/*` and
 `admin/*` templates and copy the host registers, and a project override of an
-extension template is checked against the shipped view model. A package that is
-not installed is skipped. `urlcode init --with` writes the commands with the
-flag already set; `@jimhoyd/urlcode-ui` still depends on neither peer.
+extension template is checked against the shipped view model. `urlcode init
+--with --bundle-release` writes the release pin into the generated README.
 
 ### Rules an agent must follow
 
@@ -313,6 +322,13 @@ needed schema, example or README. Context is a summary with the
 constraints and exact commands, not a schema dump, and it never hides a
 capability limit: ask `capabilities NAME` before promising a feature.
 
+When a goal spans routes, persistence or extensions, the next bounded query can
+be `urlcode plan-feature "goal" --project DIR --json` (MCP `plan_feature`). It
+matches only the current compiled project, capability catalog, bundled recipes,
+locked inert artifacts and registrations already available to the session. Read
+its operator prerequisites and explicit gaps as constraints, not as permission
+to select packages, storage, keys or grants in project YAML.
+
 The complete catalogs (`urlcode capabilities`, `recipes list`), the compact
 [llms.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms.txt) index and the generated [llms-full.txt](https://github.com/jimhoyd-com/urlcode/blob/main/llms-full.txt)
 stay available as deliberate fallback and reference, not as the opening move.
@@ -423,7 +439,7 @@ urlcode benchmark --project ./my-links --requests 100 --concurrency 2
 ```
 
 Use the intentional actual count, not always 2. Runtime checkout users can replace
-`urlcode` with `node src/cli.ts`. Template users can use the equivalent npm scripts.
+`urlcode` with `node packages/core/src/cli.ts`. Template users can use the equivalent npm scripts.
 External bindings require an already reviewed policy; add `--policy` where needed.
 The benchmark operates locally; it is not a load test of an external deployment.
 
@@ -536,9 +552,9 @@ Which handler serves the response:
 Data persistence has no native handler. The operator-installed `store` extension
 serves declared collections as a CRUD API, and `urlcode recipes search "crud store
 persist"` finds the `store-crud` recipe. It needs the operator to install
-`@jimhoyd/urlcode-store` package or an attested executable bundle and a host
-file. `init --with ui,auth,store --bundle-release extension-bundles@v…`
-scaffolds the npm-free bundle form; a no-auth
+an attested executable bundle and a host file. `init --with
+ui,auth,store --bundle-release extension-bundles@v…` scaffolds the supported
+npm-free form; a no-auth
 `--with store` needs `--ack store:public-write`, which only a core release after the
 store's first publication has, so say so rather than promising it. Report anything beyond that recipe (filtering, sorting, per-record
 ownership, a database) as a gap. `urlcode context` lists the same built-ins so
@@ -757,7 +773,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.0. Start with the function example below,
+This guide targets URLCode 0.5.6. 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.
@@ -772,10 +788,10 @@ From the runtime checkout:
 
 ```sh
 npm ci
-node src/cli.ts validate --project examples/cookbook
-node src/cli.ts test --project examples/cookbook
-node src/cli.ts audit --project examples/cookbook --expect-routes 40
-node src/cli.ts dev --project examples/cookbook
+node packages/core/src/cli.ts validate --project examples/cookbook
+node packages/core/src/cli.ts test --project examples/cookbook
+node packages/core/src/cli.ts audit --project examples/cookbook --expect-routes 40
+node packages/core/src/cli.ts dev --project examples/cookbook
 ```
 
 The cookbook is a larger learning project. The normal `urlcode init ../my-links`
@@ -898,6 +914,7 @@ schema-valid combinations activate successfully.
 | `routes.*.env.* (option 1).value` | string | yes | — |
 | `routes.*.env.* (option 2)` | object | no | unknown keys rejected |
 | `routes.*.env.* (option 2).env` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
+| `routes.*.env.* (option 2).default` | string | no | — |
 | `routes.*.secrets` | object | no | — |
 | `routes.*.secrets.*` | object | no | unknown keys rejected |
 | `routes.*.secrets.*.secret` | string | yes | pattern: "^[A-Za-z_][A-Za-z0-9_]*$" |
@@ -1593,12 +1610,17 @@ parity for a `sandbox: true` route; a trusted route has no such restriction.
 
 Context contains `inputs.path/query/header`, `args`, `env`, `secrets`. Arguments
 may be scalar literals, input references, `{env: alias}` or `{secret: alias}`.
-Bindings use `{value: "literal"}`, `{env: EXTERNAL_NAME}` or `{secret: logical_name}`.
-Literal non-secret values need no grant. Every external environment or secret
-binding is denied unless an operator policy grants that exact name to the route
-and matches the SHA-256 of the current configuration/source snapshot.
-A project cannot grant itself capabilities. See [policy setup](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md).
-Missing bindings also reject activation. Inspection parses source without running it.
+Bindings use `{value: "literal"}`, `{env: EXTERNAL_NAME}`,
+`{value: "default", env: EXTERNAL_NAME}` or `{secret: logical_name}`. The
+combined form resolves to the process environment variable when set and
+non-empty, else `value`; it needs the same operator grant as `{env: ...}`
+alone. Literal non-secret values need no grant. Every external environment or
+secret binding is denied unless an operator policy grants that exact name to
+the route and matches the SHA-256 of the current configuration/source
+snapshot. A project cannot grant itself capabilities. See
+[policy setup](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md). Missing bindings reject activation
+(the combined form always resolves, via its default). Inspection parses
+source without running it.
 
 Development may read `.env.local`; process values win. Serving never reads it.
 Dotenv supports single-line NAME=value, paired single/double quotes, blank lines
@@ -2833,7 +2855,7 @@ Extensions are trusted operator modules, separate from a project's own
 `function`/`middleware` code. Auth
 and admin implementations live in `urlcode-auth` and `urlcode-admin`; the runtime
 supplies only the generic integration contract. No project file can import a host
-extension or choose its npm package.
+extension, choose a bundle release, or choose an npm package.
 
 Stored short links moved out of core this way too: a `urlcode-dynamic-link`
 package (mount-based, like `auth`/`admin`) owned the durable link store, its CLI
@@ -2845,6 +2867,13 @@ The `store` extension is the data-owning counterpart: it serves declared,
 bounded collections as a CRUD API from an operator-owned directory. See
 [data store](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STORE.md).
 
+The `forms` extension is the browser-flow counterpart: it renders bounded
+declared fields through the `ui` kit, validates URL-encoded submissions with
+its host-supplied CSRF secret, and redirects a successful submission to a
+fixed confirmation page. It is a trusted operator extension, needs `ui`, and
+may be mounted with `auth: true`; its optional `onSubmit` hook is trusted
+project code rather than a sandbox bridge. See the [forms package](https://github.com/jimhoyd-com/urlcode/blob/main/packages/forms/README.md).
+
 A project declares versioned configuration and exclusive route mounts:
 
 ```yaml
@@ -3229,29 +3258,24 @@ Assembly rules, in the resolved order:
 
 #### Recorded versions
 
-`init --with` also writes `<directory>/package.json`: a private manifest that
-pins, at exactly the version that was resolved, the running runtime, every
-extension named in `--with`, and every package those extensions declare in
-`peerDependencies` (so `@jimhoyd/urlcode-ui` is pinned for an `auth,admin` site
-although nobody named it). Before anything is written, the whole set is checked
-against every declared peer range; an incompatible combination or a missing
-required peer refuses and names it, leaving no directory behind.
+`init --with --bundle-release extension-bundles@v…` writes a private
+`<directory>/package.json` pinning the running core and an extension bundle
+lockfile naming the verified archives. It does not add extension npm
+dependencies. Before anything is written, the selected catalog checks every
+required extension and core compatibility; a missing requirement or incompatible
+bundle refuses and names it, leaving no directory behind.
 
 Nothing is installed. The generated site has no `node_modules` and no
-`package-lock.json` until you run `npm install` in it yourself, which the
-command and the generated README both state as the next step. Reproducibility
-comes from that install, not from generation.
+`package-lock.json` until you run `npm install` in it yourself for core, which
+the command and generated README both state as the next step. Bundle
+reproducibility comes from the committed lockfile and frozen cache, not npm.
 
 - `--no-manifest` generates the site without a `package.json`, for a site whose
   dependencies are managed elsewhere. Plain `urlcode init` is unchanged and
   still writes no manifest; add `--manifest` to pin the runtime for a
   route-only project too.
-- `--pin <package>=<specifier>` records a specifier instead of the resolved
-  version, for local tarball or offline development
-  (`--pin @jimhoyd/urlcode-auth=file:/abs/urlcode-auth-0.1.0-alpha.6.tgz`). A
-  package installed from a local path or tarball is detected from npm's own
-  install record and pinned by that path without any flag; the README says so,
-  because such a pin only reproduces where that path exists.
+- `--pin <package>=<specifier>` is only for reviewed local source development.
+  New first-party extension installs use the signed bundle release instead.
 
 There is no upgrade command. Moving a generated project to newer versions today
 means editing its `package.json` and re-running `npm install` yourself; nothing
@@ -3323,8 +3347,8 @@ requirements.
 
 ### Signed executable extension bundles
 
-Official executable extensions are migrating away from consumer npm installs.
-They use a separate, immutable `extension-bundles@v…` GitHub Release namespace;
+Official executable extensions are delivered through a separate, immutable
+`extension-bundles@v…` GitHub Release namespace;
 it is intentionally disjoint from the permanently data-only `extensions@v…`
 artifact channel above. A bundle is a bounded, frozen Node module tree produced
 from reviewed first-party source, not a general extension marketplace and not
@@ -3377,10 +3401,14 @@ export default { extensions: [storeExtension({ directory: '/srv/site-data', proj
 ```
 
 This does not make bundle code sandboxed and does not alter a route that
-declares `sandbox: true`; those remain distinct execution modes. npm packages
-remain the migration fallback until the first signed bundle release and the
-fresh composed consumer flow have been released and proven. Do not unpublish a
-package merely because its data-only artifact exists.
+declares `sandbox: true`; those remain distinct execution modes. The signed
+bundle path is the supported distribution for first-party executable
+extensions. The legacy `@jimhoyd/urlcode-ui`, `@jimhoyd/urlcode-auth`,
+`@jimhoyd/urlcode-admin`, and `@jimhoyd/urlcode-store` npm packages are
+deprecated migration artifacts: existing projects may retain their locked
+copies, but new projects must use a verified bundle release. Their npm
+retention status is not a promise that they are available or supported for new
+installs.
 
 ---
 
@@ -3392,10 +3420,16 @@ One command produces a site that already has accounts, an administration
 console and a presentation kit wired together:
 
 ```sh
-npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
-urlcode init site --with ui,auth,admin
+npm install @jimhoyd/urlcode
+npx urlcode init site --with ui,auth,admin --bundle-release extension-bundles@v…
 ```
 
+Use the immutable bundle release recorded in [package and channel
+alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md). This creates a site whose npm manifest pins
+core only; UI, auth and admin are verified, locked GitHub Release bundles.
+The legacy extension npm packages are deprecated migration artifacts. New sites
+obtain extensions from the verified bundle release.
+
 This page is the map of what you may then change, and with which tool. It
 covers three different activities that are easy to confuse:
 
@@ -3573,9 +3607,10 @@ not run it. With the packages named:
   and those translations do not currently reach the console
   ([#227](https://github.com/jimhoyd-com/urlcode/issues/227)).
 
-`urlcode init <directory> --with ui,auth,admin` writes these commands into the
-generated README with the flag already set. `@jimhoyd/urlcode-ui` depends on
-neither peer; the operator names them.
+`urlcode init <directory> --with ui,auth,admin --bundle-release
+extension-bundles@v…` writes these commands into the generated README with the
+verified bundle release pinned. The operator names the logical extensions; it
+does not add extension npm dependencies.
 
 Run the extension's published `fastChecks` while editing. Theme and copy changes
 need no framework build. Template and CSS checks load only the UI kit and named

package/llms.txt

@@ -4,10 +4,11 @@
 > 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.0`. `function`/`middleware`
+> `version: "1"`. Core is Apache-2.0; this revision is `0.5.6`. `function`/`middleware`
 > routes are trusted by default with `sandbox: true` as the per-route opt-in. The
-> auth, admin and ui extension packages in this repository are versioned at the same
-> revision; confirm what is published with `npm run release:status`.
+> 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;
+> see package and channel alignment for the supported release pair.
 <!-- urlcode-current-version:end -->
 
 Use the schema and docs from the runtime revision you run. Do not assume Node
@@ -17,10 +18,10 @@ grants. Unsupported features fail with the route named; nothing degrades silentl
 
 ## Start here (read only this section for a first attempt)
 
-1. Run `urlcode context --project DIR` (MCP `get_context`). For redirect-only work run
-   `urlcode context --project DIR --task redirects`: supported shapes with exact YAML, gaps
+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. For a new redirect-only project, `urlcode init DIR --template redirects` writes the tested starter (yaml, 404 page, `npm start` honoring `PORT`, fixtures). Otherwise write `urlcode.yaml`, then `urlcode validate --local --project DIR` and `urlcode test`.
+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.
 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.
 
@@ -39,19 +40,20 @@ grants. Unsupported features fail with the route named; nothing degrades silentl
 
 Use the highest-level declarative feature before writing a function or middleware. Custom code
 only when the framework cannot express the requirement; then report the gap. Never invent fields
-or bypass target limits or operator grants ([design principle](docs/PROJECT-DIRECTION.md#design-principle-declarative-first)).
+or bypass target limits or operator grants ([design principle](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PROJECT-DIRECTION.md#design-principle-declarative-first)).
 
 | I need | Use |
 |---|---|
-| Security headers | `policies.security` ([security](docs/policies/security.md)) |
-| Cache headers / cache strategy | `cacheControl` / `policies.cache` ([assets](docs/yaml/assets.md), [cache](docs/policies/cache.md)) |
-| Body size, content type, JSON check | `request.body` ([HTTP](docs/HTTP.md)) |
+| Security headers | `policies.security` ([security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/security.md)) |
+| Cache headers / cache strategy | `cacheControl` / `policies.cache` ([assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/yaml/assets.md), [cache](https://github.com/jimhoyd-com/urlcode/blob/main/docs/policies/cache.md)) |
+| Body size, content type, JSON check | `request.body` ([HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md)) |
 | Restrict HTTP methods | `methods` (default GET/HEAD; 405 with `Allow`) |
-| Rate limiting, bot/AI-crawler blocking, compression | `policies.throttle`, `policies.agents`, `policies.compression` ([policies](docs/POLICIES.md)) |
+| Rate limiting, bot/AI-crawler blocking, compression | `policies.throttle`, `policies.agents`, `policies.compression` ([policies](https://github.com/jimhoyd-com/urlcode/blob/main/docs/POLICIES.md)) |
 | Fixed JSON/text/headers | `respond` and `response.headers` |
-| robots.txt, sitemap, favicon, security.txt | top-level `site` ([site](docs/SITE.md)) |
-| Sign-in, roles, protected routes | `extensions.auth`, then `auth: true` ([extensions](docs/EXTENSIONS.md)) |
+| robots.txt, sitemap, favicon, security.txt | top-level `site` ([site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md)) |
+| Sign-in, roles, protected routes | `extensions.auth`, then `auth: true` ([extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md)) |
 | Persistence | operator-installed store extension, recipe `store-crud`; a database, filtering and per-record ownership beyond it are gaps |
+| Stored short links (create, redirect, click count) | operator-installed store extension's `shortLinks` capability: a collection `key`, an HTTP(S) `destination` field, one `increments` counter, and a public `/go`-style redirect mount; no function needed (`urlcode docs search "shortLinks"`, MCP `search_docs`) |
 
 When only code can do it, one function serves one or more routes:
 
@@ -63,10 +65,17 @@ When only code can do it, one function serves one or more routes:
 export default (request, { args, route }) => Response.json({ hello: args.name });
 ```
 
+Function handler shape: a module whose `export default` is `(request, { args, env, route })` and returns a
+`Response` (or a promise of one). `args` holds the route's declared path inputs; the string form
+`function: functions/hello.mjs` and the long form `function: {source: ...}` both bind every declared path input
+(write `args: {}` to bind none). `sandbox: true` is a separate route option. `route.pattern` is the matched pattern; `env` holds route-scoped values only.
+Search the docs with bounded output using `npx --no --package @jimhoyd/urlcode urlcode docs search "TEXT"` (MCP `search_docs`)
+rather than grepping llms-full.txt.
+
 Handler for the response: fixed text or JSON is `respond`; one HTML file is `page`; a directory is
 `static`; an attachment is `download`; a short HTML snippet is `respond` `text` with a
 `Content-Type: text/html; charset=utf-8` header. Functions are trusted by default; add
-`sandbox: true` to opt a route in ([function security](docs/FUNCTION-SECURITY.md)).
+`sandbox: true` to opt a route in ([function security](https://github.com/jimhoyd-com/urlcode/blob/main/docs/FUNCTION-SECURITY.md)).
 
 After a real attempt, draft feedback only for a capability gap, repeated workaround, documentation
 gap or suspected defect, with sanitized YAML and validation evidence. Search existing issues first;
@@ -74,9 +83,9 @@ never publish or comment without the user's approval.
 
 ## Reference (load one only when needed)
 
-- Authoring: [AI authoring contract](docs/AI-AUTHORING.md), [YAML guide](docs/YAML-GUIDE.md), [field reference](docs/YAML-REFERENCE.md), [JSON Schema](schemas/urlcode.schema.json), [semantics](docs/SPECIFICATION.md), [cookbook](examples/cookbook/README.md), [recipes](docs/RECIPES.md).
+- Authoring: [AI authoring contract](https://github.com/jimhoyd-com/urlcode/blob/main/docs/AI-AUTHORING.md), [YAML guide](https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-GUIDE.md), [field reference](https://github.com/jimhoyd-com/urlcode/blob/main/docs/YAML-REFERENCE.md), [JSON Schema](schemas/urlcode.schema.json), [semantics](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SPECIFICATION.md), [cookbook](examples/cookbook/README.md), [recipes](https://github.com/jimhoyd-com/urlcode/blob/main/docs/RECIPES.md).
 - Skills: [authoring](.claude/skills/urlcode-authoring/SKILL.md), [operations](.claude/skills/urlcode-operations/SKILL.md).
-- Routes and handlers: [routing](docs/ROUTING.md), [HTTP](docs/HTTP.md), [middleware](docs/MIDDLEWARE.md), [assets](docs/ASSETS.md), [conditions](docs/CONDITIONS.md), [egress](docs/EGRESS.md), [prerender](docs/PRERENDER.md), [site](docs/SITE.md), [organization](docs/ORGANIZATION.md).
-- Extensions: [extensions](docs/EXTENSIONS.md) (including [signed declarative artifacts](docs/EXTENSIONS.md#signed-declarative-artifacts); MCP `get_extension_artifacts`), [composing a site](docs/COMPOSING-A-SITE.md), [urlcode-auth](packages/auth), [urlcode-admin](packages/admin), [urlcode-ui](packages/ui), each with its own llms.txt and in this repository as a workspace package. Per-route middleware is native core (`middleware:` array), not a retired extension; core has no native `link` handler and no supported extension provides stored links, so report them as a gap.
-- Tooling: [tooling and MCP](docs/TOOLING.md), [TypeScript](docs/TYPESCRIPT.md), [capabilities](docs/CAPABILITIES.md), [plugins](docs/PLUGINS.md), [interchange](docs/INTERCHANGE.md), [bulk import](docs/BULK.md).
-- Operations: [operations](docs/OPERATIONS.md), [install](docs/INSTALL.md), [deployment checks](docs/DEPLOYMENT-CHECKS.md), [readiness](docs/READINESS.md), [capacity](docs/CAPACITY.md), [resilience](docs/RESILIENCE.md), [observability](docs/OBSERVABILITY.md), [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md), [Cloudflare](docs/CLOUDFLARE.md), [static hosting](docs/STATIC.md), [release readiness](docs/RELEASE-READINESS.md), [roadmap](ROADMAP.md).
+- Routes and handlers: [routing](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ROUTING.md), [HTTP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/HTTP.md), [middleware](https://github.com/jimhoyd-com/urlcode/blob/main/docs/MIDDLEWARE.md), [assets](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ASSETS.md), [conditions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CONDITIONS.md), [egress](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EGRESS.md), [prerender](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PRERENDER.md), [site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/SITE.md), [organization](https://github.com/jimhoyd-com/urlcode/blob/main/docs/ORGANIZATION.md).
+- Extensions: [extensions](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md) (including [signed declarative artifacts](https://github.com/jimhoyd-com/urlcode/blob/main/docs/EXTENSIONS.md#signed-declarative-artifacts); MCP `get_extension_artifacts`), [composing a site](https://github.com/jimhoyd-com/urlcode/blob/main/docs/COMPOSING-A-SITE.md), [package and channel alignment](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERSION-ALIGNMENT.md). New first-party executable extension installs use an attested `extension-bundles@v…` GitHub Release and an explicit host; do not add deprecated extension npm packages to a new project. [urlcode-auth](https://github.com/jimhoyd-com/urlcode/tree/main/packages/auth), [urlcode-admin](https://github.com/jimhoyd-com/urlcode/tree/main/packages/admin), [urlcode-ui](https://github.com/jimhoyd-com/urlcode/tree/main/packages/ui), [urlcode-store](https://github.com/jimhoyd-com/urlcode/tree/main/packages/store), and [urlcode-forms](https://github.com/jimhoyd-com/urlcode/tree/main/packages/forms) are workspace bundle sources. Per-route middleware is native core (`middleware:` array), not a retired extension; core has no native `link` handler, but the store extension's `shortLinks` capability covers create, invalid-destination, redirect, missing-code and click-count for stored short links without a function — declare it under `extensions.store.config.shortLinks` (`urlcode docs search "shortLinks"`, MCP `search_docs`). Only report a gap for stored-link needs beyond that (custom redirect status, non-HTTP(S) destinations, per-record ownership).
+- Tooling: [tooling and MCP](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TOOLING.md), [TypeScript](https://github.com/jimhoyd-com/urlcode/blob/main/docs/TYPESCRIPT.md), [capabilities](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CAPABILITIES.md), [plugins](https://github.com/jimhoyd-com/urlcode/blob/main/docs/PLUGINS.md), [interchange](https://github.com/jimhoyd-com/urlcode/blob/main/docs/INTERCHANGE.md), [bulk import](https://github.com/jimhoyd-com/urlcode/blob/main/docs/BULK.md).
+- Operations: [operations](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OPERATIONS.md), [install](https://github.com/jimhoyd-com/urlcode/blob/main/docs/INSTALL.md), [deployment checks](https://github.com/jimhoyd-com/urlcode/blob/main/docs/DEPLOYMENT-CHECKS.md), [readiness](https://github.com/jimhoyd-com/urlcode/blob/main/docs/READINESS.md), [capacity](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CAPACITY.md), [resilience](https://github.com/jimhoyd-com/urlcode/blob/main/docs/RESILIENCE.md), [observability](https://github.com/jimhoyd-com/urlcode/blob/main/docs/OBSERVABILITY.md), [Vercel](https://github.com/jimhoyd-com/urlcode/blob/main/docs/VERCEL.md), [AWS](https://github.com/jimhoyd-com/urlcode/blob/main/docs/AWS.md), [Cloudflare](https://github.com/jimhoyd-com/urlcode/blob/main/docs/CLOUDFLARE.md), [static hosting](https://github.com/jimhoyd-com/urlcode/blob/main/docs/STATIC.md), [release readiness](https://github.com/jimhoyd-com/urlcode/blob/main/docs/RELEASE-READINESS.md), [roadmap](https://github.com/jimhoyd-com/urlcode/blob/main/ROADMAP.md).