@jimhoyd/urlcode 0.4.0-alpha.2 → 0.4.1

package/docs/archive/2026-09-19/MANAGEMENT-SECURITY.md

@@ -0,0 +1,102 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
+# Private management and durable mutation audit
+
+> **Retired.** This page describes the management API and mutation audit of
+> core's native link store. That store, its `urlcode links` CLI and this
+> management listener were removed from core when `link` was extracted, and the
+> `urlcode-dynamic-link` package that received them has since been retired and
+> unpublished. Nothing in the current runtime exposes this surface. The page is
+> kept because the security reasoning — loopback-only binding, operator-owned
+> credential policy, transactional mutation audit — is referenced by
+> [security audit](../../SECURITY-AUDIT.md) and applies to any component that
+> reintroduces a management listener.
+
+Management binds only `127.0.0.1` or `::1`. Use an authenticated private tunnel
+(e.g. SSH/VPN with loopback forwarding); never publish its port through a public
+proxy or container port mapping. This is operator management, not an end-user
+account service. Browser Origin requests remain rejected.
+
+## Individual credentials
+
+Use `urlcode links api --project ./my-links --store /operator/links.sqlite
+--auth-file /operator/management.json --host 127.0.0.1 --port 3001` (one line).
+The policy is operator-owned, outside the application, at most 64 KiB and mode
+600 on POSIX. Protect its parent directory and apply equivalent Windows ACLs.
+It is not YAML and must never be placed in the application or Git.
+
+Generate each token with `node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"`
+on a trusted operator machine. Deliver it through your secret manager. Hash the
+raw token using SHA-256 without a newline; the server expects `Authorization:
+Bearer <token>`. Tokens must contain 43–256 base64url characters. Never use a
+human password as a token. This synthetic policy illustrates the shape; replace
+the hash with the real token hash and choose a short operational expiry:
+
+```json
+{
+  "version": 1,
+  "credentials": [{
+    "id": "operator-alice",
+    "sha256": "0000000000000000000000000000000000000000000000000000000000000000",
+    "expires": "2026-10-01T00:00:00Z",
+    "collections": ["links"],
+    "actions": ["get", "list", "create", "update", "delete"]
+  }]
+}
+```
+
+At most 128 credentials; unique IDs and hashes; explicit collection and action
+allowlists with no wildcards. Readers should receive only `get` and `list`.
+An expired, removed or `"revoked": true` credential gets 401; a valid credential
+outside its scope gets 403. The entire policy is validated on every authenticated
+request. Malformed/unreadable policy fails closed with 503, without retaining an
+old permissive copy. Write a replacement file with mode 600 and atomically rename
+it over the policy. No restart is needed. Requests already authorized may finish;
+revocation does not cancel an in-flight transaction. Credential administration is
+an operator filesystem action, never exposed through this HTTP API.
+
+Legacy `--token-file` remains available for local compatibility, with full access
+to that listener's collection and actor `legacy-shared`. Prefer `--auth-file` for
+attribution, expiry and revocation. They are mutually exclusive. These bearer
+credentials do not establish verified human identity, MFA, SSO or session login.
+Host administrators and custom embedding code remain trusted operators.
+
+## Audit durability and recovery
+
+The built-in SQLite writer creates an additive `urlcode_link_audit` table when
+opening a store. Every successful create/update/delete (including CLI and embedded
+store calls) records revision, UTC timestamp, actor, request ID, collection,
+action and SHA-256 of the short code in the **same transaction** as the mutation.
+The default local CLI actor is `local-operator`. Scoped HTTP management requires
+an adapter explicitly declaring atomic audit support; the built-in store provides it.
+
+An audit insert failure rolls back both mutation and revision. Conditional-write
+conflicts and rejected requests produce no successful-mutation row. HTTP request
+logs still describe failed/aborted requests and remain best effort. A client timeout
+may follow a committed transaction: reconcile the revision and request ID before
+retrying. A lost HTTP reply is not evidence that the transaction was rolled back.
+
+Inspect the journal with an operator-only SQLite client, for example:
+
+```sql
+SELECT revision, timestamp, actor, request_id, collection, action, code_sha256
+FROM urlcode_link_audit WHERE revision > 0 ORDER BY revision LIMIT 100;
+```
+
+No token, URL, request body or raw short code is stored in the journal. Code hashes
+are correlatable and guessable for short codes; restrict access accordingly.
+This is a durable local transaction journal, **not tamper-evident external storage**.
+An administrator with database access can change it. Export ordered revisions to
+your protected collector/backup system and monitor lag, gaps and disk/WAL growth.
+There is no automatic pruning: define retention and verify archival before any
+operator purge. Keep audit records in backups. User_version remains 1 because
+this table is additive; older readers work, but older writers do not emit audit
+rows. Never roll a management writer back to an unaudited revision.

package/docs/{NEXT-PHASE-PLAN.md → archive/2026-09-19/NEXT-PHASE-PLAN.md}

@@ -1,3 +1,13 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
 # Next-phase implementation status
 
 Repository review and source implementation, 2026-09-17. Phase A established
@@ -10,7 +20,7 @@ Phase B–D features below. This describes the source additions after `0.3.0` th
 > The default changed in `0.4.0-alpha.2`: those routes now run trusted and
 > unsandboxed in the host process unless the route declares `sandbox: true`,
 > which gives it exactly the QuickJS/WASM execution described below. See
-> [SPIKE-DEFAULT-TRUST-MODEL.md](SPIKE-DEFAULT-TRUST-MODEL.md).
+> [SPIKE-DEFAULT-TRUST-MODEL.md](../../SPIKE-DEFAULT-TRUST-MODEL.md).
 
 ## Implementation and evidence
 
@@ -28,10 +38,10 @@ Phase B–D features below. This describes the source additions after `0.3.0` th
 | D: TypeScript guests | Fixed trusted build-time compiler, bounded relative graph, rewritten JavaScript imports, referenced-asset snapshot and safe new output | Transpilation is not type checking; no tsconfig/plugins/package execution or dotenv copying; runtime remains QuickJS JavaScript only |
 | D: consolidated SDK/MCP | Inspection, semantic validation, path explanation, compatibility, conversion previews and recipe discovery; operator-rooted stdio MCP | Read-only tooling; no arbitrary path, credential, guest execution or write authority; not a remote authenticated service |
 
-See [interchange](INTERCHANGE.md), [provider evidence](PROVIDER-VERIFICATION.md),
-[egress](EGRESS.md), [conditions](CONDITIONS.md), [recipes](RECIPES.md),
-[bulk measurements](BULK.md), [TypeScript authoring](TYPESCRIPT-AUTHORING.md), and
-[tooling/MCP](TOOLING.md) for the executable interfaces and exact restrictions.
+See [interchange](../../INTERCHANGE.md), [provider evidence](../../PROVIDER-VERIFICATION.md),
+[egress](../../EGRESS.md), [conditions](../../CONDITIONS.md), [recipes](../../RECIPES.md),
+[bulk measurements](../../BULK.md), [TypeScript authoring](../../TYPESCRIPT-AUTHORING.md), and
+[tooling/MCP](../../TOOLING.md) for the executable interfaces and exact restrictions.
 
 ## Preserved architecture
 

package/docs/{NEXT-STEPS.md → archive/2026-09-19/NEXT-STEPS.md}

@@ -1,10 +1,20 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
 # Next steps: closing the gaps
 
 Status: plan written 2026-09-18 from the cleanup, the
 [usability review](USABILITY-REVIEW.md) and the AI-first framework brief.
 Each item says what it fixes, where the work is, how it is proven, and its
 size (S: a day, M: a week, L: more). Phases can overlap; order inside a phase
-is the recommended sequence. The [roadmap](../ROADMAP.md) owns what ships;
+is the recommended sequence. The [roadmap](ROADMAP.md) owns what ships;
 this page owns how the gaps close.
 
 ## The rule everything below serves
@@ -16,7 +26,7 @@ policies, admin patterns and deployment glue on every project, and the person
 ends up owning it. URLCode's job is a small, deterministic, portable vocabulary
 in readable YAML, so generated code goes to the part that is the application.
 The agent describes what; the runtime owns how. The three tests that decide
-what gets built are in [project direction](PROJECT-DIRECTION.md#why-your-ai-should-build-your-application-not-your-framework):
+what gets built are in [project direction](../../PROJECT-DIRECTION.md#why-your-ai-should-build-your-application-not-your-framework):
 the boundary test (do agents generate this across unrelated projects?), the
 feature test (does it reduce what the agent must know, generate, debug or
 maintain?) and the evidence test (measured repetition, not a feature list).
@@ -497,7 +507,9 @@ this repository and were not run here.
 
 Fixes: protecting a route today is `policies: { extensions: { auth: {} } }`,
 which is the mechanism, not the intent. The form an agent should write is
-`auth: { required: true, roles: [admin] }`.
+`auth: { required: true, role: admin }`. (Delivered in `0.4.0-alpha.1` with
+`role` singular; `routeAuth` sets `additionalProperties: false`, so the plural
+`roles` this plan originally proposed is rejected by the validator.)
 
 - Work: a route-level `auth` key that expands to the `policies.extensions.auth`
   requirement the auth extension validates; `roles` maps to the extension's

package/docs/archive/2026-09-19/OPEN-DECISIONS.md

@@ -0,0 +1,277 @@
+# Historical record
+
+Archived 2026-09-19. This records an earlier implementation or proposal, not
+current instructions. See the [current roadmap](../../../ROADMAP.md),
+[current contract](../../SPECIFICATION.md) and [open decisions](../../OPEN-DECISIONS.md).
+Remaining acceptance work is not declared complete by archiving this record.
+
+<!-- trust-model-prose: historical-file -->
+<!-- guidance-claims: ignore-file -->
+
+# Open decisions
+
+Status: written 2026-09-19 from a review of the repositories as they then
+stood (nine; eight after `urlcode-docs` was deleted — see item 2). 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](../../VERSION-ALIGNMENT.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 (revised 2026-09-19):** eight repositories — `urlcode`,
+`urlcode-auth`, `urlcode-admin`, `urlcode-ui`, `urlcode-middleware`,
+`urlcode-template`, `urlcode-cloud` (private) and `homebrew-urlcode`. Five are
+in scope for consolidation. [The monorepo spike](SPIKE-MONOREPO.md) is
+complete, its layout is marked decided (option A), Changesets is decided, its
+migration mechanics and sequencing are written, and it has three open questions
+for the maintainer. It has been neither accepted nor rejected.
+
+**What changed since this item was written:**
+
+- The count fell rather than rose. `urlcode-dynamic-link`, `urlcode-short` and
+  `urlcode-docs` were deleted; the spike's in-scope set is **five, not six**.
+  The migration is smaller today than when this item claimed it only grows.
+- **The spike's hard precondition is currently satisfied:** zero open pull
+  requests across all five in-scope repositories, and zero open issues outside
+  core. The issue-recreation step is a no-op. This is not a stable state.
+- **The drift argument stopped being hypothetical.** `urlcode-auth`,
+  `urlcode-admin` and `urlcode-ui` all pin core at `d5e86017` and went 21
+  commits stale within a day of that pin being corrected by hand.
+- **A new argument exists.** `check-trust-model-prose.ts` and
+  `check-guidance-claims.ts` now fail CI on stale or schema-contradicting
+  prose, but only within this checkout. The original observed failure —
+  `urlcode-auth/SECURITY.md` describing guest code as sandboxed — remains
+  unreachable by any check while `auth` is a separate repository. See
+  "What consolidation would newly enforce" in the spike.
+
+**Cost of leaving it open:** 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, and the four
+downstream repositories stay outside the enforcing checks that now protect this
+one.
+
+**Recommendation, sharpened:** 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. If the answer is yes, note
+that the precondition is met now and will not stay met — the survey above is
+the cheapest it will ever be. If the answer is no, the thing that needs
+designing is how the trust-model and guidance checks reach the four downstream
+repositories, because the pin drift shows the manual pass does not hold for a
+day.
+
+## 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. Where documentation is authored — decided
+
+**Decided 2026-09-19: documentation is authored in this repository, in
+`docs/`.** The instruction that sent new reader-facing pages to urlcode-docs is
+removed from `AGENTS.md`, `CONTRIBUTING.md`, `README.md` and `docs/README.md`.
+A behaviour change and its documentation now ship in the same pull request,
+which is the arrangement where neither can land alone.
+
+The original entry, for the record:
+
+> **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 -->
+
+**The duplication is resolved by retirement, not by merging.** `urlcode-docs`
+was deleted on 2026-09-19, along with `urlcode-short` and
+`urlcode-dynamic-link`; all three GitHub repositories are gone, so links to
+them 404 with no redirect. Rather than reconcile 51 drifted page pairs, the
+content that was genuinely ahead in `urlcode-docs` was brought across before it
+went away:
+
+- Trusted-by-default corrections it carried and this repository did not, in
+  `POLICIES.md`, `policies/compression.md`, `BEST-PRACTICES.md`, `ASSETS.md`
+  and `PRERENDER.md`.
+- Two pages that existed **only** there: `MANAGEMENT-SECURITY.md`, which
+  `SECURITY-AUDIT.md` already linked to twice from this repository and which
+  was therefore a live broken link, and `EXTENSION-IMPLEMENTATION.md`.
+
+Its other pages were either behind this repository, or copies of pages owned by
+`urlcode-auth`, `urlcode-admin`, `urlcode-ui` and `urlcode-dynamic-link`. Some
+were actively stale: its `PRERENDER.md` and `VERCEL.md` still described the
+`link` handler that `0.4.0-alpha.2` removed, so taking either wholesale would
+have reintroduced a removed feature. Every page was judged individually.
+
+**The lesson worth keeping:** the drift reached this size because the same page
+existed in two places with no record of which side won. `AGENTS.md` now states
+that documentation is authored here, so the second copy cannot reappear.
+
+## 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, and urlcode-docs#17 — the last no
+longer resolvable, that repository having been deleted) 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.

package/docs/archive/2026-09-19/RELEASE-SECURITY.md

@@ -0,0 +1,186 @@
+# Historical release process — superseded September 19, 2026
+
+This is the prior process and incident record. Current instructions live in
+[release security](../../RELEASE-SECURITY.md). Links below resolve to the current documentation unless otherwise noted.
+
+# Candidate and release security process
+
+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:
+
+- `candidate.yml` is dispatched manually on main and retains a **signed build
+  candidate** for 30 days without publishing it. Use it to review a commit
+  before tagging it.
+- `release.yml` runs on a `v*` tag whose commit is already on main, and publishes
+  a GitHub release. Publication to npm and GHCR is opt-in per repository variable
+  (`PUBLISH_NPM`, `PUBLISH_CONTAINER`), so a release can be artifacts-only.
+
+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.
+   Current reviewed main is the security support baseline; no guaranteed SLA/backports.
+2. Change dependencies through protected PRs. Review upstream provenance/advisories,
+   lockfile integrity and tests. Direct dependencies are exact, npm installs use
+   `npm ci`, CI actions use full commit SHAs, and container bases use SHA-256 digests.
+   Dependabot proposes updates; it does not authorize merging. Never silently
+   refresh dependencies during a candidate build.
+3. After protected main checks pass, a maintainer manually dispatches
+   `.github/workflows/candidate.yml` **on main**, or pushes a `v<version>` tag to
+   run `.github/workflows/release.yml`. The release workflow refuses a tag whose
+   commit is not an ancestor of main, refuses a tag that disagrees with
+   `package.json`, and refuses to build a private or unlicensed package. It reads and validates the digest-pinned Node image directly from Dockerfile,
+   installs without lifecycle scripts, verifies, package-tests and runs local drills.
+   It packs the runtime and creates a CycloneDX dependency SBOM plus a manifest
+   recording source commit, lockfile hash, engine versions and artifact hashes.
+   The package contains `dist/`, produced inside that build from the tagged
+   TypeScript sources by Node's type stripping (`scripts/build.ts`); `dist` is
+   never committed. The manifest records the Node version that stripped it, the
+   locked TypeScript version and a SHA-256 per emitted file
+   (`dist/BUILD-MANIFEST.json`), so a download can be verified by running
+   `npm run build` on the tagged commit with that Node version and comparing its
+   `dist/` file by file. The build strips types and rewrites specifier
+   extensions; it never bundles, minifies or transforms syntax, so every line of
+   `dist/x.js` is the corresponding line of `src/x.ts`. CI's `build-fidelity`
+   job builds twice and diffs the trees, so the transform is known to be
+   deterministic before a tag is cut.
+4. The pinned official `actions/attest` action signs provenance for the package,
+   SBOM and manifest using short-lived GitHub OIDC/Sigstore credentials. No long-lived
+   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 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 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
+   provenance, not safety, reproducible bytes or production approval. See
+   [GitHub verification](https://cli.github.com/manual/gh_attestation_verify) and
+   [the official attestation action](https://github.com/actions/attest).
+6. Before registry publication, assign patch/release ownership and retention, and
+   document version/support policy. Before claiming hostile multi-tenant or
+   deployment-specific readiness, close independent-review and deployment gates. Keep last-good verified artifacts and compatible policies;
+   rehearse rollback. Never overwrite a published artifact/version or downgrade a
+   management writer past its audit/security baseline.
+
+The SBOM describes npm dependencies; it is not a complete OS/container SBOM. Hosted
+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` 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.