@jimhoyd/urlcode 0.4.2 → 0.4.6

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

@@ -1,277 +0,0 @@
-# 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

@@ -1,186 +0,0 @@
-# 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.