@jimhoyd/urlcode 0.4.0-alpha.1 → 0.4.0-alpha.3

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

@@ -1,6 +1,6 @@
 ---
 name: urlcode-authoring
-description: Author or modify a URLCode project — write and edit urlcode.yaml routes, function and middleware modules, pages, static assets, downloads and stored links, then validate and test them. Use whenever a urlcode.yaml file is present or referenced, when the user mentions URLCode, @jimhoyd/urlcode, urlcode routes/handlers/policies/site keys, or asks for redirects, short links or request functions in a URLCode project. Loads the implemented capability matrix so unsupported features are reported as gaps instead of invented.
+description: Author or modify a URLCode project — write and edit urlcode.yaml routes, function and middleware modules, pages, static assets and downloads, then validate and test them. Use whenever a urlcode.yaml file is present or referenced, when the user mentions URLCode, @jimhoyd/urlcode, urlcode routes/handlers/policies/site keys, or asks for redirects or request functions in a URLCode project. Loads the implemented capability matrix so unsupported features are reported as gaps instead of invented.
 ---
 
 # Authoring URLCode projects
@@ -11,23 +11,27 @@ validates. Features outside that contract do not silently degrade — they fail
 validation. So the cost of guessing is a broken project, and the whole job here
 is to author only what the pinned revision implements and then prove it.
 
+## Declarative-first default
+
+> Use URLCode's highest-level declarative features whenever possible. Generate custom code only when the framework cannot express the requirement.
+
+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.
+
 ## Read the contract before writing YAML
 
 Documentation, schema and runtime must come from the **same revision**. Read from
 the project's installed runtime (`node_modules/@jimhoyd/urlcode/`) or the
 checkout you are working in — never from memory of another version.
 
-1. `docs/AI-AUTHORING.md` — the authoring contract and the **capability matrix**
-   of what is available versus unavailable. Read this first and in full.
-2. `schemas/urlcode.schema.json` — the exact accepted structure.
-3. `docs/YAML-REFERENCE.md` and `docs/SPECIFICATION.md` — every field, and the
-   implemented semantics, defaults and sandbox API.
-4. `docs/YAML-GUIDE.md` and `examples/cookbook/` — recipes and runnable files.
-5. `docs/ROUTING.md`, `docs/HTTP.md`, `docs/MIDDLEWARE.md`, `docs/ASSETS.md` —
-   matching precedence, methods, composition, MIME and ranges.
-6. `docs/FUNCTION-SECURITY.md` — the sandbox and operator binding policy.
-
-`llms.txt` at the repository root is a compact index of all of the above.
+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.
 
 ## Workflow
 
@@ -35,15 +39,16 @@ checkout you are working in — never from memory of another version.
   tests and the pinned runtime version. Preserve the user's organization,
   naming and unrelated routes.
 - Choose exactly one handler per route — `function`, `redirect`, `respond`,
-  `page`, `static`, `download` or `link` — plus optional ordered middleware.
-  Prefer a native handler when code is unnecessary.
+  `page`, `static`, `download`, `conditional`, `proxy` or an `extension` mount
+  — plus optional ordered middleware. Prefer a native handler when code is
+  unnecessary.
 - Declare each path placeholder as a required string. Paths match whole
   segments: no regex, no greedy captures, no wildcard handlers.
 - Bind typed inputs through `args` or context. There is no `${...}`
   interpolation anywhere in the format.
 - Create every referenced module, page and asset **before** validating. All
-  paths resolve from the project root; functions and middleware use relative
-  ES-module imports only.
+  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.
 - 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.
@@ -56,11 +61,20 @@ mistakes that recur:
 - No YAML anchors, aliases, template interpolation or remote includes.
 - No recursive includes or glob discovery; includes are explicit.
 - No regex, optional or greedy route segments, and no host-based routing.
-- The sandbox is text/JSON `Request`/`Response` only: **no** `fetch`, Node or
-  npm APIs, filesystem, WebSocket, streaming or crypto API.
+- `function`/`middleware` routes run trusted and unsandboxed by default: full
+  Node, npm, filesystem and `fetch` access, in-process, like any other project
+  code. `sandbox: true` opts a route into isolation — reach for it when that
+  route's own code warrants it (unreviewed or third-party code, a secret whose
+  blast radius matters, complex logic), not reflexively on every route and
+  never merely because it handles request data -- that is untrusted in both
+  modes and must be validated either way. A
+  `sandbox: true` route gets a text/JSON `Request`/`Response` sandbox only:
+  **no** `fetch`, Node or npm APIs, filesystem, WebSocket, streaming or crypto
+  API.
 - No global middleware, Express compatibility or automatic auth.
 - `policies` accepts only `throttle`, `agents`, `security`, `compression` and
-  `cache`, every key off unless declared; `hardened` is the only built-in
+  `cache`, plus registered extension requirements under `extensions`;
+  the built-in policies are off unless declared; `hardened` is the only built-in
   profile. Check the per-target table in `docs/POLICIES.md` before declaring
   one for a serverless or Cloudflare deployment — an unsupported policy refuses
   activation rather than degrading.
@@ -68,9 +82,9 @@ mistakes that recur:
   only and off unless declared; a declared route at the same path wins. Its
   generated routes count toward `--expect-routes`, and `site.sitemap` needs
   `--origin` on every command that activates the project.
-- `dynamicLinks: true` belongs in the entry `urlcode.yaml` only, and only for
-  live `link` handlers — not for includes, and not for parameterized redirects
-  or functions.
+- There is no native `link` handler or `dynamicLinks` project flag, and no
+  supported extension package provides one; report stored short links as a gap,
+  never invent a `link` field.
 - Infrastructure (proxy ranges, storage URLs, vendor rule identifiers) is an
   operator flag, never route YAML.
 

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

@@ -1,6 +1,6 @@
 ---
 name: urlcode-operations
-description: Deploy, verify, monitor and operate a URLCode project — process/container deployment, release readiness, verifying a live deployment against the project, capacity/audit/benchmark, observability, DDoS/overload resilience, and private management (grants, live-link credentials). Use when the user asks to deploy, check readiness, verify a running deployment, size/benchmark a project, monitor it, plan for overload, or manage live links/bindings. Reports operational limits and unimplemented capabilities as gaps instead of inventing mitigations.
+description: Deploy, verify, monitor and operate a URLCode project — process/container deployment, release readiness, verifying a live deployment against the project, capacity/audit/benchmark, observability, DDoS/overload resilience, and operator binding grants. Use when the user asks to deploy, check readiness, verify a running deployment, size/benchmark a project, monitor it, plan for overload, or manage bindings. Reports operational limits and unimplemented capabilities as gaps instead of inventing mitigations.
 ---
 
 # Operating a URLCode deployment
@@ -30,9 +30,7 @@ another version.
    overload and DDoS; what layer each defense belongs to.
 6. `docs/MONITORING.md` and `docs/OBSERVABILITY.md` — health/ready probes,
    logs, metrics format, what is and is not exported.
-7. `docs/MANAGEMENT-SECURITY.md` — the private management API: credential
-   policy shape, scope, loopback-only binding.
-8. `docs/POLICIES.md` and `docs/FUNCTION-SECURITY.md` — per-target policy
+7. `docs/POLICIES.md` and `docs/FUNCTION-SECURITY.md` — per-target policy
    support and the operator binding-grant process, needed whenever a
    deployment or verification step touches either.
 
@@ -71,28 +69,25 @@ urlcode verify-deployment --project ./my-links --target https://links.example \
 Run the actual commands and report actual results, never "should work" or
 "should be reachable". `verify-deployment` needs a real target; do not
 simulate its output. In a runtime checkout, substitute `node src/cli.ts` for
-`urlcode`. Pass `--policy`/`--link-store` where a snapshot needs bindings
-already reviewed by the operator.
+`urlcode`. Pass `--policy` where a snapshot needs bindings already reviewed
+by the operator.
 
 ## Hard limits — report these as gaps, never invent around them
 
-- No provider adapters, automatic TLS/DNS, distributed rate limiting, metrics
-  exporters or durable event delivery are included; these remain the
-  operator's own infrastructure.
+- Provider adapters exist with different capability limits; query
+  `urlcode capabilities --target NAME`. Automatic TLS/DNS, distributed rate
+  limiting, metrics exporters and durable delivery require operator infrastructure.
 - No orchestration, traffic switching or automated rollback; recovery is an
   explicit snapshot reload from a known-good artifact.
 - `verify-deployment` has no infrastructure access, uses no credential,
   follows no redirect and offers no `--insecure`. It cannot check anything a
   read-only HTTP probe cannot observe.
-- The private management API binds only `127.0.0.1`/`::1`; it is never meant
-  to be exposed through a public proxy or container port mapping, and browser
-  Origin requests are rejected regardless.
-- A management credentials policy is operator-owned, outside the application,
-  never in YAML or Git, at most 64 KiB, mode 600, at most 128 credentials with
-  explicit collection/action allowlists — no wildcards.
-- Sandbox concurrency, worker slots and execution deadlines are shared across
-  every programmable route in a snapshot; there is no per-route fairness or
-  reserved capacity, and awaiting a guest timer still occupies a slot.
+- Core has no durable store and no private management API of its own, and no
+  supported extension package provides stored short links.
+- Only `sandbox: true` routes share the sandbox worker slots and forced
+  execution deadlines. Trusted routes run in Node under HTTP admission limits;
+  their cooperative timeout cannot stop blocking JavaScript. A guest timer still
+  occupies a sandbox slot. Size both modes from `docs/CAPACITY.md`.
 - `throttle` and `agents` policy counters are per instance, not distributed;
   they are a second layer behind the edge, never a replacement for it.
 
@@ -102,10 +97,9 @@ responsibility that covers it instead of inventing a flag.
 
 ## Boundaries
 
-- Never generate or approve an operator binding grant, or a management
-  credentials policy, on the user's behalf. Both are the operator's own
-  reviewed decision; produce the shape and let them fill in and store the
-  real secret.
+- Never generate or approve an operator binding grant on the user's behalf.
+  That is the operator's own reviewed decision; produce the shape and let
+  them fill in and store the real secret.
 - Keep every credential, token and policy file out of source, examples and
   Git. A synthetic example value is fine; a real one is never committed.
 - Do not deploy, expose a service, rotate a credential, or run

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Claude plugins published from the URLCode repository.",
-    "version": "0.4.0-alpha.1"
+    "version": "0.4.0-alpha.3"
   },
   "plugins": [
     {

package/CONTRIBUTING.md

@@ -37,9 +37,11 @@ update docs when support changes. Do not claim a provider or OS is supported
 without a passing test run. Preserve portable behavior and useful self-hosting.
 
 Use synthetic data. Never commit secrets, customer URL collections or local
-environment files. Treat all application function code as untrusted. Never import it into Node or
-add an unsafe fallback. Capability grants must come from operator policy outside
-the project. Extend adversarial tests with every new guest/host bridge. See the
+environment files. Project function and middleware code runs trusted in Node by default. Preserve
+explicit `sandbox: true` isolation: never add a host-execution fallback for that
+mode. Binding grants come from operator policy outside the project and govern
+what URLCode injects, not ambient access by trusted code. Extend adversarial
+tests with every new sandbox guest/host bridge. See the
 [security model](docs/FUNCTION-SECURITY.md).
 
 ## Maintaining the starter
@@ -68,19 +70,19 @@ explicit in `docs/AI-AUTHORING.md`; never present future roadmap fields as valid
 
 ## Documentation
 
-Public documentation lives in
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs) and is authored
-there. It is not generated from this repository and must not be mirrored into
-it. Write new guides, references and recipes as a pull request against
-urlcode-docs.
-
-`docs/` here is contributor and maintainer material: local development, CI,
-the release process, internal reviews, spikes, plans and the generated
-`YAML-REFERENCE.md`. Reader-facing pages still under `docs/` are being
-migrated to urlcode-docs; edit them in place and do not add new ones.
+Documentation lives in `docs/` in this repository. Write new guides,
+references and recipes here, alongside the contributor and maintainer material
+already there: local development, CI, the release process, internal reviews,
+spikes, plans and the generated `YAML-REFERENCE.md`.
 
 A behavior change that a reader depends on is not finished until the matching
-urlcode-docs pull request exists. Link the two so review can see both halves.
+page in `docs/` is updated. Put both in the **same** pull request so review can
+see both halves and neither can land alone.
+
+`urlcode-docs` was deleted on 2026-09-19. It held its own copy of most of these
+pages and had drifted from them; the content that was ahead has been brought
+across, and the repository was retired rather than reconciled page by page.
+Links to it no longer resolve.
 
 If you find a gap you cannot close, file it as an issue on the repository that
 owns the code rather than leaving it undocumented. Feature requests are wanted:
@@ -93,8 +95,10 @@ Work on a branch and open a focused pull request. Explain the problem, resulting
 behavior, validation and compatibility/security implications. Never include real
 credentials or customer data. Use the PR template and keep unrelated changes out.
 
-`main` requires a pull request, an up-to-date branch, the required Node/OS verification
-jobs, container verification, CodeQL results and resolved conversations. High/critical
+`main` requires a pull request, the `verify-complete` and `container` checks,
+CodeQL results and resolved conversations. The current ruleset does not require
+an up-to-date branch. The [development pipeline](docs/DEVELOPMENT-PIPELINE.md)
+describes the fast prose lane, full code lane and exact-commit release gate. High/critical
 security findings and error-level CodeQL alerts block merging. Force pushes and branch
 deletion are blocked; squash merging keeps a linear history. Administrators have
 no configured ruleset bypass. Automation cannot approve pull requests.

package/README.md

@@ -1,8 +1,8 @@
 # URLCode
 
 **A portable runtime for programmable URL behavior, and the framework that grows
-from it.** Declare an application's public URL surface in YAML, add isolated
-JavaScript only where declarative handlers are not enough, and run the same
+from it.** Declare an application's public URL surface in YAML, add JavaScript
+only where declarative handlers are not enough, and run the same
 project locally, in a container, on your own infrastructure or on a provider
 adapter. When the project gets serious, add accounts and an administration
 console as operator-installed extensions instead of building them again.
@@ -20,22 +20,28 @@ and agents can read: the agent describes what, the runtime owns how, and
 generated code goes to the part that is actually the application. It is
 infrastructure for AI-built software, not a framework for building AI models.
 [Why](docs/PROJECT-DIRECTION.md#why-your-ai-should-build-your-application-not-your-framework) ·
-[next steps](docs/NEXT-STEPS.md).
+[roadmap](ROADMAP.md).
 
 ## What it is
 
 A project is a `urlcode.yaml` with `version: "1"`. Each route has exactly one
 handler: `redirect`, `respond`, `page`, `static`, `download`, `function`,
-`link`, `proxy`, `conditional` or an `extension` mount, with optional ordered
+`proxy`, `conditional` or an `extension` mount, with optional ordered
 `middleware`. The runtime validates the whole project before serving it,
 compiles it once, and refuses anything a target cannot enforce with the route
-named. Functions run in a QuickJS/WebAssembly sandbox with a fresh heap per
-call and no Node, filesystem or network; secrets reach them only through
-operator grants pinned to the project revision.
-
-URLCode is not a URL shortener: short links are one handler. It is not a
-general Node web framework: guest code cannot reach the host. It is not a
-provider configuration format: infrastructure settings stay out of route YAML.
+named. Functions and middleware run trusted, in-process, with full Node
+access by default; a route opts into an isolated QuickJS/WebAssembly sandbox
+with a fresh heap per call and no Node, filesystem or network by declaring
+`sandbox: true`. Either way, secrets reach them only through operator grants
+pinned to the project revision.
+
+URLCode is not a URL shortener: stored short links are an operator-installed
+extension, not core's job. It is not a
+general Node web framework: routing, validation, middleware wiring and
+policies are declared in YAML, not hand-wired; isolating a specific route's
+code from the host is an explicit `sandbox: true` opt-in, not something every
+route gets by writing a handler. It is not a provider configuration format:
+infrastructure settings stay out of route YAML.
 See [project direction](docs/PROJECT-DIRECTION.md).
 
 ## The framework
@@ -47,10 +53,33 @@ an AI agent must follow are in [the framework](docs/FRAMEWORK.md).
 
 | Package | Adds | Status |
 |---|---|---|
-| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, live links, provider adapters, extension contract | `0.4.0-alpha.1` (alpha) on top of the `0.3.0` release, Apache-2.0 |
-| [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.1.0-alpha.1` on npm, alpha: review pending |
-| [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.1.0-alpha.1` on npm, alpha: review pending |
-| [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.1.0-alpha.1` on npm, alpha: review pending |
+| [urlcode](https://github.com/jimhoyd-com/urlcode) (this repository) | Runtime, CLI, policies, provider adapters, extension contract | `0.4.0-alpha.2` (alpha) on top of the `0.3.0` release, Apache-2.0 |
+| [urlcode-ui](packages/ui) (in this repository) | Shared presentation: escaped templates, shadcn/ui partials, themes, translations | `0.1.0-alpha.5` on npm, alpha: review pending |
+| [urlcode-auth](packages/auth) (in this repository) | Accounts: password, passkeys, OIDC, email codes, TOTP, sessions, roles, account page | `0.1.0-alpha.3` on npm, alpha: review pending |
+| [urlcode-admin](packages/admin) (in this repository) | Administration: users, sessions, roles, audit, approvals, cases, impersonation | `0.1.0-alpha.3` on npm, alpha: review pending |
+
+Every version in this table is the one published to npm under the `alpha`
+dist-tag, and they are released together in the order core → ui → auth →
+admin. The authoritative cross-repository register, including each
+package's declared peer ranges and the rules that keep them consistent, is
+[docs/VERSION-ALIGNMENT.md](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
+their repositories deleted, and neither has a successor. Nothing supported
+provides stored short links today — a project that needs them owns that storage
+itself. Anything still pinned to `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1`
+also has to deal with its exact declared peer `@jimhoyd/urlcode: 0.4.0-alpha.1`,
+which cannot be installed beside core `0.4.0-alpha.2` and never will be.
+
+`urlcode-middleware` was retired the same way on 2026-09-19 —
+`@jimhoyd/urlcode-middleware` was unpublished from npm at `0.1.0-alpha.2` and
+its repository deleted. Unlike the two above, its capability did not go away
+with it: **per-route middleware is native to core**, through the
+`middleware:` array documented in [docs/MIDDLEWARE.md](docs/MIDDLEWARE.md).
+The deleted package only ever offered the same behavior through the extension
+seam. A project using it moves its entries to the native array; there is no
+gap to report here.
 
 ```yaml
 version: "1"
@@ -74,23 +103,25 @@ it. Cross-repository acceptance is tracked in
 
 ## Status
 
-`0.4.0-alpha.1` is the current release of the extension contract and the
-agent tooling, on top of the `0.3.0` self-hosted release. It adds the
-extension contract, capabilities and provider conformance, strict redirect
-interchange, bulk import, recipes and search, TypeScript guest authoring,
-conditions, bounded proxy and signals, and the MCP read and authoring modes;
-use the schema and docs from the runtime revision you run.
+`0.4.0-alpha.2` is the current release of the extension contract and the
+agent tooling, on top of the `0.3.0` self-hosted release. `0.4.0-alpha.1`
+added the extension contract, capabilities and provider conformance, strict
+redirect interchange, bulk import, recipes and search, TypeScript guest
+authoring, conditions, bounded proxy and signals, and the MCP read and
+authoring modes. `0.4.0-alpha.2` then made `function` and `middleware` routes
+run trusted and unsandboxed by default, with `sandbox: true` as a per-route
+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.
 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
 remain open.
 
-Live-link storage uses separate bounded reader/writer pools. It requires a Node
-build containing a patched SQLite version — 3.51.3 or newer, 3.50.7, or 3.44.6 —
-which some current releases on a supported Node line do not carry. Run
-`urlcode doctor` and check `liveLinks` before relying on it; everything else
-runs on any supported Node.
-See [pool controls and scaling limits](docs/DYNAMIC-LINKS.md#separate-reader-and-writer-pools).
+Core has no native `link` handler. Stored short links moved out to a
+mount-based `urlcode-dynamic-link` extension, which has since been retired and
+unpublished; no supported package provides them.
 
 URLCode is free and open-source software licensed under the
 [Apache License 2.0](LICENSE). Commercial use, modification, redistribution and
@@ -109,6 +140,14 @@ project grows. Operators should read [capacity/concurrency](docs/CAPACITY.md) an
 [DDoS and recovery playbook](docs/RESILIENCE.md). Embedding the runtime from
 TypeScript is covered in [TypeScript](docs/TYPESCRIPT.md). [All documentation](docs/README.md).
 
+All of it lives in [`docs/`](docs/README.md) in this repository — guides,
+references and recipes alongside the contributor and maintainer material: local
+development, CI, the release process, reviews and the generated field
+reference. New pages belong here, in the same pull request as the change they
+describe. `urlcode-docs`, a private repository that served a documentation site
+from its own copy of these pages, is being retired; the content that was ahead
+of this repository has been brought across.
+
 ## Start your own project
 
 Use [urlcode-template](https://github.com/jimhoyd-com/urlcode-template) for a small
@@ -123,42 +162,14 @@ npm ci
 npm run dev
 ```
 
-Live stored-link routes require **`dynamicLinks: true`** in the entry `urlcode.yaml`;
-the starter explicitly sets false. Ordinary functions and parameterized redirects
-do not need it. [Live-link setup](docs/DYNAMIC-LINKS.md).
-
-## Built with URLCode
-
-[urlcode-shortener](https://github.com/jimhoyd-com/urlcode-shortener) is a
-standalone, account-free demo built on URLCode's public runtime and storage APIs.
-It combines short links that expire after one hour or less, QR downloads, and a
-shadcn/ui + Tailwind frontend. URLCode handles the page/assets and stored-link
-redirects; the application adds anonymous creation and its own limits.
-
-Read its [build retrospective](https://github.com/jimhoyd-com/urlcode-shortener/blob/main/docs/BUILD-RETROSPECTIVE.md)
-for what the runtime supplied, what the application still needed, and proposed
-improvements. The demo's license, hosting and production validation remain open;
-it does not change URLCode's Apache-2.0 license or guest isolation model.
-
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs) demonstrates URLCode
-hosting a static documentation site with shadcn/ui and Tailwind. It syncs this
-repository’s Markdown and examples at a pinned revision, applies templates through
-sandboxed middleware during the build, and serves the output through native
-page/static/download routes. This repository remains the documentation source of
-truth. See the [docs-site retrospective](https://github.com/jimhoyd-com/urlcode-docs/blob/main/docs/BUILD-RETROSPECTIVE.md)
-for reuse, integration work and upstream improvements. Hosting and a public domain
-are not yet selected; the original site-code license is pending.
-
 ## Start from YAML
 
 Already wrote `urlcode.yaml`? Run `urlcode scaffold --project ./my-links --dry-run`,
 then remove `--dry-run` to create missing modules, pages and directories. Existing
 files are preserved; code placeholders return 501 until implemented.
-[Scaffolding guide](docs/SCAFFOLDING.md).
-Live-link storage and the auth extension need a Node build whose SQLite is
-3.51.3 or newer, 3.50.7 or 3.44.6. `urlcode doctor` reports `liveLinks`;
-everything else runs on any supported Node (22.13+ installed, 22.18+ to run
-the TypeScript source).
+[Scaffolding guide](docs/SCAFFOLDING.md). Node 22.13+ installed, 22.18+ to run
+the TypeScript source; the separate `urlcode-auth` extension may have its own
+SQLite build requirement, unverified from this repository.
 
 ## Try it
 
@@ -204,9 +215,6 @@ and [middleware](docs/MIDDLEWARE.md).
 
 - **Pages, files, downloads:** `page`, `static`, `download` with MIME detection,
   ETags, ranges and safety limits. [Assets](docs/ASSETS.md).
-- **Live short links:** a `link` route on an optional SQLite store; create,
-  update and delete without reloads through the CLI or the private management
-  API. [Dynamic links](docs/DYNAMIC-LINKS.md).
 - **HTTP:** methods, validated path/query/header inputs, body limits, response
   headers and cookies. [HTTP](docs/HTTP.md).
 - **Policies and site conventions:** throttle, agents, security headers,
@@ -227,11 +235,13 @@ and [middleware](docs/MIDDLEWARE.md).
 Self-hosted Node process or container first. `@jimhoyd/urlcode/vercel` and
 `@jimhoyd/urlcode/aws` serve declarative projects as native handlers;
 `urlcode build --target cloudflare` compiles redirects and declared responses
-into a Worker. Each target refuses at activation or build time what it cannot
+into a Worker; `urlcode build --target static` compiles redirects and static
+files into plain objects and redirect metadata for S3 + CloudFront, with no
+server at all. Each target refuses at activation or build time what it cannot
 run, with the route named. None has been exercised on its provider yet; the
 adapters have local conformance tests only. [Operations](docs/OPERATIONS.md),
 [capabilities](docs/CAPABILITIES.md), [Vercel](docs/VERCEL.md), [AWS](docs/AWS.md),
-[Cloudflare](docs/CLOUDFLARE.md).
+[Cloudflare](docs/CLOUDFLARE.md), [static hosting](docs/STATIC.md).
 
 ## For AI agents
 
@@ -242,25 +252,18 @@ inspection, validation and conversion previews over stdio, and
 `--allow-authoring` adds project-confined authoring tools
 ([tooling](docs/TOOLING.md)).
 
-## Documentation
-
-Full documentation lives in
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs). It is authored
-there directly, not generated from this repository, and it is where new guides,
-references and recipes belong.
-
-`docs/` in this repository is contributor and maintainer material — local
-development, CI, the release process, reviews and the generated field
-reference. Reader-facing pages still under `docs/` are being migrated.
-
 ## Built with URLCode
 
-[urlcode-short](https://github.com/jimhoyd-com/urlcode-short), an
-account-free short-link demo with a shadcn/ui front end, and
-[urlcode-docs](https://github.com/jimhoyd-com/urlcode-docs), a static
-documentation site rendered through sandboxed middleware at build time. Both are
-ordinary consumers of the public runtime; their retrospectives list what the
-runtime supplied and what they still had to build.
+Two applications were built on the public runtime as ordinary consumers, and
+both have since been retired: `urlcode-docs`, a static documentation site
+rendered through its own middleware at build time and served through native
+page/static/download routes, and `urlcode-short`, an account-free short-link
+demo combining expiring links, QR downloads and a shadcn/ui frontend — URLCode
+supplied the pages, assets and routing, the application supplied anonymous
+creation, link storage and its own limits. `urlcode-short`'s repository is
+deleted, so its build retrospective is no longer reachable; what it recorded
+about the gap between the runtime and a real application is carried in
+[principles and open decisions](docs/OPEN-DECISIONS.md) and [roadmap](ROADMAP.md).
 
 ## License and contributing