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

package/docs/OPEN-DECISIONS.md

@@ -1,212 +1,184 @@
-# Open decisions
-
-Status: written 2026-09-19 from a review of the nine repositories. Every item
-here is a maintainer decision that documentation cannot make. Each states what
-is actually true today, what the options are, what it costs to leave open, and
-a recommendation. Nothing here is committed scope; the
-[roadmap](../ROADMAP.md) owns sequence and the
-[readiness register](RELEASE-READINESS.md) owns what is proven.
-
-This page exists because several documented positions have drifted apart from
-each other and from the source. The drift is not the decisions themselves — it
-is that they were never recorded in one place where the next contributor, human
-or agent, would look.
-
-## 1. Publish `0.4.0-alpha.2` — decided
-
-**Decided 2026-09-19: publish `alpha.2`.** The recommendation below was taken
-rather than walking back a correct declaration. The alignment is prepared
-across all nine repositories and the order is recorded in
-[the version register](VERSIONS.md); what remains is merging and tagging.
-
-The second hazard was taken with it: `@jimhoyd/urlcode-auth` moves `latest`
-up to `0.1.0-alpha.2` so that a plain `npm install` no longer resolves a build
-older than the floor `@jimhoyd/urlcode-admin` declares. That is a registry
-operation (`npm dist-tag add`), not a source change, and it is listed in the
-release steps.
-
-The original entry, for the record:
-
-> **Today:** the repository source is `0.4.0-alpha.2`. The npm dist-tags are
-> `latest = 0.3.0` and `alpha = 0.4.0-alpha.1`. `alpha.2` carries the
-> trusted-by-default execution change ([the decision](SPIKE-DEFAULT-TRUST-MODEL.md)).
->
-> **Why it blocks other things:** `@jimhoyd/urlcode-middleware@0.1.0-alpha.1` is
-> published with `peerDependencies: { "@jimhoyd/urlcode": ">=0.4.0-alpha.2" }`.
-> No published core version satisfies that range, so a registry install of that
-> package cannot resolve its peer. The range is correct; the publication order
-> was not.
->
-> **Recommendation:** publish `alpha.2`. It is the only option that does not
-> require walking back a correct declaration.
-
-## 2. Consolidate the repositories, or commit to the split
-
-**Today:** nine repositories. [The monorepo spike](SPIKE-MONOREPO.md) is
-complete, its layout is marked decided (option A), its migration mechanics and
-sequencing are written, and it has three open questions for the maintainer. It
-has been neither accepted nor rejected. It was drafted for four repositories;
-`urlcode-dynamic-link`, `urlcode-middleware` and `urlcode-short` have appeared
-since.
-
-**Cost of leaving it open:** the migration gets larger with every repository
-added, and the coordination work the spike describes — pinning reviewed peer
-revisions by hand, chasing prose across repositories when a contract changes —
-is paid again on every contract change in the meantime.
-
-**Recommendation:** decide before the next structural change, in either
-direction. A recorded "no, and here is what we do instead about cross-repo
-drift" closes this as well as a yes does.
-
-## 3. One way to attach middleware, or two
-
-**Today:** core has the native `routes.<path>.middleware[]` array.
-`urlcode-middleware` provides the same capability through the extension seam
-and states that core's native array "keeps working unchanged".
-[The layering spike](SPIKE-CORE-LAYERING.md) proposed *extracting* middleware
-to narrow core to YAML plus `function`; what exists is an addition alongside it.
-
-**Why this is a principle question:** the
-[extension model review](SPIKE-EXTENSION-MODEL.md) rejected an earlier design
-for exactly this reason — two ways to protect a route would drift apart — and
-resolved it by removing one. The same test applies here.
-
-**Options:** deprecate the native array on a stated timeline and complete the
-extraction; or keep both and document precisely when each is correct, treating
-the extension as a bounded variant rather than a successor.
-
-**Recommendation:** decide explicitly and write the answer into both
-repositories. Either is defensible; leaving both undescribed is not.
-
-## 4. Where the backlog lives
-
-**Today:** [next steps](NEXT-STEPS.md) holds roughly thirty tracked items
-across nine phases. The repository has one open issue (#58). `AGENTS.md`
-instructs contributors and agents to file what they find as issues on the
-owning repository.
-
-**The contradiction:** the instruction points at the issue tracker; the actual
-plan is a Markdown file that no tracker reflects. A plan document also has no
-state, so items stay written as future work after they ship — which is how
-route-level `auth` came to be described as an invented field in merged agent
-guidance (see item 7).
-
-**Options:** move the phase items into issues and keep the document as the
-narrative that links them; or keep the document as the system of record and
-amend `AGENTS.md` to say so.
-
-**Recommendation:** issues for items, document for sequence. It is the only
-arrangement where "done" is recorded automatically.
-
-## 5. Gate the business suite on evidence
-
-**Today:** [the business suite spike](SPIKE-BUSINESS-SUITE.md) proposes seven
-applications. [Project direction](PROJECT-DIRECTION.md) states the evidence
-test: the framework grows from measured repetition, not from a list of things
-applications might need. Phase 6 of [next steps](NEXT-STEPS.md) says candidate
-areas are built only when the repetition log shows them repeating. The
-repetition log does not exist yet, and the Phase 0 agent benchmark has not been
-run.
-
-**Recommendation:** record on the spike itself that it is gated behind the
-benchmark and the repetition log, or amend the evidence test. Holding both
-positions unannotated makes the stated principle decorative.
-
-## 6. Finish the documentation move, or describe the split
-
-**Today:** `AGENTS.md` states that urlcode-docs is the documentation home and
-the only place readers are sent, that new reader-facing pages go there, and
-that pages still under `docs/` here are being migrated. Roughly forty
-reader-facing pages remain in this repository, several duplicated in
-urlcode-docs.
-
-**Observed consequence:** the same fact drifts between copies. The public
-documentation site carried the correct trusted-by-default contract while
-`docs/OPERATIONS.md` in this repository still described functions as untrusted
-and isolated by default. <!-- trust-model-prose: historical -->
-
-**Options:** finish the migration against a dated list; or state which pages
-stay here permanently and why, and add a check that fails when a new
-reader-facing page appears beside them.
-
-## 7. A review window, and a check that does not need one
-
-**Today:** [governance](../GOVERNANCE.md) records one maintainer, a required
-approval count of zero, and that "an independent human review is not yet
-guaranteed". Pull requests and CI are mandatory; a second pair of eyes is not.
-
-**What that permitted, concretely:** on 2026-09-19, three coordinated pull
-requests (urlcode#158, urlcode-template#6, urlcode-docs#17) opened and merged
-within nine minutes. They recorded a genuine improvement — the declarative-first
-principle, propagated to every copy in one change — and alongside it the
-statement that agents must "never invent an `auth` field". Route-level `auth` is
-implemented: it is defined in `schemas/urlcode.schema.json` as a short form
-expanding to `policies.extensions.auth`, expanded in `src/config.ts`, typed in
-`src/types.ts`, and asserted in `test/recipes.test.ts`. The guidance now
-instructs agents away from a supported declarative short form and toward the
-lower-level policy form — the opposite of the principle the same change
-introduced — in the generated project guide, the bundled starter, both
-authoring skills, the packaged plugin skill and the two generated `llms` files.
-
-Nothing failed. Lint, typecheck, generated-resource checks, the package smoke
-test and 501 tests all passed, because no check compares what the guidance
-claims against what the schema implements.
-
-**The check, now implemented.** `scripts/check-guidance-claims.ts` runs inside
-`npm run check` and exits non-zero on a contradiction between agent-facing
-guidance and the schema, so this class of error fails CI instead of depending on
-a reviewer's attention:
-
-- Inputs: the agent-facing surfaces — `src/agents-guide.ts`,
-  `starters/default/AGENTS.md`, `skills/urlcode/SKILL.md`,
-  `.claude/skills/*/SKILL.md`, `packaging/claude-plugin/skills/*/SKILL.md`,
-  `llms.txt`, `llms-full.txt`, `docs/AI-AUTHORING.md`.
-- Assertion one: every YAML field named as valid in those files resolves in
-  `schemas/urlcode.schema.json`. A guidance file may not teach a field the
-  schema does not accept.
-- Assertion two, the one that would have caught this: no field that the schema
-  *does* define is described as unsupported, invented or nonexistent. Match the
-  negative phrasings deliberately ("never invent", "does not exist",
-  "unsupported field") within a short window of a schema-resolvable field name.
-- Assertion three: handlers listed as available match the capability catalog,
-  so a removed handler (`link`, extracted to `urlcode-dynamic-link` in
-  `f7dbe54`) cannot linger in generated guidance.
-- Exits non-zero on violation, with a documented `<!-- guidance-claims: ignore -->`
-  marker for text that is deliberately about another version. Verified against
-  both regressions: reintroducing the "never invent an `auth` field" sentence
-  fails the check, and adding the removed `link` handler to the inventory line
-  fails it.
-
-What remains a decision: whether `npm run check` membership is enough, or the
-check should also be named in the repository's required status checks so it
-cannot be bypassed.
-
-**Recommendation:** the check is in; keep it required. It is the part that does
-not depend on a person being available. Whether to
-also raise the required approval count is a separate call, and
-[governance](../GOVERNANCE.md) already states the condition — when the trusted
-maintainer team grows.
-
-## 8. One publishing convention
-
-**Today:** `urlcode-dynamic-link` and `urlcode-middleware` keep
-`"private": true` on their main branch and drop it in the release commit;
-`urlcode-auth`, `urlcode-admin` and `urlcode-ui` do not. All are published.
-Both practices are defensible; having both means the flag no longer indicates
-publication state.
-
-**Recommendation:** pick one and state it where release process is documented.
-
-## 9. Adjudicate the vendored skill drift
-
-**Today:** `npm run check:downstream-skills` reports that `urlcode-template`'s
-vendored authoring and operations skills differ from core's current `main` by
-79 and 91 lines. The report is advisory by design and never fails, because a
-downstream repository can correctly pin an older published core version
-([issue 155](https://github.com/jimhoyd-com/urlcode/issues/155)).
-
-**What is missing:** the judgment the report defers. No one has read the two
-diffs and recorded which side is right for the template's `0.4.0-alpha.1` pin.
-
-**Recommendation:** review both diffs once, record the verdict, and re-run the
-report when the template repins.
+# Decisions to align
+
+Reviewed 2026-09-19 against core `db375bf` and the current public package sources.
+This is the maintainer's decision list, not a second implementation backlog.
+The [roadmap](../ROADMAP.md) gives sequence and the [archive](archive/README.md)
+keeps earlier discussions. Recommendations below are not accepted decisions.
+
+## Principles already settled, in plain language
+
+- **Describe first, code only when needed.** Use a supported YAML feature or
+  extension before writing plumbing. Custom application code is still welcome.
+- **Your application code runs like normal Node code.** Functions and middleware
+  are trusted by default. `sandbox: true` deliberately restricts a route's whole
+  function/middleware chain. Request data still needs validation in either mode.
+- **A grant controls what URLCode supplies, not what trusted code can access.**
+  Trusted code can independently read the host environment, files and network.
+  Opt-in sandboxing retains its existing isolation and revision-pinned grants.
+- **Portable does not mean every host supports every feature.** Keep infrastructure
+  out of route YAML and reject unsupported targets before activation.
+- **Core works alone; optional packages add accounts, admin and presentation.**
+  Core never imports those implementations. Shared UI belongs in `urlcode-ui`.
+- **Documentation stays beside the owning code.** Core guides live here;
+  extension contracts and implementation status live in their repositories.
+  `urlcode-docs` is deleted. `urlcode-short` and `urlcode-dynamic-link` are retired.
+- **Passing tests proves the tested behavior.** It does not prove deployment,
+  accessibility, hostile tenant isolation or independent security assessment.
+- **Keep the free runtime useful.** Apache-2.0 remains unchanged; no mandatory
+  hosted account, paid capability gate or provider lock-in belongs in core.
+
+## Decisions still needed
+
+| Decision | What the code says today | Recommendation and consequence |
+|---|---|---|
+| Where does work status live? | Several old plans repeated issues and continued calling delivered work unfinished. | Issues for actionable status, this short roadmap for sequence, archive for completed proposals. Preserve evidence gaps when archiving. |
+| Expand into business applications now? | No collection handler or proposed business suite is implemented; the model-backed benchmark evidence is missing. | Measure existing tasks and record repeated application plumbing before selecting a collection/CMS/forms project. Retired short-link products stay retired. [Proposal](SPIKE-BUSINESS-SUITE.md). |
+| Which provider execution model next? | AWS/Vercel still reject function/middleware despite the trusted default. | Decide demand first, then compare one Node deployment per project against one Lambda per route. Do not promise either today. [Proposal](SPIKE-LAMBDA-COMPILE.md). |
+| Fold extension schemas into retrieved context? | `urlcode extensions` and the MCP `get_extensions` query return the registered configuration and policy schemas, but `src/context.ts:113` reports `extensions` as names only, so an author writing `extensions.<name>.config` or `policies.extensions.<name>` must run the separate operator-authorized query first. | Decide from retrieval and task evidence, not preference: the existing small-task harness can measure whether folding schemas into bounded context improves authoring. Keep the token budget bounded and never auto-load a project-selected host file. This is a discovery improvement, not a defect in the existing query. |
+| Retire the UI primitive fallback? | Auth and admin use the kit when supplied, and retain tested primitive rendering without it. | Keep both until an explicit compatibility/deprecation decision; adoption is already implemented. |
+
+The broader [AI benchmark proposal](SPIKE-AI-FRAMEWORK-BENCHMARK.md) also needs a
+chosen application, model-run budget and execution authorization. The existing
+small-task harness can supply evidence without committing to that larger study.
+
+## Closed questions removed from the active list
+
+- Publishing convention is recorded in [version alignment](VERSION-ALIGNMENT.md):
+  publishable manifests on main, releases through reviewed tags/workflows.
+- Core `0.4.0-alpha.2` and current extension releases exist; publishing that
+  already-shipped version is not a next step.
+- Auth/admin kit adoption and shared form helpers are implemented in their code.
+- The template pins `0.4.0-alpha.2`. Its skill differences were read against that
+  pin: omitted handlers and advice about the removed management API are stale,
+  not intentional older-version behavior.
+- The guidance checks run through `npm run check` inside `verify`; a regex check
+  is not a schema validator for every example. Extending its coverage is tracked
+  separately, not a reason to weaken review or bypass required checks.
+
+## Accepted: per-package release tags
+
+**Decided 2026-09-19.** Workspace packages under `packages/` release on
+Changesets' own `<package name>@<version>` form — for example
+`@jimhoyd/urlcode-ui@0.1.0-alpha.6`. Core keeps bare `v*`.
+
+**The problem.** Core and all three extensions arrived here triggering on
+`tags: ['v*']`, and their alpha tags overlap outright: ui shipped
+`v0.1.0-alpha.2` through `-alpha.5`, admin `v0.1.0-alpha.1` and `-alpha.3`,
+auth `v0.1.0-alpha.1` through `-alpha.3`. Across four repositories that was
+fine. In one repository a single bare tag push starts more than one release
+workflow. Each one fails closed on its own tag-matches-manifest check, so
+nothing can mis-publish — but "two workflows race and one errors on every
+release" is not a release process, and the failure is confusing rather than
+informative.
+
+**Why Changesets' form rather than a prefix like `ui-v0.1.0-alpha.6`.** Both
+work and both are valid ref names. The deciding factor is that Changesets is
+already the chosen release flow, and `changeset tag` emits the
+`<name>@<version>` form natively. Picking anything else means writing and
+maintaining a translation layer between the tool that computes the version and
+the tag that triggers the publish — new code whose only job is to disagree
+with a default. The spike chose Changesets partly because it is "cheap and
+low-risk for an agent or a human to generate correctly"; hand-rolling the tag
+shape undercuts exactly that.
+
+**Why the two schemes cannot collide.** A scoped package name begins with `@`,
+and GitHub's `v*` filter requires a leading `v`, so no tag can match both.
+Verified rather than assumed, including that `*` does not match `/` in a filter
+pattern, so `@jimhoyd/urlcode-ui@*` matches the version segment only.
+
+**Core's asymmetry is forced, not preferred.** Under layout A core is the
+repository root rather than a workspace member, so Changesets does not manage
+it and `changeset version` will not bump it. Core therefore keeps the tag
+scheme and release workflow it already had.
+
+[`scripts/check-release-tags.ts`](../scripts/check-release-tags.ts) enforces
+this in `npm run check`: it rejects a workspace package workflow that does not
+trigger on its own `<name>@*`, rejects any workflow other than core's claiming
+`v*`, and independently asserts that no two filters can match the same tag. The
+reasoning above is the kind of prose that rots as soon as `auth` and `admin`
+arrive, which is the whole argument this repository makes for enforcing checks
+over documented intent.
+
+## Done: the monorepo migration is complete
+
+**Closed 2026-09-19.** `urlcode-ui`, `urlcode-auth` and `urlcode-admin` are
+workspace packages under `packages/`, and all three have been released from
+this repository — `@jimhoyd/urlcode-ui@0.1.0-alpha.6`,
+`@jimhoyd/urlcode-auth@0.1.0-alpha.6`, `@jimhoyd/urlcode-admin@0.1.0-alpha.4`,
+each on `alpha` with `latest` deliberately held behind. Core's dist-tags are
+unchanged. The three source repositories are gone; their history survives only
+as verified `git bundle`s, because the repository allows squash merges only and
+the imported commits did not survive onto `main`.
+
+The operational runbook is [DEVELOPMENT-PIPELINE.md](DEVELOPMENT-PIPELINE.md)
+and [RELEASE-SECURITY.md](RELEASE-SECURITY.md). The plan itself is archived at
+[archive/2026-09-19/SPIKE-MONOREPO.md](archive/2026-09-19/SPIKE-MONOREPO.md),
+whose closing note records what the plan got wrong — chiefly that its
+strongest argument, the reach of the enforcing checks, only became true after
+both checkers were changed to discover workspace packages.
+
+The section below is kept for the middleware decision it records, which is
+still the reason there is no `packages/middleware`.
+
+## Accepted: monorepo first — middleware withdrawn rather than consolidated
+
+The maintainer confirmed that monorepo work is starting now. The earlier
+recommendation to keep repositories separate for now is superseded.
+
+**Reversed 2026-09-19: the middleware half of this decision no longer applies.**
+This section used to say "move middleware into the monorepo as its own package
+first, preserving its existing API and behavior," and explicitly: "do not
+unpublish or retire the middleware package as part of the initial move."
+That instruction was overtaken. `@jimhoyd/urlcode-middleware` has been
+**unpublished** from npm at `0.1.0-alpha.2` and `jimhoyd-com/urlcode-middleware`
+**deleted** — the package was withdrawn outright instead of migrated, so there
+is no `packages/middleware` to create and no subsequent fold-into-core step.
+The reversal is recorded here rather than deleted because the instruction it
+replaces was explicit, and a reader who remembers it should be able to see that
+it was changed deliberately and not simply forgotten.
+
+Nothing was lost in capability terms: per-route middleware is **native to
+core** via the `middleware:` array ([MIDDLEWARE.md](MIDDLEWARE.md)), and the
+deleted package only ever offered the same behavior through the extension
+seam. Trust remains the default and explicit sandbox choices keep their
+meaning. The generic extension wrapping hook (`ExtensionInstance.middleware`,
+`RuntimeExtension.cacheSensitive`) stays in core's contract for other
+extensions — it is no longer exercised by any shipped package, which is worth
+knowing before it is assumed to be covered. Static targets continue rejecting
+request-time middleware because there is no server to run it.
+
+Migration scope is therefore **core, auth, admin and UI**. Template and the
+distribution tap stay outside that package move. The observed stale peer pins
+and checkout-limited guidance checks strengthen the case for shared
+verification: carry those checks across the new package paths, since merely
+moving files does not prove every generated skill is covered. The cleanup PRs
+that superseded the earlier zero-open-PR survey have since merged, and a fresh
+survey again reports zero open pull requests across all four in-scope
+repositories — re-run it per repository immediately before that repository
+moves rather than trusting this line.
+
+The [archived monorepo plan](archive/2026-09-19/SPIKE-MONOREPO.md) records
+migration context.
+[Issue 172](https://github.com/jimhoyd-com/urlcode/issues/172), which tracked
+"consolidate middleware into core after moving it into the monorepo," is
+**moot and still open** — there is nothing left to consolidate. It should be
+closed with a pointer to this section. Migration starting is not a claim that
+it has landed.
+
+## Source review baseline
+
+| Repository | Reviewed commit | Code checked |
+|---|---|---|
+| core | `db375bf` | Runtime dispatch, schema normalization, capabilities, static compiler, prerender, MCP and resource generators |
+| auth | `71957dd` | Lifecycle hooks, UI rendering and shared helper imports |
+| admin | `f3b4882` | UI rendering, auth-service integration and shared helper imports |
+| UI | `0e96f7f` | Shared forms, kit/host exports and copied core contract |
+| ~~middleware~~ | `f201f4b` | Extension wrapping, per-entry sandbox dispatch and scaffolding — **repository deleted 2026-09-19; this baseline is unreachable except through the local `urlcode-middleware.bundle`** |
+| template | `4e09e50` | Exact core pin, generated guide and both vendored skills |
+
+The Homebrew tap (`73eaaef`) still selects stable core `0.3.0`; its old trust
+behavior belongs to that pin and must not be rewritten as alpha.2 behavior.
+The other organization tap and Scoop bucket contain Gitroll, not URLCode.
+The deleted documentation repository is historical context, not a second source
+of current contracts; its former GitHub links no longer resolve. This review is targeted source inspection, not an audit of
+every execution path or an independent security assessment.

package/docs/OPERATIONAL-PROOF.md

@@ -13,9 +13,9 @@ only (3 of the 9 combinations); the macOS/Windows legs only run once a PR
 merges, per `.github/workflows/ci.yml`'s matrix.
 
 Core has no durable store of its own, so this drill has no backup/restore or
-disk-exhaustion exercise: a future extension package owning durable state
-(such as the planned `urlcode-dynamic-link`) is responsible for its own
-persistence proof once it exists.
+disk-exhaustion exercise: an extension package owning durable state is
+responsible for its own persistence proof. No such package ships today — the
+`urlcode-dynamic-link` package that did has been retired.
 
 ## Required proof on the intended deployment
 

package/docs/OPERATIONS.md

@@ -149,9 +149,9 @@ deployment controls, not portable route behavior. Horizontal replicas
 must use identical application/config versions and secret bindings. In-memory
 function state is reset after every invocation, not durable/shared application state.
 General application storage needs a future explicit capability broker; no
-storage/network access is exposed to the guest. Stored short links are moving
-to a future `urlcode-dynamic-link` extension package, not yet published; core
-no longer has a native link store.
+storage/network access is exposed to the guest. Core no longer has a native
+link store, and the `urlcode-dynamic-link` extension package that replaced it
+has been retired and unpublished.
 
 The health version combines route-definition and asset-representation digests;
 it does not identify the complete function/runtime release. Record runtime commit,

package/docs/POLICIES.md

@@ -3,9 +3,10 @@
 Policies are host-enforced behavior declared in YAML around a route: a
 per-client request budget, a User-Agent deny list, a security-header profile,
 content-coding negotiation and an HTTP caching strategy. They run in the host
-process, outside the sandbox, so they can see the client address, keep counters
-across requests and touch the transport, which route middleware by design
-cannot ([middleware](MIDDLEWARE.md), [function security](FUNCTION-SECURITY.md)).
+process, outside function/middleware execution — trusted or sandboxed alike —
+so they can see the client address, keep counters across requests and touch
+the transport, which route middleware by design cannot
+([middleware](MIDDLEWARE.md), [function security](FUNCTION-SECURITY.md)).
 
 Everything here is optional and off by default. A project with no `policies`
 key and no `profiles` key behaves exactly as before: no policy module is
@@ -20,7 +21,7 @@ compiled and the request path is unchanged. Each policy has its own page:
 | `cache` | [cache](policies/cache.md) | Named strategies from RFC 9111/5861/8246/9213 plus an origin memory cache |
 
 The design and the reasoning behind each choice are in the
-[extensions spike](SPIKE-EXTENSIONS.md). Operators who need behavior the
+[extensions spike](archive/2026-09-19/SPIKE-EXTENSIONS.md). Operators who need behavior the
 declarative block cannot express pass host [plugins](PLUGINS.md) in code; plugins
 are never named in YAML.
 
@@ -42,7 +43,14 @@ routes:
 `policies` at the top level sets project defaults; `routes.<path>.policies`
 adjusts them for one route. Two route-level short forms exist. `auth`
 expands to `policies.extensions.auth` when the project declares an auth
-[extension](EXTENSIONS.md). `cache: {strategy, maxAge, ...}` expands to
+[extension](EXTENSIONS.md), carrying the same keys minus `required`;
+`required: false` documents the intent and emits no policy. It accepts
+`required`, `role`, `permission`, `verified`, `freshWithinSeconds` and
+`onDeny` and nothing else — `role` is singular, and there is no `roles`. Like
+`cache` below, it is refused rather than silently ignored in three cases: when
+the project declares no `extensions.auth`, when the route also sets
+`policies.extensions.auth` (use one form), and when the route sets
+`policies.extensions: false`. `cache: {strategy, maxAge, ...}` expands to
 `policies.cache` the same way — the compiler merges it into that route's
 `policies` before anything else reads the project, so `routes`, `audit` and
 `explain` see only the expanded long form, and it is refused alongside a

package/docs/PRERENDER.md

@@ -2,8 +2,10 @@
 
 Render a project's function and middleware routes once, at build time, into a
 project whose routes are all native `page` handlers. The published site answers
-from prevalidated byte buffers: no guest code runs to serve a request, so the
-sandbox, its deadline and its memory budget are not on the request path at all.
+from prevalidated byte buffers: no guest code runs to serve a request at all,
+so whatever execution mode the source routes used — trusted by default, or
+isolated QuickJS/WASM where a route declares `sandbox: true` — along with its
+deadline and memory budget where sandboxed, is not on the request path.
 
 The shared orchestration ships as a build helper, `@jimhoyd/urlcode/prerender`, and the
 runnable recipe is [`examples/prerender`](../examples/prerender/README.md), which
@@ -24,7 +26,7 @@ and publish the result:
 
 ```
 function + template middleware  ──render once──▶  HTML file  ──▶  page route
-        (sandbox, build time)                                   (no sandbox)
+   (trusted or sandboxed, build time)                        (no guest code)
 ```
 
 The alternative — reading Markdown through `next().text()` on a native route —
@@ -111,9 +113,11 @@ specifically:
   instead of hanging on its worker threads.
 
 The helper is operator build tooling. It runs in Node with normal filesystem
-access because it is not guest code; nothing here gives the sandbox a filesystem,
-and no host-code fallback is introduced. It is a separate package export from the
-runtime for that reason. Review it as you review any deployment tooling.
+access because it is not guest code; it does not itself widen a source route's
+declared execution mode — a route with `sandbox: true` still renders isolated,
+with no filesystem, and no host-code fallback is introduced for it. It is a
+separate package export from the runtime for that reason. Review it as you
+review any deployment tooling.
 
 ## Assembling a site
 
@@ -196,8 +200,9 @@ Two consequences worth knowing:
   and their imports exceed the budgets cannot be split, and fails with the
   collector's message. That is a route to make smaller, not a pass to add.
 
-The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) renders
-62 documentation pages this way.
+The `urlcode-docs` site rendered 62 documentation pages this way. That
+repository has since been deleted, so no link is given; the runnable
+version of the same pattern is [`examples/prerender`](../examples/prerender/README.md).
 
 ## Larger sites: generating the source project
 
@@ -219,9 +224,8 @@ things to hold onto:
   interpolates, but content injected as raw HTML is published as written. Whatever
   produces that HTML owns its safety.
 
-The [urlcode-docs showcase](https://github.com/jimhoyd-com/urlcode-docs) builds
-its site this way. That is a working integration, not a deployment or performance
-claim.
+The `urlcode-docs` site built itself this way before that repository was
+retired. It was a working integration, not a deployment or performance claim.
 
 ## What this is not
 
@@ -231,3 +235,11 @@ native bodies readable. Not a template engine — the template is ordinary
 middleware you write. Not a CLI command: prerendering is a step inside a build
 that already runs JavaScript, so the helper is a library. Content compilation,
 sanitization, search, asset assembly and deployment stay in the application.
+
+
+Trusted build-time functions and middleware use ordinary Node imports, including
+npm packages and dynamic imports. The pass planner applies source-graph budgets
+only to `sandbox: true` routes; it does not parse trusted modules as sandbox
+code. Page-count and output-byte budgets still apply to both modes. After
+rendering, emit native page/file routes without middleware, then use the static
+build target. Static hosting cannot execute middleware on incoming requests.

package/docs/PROJECT-DIRECTION.md

@@ -40,8 +40,8 @@ capability grants. Application data stays in the operator's systems.
 
 - **Not a URL shortener.** Core is redirects, validated responses, request
   functions, middleware, pages, static assets and downloads. Stored short
-  links are moving to a future `urlcode-dynamic-link` extension package
-  (mount-based, like `auth`/`admin`, not yet published), not a core handler.
+  links are not a core handler; the `urlcode-dynamic-link` extension package
+  that owned them has been retired and unpublished.
 - **Not a general Node web framework.** There is no framework code to write
   for routing, validation, middleware wiring or policies — those are declared
   in YAML and enforced by the runtime. Function/middleware code that needs
@@ -104,7 +104,7 @@ lines an agent generated, how many are the idea and how many are plumbing. A
 traditional build might be 2,900 lines of business logic inside 18,400; the
 same application on URLCode should be the same 2,900 inside a few thousand.
 Until a reproducible benchmark shows that ratio, the thesis is a hypothesis,
-and [next steps](NEXT-STEPS.md) puts the benchmark before the features.
+and [the roadmap](../ROADMAP.md) puts the benchmark before the features.
 
 ## License