@jimhoyd/urlcode 0.3.0 → 0.4.0-alpha.2

package/docs/README.md

@@ -1,58 +1,111 @@
 # URLCode documentation
 
-Start with [project direction](PROJECT-DIRECTION.md) for what URLCode is, what it
-is not, how application projects fit, and the license.
+> **Public documentation is authored in a separate `urlcode-docs` repository,
+> not generated from this tree.** New reader-facing pages belong there; `docs/`
+> here keeps contributor and maintainer material (local development, CI, release
+> process, reviews, spikes, plans and the generated field reference). The
+> reader-facing pages still listed below are being migrated.
+>
+> `urlcode-docs` is currently private, so it isn't publicly browsable yet —
+> until it is, this file and this repository's README are the practical
+> reference.
 
-For runtime 0.2.0. Use documentation pinned to your runtime revision.
+Start with [the framework](FRAMEWORK.md): the four packages, the ladder from
+redirects to a full application, the composition contract and the rules an AI
+agent must follow. [Project direction](PROJECT-DIRECTION.md) states the
+boundary and the license. Use documentation pinned to your runtime revision;
 `version: "1"` is the stable project-format contract for this release line.
 
+## Author a project
+
 | Goal | Start here |
 |---|---|
 | Install the CLI | [Installation](INSTALL.md) |
-| Generate placeholders from YAML | [Scaffolding](SCAFFOLDING.md) |
 | Write YAML with examples | [YAML guide and recipes](YAML-GUIDE.md) |
 | Look up every accepted field | [Generated field reference](YAML-REFERENCE.md), [JSON Schema](../schemas/urlcode.schema.json) |
 | Let an AI build routes | [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt) |
+| Load authoring/operations rules into an agent | [Authoring skill](../.claude/skills/urlcode-authoring/SKILL.md), [operations skill](../.claude/skills/urlcode-operations/SKILL.md), [how they are distributed](AI-AUTHORING.md#agent-skills) |
 | Run examples | [25-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
-| Explore a standalone application | [URLCode Shortener demo](https://github.com/jimhoyd-com/urlcode-shortener), [build retrospective](https://github.com/jimhoyd-com/urlcode-shortener/blob/main/docs/BUILD-RETROSPECTIVE.md) |
-| Explore a static docs-site integration | [URLCode Docs project](https://github.com/jimhoyd-com/urlcode-docs), [build retrospective](https://github.com/jimhoyd-com/urlcode-docs/blob/main/docs/BUILD-RETROSPECTIVE.md) — synced from this repository, which remains the source of truth |
-| Create/update short links live | [Dynamic links, storage and management API](DYNAMIC-LINKS.md) |
+| Explore a standalone application | [URLCode Short demo](https://github.com/jimhoyd-com/urlcode-short), [build retrospective](https://github.com/jimhoyd-com/urlcode-short/blob/main/docs/BUILD-RETROSPECTIVE.md) |
+| Explore a static docs-site integration | URLCode Docs project (private repository; not yet publicly browsable) |
 | Understand exact behavior | [Specification](SPECIFICATION.md), [routing](ROUTING.md), [HTTP](HTTP.md) |
-| Reuse code around routes | [Middleware](MIDDLEWARE.md) |
-| Throttle, block agents, set security headers, compress or cache from YAML | [Policies](POLICIES.md): [throttle](policies/throttle.md), [agents](policies/agents.md), [security](policies/security.md), [compression](policies/compression.md), [cache](policies/cache.md) |
+| Run examples | [40-route cookbook](../examples/cookbook/README.md), [prerender recipe](../examples/prerender/README.md), [small starter](STARTERS.md) |
+| Let an AI build routes | [The framework](FRAMEWORK.md), [AI authoring guide](AI-AUTHORING.md), [llms.txt](../llms.txt), [SDK and read-only MCP](TOOLING.md) |
+| Reuse code around routes | [Middleware](MIDDLEWARE.md), [middleware examples](MIDDLEWARE-EXAMPLES.md) |
+| Handle secrets and decide what to sandbox | [Function security](FUNCTION-SECURITY.md) |
+| Author guest functions in TypeScript | [Build-time guest transpilation](TYPESCRIPT-AUTHORING.md) |
+| Serve pages, files and downloads | [Assets](ASSETS.md) |
+| Publish a site with no request-time guest code | [Prerendering helper and recipe](PRERENDER.md) |
+| Select response branches | [Exact conditions](CONDITIONS.md) |
+| Proxy an API or emit a webhook | [Bounded egress and operator grants](EGRESS.md) |
+| Throttle, block agents, set security headers, compress or cache | [Policies](POLICIES.md): [throttle](policies/throttle.md), [agents](policies/agents.md), [security](policies/security.md), [compression](policies/compression.md), [cache](policies/cache.md) |
+| Generate robots.txt, sitemap.xml, favicon, security.txt and llms.txt | [Site conventions](SITE.md) |
+| Organize YAML across folders | [Organization](ORGANIZATION.md), [readability practices](BEST-PRACTICES.md) |
+| Generate placeholders from YAML | [Scaffolding](SCAFFOLDING.md) |
+| Convert provider redirect files | [Strict interchange and conversion reports](INTERCHANGE.md) |
+| Import thousands of redirects | [Bulk import and scale evidence](BULK.md) |
+| Reuse local project recipes | [Recipe catalog](RECIPES.md) |
+| Check declared configuration against standards-referenced rules | [Compliance](COMPLIANCE.md) |
+
+## Extend the runtime
+
+| Goal | Start here |
+|---|---|
+| Add accounts, sign-in and protected routes | [urlcode-auth](https://github.com/jimhoyd-com/urlcode-auth#readme) |
+| Manage users, sessions, roles and audit | [urlcode-admin](https://github.com/jimhoyd-com/urlcode-admin#readme) |
+| Restyle every extension page and translate copy | [urlcode-ui](https://github.com/jimhoyd-com/urlcode-ui#readme), [ui contract](https://github.com/jimhoyd-com/urlcode-ui/blob/main/CONTRACT.md) |
+| Write or install a versioned extension | [Extensions](EXTENSIONS.md), [example fixture](../examples/extensions/README.md) |
+| Know which core version an extension package supports, and how it says so | [Core version alignment](VERSION-ALIGNMENT.md) |
 | Add host behavior in operator code | [Plugins](PLUGINS.md) |
 | Use the API from TypeScript | [TypeScript: shipped declarations, exports, build and fidelity](TYPESCRIPT.md) |
-| Check declared configuration against standards-referenced rules | [Compliance](COMPLIANCE.md) |
-| See how the runtime conforms to the standards it uses | [Standards audit](STANDARDS.md) |
-| Serve pages/files/downloads | [Assets](ASSETS.md) |
-| Generate robots.txt, sitemap.xml, favicon, security.txt and llms.txt | [Site conventions](SITE.md) |
-| Publish a site with no request-time guest code | [Prerendering helper and recipe](PRERENDER.md) |
-| Keep code and YAML readable | [Organization and readability practices](BEST-PRACTICES.md) |
-| Organize YAML across folders | [Organization](ORGANIZATION.md) |
-| Work locally | [Local development](LOCAL-DEVELOPMENT.md) |
-| Share a local project publicly | [Tunnels](TUNNELS.md) |
-| Watch a deployment | [Monitoring](MONITORING.md) |
-| Wire your own monitoring or scrape metrics | [Observability](OBSERVABILITY.md) |
-| Load test a deployment | [Load testing](LOAD-TESTING.md) |
-| Deploy to Vercel | [Vercel adapter](VERCEL.md) |
-| Deploy to AWS Lambda | [AWS adapter](AWS.md) |
-| Deploy to Cloudflare Workers | [Cloudflare target](CLOUDFLARE.md) |
-| Handle secrets/untrusted code | [Function security](FUNCTION-SECURITY.md) |
+
+## Operate and deploy
+
+| Goal | Start here |
+|---|---|
+| Work locally | [Local development](LOCAL-DEVELOPMENT.md), [tunnels](TUNNELS.md) |
 | Prove responses and counts | [Readiness](READINESS.md) |
-| Estimate concurrency/memory | [Capacity and limits](CAPACITY.md), [measurements](PERFORMANCE.md) |
-| Prepare for overload/DDoS/recovery | [Resilience playbook](RESILIENCE.md) |
+| Check pull requests of a project on GitHub | [CI action, route diffs and the starter workflow](CI.md) |
 | Deploy and roll back | [Operations](OPERATIONS.md) |
 | Review security findings and gaps | [Internal security audit](SECURITY-AUDIT.md) |
 | Assess release readiness | [Evidence and open gates](RELEASE-READINESS.md) |
 | See unfinished work | [Roadmap](../ROADMAP.md) |
 | Read the design behind policies, plugins and templates | [Extensions spike](SPIKE-EXTENSIONS.md) |
+| Read the design for an authentication and authorization plugin | [Auth spike](SPIKE-AUTH.md) |
+| Read the design for the administration extension that manages users | [Admin spike](SPIKE-ADMIN.md) |
+| Read the design for the shared template kit every extension renders with | [UI kit spike](SPIKE-UI.md) |
+| Read the review of the extension model, its precedents and alignment | [Extension model review](SPIKE-EXTENSION-MODEL.md) |
+| Read the design for compiling function routes into per-route Lambdas | [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) |
+| Verify a running deployment matches the project | [Deployment checks](DEPLOYMENT-CHECKS.md) |
+| Inspect target support | [Capabilities and normalized representation](CAPABILITIES.md) |
+| Deploy to Vercel, AWS Lambda or Cloudflare Workers | [Vercel](VERCEL.md), [AWS](AWS.md), [Cloudflare](CLOUDFLARE.md), [provider verification evidence](PROVIDER-VERIFICATION.md) |
+| Watch a deployment | [Monitoring](MONITORING.md), [observability](OBSERVABILITY.md) |
+| Estimate concurrency and memory | [Capacity and limits](CAPACITY.md), [measurements](PERFORMANCE.md), [load testing](LOAD-TESTING.md) |
+| Prepare for overload, DDoS and recovery | [Resilience playbook](RESILIENCE.md) |
 
-Examples are educational unless backed by the runnable cookbook/fixtures.
-Infrastructure limits are deployment settings, not fields to invent in route YAML.
+## Evidence, reviews and design records
 
-## Security and acceptance
+These are dated records, not guides. They say what has been checked and what
+has not, and why the design is the way it is.
 
-- [Independent sandbox review package](SANDBOX-REVIEW.md)
-- [Private management credentials and atomic audit](MANAGEMENT-SECURITY.md)
-- [Operational drills and deployment acceptance](OPERATIONAL-PROOF.md)
-- [Candidate signing and release security](RELEASE-SECURITY.md)
+| Record | What it is |
+|---|---|
+| [Release readiness](RELEASE-READINESS.md) | Verified safeguards, open gates, supported scope |
+| [Usability review](USABILITY-REVIEW.md) | Where the framework is easier or harder than the tools it replaces, and ranked changes |
+| [Next steps](NEXT-STEPS.md) | The phased plan: agent discovery, context compression, retrieval, the ladder, benchmarks and the remaining proof gaps |
+| [AI-first framework benchmark spike](SPIKE-AI-FRAMEWORK-BENCHMARK.md) | Proposed research-first, independent-agent application and runtime benchmark with a verified issue/improvement loop |
+| [Next-phase implementation status](NEXT-PHASE-PLAN.md) | Source additions after 0.3.0 shipped in 0.4.0-alpha.1, and their evidence limits |
+| [Security review](SECURITY-AUDIT.md) | Internal findings and fixes; not an independent test |
+| [Standards audit](STANDARDS.md) | How the runtime conforms to the RFCs it touches |
+| [Sandbox review package](SANDBOX-REVIEW.md) | What an independent reviewer needs; assessment not yet performed |
+| [Operational drills](OPERATIONAL-PROOF.md) | Deployment acceptance drills CI runs |
+| [Release security](RELEASE-SECURITY.md) | Candidate signing and publication process |
+| [Core version alignment](VERSION-ALIGNMENT.md) | The supported core floor for each downstream repository, how it is declared, and the publish-then-raise-then-regenerate order |
+| [Extension model review](SPIKE-EXTENSION-MODEL.md) | Why extensions are shaped this way, with framework precedents |
+| [Extensions spike](SPIKE-EXTENSIONS.md) | The design behind policies and plugins; implemented |
+| [Lambda compile spike](SPIKE-LAMBDA-COMPILE.md) | Proposal: per-route Lambdas for functions; not implemented |
+| Auth, admin and UI spikes | Live in their repositories: [auth](https://github.com/jimhoyd-com/urlcode-auth/blob/main/docs/SPIKE-AUTH.md), [admin](https://github.com/jimhoyd-com/urlcode-admin/blob/main/docs/SPIKE-ADMIN.md), [ui](https://github.com/jimhoyd-com/urlcode-ui/blob/main/docs/SPIKE-UI.md) |
+| [Roadmap](../ROADMAP.md) | Implemented versus planned |
+
+Examples are educational unless backed by the runnable cookbook and fixtures.
+Infrastructure limits are deployment settings, not fields to invent in route YAML.

package/docs/RECIPES.md

@@ -0,0 +1,99 @@
+# Local recipes
+
+Recipes are ordinary version-controlled URLCode projects shipped with the
+runtime. There is no network registry, install script, provider account or
+project-code execution during authoring. Search them before writing a common
+route by hand: the catalog is the vocabulary of behavior the runtime already
+supports, and every recipe validates, tests and audits.
+
+```sh
+urlcode recipes list
+urlcode recipes search "webhook json"        # id, description, tags, capabilities
+urlcode recipes search webhook --json
+urlcode recipes show webhook-receiver        # metadata first, then every file
+urlcode recipes add webhook-receiver --out ./orders-hook --dry-run
+urlcode recipes add webhook-receiver --out ./orders-hook
+urlcode validate --local --project ./orders-hook
+```
+
+## The catalog
+
+| Recipe | Complexity | What it shows | Needs |
+|---|---|---|---|
+| `redirect` | starter | Permanent redirect forwarding one allowlisted query key | nothing |
+| `health-page` | starter | Native `/health` text and `/status` JSON, no-store | nothing |
+| `json-api` | starter | Bounded JSON body echoed by a sandboxed function | self-hosted runtime |
+| `webhook-receiver` | starter | JSON event with a type header, shape-checked, `202` | self-hosted runtime |
+| `typescript` | intermediate | Typed guest transpiled by `build-typescript` | build step |
+| `static-plus-api` | intermediate | Page, static directory and one JSON function | self-hosted runtime |
+| `cors-api` | intermediate | Preflight and CORS headers from route middleware | self-hosted runtime |
+| `contact-form` | intermediate | Validated message, fixed signal to a hook after the response | signal grant (`--policy`) |
+| `middleware` | advanced | Fourteen reusable middleware patterns ([described here](MIDDLEWARE-EXAMPLES.md)) | self-hosted runtime |
+| `authenticated-json-api` | advanced | Function behind `auth: true` | operator auth extension, `--host-file`, `--origin` |
+| `protected-download` | advanced | Native attachment behind `auth: true` | operator auth extension, `--host-file`, `--origin` |
+
+Each recipe contains a README, `tests/requests.json` and editable files.
+Replace example destinations and review the resulting files before use. The
+authenticated recipes declare `extensions.auth` and protect their route with
+the short form described in [extensions](EXTENSIONS.md); their README shows the
+minimal host-file fixture that reproduces the bundled tests. Nothing in the
+catalog verifies webhook signatures: the sandbox has no crypto or network API,
+so signed webhooks belong behind an operator extension or a trusted host.
+
+## `recipe.yaml`
+
+Every recipe carries `recipe.yaml`, validated against
+[`schemas/recipe.schema.json`](../schemas/recipe.schema.json) by `npm run check`:
+
+- `id`, `description`, `tags`, `complexity` (`starter`, `intermediate`,
+  `advanced`): written by hand; `search` matches id, description, tags and
+  capabilities, every word must match, and whole-tag or id hits rank first.
+- `capabilities`, `targets`, `routes`: derived from the capability preflight
+  (`analyzeProjectCapabilities` per target after site expansion). The check
+  refuses a hand-edited value that differs, so a recipe cannot claim a target
+  it does not activate on. `targets` is `compatible`, or the strongest issue
+  (`conditional`, `unknown`, `refused`); `routes` is the `--expect-routes` value.
+- `services` (external services), `grants` (operator grants, never from project
+  files), `inputs` (what to edit), `files` (the copy list), `tests` (fixtures
+  and the exact commands) and `behavior` (one observable statement per line).
+
+`show` prints this metadata before the file contents so a reader sees what a
+recipe needs before its files scroll past; `--json` returns the same object with
+a `content` map. `list` prints one line per recipe, or the metadata with `--json`.
+
+## Examples
+
+`examples/*/example.yaml` uses the same schema, and `urlcode examples search
+<text> [--json]` returns the smallest matching runnable example first with the
+file to read. The cookbook's forty routes are indexed per route in the generated
+[`examples/cookbook/route-index.json`](../examples/cookbook/route-index.json)
+(handler, methods, capabilities, policies and middleware module names as tags;
+`npm run docs:cookbook-index` regenerates it and `npm run check` refuses a stale
+copy), so a search for `etag` answers the cookbook and its `/versioned` route.
+Entries without a `urlcode.yaml` (operator rules, monitoring configuration,
+scripts) are `runnable: false` and carry no derived fields.
+
+## Adding a recipe
+
+`add` creates a new standalone directory. It refuses an existing destination,
+even an empty directory; it never merges or overwrites existing project routes.
+Review or copy selected declarations manually when combining projects. Dry-run
+reads and validates the packaged recipe and checks the destination, but writes
+nothing. The output parent must already exist and be owned by the caller.
+Dependencies are written first and the complete `urlcode.yaml` is published by
+rename last. A failed write removes the new directory. This is atomic project
+activation, not an atomic directory replacement or a guarantee against a local
+attacker concurrently replacing the caller's output directories.
+
+## SDK and MCP
+
+The SDK provides `listRecipes()`, `searchRecipes(text)`, `showRecipe(name)`,
+`addRecipe(name, output, {dryRun})`, `listExamples()` and `searchExamples(text)`.
+Catalog names are a fixed list in code; metadata and file lists come from each
+schema-checked `recipe.yaml` and are returned as copies. Unknown names and
+arbitrary paths/URLs fail closed. The stdio MCP server adds `search_recipes` and
+`search_examples` beside `recipes_list` and `recipes_show`
+([tooling](TOOLING.md)). Integration tests run every recipe through the real
+runtime with its fixtures and audit it with its declared route count (after
+building the TypeScript recipe, with a fixture registry for the authenticated
+ones and the generated policy for the contact form).

package/docs/RELEASE-READINESS.md

@@ -1,41 +1,59 @@
 # Release readiness
 
-Status: stable 0.1 self-hosted release. Production approval remains specific to
+Status: `0.4.0-alpha.2` (`package.json`) alpha of the extension contract and
+agent tooling on top of the `0.3.0` self-hosted release; `0.4.0-alpha.1` is the
+most recent alpha actually published; the npm dist-tags for `@jimhoyd/urlcode`
+were `latest` = `0.3.0` and `alpha` = `0.4.0-alpha.1` when checked against the
+registry on 2026-09-19, so the repository's `0.4.0-alpha.2` is unpublished (see
+"Packaging" below). Production approval remains specific to
 the workload and deployment environment.
 This register describes the current public runtime, not future promises.
 Use the contract and docs from the same pinned commit as your installed runtime.
 
 ## What is aligned
 
-- One portable YAML project, explicit includes, seven mutually exclusive handlers,
+- One portable YAML project, explicit includes, one handler per route (redirect, respond, page, static, download, function, proxy, conditional or extension),
   per-route middleware and consistent request/response validation.
 - One starter with a function route first and an ordinary redirect second.
   Clone urlcode-template or use `urlcode init`; neither requires a database.
 - Native handlers avoid user-code execution unless middleware is attached.
-- Live links are mutable records behind a declared route. Git owns definitions;
-  an optional external SQLite store owns records. This is single-host storage.
-- Untrusted functions run in isolated QuickJS/WASM with no ambient filesystem,
-  network or Node APIs. Host bindings require external revision-pinned approval.
+- Functions/middleware run trusted and unsandboxed by default (in-process,
+  full Node access); `sandbox: true` opts a route into isolated QuickJS/WASM
+  with no ambient filesystem, network or Node APIs (docs/SPIKE-DEFAULT-TRUST-MODEL.md).
+  Host bindings require external revision-pinned approval either way.
 - The runtime is released under Apache-2.0.
 
 ## Regression evidence
 
 `npm run verify` is the lint, syntax/schema-reference and unit/HTTP regression gate.
 `npm run test:package` installs the packed artifact and exercises initialized apps,
-route audits, bounded benchmarks, assets and live links. CI runs Node 22/24/26 on
-Linux/macOS/Windows and tests the container under resource restrictions.
+route audits, bounded benchmarks and assets. On a push to `main`, CI runs Node
+22/24/26 on Linux/macOS/Windows (nine combinations) and tests the container
+under resource restrictions; a pull request runs the same Node versions on
+Linux only (`.github/workflows/ci.yml`'s matrix), with the macOS/Windows legs
+deferred to the post-merge run.
 
 | Area | Covered behavior | Practical limit |
 |---|---|---|
 | Routing and HTTP | Exact/parameter/static precedence, methods, inputs, assets, middleware and response assertions | Stable 0.1 contract; unsupported semantics reject rather than emulate |
-| Isolation | Sandbox capability/permission boundaries, deadlines, memory and invalid outputs | Not an independent security assessment or multi-tenant service certification |
-| Overload | Function/store queue caps; HTTP admission saturation, separate bounded probe budget, health availability and recovery after upload completion/disconnect | 64 application requests default; no fairness, upstream DDoS protection or end-to-end deadline |
-| Worker replacement | Repeated guest deadlines shed load and the pool returns to service after backoff, rather than latching off for the life of the process | Store-connection replacement shares this logic but its failure branch has no automated test; a crash there is covered by reasoning and review only |
-| Persistence | Committed writes visible to independent readers; concurrent CAS, restart and abrupt writer exit | SQLite on one host; no distributed availability |
-| Shutdown | Full accepted store queue drains; new work rejects; repeated close shares completion | Existing deadlines can still fail; uncertain writes must be reconciled |
-| Management | Token boundaries, body limits, origin rejection, conditional mutations, endpoint-specific Allow headers | Private operator API, not public end-user account management |
-| Activation/recovery | Invalid reload retains last-good snapshot; corrupt revision metadata rejects activation | No deployment orchestration or automatic database repair |
-| Packaging | Packed installation and starter examples tested; sensitive files excluded | No published npm/Homebrew release or provider adapter guarantee |
+| Isolation | `sandbox: true` capability/permission boundaries, deadlines, memory and invalid outputs; the trusted default's grant scoping | Not an independent security assessment or multi-tenant service certification; trusted-route code safety is the project's own call |
+| Overload | Function pool queue caps; HTTP admission saturation, separate bounded probe budget, health availability and recovery after upload completion/disconnect | 64 application requests default; no fairness, upstream DDoS protection or end-to-end deadline |
+| Worker replacement | Repeated guest deadlines shed load and the pool returns to service after backoff, rather than latching off for the life of the process | Bounded by the configured worker count; no cross-process load balancing |
+| Shutdown | New work rejects; repeated close shares completion | Existing deadlines can still fail during shutdown |
+| Activation/recovery | Invalid reload retains last-good snapshot; corrupt revision metadata rejects activation | No deployment orchestration |
+| Packaging | Packed installation and starter examples tested; sensitive files excluded | `0.3.0` and `0.4.0-alpha.1` are published to npm as `@jimhoyd/urlcode` (`latest` and `alpha` dist-tags respectively; dist-tags verified against the npm registry on 2026-09-19, when the repository stood at the unpublished `0.4.0-alpha.2`). Published extension packages on the same date: `@jimhoyd/urlcode-auth@0.1.0-alpha.2`, `@jimhoyd/urlcode-admin@0.1.0-alpha.2`, `@jimhoyd/urlcode-ui@0.1.0-alpha.4`, `@jimhoyd/urlcode-short@0.1.0-alpha.1`, `@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1`, `@jimhoyd/urlcode-middleware@0.1.0-alpha.1`. Observed in passing: auth's dist-tags are split — `alpha` points at `0.1.0-alpha.2` while `latest` still points at `0.1.0-alpha.1`, so a plain `npm install @jimhoyd/urlcode-auth` resolves the older alpha. GitHub Releases attach a Homebrew formula (`urlcode.rb`) for manual copy into a tap, not an automated Homebrew Core/tap publish. No provider adapter guarantee. |
+
+`npm run check:downstream-skills` is a manual, advisory report worth running
+before a release: it diffs core's `.claude/skills/` copies against copies
+vendored by downstream repositories (currently `urlcode-template`) when that
+repository is cloned as a sibling checkout, and prints how many lines differ
+per skill. It never fails and never asserts which side is correct -- a
+downstream repo commonly pins an older published core version, and
+divergence from core's current `main` can be the *correct* reflection of
+that pin rather than staleness (see issue #155). It is not part of `check`
+or `verify` because it depends on an out-of-repo sibling checkout that
+normal CI does not have; it is a prompt to review the diff against the
+downstream pin, not a pass/fail gate.
 
 `npm audit --omit=dev` now runs in CI and fails the build on any runtime advisory;
 development-only advisories are reported without blocking. Dependabot proposes npm,
@@ -49,22 +67,20 @@ These remain open. Record workload, runtime/app/image revisions, environment,
 commands, results and owner for each exercise; do not convert a passing local
 benchmark into a universal throughput claim.
 
-1. Independent review of host/sandbox boundaries and authenticated management.
+1. Independent review of host/sandbox boundaries.
 2. Sustained load and soak on intended hardware, through the actual TLS/proxy
    path: successful throughput, tail latency, 503/504 rate, RSS and recovery.
    `urlcode benchmark --target` measures a running deployment through its real
    path and separates shed responses from transport errors; see
    [load testing](LOAD-TESTING.md). The tool is GET/HEAD only and caps at 300
    seconds, so it does not by itself close this gate.
-   Include mixed native/function/live-link workloads and slow peers.
-3. A real backup/restore drill on a separate host/volume, with record/version
-   reconciliation and measured recovery time/data loss. Keep SQLite WAL files
-   consistent; copying a live main database file alone is not a backup.
-4. Kill/restart, resource exhaustion, disk-full and rolling deployment/rollback
-   exercises with the chosen supervisor, ingress and persistent storage.
-5. Alerting and ownership for sustained errors, latency, readiness, dropped logs,
+   Include mixed native/function workloads and slow peers.
+3. Kill/restart, resource exhaustion and rolling deployment/rollback
+   exercises with the chosen supervisor and ingress. A future durable-state
+   extension needs its own backup/restore drill; core has no durable store.
+4. Alerting and ownership for sustained errors, latency, readiness, dropped logs,
    disk space, restarts and backups. Pick service objectives for the actual app.
-6. Stable-release support commitments before packaging/public reuse claims.
+5. Stable-release support commitments before packaging/public reuse claims.
    Private security reporting and the current support baseline are documented in
    SECURITY.md.
 
@@ -72,12 +88,13 @@ License selection is resolved: URLCode is released under the Apache License 2.0,
 `package.json` declares it, and the repository carries the full license text.
 The remaining gates above are engineering and operational, not legal.
 
-The full free-product roadmap additionally includes bulk interchange tooling,
-installers/Homebrew, provider adapters and reusable templates/signals. Those
-features are not implemented merely because
-YAML has a portable design. Node process/container hosting is the supported
-execution target today; AWS/Vercel/Cloudflare adapters and guest network/realtime
-capabilities remain future work. See [roadmap](../ROADMAP.md).
+The unreleased next-phase source now includes strict bulk/provider interchange,
+local recipes, TypeScript authoring, bounded self-hosted proxy/signals and read-only
+MCP. Local AWS/Vercel/Cloudflare adapter tests and deployment probe tooling exist,
+but actual provider deployments remain unverified. Node process/container hosting
+remains the reference execution target. Guest networking, durable signals and
+realtime capabilities are not provided. See [implementation status](NEXT-PHASE-PLAN.md)
+and [roadmap](../ROADMAP.md); these additions do not close the operational gates above.
 
 The [internal security audit](SECURITY-AUDIT.md) records reproduced findings, fixes
 and prioritized gaps. Its regressions supplement these gates; they do not replace
@@ -86,10 +103,15 @@ independent assessment or real deployment exercises.
 ## Hardening follow-up
 
 Implemented: bounded YAML workers and aggregate source budgets, cooperative route
-compilation deadline, loopback-only management, scoped/expiring/revocable operator
-credentials, atomic SQLite mutation audits, executable local/CI operational drills,
-and a main-only candidate signing/SBOM workflow.
+compilation deadline, scoped/expiring/revocable operator credentials for host
+bindings, executable local/CI operational drills, and a main-only candidate
+signing/SBOM workflow. The loopback-only management API and its atomic SQLite
+mutation audits were part of the `link`/`dynamicLinks` store that PR #126
+removed from core; that functionality, and its hardening, now belongs to the
+`urlcode-dynamic-link` extension (docs/EXTENSIONS.md), published on npm as
+`@jimhoyd/urlcode-dynamic-link@0.1.0-alpha.1` as of 2026-09-19, not this
+runtime.
 
 Still required: [independent review](SANDBOX-REVIEW.md), [actual deployment proof](OPERATIONAL-PROOF.md),
-and publication/support arrangements. The Apache-2.0 license and the 0.2.0 self-hosted
+and publication/support arrangements. The Apache-2.0 license and the 0.3.0 self-hosted
 release do not close the security and deployment gates. See [release process](RELEASE-SECURITY.md).

package/docs/RELEASE-SECURITY.md

@@ -1,6 +1,6 @@
 # Candidate and release security process
 
-URLCode 0.2.0 is the Apache-2.0 self-hosted baseline; licensing is defined
+URLCode 0.3.0 is the Apache-2.0 self-hosted baseline; licensing is defined
 in [LICENSE](../LICENSE). Two workflows share one audited build path and differ
 only in what they do with its output:
 
@@ -14,6 +14,16 @@ only in what they do with its output:
 Neither workflow is a statement that a release is production-ready; see
 [release readiness](RELEASE-READINESS.md).
 
+## Publishing an alpha
+
+An alpha such as `0.4.0-alpha.1` follows the same path: tag `v0.4.0-alpha.1`
+on a commit that is already on main. The release workflow publishes to npm
+only when the repository variable `PUBLISH_NPM` is `true` and the npm trusted
+publisher for this repository and `release.yml` exists; otherwise the run is
+artifacts-only (a GitHub release with the signed tarball). Publish order is
+core → ui → auth → admin, because the extension packages declare
+`@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0` and must resolve the core alpha.
+
 1. Report vulnerabilities privately through [GitHub advisories](https://github.com/jimhoyd-com/urlcode/security/advisories/new).
    The maintainer triages impact, confirms affected exact revisions, coordinates a
    fix/retest privately, and publishes an advisory with upgrade guidance when safe.
@@ -47,10 +57,23 @@ Neither workflow is a statement that a release is production-ready; see
    signing key is stored. Signing permissions exist only in this manual job; build
    commands run in a container without passing GitHub tokens. Candidate files are
    retained as GitHub Actions artifacts for 30 days. A release additionally attaches
-   them to the GitHub release, and publishes to npm with `--provenance` and to GHCR
-   when those repository variables are enabled.
+   them to the GitHub release, and publishes to npm and to GHCR when those
+   repository variables are enabled.
+
+   **npm publication holds no credential.** The registry is configured with a
+   trusted publisher naming this repository and `release.yml`, so the publish
+   step exchanges the job's OIDC identity for a credential that lives for the
+   length of one publish. There is no npm token in the repository's secrets to
+   leak, revoke or rotate, and a fork or another workflow cannot publish under
+   this package's name. Provenance is generated on that same identity, so
+   `--provenance` is not passed and its absence is not a downgrade.
+
+   A bearer token would silently take precedence over this exchange, so the
+   publish step must reference none; `test/release.test.ts` fails if one
+   reappears in it, and checks the npm and Node floors below which the exchange
+   is not attempted at all.
 5. Download the candidate for the intended commit and verify **each file**, e.g.
-   `gh attestation verify urlcode-0.2.0.tgz --repo jimhoyd-com/urlcode --signer-workflow jimhoyd-com/urlcode/.github/workflows/candidate.yml --source-ref refs/heads/main --source-digest APPROVED_COMMIT_SHA`
+   `gh attestation verify jimhoyd-urlcode-0.3.0.tgz --repo jimhoyd-com/urlcode --signer-workflow jimhoyd-com/urlcode/.github/workflows/candidate.yml --source-ref refs/heads/main --source-digest APPROVED_COMMIT_SHA`
    (use `release.yml` as the signer workflow for a tagged release).
    Check the verified provenance's source commit against the approved commit, and
    compare package/SBOM hashes with the signed manifest. A signature establishes
@@ -67,6 +90,92 @@ The SBOM describes npm dependencies; it is not a complete OS/container SBOM. Hos
 runners and action runtimes remain platform-controlled. Digest pins improve supply
 chain integrity but do not prove byte-for-byte reproducibility or engine safety.
 Signing verification must be demonstrated on a successful main workflow run before
-claiming a candidate has been signed. Workflow definition alone is not that evidence:
-`release.yml` has never been executed, so no release has yet been produced or signed
-by it, and the npm and GHCR publication paths are unproven until a real tag runs.
+claiming a candidate has been signed. Workflow definition alone is not that evidence.
+`release.yml` ran successfully for the first time publishing `v0.4.0-alpha.1`
+(2026-09-18), after the fixes below; treat any repository whose workflow has not
+had a real successful tagged run the same way this one was treated before that.
+
+## What broke on every first release, and why
+
+Four repositories (core, ui, auth, admin) each cut their first tagged release in
+the same session. Every one hit a subset of the same bugs, because each
+`release.yml` was written and reviewed but never actually run end-to-end against
+a real tag before. None of this is repository-specific; check for all of it
+before trusting an unexercised release workflow:
+
+- **`npm ci` on the bare runner's root-owned npm.** A build that runs entirely
+  inside a pinned Docker image never calls `actions/setup-node`, so a later
+  `npm install --global npm@11.5.1` (needed for the trusted-publishing floor)
+  hits the runner's preinstalled, root-owned npm and fails `EACCES`. Add
+  `actions/setup-node` before any step that installs global npm packages, even
+  if the main build never touches the runner's own Node.
+- **The floor check must run after the pin, not before.** A guard asserting
+  "npm ≥ 11.5.1" is useless directly after `setup-node` with `node-version: '22'`,
+  which bundles npm ~10.9.x — it can never pass. The floor only means something
+  once the publish step's own `npm install --global npm@11.5.1` has actually run.
+- **`npm publish` refuses an unqualified prerelease.** `You must specify a tag
+  using --tag when publishing a prerelease version.` npm's safety default is
+  `latest`; a prerelease must derive an explicit dist-tag from its version
+  (`0.1.0-alpha.1` → `alpha`, anything without a `-` → `latest`) and pass
+  `--tag`. This path is only exercised by a package's *first* prerelease, so it
+  silently sat broken in every repository until each hit it for the first time.
+- **`npm pack --pack-destination candidate` needs `candidate/` to exist first.**
+  npm does not create the destination directory; `mkdir -p candidate` first.
+- **A private repository's unauthenticated `git fetch origin main` cannot work.**
+  If checkout uses `persist-credentials: false` (correct, for a step that
+  should not need write access) and the repo is private, `git fetch` fails
+  `could not read Username for 'https://github.com'` before ever reaching the
+  version check. Compare the tag against main through the GitHub API instead
+  (`gh api repos/OWNER/REPO/compare/main...SHA --jq .status`, expecting
+  `identical` or `behind`) — it needs no credentials and stays read-only. Public
+  repositories can keep the plain fetch; it works there.
+- **`--conditions=development` in `npm run verify`'s test script resolves peers
+  to source that a real npm install never ships.** The regular CI job symlinks
+  sibling checkouts in place of `node_modules`, so `./src/*.ts` exists and the
+  flag is correct there. A release installs real published tarballs of its
+  peers, which only ever ship `dist/`, so the same flag makes every import of a
+  peer fail `ERR_MODULE_NOT_FOUND`. Drop the flag for the release-workflow test
+  invocation specifically (run `node scripts/check-sqlite.mjs` explicitly first,
+  since bypassing `npm test` skips that pretest hook), and audit any test file
+  that separately hardcodes the flag in a spawned child process — it has to be
+  fixed the same way, independently, wherever it appears.
+- **A peer-install command with the wrong flag combination is a silent no-op.**
+  `npm install --no-save --no-package-lock --ignore-scripts --legacy-peer-deps
+  <peer>@<version>` installed *nothing*, with no error, when the target package
+  names already appear in `peerDependencies` — `npm ci` earlier reports "added N
+  packages" as if it worked. Confirm the install actually happened
+  (`ls node_modules/@scope/*/package.json` and print each version) rather than
+  trusting the exit code; `--no-save --ignore-scripts <specs>` (no
+  `--no-package-lock`, no `--legacy-peer-deps`) is the version that works, paired
+  with `git diff --exit-code -- package.json package-lock.json` to prove nothing
+  was recorded as a dependency.
+- **A version published from an unbuilt checkout is burned forever.** npm never
+  allows a version to be replaced. `@jimhoyd/urlcode-auth@0.1.0-alpha.1` reached
+  the registry from something other than the CI workflow (a manual `npm
+  publish` run before `npm run build` had produced `dist/`), so the published
+  tarball contained only metadata files and no code. Every consumer's typecheck
+  failed with `Cannot find module '@jimhoyd/urlcode-auth'` — a real, correct
+  failure, not a bug in the consumer. The only fix is bumping to a new version
+  and publishing that instead; nothing can repair or unpublish the bad one.
+  **Never run `npm publish` by hand outside the release workflow** — the
+  workflow is the only place that reliably builds before packing.
+- **`ENEEDAUTH` on `npm publish` under trusted publishing usually means the
+  registry-side configuration doesn't exist or doesn't permit direct publish
+  yet**, not a workflow bug. Trusted publishing needs an entry under the
+  package's npm settings ("Trusted Publisher") naming the exact GitHub
+  org/repo and workflow filename, with no environment set unless the workflow
+  declares one; recent npm UI changes default new configurations to
+  "stage publish" only; "allow npm publish" (direct publish, which is what
+  this project's workflows do) must be explicitly enabled too. A wrong
+  org/repo/workflow match tends to surface as a 404, not `ENEEDAUTH`;
+  `ENEEDAUTH` is the signature of no matching configuration existing at all.
+- **Publish order matters and is easy to get backwards.** Extension packages
+  declare `@jimhoyd/urlcode >=X <Y` as a peer range; publish core before ui,
+  auth or admin, or their own release-workflow peer-install step has nothing
+  real to resolve against.
+
+None of the above is exotic; all nine bugs were found by actually running each
+workflow against a real tag, one release at a time, and reading the actual
+failure rather than guessing from the workflow source. Treat "the workflow file
+looks right" and "the workflow has actually published successfully once" as two
+different, unrelated claims.