🔀 Merge chore/docs-restructure into main

📝 Check off the docs restructure and note it in the changelog
📝 Improve docs after split
2026-09-15 21:51:33 +00:00 · 2026-09-15 21:51:21 +00:00 · 2026-09-15 21:46:41 +00:00 · 2026-09-15 13:56:49 +00:00 · 2026-09-15 13:47:01 +00:00 · 2026-09-15 13:46:31 +00:00
24 changed files with 1538 additions and 387 deletions
@@ -49,15 +49,27 @@ jobs:
        needs: release-gate
        if: needs.release-gate.outputs.skip != 'true'
        runs-on: ubuntu-latest
-        # Bind-mount the shared pages tree so the coverage step below can write
-        # into it. The runner whitelists this path via `container.valid_volumes`
-        # (docker-space `setup/gitea.sh`); `image` is omitted on purpose so the
-        # runner keeps using its default job image.
+        # `image` extends the runner's default job image (catthehacker/act)
+        # with Node 26 pre-planted in the tool cache layout, so setup-node's
+        # version probe hits and never downloads (see docker/Dockerfile). The
+        # tag MUST equal the exact version pinned in `.node-version`; the bump
+        # ritual is documented in CONTRIBUTING.md § CI runner image. The volume
+        # bind-mounts the shared pages tree so the
+        # coverage step below can write into it; the runner whitelists this
+        # path via `container.valid_volumes` (docker-space `setup/gitea.sh`).
        container:
+            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
            volumes:
                - /data/gitea-pages:/data/gitea-pages
        steps:
            - uses: actions/checkout@v4
+            # Fail fast when the job container is not the baked image: a stale
+            # tag on the runner (`forcePull=false` in its pull log) silently
+            # reintroduces the per-job download. Cheap, and it names the
+            # invariant.
+            - name: Assert the baked tool cache is present
+              run: |
+                  test -f "/opt/hostedtoolcache/node/$(tr -d '[:space:]' < .node-version)/x64.complete"
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
@@ -108,6 +120,10 @@ jobs:
        if: needs.release-gate.outputs.skip != 'true'
        runs-on: ubuntu-latest
        continue-on-error: true
+        # Same baked image as `build` — without it this job re-downloads Node
+        # per run (see docker/Dockerfile).
+        container:
+            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
        steps:
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
@@ -121,24 +137,30 @@ jobs:
        if: startsWith(gitea.ref, 'refs/tags/')
        needs: build
        runs-on: ubuntu-latest
+        # Same baked image as `build` — setup-node still owns the registry-url
+        # `.npmrc` rewrite here; only the Node download is skipped.
+        container:
+            image: gitea.e1nsnull.de/tmu/act-ci:26.8.2
        # The release page is created with the run's automatic Gitea token
-        # (`github.token`), not `NPM_TOKEN`, so it needs `contents: write`.
+        # (`github.token`), so it needs `contents: write`.
        permissions:
            contents: write
+        # The npm token is optional: `secrets` is not an allowed context in a
+        # step `if` (see GitHub's context-availability table), so it is lifted
+        # into job-level `env`, where an unset secret arrives as the empty
+        # string and skips the publish rather than attempting an unauthenticated
+        # one. Set NPM_TOKEN in the Gitea repo: Settings → Actions → Secrets.
+        env:
+            NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
        steps:
-            # Double-gate: publish only runs on a tag *and* aborts here if NPM_TOKEN
-            # is unset, so a tag push never silently no-ops (or half-publishes). Set
-            # NPM_TOKEN in the Gitea repo: Settings → Actions → Secrets.
-            - name: Assert NPM_TOKEN is configured
-              run: |
-                  if [ -z "${{ secrets.NPM_TOKEN }}" ]; then
-                      echo "::error::NPM_TOKEN secret is not set — refusing to publish."
-                      exit 1
-                  fi
            - uses: actions/checkout@v4
            - uses: actions/setup-node@v4
              with:
                  node-version-file: .node-version
+                  # Same lockfile/key as `build`, and tag runs can read caches
+                  # saved on `main` — without this, every release pays a cold
+                  # `npm ci` despite the warm shared npm cache.
+                  cache: "npm"
                  registry-url: "https://registry.npmjs.org/"
            - run: npm ci
            # Consume the dist/ that `build` produced and gated, instead of
@@ -159,9 +181,28 @@ jobs:
              env:
                  TAG_REF: ${{ gitea.ref }}
              run: ./scripts/release-notes.sh "${TAG_REF#refs/tags/}" > release-notes.md
-            - uses: https://gitea.com/actions/gitea-release-action@v1
+            - name: Create the Gitea release
+              id: gitea_release
+              uses: https://gitea.com/actions/gitea-release-action@v1
              with:
                  body_path: release-notes.md
-            - run: npm publish --access public
+            - name: Publish to npm
+              id: npm_publish
+              if: env.NPM_TOKEN != ''
+              run: npm publish --access public
              env:
-                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+                  NODE_AUTH_TOKEN: ${{ env.NPM_TOKEN }}
+            # All-or-nothing: the tag is only released once *both* the release
+            # page and the npm package are up. A skipped npm publish (NPM_TOKEN
+            # unset) has no `success` outcome, so `always()` reaches this check
+            # even after a failure and turns the skipped half into an explicit
+            # red job instead of a silently green one.
+            - name: Require both releases
+              if: always()
+              run: |
+                  GITEA="${{ steps.gitea_release.outcome }}"
+                  NPM="${{ steps.npm_publish.outcome }}"
+                  if [ "${GITEA}" != success ] || [ "${NPM}" != success ]; then
+                      echo "::error::incomplete release — gitea=${GITEA:-skipped} npm=${NPM:-skipped}"
+                      exit 1
+                  fi
@@ -1 +1 @@
-26
+26.8.2
@@ -12,6 +12,7 @@ first-action facts. Do not restate evolving prose here — it will drift.
 - **Optional code intelligence:** this repo installs `@spences10/pi-lsp` (pinned in `.pi/settings.json`) as a project-local pi extension. It talks to the repo's own TypeScript 7 via `tsc --lsp --stdio` and exposes **read-only** tools — `lsp_hover`, `lsp_definition`, `lsp_references`, `lsp_find_symbol`, `lsp_document_symbols`, `lsp_diagnostics(_many)`. Prefer `lsp_references` over `grep -w` for widely-colliding identifiers (`matches`, `type`, …); use `lsp_hover` to read inferred types on generic-heavy code. It has no rename / code-action / apply-edit surface — the write side is pi's `edit` tool + `check:tsc`. Treat empty LSP output as _inconclusive_, not success: **`npm run test` / `npm run verify` remain the sole authoritative gate** (see the next bullet). The server keeps running across that gate with a ~5 min idle timeout and registers no file watchers, so if you change `tsconfig.json` / `package.json` mid-session its diagnostics can be stale — when LSP output disagrees with `check:tsc`, trust `check:tsc` and restart pi (or wait out the idle timeout) before concluding the LSP is wrong.
 - **Definition of done — run this before you call the work finished:** `npm run verify`. If all green, commit. If red, look at the output, fix the root cause, and re-run.
 - **On commit:** write a good message (see [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages)). Lefthook's pre-commit hook already runs the fast, offline, staged-file checks — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
+- **Document decisions where the next maintainer will look:** rationale, rejected alternatives and known issues go in `development/<category>.md` (see [development/README.md](./development/README.md)); the actionable rule stays in [CONTRIBUTING.md](./CONTRIBUTING.md) and links to it. Write each fact once — never copy the rule into `development/` or the reason into `CONTRIBUTING.md` — and change both in the same commit when a rule changes.
 - **`npm run maintain` is NOT part of the feature loop.** Its scans are advisory, never a gate; run them only on an explicit maintenance / update-deps branch.

    ```sh
@@ -64,5 +65,6 @@ In both cases, follow [CONTRIBUTING.md § Testing discipline (type-driven)](./CO
 - [CONTRIBUTING.md § Script prefix convention](./CONTRIBUTING.md#script-prefix-convention) — adding an `npm run` script? reuse an existing prefix or it doesn't belong.
 - [CONTRIBUTING.md § Commit messages](./CONTRIBUTING.md#commit-messages) — gitmoji + imperative + 50/72.
 - [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers) — what runs when and at what cost (`watch` / pre-commit / pre-push / `check` / `verify` / `fix` / `maintain` / CI).
- [README.md § Tooling decisions](./README.md#tooling-decisions) — the rationale behind each tool choice; read before changing tooling.
+- [development/](./development/README.md) — the decisions, rejected alternatives and known issues behind the rules; the “why” that CONTRIBUTING.md links to. Read the relevant file before changing an area.
+- [development/tooling.md](./development/tooling.md) — the rationale behind each tool choice; read before changing tooling.
 - [package.json `#scripts`](./package.json) — the source of truth for every command (the `LEFTHOOK_FILES` convention scopes them to staged files vs. the whole project).
@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 ## [Unreleased]

+- restructure the documentation: README.md for users, CONTRIBUTING.md for contributors, and development/ for the decisions, rejected alternatives and known issues
+- document the decisions and known issues for CI, tooling, testing, publishing and the workflow
+
+## [0.1.5] - 2026-09-15
+
+- improve CI configuration
+
+## [0.1.4] - 2026-09-14
+
+- fix CI to node from custom image
+- upgrade dependencies
+
+## [0.1.3] - 2026-09-14
+
+- change to custom image for CI
+
+## [0.1.2] - 2026-09-14
+
+- upgrade dependencies
+
 ## [0.1.1] - 2026-09-14

 - upgrade dependencies
@@ -15,6 +35,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

 - basic setup

-[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.1...main
+[Unreleased]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.5...main
+[0.1.5]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.4...0.1.5
+[0.1.4]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.3...0.1.4
+[0.1.3]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.2...0.1.3
+[0.1.2]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.1...0.1.2
 [0.1.1]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/0.1.0...0.1.1
 [0.1.0]: https://gitea.e1nsnull.de/tmu/tiny-pattern-ts/compare/20308c5a6d8cccfb09b02ac2ebebd8055e91cd11...0.1.0
@@ -1,52 +1,39 @@
 # Contributing

-This document is for maintainers and contributors working on the project itself. End-user documentation is in [README.md](./README.md). The machine entry point for AI coding agents is [AGENTS.md](./AGENTS.md); keep this file as the prose home for the rules below so agents and humans don't diverge.
+This document is for maintainers and contributors working on the project
+itself. End-user documentation is in [README.md](./README.md). The reasons
+behind the rules here — the decisions, rejected alternatives, and known issues —
+live in [development/](./development/README.md). The machine entry point for AI
+coding agents is [AGENTS.md](./AGENTS.md); keep this file as the prose home for
+the rules so agents and humans don't diverge.

-## Rules the tools don't enforce
+## Setup

-CI and review will bounce these even though `npm run check` and the linters don't catch them. They're the high-frequency things a contributor (or an agent) reaches for by default:
+1. Clone the repository.
+2. Install Node.js >= 26 — see [.node-version](./.node-version); the exact pinned
+   version is what CI and the runner image use.
+3. `npm ci`.
+4. `npm run setup` — the one-time clone configuration (currently registers the
+   commit-message template).

- **Source imports use `.ts` extensions, never `.js`.** `node --strip-types` only resolves the `.ts` form at test time; "Pre-fixing" an import to `.js` breaks the inner loop. (rationale: README § Tooling decisions)
- **A new `npm run` script must reuse an existing prefix** (`create:` / `check:` / `fix:` / `test:` / `watch:` / `maintain:` / `publish:` / `setup:`). If none fits, that's a signal the script doesn't belong in the pipeline — not a reason to invent a new prefix. If it genuinely does belong, add the prefix to both lists here in the same commit; an undocumented prefix becomes invisible and quietly accrues members. (see [Script prefix convention](#script-prefix-convention))
- **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The trade-off must sit next to the code it silences. This is a _human_ last-resort convention; agents must not add these — see [AGENTS.md § Never do](./AGENTS.md#never-do). (rationale: README § Tooling decisions)
- **Don't put slow / network / whole-project scans in `check` or pre-commit.** Advisory scans are not correctness gates; they belong under `maintain:`. (see [Feedback tiers](#feedback-tiers) and [Script prefix convention](#script-prefix-convention))
- **New work starts with `npm run create:branch`, never a hand-written `git switch -c`/`git checkout -b`.** The command carries the branch precondition; branching around it skips the clean-tree, current-`main` and green-baseline checks, and the skip is invisible until a failure can no longer be attributed. (see [Branching model](#branching-model))
- **Work is merged back with `npm run create:finish`, never a hand-written `git merge`.** The command carries the merge-side preconditions (clean tree, current `main`, a `feature/`/`fix/`/`chore/` branch) and runs `npm run verify` after the merge, so a merge cannot land unverified. (see [Branching model](#branching-model))
- **There is no local `npm run publish`, and `publish:publint` / `publish:attw` don't go in `check`.** (see [Publishing workflow](#publishing-workflow))
+## Development commands

-## Editor configuration
-
-`.editorconfig` is for editor compatibility, not a gate — it is a sane fallback for the files oxfmt does not format (shell scripts, dotfiles, `LICENSE`, the commit-message template, and git's `COMMIT_EDITMSG` buffer). Where both apply, `.oxfmtrc.json` is authoritative: oxfmt is the formatter, and the overlapping `.editorconfig` keys only keep non-oxfmt editors close to the formatted result.
-
-## Commit messages
-
-Gitmoji subject, imperative mood, 50/72 wrapping. The template is `commit-message-template`; run `npm run setup:git-commit-message` once after cloning to register it as git's `commit.template` (or `npm run setup` to run every one-time clone step).
-
-Examples from history: `:sparkles: Add watch tier with watch:test child`, `:recycle: Move type-aware config to .oxlintrc.json; use source-level disable directives`, `:memo: Restore unique maintainer content as CONTRIBUTING.md`. The body explains _what and why_, not _how_; link issues with `Resolves #...`.
-
-## Script prefix convention
-
-Script names in `package.json` use a prefix that signals _when_ the script is intended to run. A `<prefix>:<name>` script is implicitly aggregated by a `<prefix>` script (if one exists) and run by the corresponding lefthook hook or CI step. Picking the right prefix documents the script's intended lifecycle:
-
- `create:*` — front doors of the repo's own workflow; these mutate git state rather than the source. `create:branch` opens a unit of work (asserts a clean tree, a current `main` and a green baseline before it branches), `create:finish` closes the branch half (merges the current unit of work into `main` and verifies the result), `create:release` closes the release half (maintainer-only). No bare `create` aggregator on purpose — see `publish:*` for the precedent.
- `check:*` — read-only verification; never modifies files. Aggregated by `npm run check`.
- `fix:*` — mutating counterpart of a `check:*` script. Aggregated by `npm run fix`; the diff is the review surface.
- `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` + unit tests); `test:unit` skips the typecheck for fast local iteration; `test:ci` adds c8 coverage.
- `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by `watch`; currently a single child (`watch:test`), and a future `watch:oxlint` / `watch:tsc` would run concurrently under that umbrella.
- `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project and/or network-bound, so never a correctness gate. Aggregated by `npm run maintain`.
- `publish:*` — validates the _publishable artifact_ (e.g. `dist/`) rather than the source, so it needs a fresh build. (see [Rules the tools don't enforce](#rules-the-tools-dont-enforce) and [Publishing workflow](#publishing-workflow))
- `setup:*` — one-time configuration of a fresh clone; mutates the local environment (git config, editor settings) rather than the repo source, so it is never part of a hook or CI step. Aggregated by `npm run setup` (the umbrella), run once after cloning.
-
-A new script should pick the prefix that matches its lifecycle, not invent a new one. If no existing prefix fits, that's a signal the script doesn't belong in the standard pipeline. When it genuinely does belong, a new prefix is allowed — but it enters both lists in this file in the same commit as its first member, otherwise the rule "reuse an existing prefix" silently develops an exception (the old `use:` prefix was exactly that; it is now retired into `setup:`).
-
-Separately, some top-level scripts are **bare** (no prefix): the entry points that either run a single tool (`build`, `clean`) or aggregate a `prefix:*` family (`check`, `fix`, `test`, `watch`, `maintain`, `setup`), plus one convenience that composes across tiers: `verify` — composing `check` + `test:unit` into one whole-project correctness gate (it deliberately uses `test:unit` rather than `test` because `check` already runs `check:tsc`, so the type checker runs exactly once). Bare commands are how you invoke a tier; the `prefix:*` scripts are what those tiers are made of.
+- **Build:** `npm run build`
+- **Test:** `npm run test`, `npm run test:ci`
+- **Watch:** `npm run watch` - re-runs tests on file save, humans only
+- **Checks:** `npm run check`, `npm run fix`
+- **Verify:** `npm run verify` — the definition of done
+- **Maintenance:** `npm run maintain` — advisory only
+- **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`

 ## Feedback tiers

-The tools are organized into a feedback ladder. Each tier catches different things at different costs; the rule of thumb is "earlier tiers fire more often, faster tiers catch less, slower tiers are more thorough":
+The tools are organized into a feedback ladder. Each tier catches different
+things at different costs; the rule of thumb is "earlier tiers fire more often,
+faster tiers catch less, slower tiers are more thorough":

 | Tier                             | When                    | What it runs                                                                                                                                            | Time  |
-| -------------------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------- | ----- |
+| -------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
 | `npm run watch`                  | manual                  | `watch:test` — re-runs tests on file save                                                                                                               | ~0.1s |
 | Pre-commit (auto)                | on stage                | tsc + oxlint + oxfmt + cspell (staged files only)                                                                                                       | ~1.3s |
 | Pre-push (auto)                  | on push                 | `npm test` (full tsc + unit tests)                                                                                                                      | ~3.5s |
@@ -56,45 +43,176 @@ The tools are organized into a feedback ladder. Each tier catches different thin
 | `npm run maintain`               | manual / CI (advisory)  | `maintain:knip` + `maintain:outdated` (whole-project + network scans)                                                                                   | ~10s  |
 | CI build (auto)                  | on push to `main` / tag | `build` job (build + correctness + packaging) — see [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)                                                | ~30s+ |
 | CI maintain (auto, non-blocking) | on push to `main`       | `npm run maintain` — reports, never fails the build                                                                                                     | ~10s  |
-| CI publish (auto)                | on tag                  | Gitea release page (body from CHANGELOG) + `publish:publint` + `publish:attw`, then `npm publish`        | ~15s  |
+| CI publish (auto)                | on tag                  | packaging checks + `publish:publint` / `publish:attw`, then the Gitea release page and `npm publish` (skipped, and the job failed, without `NPM_TOKEN`) | ~15s  |

-### Why these splits?
-
- **`watch:*` is a manual tier, not a hook.** The developer starts it on demand (it has to be killed with Ctrl-C) and it runs in a dedicated terminal pane. It sits as the earliest tier in the feedback ladder, catching failures the moment a file is saved — before staging, before commit.
- **`check:tsc`, `check:oxlint`, `check:oxfmt`, `check:cspell`** are in pre-commit because they are fast (~0.2–0.5s each), fully offline, and naturally scope to staged files via the `LEFTHOOK_FILES` env var convention. They give instant feedback on what you typed.
- **`test` (and the `tsc` it includes) is in pre-push** because it runs the whole test suite across the whole project. The pre-commit `LEFTHOOK_FILES` convention doesn't apply to the test runner, so pre-commit isn't the right home. Pre-push runs after all commits are made but before the push leaves the machine, catching regressions that span multiple commits.
-
-### Before pushing
-
-Run `npm run verify` — the one-shot correctness gate in the table above. Run `npm run maintain` only on a maintenance / update-deps branch.
+Before pushing, run `npm run verify` — the one-shot correctness gate. Run
+`npm run maintain` only on a maintenance / update-deps branch. Why the splits
+are where they are: [development/workflow.md § Feedback tiers](./development/workflow.md#feedback-tiers).

 ## Testing discipline (type-driven)

-For this library the types _are_ the feature — narrowing, `exhaustive()` returns, the `Matcher<T>` contract — so a runtime-only test loop would verify the wrong thing. New behavior follows **type-driven development** (in Edwin Brady's sense): _treat the type as the plan for a program, and use the compiler and type checker as your assistant, guiding you to a complete program that satisfies the type_ ([idris-lang.org](https://www.idris-lang.org/)). Here that plan is the `expectTypeOf` assertion, written first. The loop is **type → red → green → refactor**:
+For this library the types _are_ the feature, so development is **type-driven**:
+the compile-time expectation is written before the runtime assertion, and both
+before the implementation. The loop is **type → red → green → refactor**:

-1. **Type** — write the compile-time expectation first (`expectTypeOf(...).toEqualTypeOf<…>()`) and let `npm run check:tsc` fail on the _type_. The type error is the spec you want to hit before the runtime logic exists.
-2. **Red** — add the matching runtime assertion (`assert.*`) so `npm run test:unit` now fails on behavior.
-3. **Green** — implement in `src/*.ts` until both the type check and the test pass.
-4. **Refactor** — with the type system and the tests as the safety net, then `npm run verify` as the definition-of-done gate.
+1. **Type** — write the compile-time expectation first
+   (`expectTypeOf(...).toEqualTypeOf<…>()`) and let `npm run check:tsc` fail on
+   the _type_. The type error is the spec you want to hit before the runtime
+   logic exists.
+2. **Red** — add the matching runtime assertion (`assert.*`) so
+   `npm run test:unit` now fails on behavior.
+3. **Green** — implement in `src/*.ts` until both the type check and the test
+   pass.
+4. **Refactor** — with the type system and the tests as the safety net, then
+   `npm run verify` as the definition-of-done gate.

-This is why every test in the suite pairs an `expectTypeOf(...)` with an `assert.*` — keep them together. Type-first is also enforced structurally: `npm test` runs `check:tsc` before the test runner, so a wrong type can never be papered over by a passing assertion. Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the types so both the type check and the runtime assertion pass, never suppress the ones you can't make pass.
+Every test pairs an `expectTypeOf(...)` with an `assert.*`; keep them together.
+Type-first is enforced structurally: `npm test` runs `check:tsc` before the
+test runner, so a wrong type can never be papered over by a passing assertion.
+Per [AGENTS.md § Never do](./AGENTS.md#never-do), reach green honestly — fix the
+types, never suppress the checks you can't make pass. Full rationale:
+[development/testing.md](./development/testing.md).
+
+## Code style and formatting
+
+`oxfmt` is the formatter and `oxlint` is the linter (with type-aware rules).
+`npm run fix` resolves the fixable issues; `npm run check` verifies without
+writing. Suppressions must be fixed at the root — do not add `oxlint-disable`
+directives or `as` casts to force a green run (see
+[AGENTS.md § Never do](./AGENTS.md#never-do)).
+
+Suggested VSCode extensions are in
+[.vscode/extensions.json](./.vscode/extensions.json); the project's formatter
+and linter are wired up there. Toolchain decisions:
+[development/tooling.md](./development/tooling.md).
+
+## Commit messages
+
+Gitmoji subject, imperative mood, 50/72 wrapping. The template is
+[commit-message-template](./commit-message-template); `npm run setup`
+(or `npm run setup:git-commit-message`) registers it as git's
+`commit.template`. Examples and rationale:
+[development/workflow.md § Commit messages](./development/workflow.md#commit-messages).
+
+## Script prefix convention
+
+Script names in `package.json` use a prefix that signals _when_ the script is
+intended to run. A `<prefix>:<name>` script is implicitly aggregated by a
+`<prefix>` script (if one exists) and run by the corresponding lefthook hook or
+CI step. Pick the prefix that matches the script's lifecycle:
+
+- `create:*` — front doors of the repo's own workflow; these mutate git state
+  rather than the source. `create:branch` opens a unit of work, `create:finish`
+  closes the branch half, `create:release` closes the release half
+  (maintainer-only). No bare `create` aggregator on purpose.
+- `check:*` — read-only verification; never modifies files. Aggregated by
+  `npm run check`.
+- `fix:*` — mutating counterpart of a `check:*` script. Aggregated by
+  `npm run fix`; the diff is the review surface.
+- `test:*` — test scripts. `test` is the canonical entry point (`check:tsc` +
+  unit tests); `test:unit` skips the typecheck for fast local iteration;
+  `test:ci` adds c8 coverage.
+- `watch:*` — long-running watchers for the manual inner dev loop. Aggregated by
+  `watch`.
+- `maintain:*` — advisory repo-maintenance scans: read-only, but whole-project
+  and/or network-bound, so never a correctness gate. Aggregated by
+  `npm run maintain`.
+- `publish:*` — validates the _publishable artifact_ (e.g. `dist/`) rather than
+  the source, so it needs a fresh build.
+- `setup:*` — one-time configuration of a fresh clone; mutates the local
+  environment rather than the repo source, so it is never part of a hook or CI
+  step. Aggregated by `npm run setup`, run once after cloning.
+
+A new script must reuse an existing prefix. If none fits, that's a signal the
+script doesn't belong in the pipeline — not a reason to invent a new prefix. If
+it genuinely does belong, add the prefix to this list in the same commit as its
+first member; an undocumented prefix becomes invisible and quietly accrues
+members. Why `create:` exists, the rejected names, and the design of the bare
+scripts: [development/workflow.md § Script prefix convention](./development/workflow.md#script-prefix-convention).
+
+## Rules the tools don't enforce
+
+CI and review will bounce these even though `npm run check` and the linters
+don't catch them. They're the high-frequency things a contributor (or an agent)
+reaches for by default:
+
+- **Source imports use `.ts` extensions, never `.js`.** `node --strip-types`
+  only resolves the `.ts` form at test time; "pre-fixing" an import to `.js`
+  breaks the inner loop. (why:
+  [development/tooling.md](./development/tooling.md#source-imports-use-ts-extensions))
+- **A new `npm run` script must reuse an existing prefix.** See
+  [Script prefix convention](#script-prefix-convention).
+- **`oxlint-disable` directives live in source, not `.oxlintrc.json`.** The
+  trade-off must sit next to the code it silences. This is a _human_ last-resort
+  convention; agents must not add these — see
+  [AGENTS.md § Never do](./AGENTS.md#never-do). (why:
+  [development/tooling.md](./development/tooling.md#oxlint-disable-directives-live-next-to-the-code))
+- **Don't put slow / network / whole-project scans in `check` or pre-commit.**
+  Advisory scans are not correctness gates; they belong under `maintain:`. (why:
+  [development/workflow.md](./development/workflow.md#feedback-tiers))
+- **New work starts with `npm run create:branch`, never a hand-written
+  `git switch -c` / `git checkout -b`.** The command carries the branch
+  precondition; branching around it skips the clean-tree, current-`main` and
+  green-baseline checks, and the skip is invisible until a failure can no longer
+  be attributed. (why:
+  [development/workflow.md](./development/workflow.md#branching-model))
+- **Work is merged back with `npm run create:finish`, never a hand-written
+  `git merge`.** The command carries the merge-side preconditions (clean tree,
+  current `main`, a `feature/`/`fix/`/`chore/` branch) and runs `npm run verify`
+  after the merge, so a merge cannot land unverified. (why:
+  [development/workflow.md](./development/workflow.md#branching-model))
+- **There is no local `npm run publish`, and `publish:publint` / `publish:attw`
+  don't go in `check`.** (why:
+  [development/publishing.md](./development/publishing.md#ci-only-publishing))
+- **A decision or its rationale belongs in `development/`, not here.** This file
+  holds the actionable rule; `development/<category>.md` holds why, the rejected
+  alternatives and the known issues. When you change a rule, update its category
+  file in the same commit and cross-link the two. (why:
+  [development/README.md](./development/README.md))

 ## Branching model

-**GitHub Flow (single-developer).** Every change — feature, fix, refactor — branches off `main` and is merged back via a local commit (no PR workflow on Gitea yet). Collaborative review via Gitea UI is not in place — Gitea is the lab; when something is tested and ready for production it will be promoted to GitHub.
+**GitHub Flow (single-developer).** Every change — feature, fix, refactor —
+branches off `main` and is merged back via a local commit. There is no pull
+request workflow on Gitea yet.

 - **Base branch:** `main`
 - **Branch naming:** `feature/<desc>` / `fix/<desc>` / `chore/<desc>`
- **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses, without changing anything, unless the working tree is clean (untracked files included), no merge/rebase/cherry-pick is in progress, `main` matches its upstream, and `npm run test` is green on `main` — so a later failure is always attributable to your edits. The prefix is still _your_ call, inferred from the task; the script validates it rather than guessing it.
- **Merging:** `npm run create:finish` (on the branch). It asserts the same clean-tree / no-operation / current-`main` preconditions, fast-forwards a stale `main` (a true divergence is refused), merges the branch `--no-ff`, runs `npm run verify`, and deletes the branch only after the merge is green. The push is deliberately left to `create:release`, so the merge stays local and reviewable — read the diff yourself before finishing.
- CI runs `npm run check` + `npm run test:ci` on every push to `main` — this is the authoritative gate. The one exception: a push headed by a release commit (`:rocket: Release x.y.z`) skips the full `build`/`maintain` jobs, because `create:release` pushes the tag for that exact commit right after and the tag run is the authoritative one (see `release-gate` in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml)).
- **Releases are NOT triggered by pushes.** Only the maintainer triggers a release (see [Publishing workflow](#publishing-workflow)).
+- **Starting work:** `npm run create:branch -- <prefix>/<desc>`. It refuses,
+  without changing anything, unless the working tree is clean, no
+  merge/rebase/cherry-pick is in progress, `main` matches its upstream, and
+  `npm run test` is green on `main`. The prefix is _your_ call, inferred from the
+  task; the script validates it rather than guessing it.
+- **Merging:** `npm run create:finish` (on the branch). It re-asserts the same
+  preconditions, merges `--no-ff`, runs `npm run verify`, and deletes the branch
+  only after the merge is green. The push is left to `create:release`, so the
+  merge stays local and reviewable.
+- CI runs on every push to `main` — see [Feedback tiers](#feedback-tiers) and
+  [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml).
+- **Releases are NOT triggered by pushes.** Only the maintainer triggers a
+  release; see [Publishing](#publishing).

-## Publishing workflow
+Full rationale, including the front-door decisions and a known issue about
+`main` being ahead of its upstream between a merge and the next push:
+[development/workflow.md § Branching model](./development/workflow.md#branching-model).

-Publishing is CI-only by policy. Local `npm publish` is not supported. The maintainer triggers releases from `main`:
+## Submitting changes

-1. All intended changes are merged to `main` and passing CI.
-2. The maintainer runs `npm run create:release`. VS Code opens `CHANGELOG.md` to finalize the `[Unreleased]` notes; because pubv refuses a dirty tree, any edit is committed first (then folded into the release commit), and pubv's interactive prompt suggests a version from those notes — the maintainer confirms or edits it.
-3. `scripts/release.sh` creates a single release commit (graduated changelog + package.json bump, amended into one commit), tags it, and pushes everything to Gitea.
-4. CI fires on both pushes: the `publish` job runs on the tag (`build` + publish-tier checks + release page + `npm publish`), while the branch run's `release-gate` job recognizes the release commit and skips `build`/`maintain` — the tag verifies the identical SHA, so no work is duplicated. The job graph lives in [.gitea/workflows/ci.yml](./.gitea/workflows/ci.yml) — keep that file, not this list, as the source of truth. The publish-tier checks must pass before the artifact is published. The `publish` job also creates the Gitea release page from the matching Keep-a-Changelog section (`scripts/release-notes.sh`); it runs _before_ `npm publish` so a broken page fails CI without consuming a version, and `npm publish` stays the last step.
+There is no pull request workflow on Gitea yet, so a contribution is submitted
+as a branch that is merged locally:
+
+1. `npm run create:branch -- <prefix>/<desc>`.
+2. Commit your work (one or more commits, per the tests and style rules above).
+3. `npm run verify` — the definition of done.
+4. `npm run create:finish` to merge the branch into `main` and verify the
+   result.
+5. Present a handover for review. Once there are no further objections, the
+   maintainer pushes.
+
+When the project is promoted to GitHub, this step becomes a normal pull request
+against `main`.
+
+## Publishing
+
+Publishing is maintainer-only and CI-only. See
+[development/publishing.md](./development/publishing.md).
@@ -2,68 +2,172 @@

 Pattern matching for TypeScript/ESM environments (F#-style, not regex).

-## Development
+## Synopsis

- **Build:** `npm run build`
- **Test:** `npm run test`, `npm run test:ci`
- **Watch:** `npm run watch`
- **Checks:** `npm run check`, `npm run fix`
- **Verify:** `npm run verify` — the definition of done
- **Maintenance:** `npm run maintain` — advisory only
- **Individual fixes:** `npm run fix:oxfmt`, `npm run fix:oxlint`
+```ts
+import { match, P } from "tiny-pattern-ts";

-What each tier runs, when it fires and what it costs:
-[CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers). How the
-`prefix:` in a script name is chosen:
-[§ Script prefix convention](./CONTRIBUTING.md#script-prefix-convention).
+const reply = (answer: "yes" | "no") =>
+    match(answer)
+        .with(P.literal("yes"), (): "agreed" => "agreed")
+        .with(P.literal("no"), (): "declined" => "declined")
+        .exhaustive();

-### Tooling
+reply("yes"); // "agreed"
+```

- **TypeScript 7** — type checker and build (`tsc`).
- **node --test** + `--strip-types` — test runner.
- **c8** — code coverage for `test:ci`.
- **oxlint** — Rust-based linter, with type-aware rules powered by **oxlint-tsgolint** (typescript-go).
- **oxfmt** — Rust-based formatter (Prettier-compatible). Formats JS/TS, JSON/JSONC, YAML, Markdown, MDX, and more; built-in `package.json` key sorting replaces `sort-package-json`.
- **cspell** — spell checking.
- **knip** — finds unused dependencies, exports, and files.
- **check-outdated** — reports dependencies behind the registry; it exits non-zero whenever _any_ dependency is outdated.
- **publint** — validates `package.json` for ESM publishing correctness.
- **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` declarations against multiple module-resolution scenarios.
- **lefthook** — git hooks.
- **@spences10/pi-lsp** — read-only LSP code intelligence for AI coding agents (project-local `.pi/settings.json`). Talks to this repo's TypeScript 7 via `tsc --lsp --stdio`.
+## Description

-Each tool's configuration trade-off is recorded in [Tooling decisions](#tooling-decisions); when it runs is in [CONTRIBUTING.md § Feedback tiers](./CONTRIBUTING.md#feedback-tiers).
+`tiny-pattern-ts` gives TypeScript the shape of F#-style pattern matching:
+a value flows through a chain of patterns, the first one that matches runs its
+handler, and the handler receives the value narrowed to that pattern's type. The
+"patterns" are ordinary objects whose `matches` method is a TypeScript type
+guard, so narrowing composes the way any other guard does.

-### Tooling decisions
+It is deliberately not a regex engine and not a macro. There is no transpiler
+and no DSL to learn: `match(value)` returns a builder, `.with(pattern, handler)`
+adds a case, and the chain ends in either `.exhaustive()` or `.otherwise(...)`.
+The type-level contract is the feature — see
+[development/library.md](./development/library.md) for the design decisions and
+the known limitations.

-The choice and configuration of each tool above is the result of deliberate trade-offs, not defaults. The non-obvious ones:
+## Requirements

- **`tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`**; `tsconfig.build.json` extends it to add the emit-only options (`declaration`, `sourceMap`, `inlineSources`, `outDir`, `target: es2024`, `rewriteRelativeImportExtensions: true`) and to exclude test files. `inlineSources` embeds the original TypeScript in `dist/*.js.map`, so debuggers can map into `src/` without it being shipped; `declarationMap` is intentionally off because a `.d.ts.map` cannot embed source and would dangle. This separation lets the editor and CI type-check from one config while the build emits from the other.
- **`npm run build` first runs a `prebuild` hook that empties `dist/`.** `tsc` does not prune orphaned emit output — dropping `declarationMap`, for example, left stale `*.d.ts.map` files behind — so the build must start from an empty `dist/` to be reproducible. `prebuild` removes only `dist`; the manual `clean` still resets `dist` + `coverage`, so a local coverage report survives a build.
- **Source imports use `.ts` extensions** so `node --strip-types` resolves them at test time. `rewriteRelativeImportExtensions: true` in `tsconfig.build.json` rewrites them to `.js` in the emitted JavaScript; the emitted `.d.ts` keep the `.ts` specifier, which TypeScript >= 5.0 resolves (see [Requirements](#requirements)), so no post-processing step is needed.
- **Type-aware oxlint is enabled declaratively** via `options.typeAware: true` in `.oxlintrc.json` (powered by `oxlint-tsgolint`). The script commands stay clean — no CLI flag — and type-aware mode is a property of the config, not the invocation.
- **Source-level `oxlint-disable` directives** are used for known type-aware false positives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`). The disable lives next to the code it silences, not in `.oxlintrc.json`, so the trade-off is visible to anyone reading the source.
- **`knip --include dependencies,exports,files`** intentionally omits the `types` category, which produces systematic false positives for libraries whose exported types are part of the public API. The targeted scope keeps the signal high without config-file boilerplate.
- **`attw --profile esm-only`** is semantically correct: this package is intentionally ESM-only (no CommonJS shim), so CJS resolution scenarios are out of scope by design, not a bug.
- **`check:tsc` runs first** in the `npm run check` chain so a type error short-circuits the rest (faster feedback than letting oxlint/oxfmt run and then failing on tsc at the end).
- **The pre-commit hook sets the `LEFTHOOK_FILES` env var** to the staged-files list, and the affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole project when invoked manually. This keeps `package.json#scripts` as the single source of truth for the underlying commands — `lefthook.yml` only describes _what to run on which files_.
- **`tslib` and `type-fest` are deliberately not used.** `tslib` is a runtime helper for old ES3/ES5 targets (the project targets ES2024); `type-fest` was never imported. knip caught both.
- **`@spences10/pi-lsp` is pinned to `0.0.46` and is read-only by design.** The package inspects `node_modules/typescript`, sees major ≥ 7 with no `lib/tsserver.js` (true of the `typescript-go` / `tsgo` port), and spawns the repo's own `tsc --lsp --stdio` binary — no `typescript-language-server` dependency is required. Earlier releases (`≤ 0.0.10`) hard-wire to `typescript-language-server --stdio` and are TS6-only. The tool is _intermediate_ agent feedback (hover, references, definition, symbols, diagnostics); it has no rename / code-action / apply-edit surface, and never a correctness gate — `npm run check` / `verify` remain that. `.pi/settings.json` is the shared, committed declaration; `.pi/npm/` is a gitignored install cache that pi recreates automatically on a trusted startup (it runs `npm install` for any missing project package), so the cache is deliberately not tracked.
+- **Node.js >= 26** (`engines` field; pinned via `.node-version`).
+- **TypeScript >= 5.0** to consume the published declarations. The emitted `.d.ts`
+  use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers;
+  both resolve on TS >= 5.0 in `node10` / `node16` / `nodenext` / `bundler`.
+- The package is **ESM-only** (no CommonJS shim).

-### Requirements
+## Examples

- Node.js >= 26 (engines field; pinned via `.node-version`).
- TypeScript >= 5.0 to consume the published declarations. The emitted `.d.ts` use `const` type parameters (TS 5.0) and keep their relative `.ts` specifiers; both resolve on TS >= 5.0 in `node10`/`node16`/`nodenext`/`bundler`.
+### Literal matching and `exhaustive()`

-## VSCode integration
+`.exhaustive()` returns the union of the handler return types and throws if no
+case matched. Annotate handler returns when you want literal types rather than
+`string`:

- Recommended extensions: see `.vscode/extensions.json` (oxc, cspell, TypeScript native-preview, EditorConfig, todo-tasks).
- TypeScript 7 is used via the `typescriptteam.native-preview` extension.
- oxc extension provides oxlint squiggles and oxfmt format-on-save; `.vscode/settings.json` pins it per language so a user's local `[language]` formatter settings cannot override the project's choice.
+```ts
+type Answer = "yes" | "no";
+
+const reply = (answer: Answer): "agreed" | "declined" =>
+    match(answer)
+        .with(P.literal("yes"), (): "agreed" => "agreed")
+        .with(P.literal("no"), (): "declined" => "declined")
+        .exhaustive();
+
+reply("yes"); // "agreed"
+```
+
+`exhaustive()` checks at runtime, not at compile time — TypeScript does not force
+every union member to have a case (see
+[development/library.md](./development/library.md#exhaustive-is-a-runtime-check)).
+Use `.otherwise(...)` when a fallback is wanted:
+
+```ts
+const label = (answer: Answer): string =>
+    match(answer)
+        .with(P.literal("yes"), () => "agreed")
+        .otherwise(() => "not agreed");
+```
+
+### Matching by `typeof`
+
+`P.type<T>(name)` pairs an explicit type `T` with the runtime `typeof` name it
+should test for:
+
+```ts
+const describe = (value: unknown): string =>
+    match(value)
+        .with(P.type<string>("string"), (s) => `string of length ${s.length}`)
+        .with(P.type<number>("number"), (n) => `number ${n.toFixed(2)}`)
+        .otherwise(() => "something else");
+```
+
+The supported names are `string`, `number`, `boolean`, `bigint`, `symbol`,
+`undefined`, `object`, and `function`. `"object"` matches non-null objects and
+functions; `"undefined"` compares against `undefined` directly.
+
+### Structural matching and discriminated unions
+
+`P.shape(shape, refine?)` checks that every key in `shape` exists on the value.
+A value that is itself a matcher is applied, otherwise it is compared with
+strict equality. To narrow to a concrete type, pass a `refine` type guard:
+
+```ts
+interface Circle {
+    readonly kind: "circle";
+    readonly radius: number;
+}
+
+interface Square {
+    readonly kind: "square";
+    readonly side: number;
+}
+
+type Shape = Circle | Square;
+
+const area = (shape: Shape): number =>
+    match(shape)
+        .with(
+            P.shape({ kind: "circle" }, (v): v is Circle => "radius" in v),
+            (c) => Math.PI * c.radius ** 2,
+        )
+        .with(
+            P.shape({ kind: "square" }, (v): v is Square => "side" in v),
+            (s) => s.side ** 2,
+        )
+        .exhaustive();
+```
+
+Without `refine`, `P.shape` returns a matcher for the shape's own type, not the
+narrowed one. Nested matchers can be used in the shape object, for example
+`P.shape({ name: P.type<string>("string") })`.
+
+### Custom guards with `when`
+
+`P.when` takes a type guard and infers the narrowed type from it:
+
+```ts
+const toNumber = (value: unknown): number =>
+    match(value)
+        .with(
+            P.when((v): v is string => typeof v === "string"),
+            (s) => Number.parseInt(s, 10),
+        )
+        .otherwise(() => 0);
+```
+
+### Widening with `any`
+
+`P.any<T>(predicate)` takes a plain boolean predicate and a declared type `T`,
+for cases where the predicate cannot be written as a type guard:
+
+```ts
+const firstNumber = (items: readonly unknown[]): number | undefined =>
+    match(items)
+        .with(
+            P.any<readonly number[]>(
+                (v) =>
+                    Array.isArray(v) &&
+                    v.every((item) => typeof item === "number"),
+            ),
+            (xs) => xs[0],
+        )
+        .otherwise(() => undefined);
+```
+
+## API
+
+Yet to be implemented
+
+## License
+
+MIT © 2025 tmu. See [LICENSE](./LICENSE).

 ## Contributing

-For maintainer and contributor docs — the script prefix convention, the feedback-tier system, the rules the tools don't enforce, and the publishing workflow — see [CONTRIBUTING.md](./CONTRIBUTING.md). AI coding agents: your entry point is [AGENTS.md](./AGENTS.md), which points back to CONTRIBUTING.md.
-
- Commit signing (GPG).
- Type-only tests use `expect-type`'s `expectTypeOf(...)` inside `node --test` cases.
+Contributions are documented in [CONTRIBUTING.md](./CONTRIBUTING.md); the
+reasons behind the project's decisions, rejected alternatives, and known issues
+live in [development/](./development/README.md). AI coding agents start at
+[AGENTS.md](./AGENTS.md).
@@ -6,7 +6,7 @@ Backlog and tracking for tiny-pattern-ts. Managed in vscode-todotasks format.

 Setup:
 ✔ Add gitea release page in CI @high @done
-☐ Manually verify the Gitea release page on a real tag push (needs main) @high
+✔ Manually verify the Gitea release page on a real tag push (needs main) @high @done (9/15/2026, 1:18:15 PM)
 ☐ Split off template into separate package => pi --session 01a07dde-7050-7054-bb36-1606d7eb2bc3 @high

 v1.0:
@@ -24,11 +24,43 @@ Bugs:
 Enhancements:

 Documentation:
-☐ Add usage examples to README.md
+✔ Clean up CONTRIBUTING.md and README.md, create docs @done
+    ✔ Review existing documentation for accuracy and completeness @done
+    ✔ README.md should be the main entry point for users, and CONTRIBUTING.md should be the main entry point for contributors @done
+    ✔ Move the decisions, shortcomings and known issues out of README.md and CONTRIBUTING.md @done
+        ✔ Decided: category files under development/ (one per area), not ADRs. Each decision is a block with #### Decision (YYYY-MM) / #### Why / #### Rejected / #### Known issue; rationale in development/README.md @done
+        ✔ have a look at other well known repositories for inspiration on how to structure the docs @done
+        ✔ often times a docs folder is used, but this usually contains further user of the library documentation, that is deployed to a website. Deployment is out of scope for now @done
+        ✔ make sure to preserve that information in the new docs @done
+        ✔ development/README.md - index and decision-block convention @done
+        ✔ development/workflow.md - branching, script prefixes, feedback tiers, commits @done
+        ✔ development/tooling.md - toolchain decisions and editor setup @done
+        ✔ development/testing.md - type-driven testing @done
+        ✔ development/ci.md - pipeline, runner image, coverage serving @done
+        ✔ development/publishing.md - release and npm publishing @done
+        ✔ development/library.md - public API design and its limitations @done
+    ✔ README.md @done
+        ✔ I really like the order perl documentation does it: name with a single line description, version, Synopsis, Description, examples, API reference, license @done
+            (example: https://metacpan.org/pod/Scalar::Util)
+        ✔ should include a clear description of the library, its purpose, and how to use it @done
+        ✔ Add usage examples to README.md @done
+        ✔ version needs to be kept in sync with package.json in release.sh @done
+        ✔ Not every section in current README fits in the above order, so put them in another file @done
+    ✔ CONTRIBUTING.md @done
+        ✔ should include instructions for how to contribute to the project, including how to set up a development environment, run tests, and submit pull requests @done
+        ✔ should include guidelines for code style and formatting and a hint, that vscode extensions are suggested from .vscode/extensions.json @done
+        ✔ Not every section in current CONTRIBUTING.md fits in, so put them in another file @done
+
+
+
 ☐ Create `examples/` directory with runnable snippets
-☐ Add comparison section vs. other TS pattern-matching libs
+☐ Add comparison section vs. other TS pattern-matching libs in Readme.md
 ☐ Write migration guide for users coming from discriminated unions
 ☐ Create backlog tasks for implementation
+☐ Validate code fences in Markdown (start with README.md) — compile the TypeScript examples against `src/` so the docs cannot drift from the API
+
+Workflow:
+☐ Resolve the finish/push tension: `create:finish` leaves `main` ahead of its upstream while `create:branch` refuses until `main` matches upstream — decide whether `finish` should push or `branch` should compare only `BEHIND` (see development/workflow.md)

 Maintenance:
 ☐ Serve CI coverage over a tiny self-hosted webserver (replace the zip artifact) @low
@@ -45,3 +77,19 @@ Maintenance:
    ☐ Add a minimal dir-listing webserver to the gitea docker setup for serving landing page (reuse existing reverse proxy)
    ☐ CI writes landing page to a shared volume keyed by project + tag (e.g. `/landing/tiny-pattern-ts/<tag>/`)
    ☐ Browse to `…/tiny-pattern-ts/index.html` in the browser
+✔ Stop Gitea CI re-downloading Node on every job @done
+    ✔ Share the warm npm cache with the publish job @done
+    ✔ Bake Node into the CI job image (docker/Dockerfile, container.image in ci.yml) @done
+    ✔ Build/push gitea.e1nsnull.de/tmu/act-ci:26.8.2 and confirm setup-node skips the download @done
+    ✔ Write the `<version>/x64.complete` marker — actions/tool-cache ignores a bare directory, so the probe missed and the download continued @done
+    ✔ Log tool-cache state from the job container to find it (temporary, removed once understood) @done
+    ✔ Guard the invariant in CI (`Assert the baked tool cache is present`) @done
+✘ Enable force-pull for the runner so a changed act-ci image is never missed @low @cancelled
+    → decided against: it is acceptable to miss a runner-side image change, and the image is only rebuilt on a Node bump, which changes the tag anyway. A Dockerfile-only change re-pushed under an unchanged tag is a known issue with a manual `docker rmi` workaround (see development/ci.md).
+✔ Improve CI publish @done
+    ✔ Check whether publish job is only run on tags, if not, guard it @done
+    ✔ Gate only single steps @done
+        ✔ Do not publish to npm, if NPM_TOKEN is not set (e.g. PRs from forks) @done
+        ✔ Do not publish to Gitea — uses the run's automatic `github.token`, so no secret gate is needed @done
+        ✔ Otherwise run the steps @done
+        ✔ Fail the job unless both the Gitea release and npm publish succeeded @done
@@ -27,6 +27,14 @@
        "knope",
        "runwisp",
        "glab",
+        "hostedtoolcache",
+        "nodebase",
+        "frontends",
+        "catthehacker",
+        "nsnull",
+        "dedup",
+        "dedupe",
+        "repoint",
        "postversion",
        "prebuild",
        "Zilla",
@@ -0,0 +1,78 @@
+# Development documentation
+
+Why this project works the way it does: the decisions, what was rejected, and
+the shortcomings and known issues we carry. Written for maintainers and
+contributors.
+
+The actionable rules — setup, running, testing, submitting — live in
+[CONTRIBUTING.md](../CONTRIBUTING.md). **Each fact is written once**: the rule
+there, the reason here; neither restates the other, and where a fact is useful
+in both they link. Read the relevant file before changing an area, and when a
+rule changes update its rationale here in the same commit.
+
+User-facing documentation is [README.md](../README.md). `docs/` is deliberately
+unused: that name is reserved for the future user documentation site, and
+deploying it is out of scope. These files are not part of that site.
+
+## Layout
+
+One file per category:
+
+| File                             | Covers                                                                  |
+| -------------------------------- | ----------------------------------------------------------------------- |
+| [library.md](./library.md)       | Public API design, the type-level contract, and its limitations         |
+| [workflow.md](./workflow.md)     | Branching and merging, script prefixes, feedback tiers, commit messages |
+| [tooling.md](./tooling.md)       | Toolchain choices and configuration, editor setup                       |
+| [testing.md](./testing.md)       | Test strategy and type-driven development                               |
+| [ci.md](./ci.md)                 | CI pipeline, runner image, coverage serving                             |
+| [publishing.md](./publishing.md) | Release and npm publishing                                              |
+
+We start with one file per category so each area stays small enough to hold in
+mind; a category that outgrows it becomes a folder with an index, and the links
+in CONTRIBUTING.md and README.md point at the category, not a single decision.
+
+## Decision blocks
+
+Record every non-obvious choice as a block in the relevant category file:
+
+```md
+## Runner image
+
+#### Decision (2026-09)
+
+Bake Node into the CI job image at the setup-node tool-cache layout instead
+of downloading per job.
+
+#### Why
+
+- ...
+
+#### Rejected
+
+- Gitea Pages / per-job download
+- force-pull
+
+#### Known issue
+
+- a Dockerfile-only change re-pushed under an unchanged tag is invisible to the runner
+    - recover with `docker rmi <image>`
+```
+
+- The date is the month the decision was made, not when the file was edited —
+  the anchor for "current" versus "was current once".
+- `Rejected` stops the project re-litigating the same alternatives; an empty one
+  usually means they were never written down.
+- `Known issue` is where shortcomings live. A caveat not tied to one decision
+  goes under a `## Known issues` section at the end of the file.
+- Replace a superseded decision in place rather than archiving it; git history
+  is the archive.
+
+## Adding to these docs
+
+1. Pick the category: `library`, `workflow`, `tooling`, `testing`, `ci`,
+   `publishing`.
+2. Add or update a decision block; keep existing text unless the decision
+   changed.
+3. If an actionable rule changes, update
+   [CONTRIBUTING.md](../CONTRIBUTING.md) in the same commit and cross-link.
+   Never change a rule there without updating its rationale here.
@@ -0,0 +1,136 @@
+# CI
+
+[.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml) is the source of truth for
+the job graph; this file records why it is shaped the way it is.
+
+## Pipeline
+
+- **`build`** (push to `main` / tag) — build + correctness + packaging.
+- **`maintain`** (push to `main`, non-blocking) — `npm run maintain`; reports,
+  never fails the build.
+- **`publish`** (tag) — packaging checks + `publish:publint` / `publish:attw`,
+  then the Gitea release page and `npm publish` (see
+  [publishing.md](./publishing.md)).
+- **`release-gate`** — on a `:rocket: Release x.y.z` commit it skips
+  `build`/`maintain`, because `create:release` pushes the tag for the same commit
+  right after and the tag run is authoritative. It uses no Node and stays on the
+  default image.
+
+## Runner image
+
+#### Decision (2026-09)
+
+`build` / `maintain` / `publish` run in `gitea.e1nsnull.de/tmu/act-ci:<version>`
+([docker/Dockerfile](../docker/Dockerfile)): the default act image with Node
+overlaid at the exact `/opt/hostedtoolcache` layout `actions/setup-node` probes.
+
+#### Why
+
+- No job pays the ~50 MB Node fetch, because the probe hits the baked entry.
+- The tag must equal the exact [.node-version](../.node-version) pin, and the
+  image is rebuilt only as part of a Node bump — there is no other trigger.
+- Building needs a docker daemon and registry credentials, so it belongs to no
+  feedback tier. That is why it is **not** an `npm run` script: no
+  [prefix](./workflow.md#script-prefix-convention) fits, and that is the signal.
+
+#### Rejected
+
+- Downloading Node in every job — the ~50 MB fetch was the original problem.
+- Caching Proxy (Squid or similar) — adds complexity to global setup
+- Mounting the tool cache - No invalidation will fill the cache with stale versions
+
+## Bumping Node
+
+Bumping Node is one coordinated change, committed as a unit:
+
+1. Edit [.node-version](../.node-version) to the exact `x.y.z` — floats like `26`
+   resolve to the latest patch at runtime and bust the baked entry, so
+   [scripts/runner-image.sh](../scripts/runner-image.sh) refuses them.
+2. `docker login gitea.e1nsnull.de` (user + package/access token), then
+   `./scripts/runner-image.sh --push`, which reads the version and pushes
+   `<IMAGE_REPO>:<version>`.
+3. Repoint the three `container.image` tags in
+   [.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml) to that version.
+
+Skipping step 2 fails CI at image pull; skipping step 3 silently reverts to the
+per-job download.
+
+## Image invariants
+
+For the `setup-node` probe to hit, two things must hold — both easy to break:
+
+### The `x64.complete` marker
+
+#### Decision (2026-09)
+
+Bake a `<version>/<arch>.complete` marker next to the Node directory.
+
+#### Why
+
+- `actions/tool-cache` accepts a cached tool only when
+  `<version>/<arch>.complete` exists beside it (`tc.find()` checks). A bare
+  `node/<version>/x64/` is ignored and the download happens anyway. See the
+  comment in [docker/Dockerfile](../docker/Dockerfile).
+
+### Tag freshness, with force-pull deliberately off
+
+#### Decision (2026-09)
+
+Leave `act_runner`'s `force_pull` disabled.
+
+#### Why
+
+- The tag encodes only the Node version, and the image is rebuilt only when that
+  changes — so the normal flow always yields a new tag and the runner pulls it.
+- Forcing a pull re-pulls the image on every job for no benefit.
+
+#### Rejected
+
+- Enabling `force_pull`: it is acceptable to miss a runner-side image change,
+  and a `Dockerfile`-only change is not worth a per-job pull.
+
+#### Known issue
+
+- A `Dockerfile`-only change (like the marker above) re-pushed under an
+  unchanged tag is invisible to the runner, which keeps the old image while the
+  registry shows the new digest. Remove the stale tag on the runner host
+  (`docker rmi gitea.e1nsnull.de/tmu/act-ci:<version>`); do not reach for
+  force-pull.
+
+## Coverage serving
+
+#### Decision (2026-09)
+
+Serve CI coverage from a shared directory on the runner, with no deploy step in
+CI.
+
+#### Why
+
+- The webserver exposes the shared directory and the Gitea docker setup reuses
+  the existing reverse proxy — no upload artifact, no external service.
+- Coverage is written to a shared volume keyed by project and tag (for example
+  `/docs/tiny-pattern-ts/<tag>/`).
+
+#### Rejected
+
+- Gitea Pages and Codecov: neither was confirmed available or wanted.
+
+#### Known issue
+
+- Coverage is served for tag pushes only; non-tag pushes (for example
+  `main/coverage`) are tracked separately.
+
+[scripts/precompress.ts](../scripts/precompress.ts) emits `.br` / `.gz` / `.zst`
+sidecars next to text assets. The Gitea pages service (`static-web-server` with
+`SERVER_COMPRESSION_STATIC=true`) serves the sidecar matching `Accept-Encoding`
+and falls back to the original.
+
+#### Decision (2026-09)
+
+Precompress into sidecars rather than per request.
+
+#### Why
+
+- The assets are static and change only on deploy, so the work is paid once.
+- Images, fonts and archives are already compressed; a sidecar would only grow
+  them, so only text extensions are emitted.
@@ -0,0 +1,6 @@
+# Library design
+
+The type-level design of the public API and the limitations it carries. The
+user-facing reference is [README § API](../README.md#api).
+
+Currently the library is placeholder code.
@@ -0,0 +1,131 @@
+# Publishing
+
+Publishing is CI-only: local `npm publish` is not supported, and the maintainer
+triggers releases from `main`. The mechanics are in
+[scripts/release.sh](../scripts/release.sh) and
+[scripts/release-notes.sh](../scripts/release-notes.sh); the job graph is
+[.gitea/workflows/ci.yml](../.gitea/workflows/ci.yml).
+
+## Release steps
+
+1. All intended changes are merged to `main` and passing CI.
+2. The maintainer runs `npm run create:release`. VS Code opens
+   [CHANGELOG.md](../CHANGELOG.md) to finalize the `[Unreleased]` notes; because
+   pubv refuses a dirty tree, the edit is committed first (then folded into the
+   release commit), and pubv suggests a version from those notes to confirm or
+   edit.
+3. `scripts/release.sh` creates one release commit (graduated changelog +
+   `package.json` bump, amended together), tags it, and pushes.
+4. CI fires on both pushes. `publish` runs on the tag (build + publish checks +
+   release page + `npm publish`), while `release-gate` recognizes the release
+   commit and skips `build`/`maintain`: the tag verifies the identical SHA, so no
+   work is duplicated. The publish checks pass before the artifact is published,
+   and the release page is created from the matching Keep-a-Changelog section
+   _before_ `npm publish`, so a broken page fails CI without consuming a version
+   and `npm publish` stays the last step.
+
+## CI-only publishing
+
+#### Decision (2026-09)
+
+Releases are cut by CI from `main`; there is no local `npm publish` and no
+`publish:*` script in the `check` chain.
+
+#### Why
+
+- The tag is the artifact marker: CI verifies the exact commit it points at, so
+  a local publish could ship something the tag does not describe.
+- `publish:publint` / `publish:attw` validate the _publishable artifact_, which
+  needs a fresh build; they are not source-correctness checks and do not belong
+  in `check`.
+
+## The release commit is assembled from two tools
+
+#### Decision (2026-09)
+
+`create:release` uses `pubv` for the changelog graduation and bump heuristic,
+then `npm version` for the `package.json` + lockfile bump, amended into a single
+release commit.
+
+#### Why
+
+- We want hand-written Keep-a-Changelog notes, an `[Unreleased]` ->
+  `## [x.y.z] - DATE` graduation, and a tag on the exact commit that gets
+  published — and no single tool did both the graduation and the `package.json`
+  bump.
+- Split by strength: `pubv` (tiny, changelog-driven) owns preflight, the
+  interactive major/minor/patch heuristic, and graduating and committing
+  `CHANGELOG.md` (no tag, no push); `npm version` syncs `package.json` + the
+  lockfile; `--amend` folds them into one commit; the tag is created _after_ the
+  amend so it is never orphaned.
+- The notes are finalized _before_ pubv because its bump heuristic reads the
+  `[Unreleased]` body — editing afterwards would inform the changelog only, not
+  the version. The staging commit that satisfies pubv's clean-tree check is
+  folded back into the single release commit.
+
+#### Rejected
+
+- The conventional-commits family: the history is gitmoji, not Conventional, and
+  the notes are hand-written (see
+  [workflow.md § Commit messages](./workflow.md#commit-messages)).
+- `changesets` / `rtk`: config plus a heavier flow that fights the CI-only
+  publish.
+- `knope` / `kacl` / `bestikk`: changelog-only (no `package.json` bump) and
+  5-year / 2-year / brand-new maintenance.
+- `pubv` alone: it never writes `package.json`.
+- `versions` (silverwind): good Gitea support, but pairing it with a hand-rolled
+  promote became a ~180-line script, which this ~30-line version replaces.
+
+## The version has one source of truth
+
+#### Decision (2026-09)
+
+The version is derived from the graduated `## [x.y.z]` heading in
+[CHANGELOG.md](../CHANGELOG.md) and written to `package.json` +
+`package-lock.json` by `npm version`.
+
+#### Why
+
+- `release.sh` reads the version from the changelog, so the changelog is the
+  input and `package.json` the derived copy — one direction, no drift.
+
+#### Rejected
+
+- A `## Version` line in the README: it makes `release.sh` responsible for a
+  third file.
+- Linking `package.json` from the README: it invites a hand-maintained duplicate
+  the link does not keep in sync.
+
+## Release notes are extracted from the changelog
+
+#### Decision (2026-09)
+
+`scripts/release-notes.sh <tag>` prints the Keep-a-Changelog section for the tag
+and exits non-zero when it is missing.
+
+#### Why
+
+- CI reuses the release body from the same file that drove the version, so the
+  page and the changelog cannot disagree.
+- Failing on a missing section means a release can never publish an empty body.
+  A leading `v` is tolerated so both `v1.2.3` and `1.2.3` match `## [1.2.3]`.
+
+## Token gates
+
+#### Decision (2026-09)
+
+The Gitea release page uses the run's automatic token (`github.token`).
+`npm publish` is gated on `NPM_TOKEN`, lifted into job-level `env`. A final
+`always()` step fails the job unless both halves reported `success`.
+
+#### Why
+
+- The automatic token needs only `contents: write`, so the release page needs no
+  secret gate.
+- `secrets` is not allowed in a step `if`, so `NPM_TOKEN` must be lifted into
+  job-level `env`; an unset secret then skips the publish instead of attempting
+  an unauthenticated one.
+- A tag is all-or-nothing: without the `always()` guard a skipped or failed npm
+  half would leave the job silently green. The guard turns it red.
+
+Set `NPM_TOKEN` (npm publish rights) under Settings -> Actions -> Secrets.
@@ -0,0 +1,45 @@
+# Testing
+
+For this library the types _are_ the feature, so a runtime-only test loop would
+verify the wrong thing. The commands are in
+[CONTRIBUTING.md](../CONTRIBUTING.md); this file records why the loop is shaped
+the way it is.
+
+## Type-driven development
+
+The rules — the loop and the pairing rule — are in
+[CONTRIBUTING.md § Testing discipline (type-driven)](../CONTRIBUTING.md#testing-discipline-type-driven).
+What follows is why and what was rejected.
+
+#### Decision (2026-09)
+
+The compile-time expectation is written before the runtime assertion, and both
+before the implementation.
+
+#### Why
+
+- A runtime-only test can pass while the type is wrong, so a type-level library
+  would ship a broken feature its tests bless.
+- The type error is a more precise spec than a failing assertion, because it
+  states the exact expected type before the logic exists.
+
+#### Rejected
+
+- Runtime-first (classic red/green): it verifies the value, not the contract,
+  and the contract is the product.
+- Testing the type only: it would not catch handler wiring, `exhaustive()`
+  throwing, or the `otherwise` fallback (see `src/index.test.ts`).
+
+The runner is `node --test --strip-types "src/**/*.test.ts"` and the tiers are in
+[CONTRIBUTING.md § Development commands](../CONTRIBUTING.md#development-commands).
+`c8` uses V8 coverage, so the `--strip-types` source is instrumented without a
+build step, and the runner relies on the `.ts` import-extension convention (see
+[tooling.md](./tooling.md#source-imports-use-ts-extensions)).
+
+## Known issues
+
+- The type-aware linter misidentifies `expectTypeOf()` as a floating promise, so
+  `src/index.test.ts` carries a file-level `oxlint-disable
+typescript/no-floating-promises` with an explanatory comment. It is a known
+  false positive, not a rule worth disabling project-wide (see
+  [tooling.md § oxlint-disable directives live next to the code](./tooling.md#oxlint-disable-directives-live-next-to-the-code)).
@@ -0,0 +1,236 @@
+# Tooling
+
+Every tool below was chosen and configured deliberately. The commands a
+contributor runs are in [CONTRIBUTING.md](../CONTRIBUTING.md) and the versions
+in [package.json](../package.json).
+
+## Tool inventory
+
+- **TypeScript 7** — type checker and build (`tsc`).
+- **node --test** + `--strip-types` — test runner.
+- **c8** — coverage for `test:ci`.
+- **oxlint** — Rust linter, type-aware via **oxlint-tsgolint** (typescript-go).
+- **oxfmt** — Rust formatter (Prettier-compatible) for JS/TS, JSON/JSONC, YAML,
+  Markdown, MDX, and more; its `package.json` key sorting replaces
+  `sort-package-json`.
+- **cspell** — spell checking.
+- **knip** — unused dependencies, exports, and files.
+- **check-outdated** — dependencies behind the registry; exits non-zero when any
+  is outdated.
+- **publint** — validates `package.json` for ESM publishing.
+- **@arethetypeswrong/cli** (`attw`) — validates `.d.ts` against module-resolution
+  scenarios.
+- **lefthook** — git hooks.
+- **@spences10/pi-lsp** — read-only LSP code intelligence for AI agents
+  (project-local `.pi/settings.json`); talks to this repo's TypeScript 7 via
+  `tsc --lsp --stdio`.
+
+When each runs is in
+[CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers).
+
+## TypeScript and build
+
+### One type-check config, one emit config
+
+#### Decision (2026-09)
+
+`tsconfig.json` extends `@tsconfig/strictest` + `@tsconfig/node26`.
+`tsconfig.build.json` adds the emit-only options (`declaration`, `sourceMap`,
+`inlineSources`, `outDir`, `target: es2024`,
+`rewriteRelativeImportExtensions: true`) and excludes test files.
+
+#### Why
+
+- The editor and CI type-check from one config while the build emits from the
+  other, so a test file cannot leak into `dist/`.
+- `inlineSources` embeds the original TypeScript in `dist/*.js.map`, so
+  debuggers map into `src/` without it being shipped.
+- `declarationMap` stays off: a `.d.ts.map` cannot embed source and would
+  dangle.
+
+### The build starts from an empty `dist/`
+
+#### Decision (2026-09)
+
+`npm run build` runs a `prebuild` hook that empties `dist/`.
+
+#### Why
+
+- `tsc` does not prune orphaned emit output — dropping `declarationMap` left
+  stale `*.d.ts.map` files — so reproducibility needs an empty `dist/`.
+- `prebuild` removes only `dist`; the manual `clean` resets `dist` + `coverage`,
+  so a local coverage report survives a build.
+
+### Source imports use `.ts` extensions
+
+#### Decision (2026-09)
+
+Source imports use `.ts`, never `.js`.
+
+#### Why
+
+- `node --strip-types` resolves the `.ts` form at test time.
+- `rewriteRelativeImportExtensions` rewrites them to `.js` in the emitted
+  JavaScript.
+- The emitted `.d.ts` keep the `.ts` specifier, which TypeScript >= 5.0 resolves
+  (see [README § Requirements](../README.md#requirements)), so no
+  post-processing step is needed.
+
+#### Rejected
+
+- "Pre-fixing" an import to `.js`: it breaks the inner `node --strip-types`
+  loop.
+
+## Linting and formatting
+
+### Type-aware oxlint is a config property
+
+#### Decision (2026-09)
+
+Type-aware oxlint is enabled via `options.typeAware: true` in `.oxlintrc.json`
+(powered by `oxlint-tsgolint`).
+
+#### Why
+
+- The script commands stay clean — no CLI flag.
+- A config property cannot be forgotten on one call site.
+
+#### Rejected
+
+- A CLI flag in the `check:oxlint` / `fix:oxlint` scripts: it puts the mode in
+  two places and invites them to drift.
+
+### `oxlint-disable` directives live next to the code
+
+#### Decision (2026-09)
+
+Known type-aware false positives are silenced with source-level `oxlint-disable`
+directives (see `src/pattern.ts`, `src/match.ts`, `src/index.test.ts`), not with
+rules disabled in `.oxlintrc.json`.
+
+#### Why
+
+- The disable sits next to the code it silences, visible to anyone reading the
+  source.
+
+#### Rejected
+
+- A project-wide disable in `.oxlintrc.json`: it hides the suppression from the
+  reader of the affected code.
+
+#### Known issue
+
+- A source-level disable is a _human_ last resort. AI agents must not add one;
+  they fix the type at its root (see [AGENTS.md § Never do](../AGENTS.md#never-do)).
+
+### `check:tsc` runs first
+
+#### Decision (2026-09)
+
+`check:tsc` runs first in the `npm run check` chain.
+
+#### Why
+
+- A type error short-circuits the rest, which is faster than running
+  oxlint/oxfmt and failing on `tsc` at the end.
+
+### `.editorconfig` is a fallback, not a gate
+
+#### Decision (2026-09)
+
+`.editorconfig` exists for editor compatibility; where both apply,
+`.oxfmtrc.json` is authoritative.
+
+#### Why
+
+- `.editorconfig` covers the files oxfmt does not format: shell scripts,
+  dotfiles, `LICENSE`, the commit-message template, and git's `COMMIT_EDITMSG`
+  buffer.
+- oxfmt is the formatter; the overlapping keys only keep non-oxfmt editors close
+  to the formatted result, so they cannot disagree with the checker.
+
+## Static analysis and packaging
+
+### `knip` omits the `types` category
+
+#### Decision (2026-09)
+
+`knip --include dependencies,exports,files` omits the `types` category.
+
+#### Why
+
+- `types` produces systematic false positives for libraries whose exported types
+  are part of the public API.
+- The narrower scope keeps the signal high without config-file boilerplate.
+
+### `attw` targets ESM-only
+
+#### Decision (2026-09)
+
+`attw --profile esm-only` is used.
+
+#### Why
+
+- The package is intentionally ESM-only (no CommonJS shim), so CJS resolution
+  scenarios are out of scope by design, not a bug.
+
+### `tslib` is deliberately not used
+
+#### Decision (2026-09)
+
+`tslib` is not a dependency.
+
+#### Why
+
+- `tslib` is a runtime helper for old ES3/ES5 targets; this project targets
+  ES2024.
+
+## Git hooks and script wiring
+
+### `LEFTHOOK_FILES` scopes commands to staged files
+
+#### Decision (2026-09)
+
+The pre-commit hook sets `LEFTHOOK_FILES` to the staged-files list, and the
+affected scripts use `${LEFTHOOK_FILES:-<default>}` to default to the whole
+project.
+
+#### Why
+
+- It keeps `package.json#scripts` the single source of truth; `lefthook.yml`
+  only says what to run on which files.
+- The same script works by hand (whole project) and staged (scoped), so there is
+  no second command to maintain.
+
+## Editor and agent tooling
+
+### VSCode integration
+
+- Recommended extensions are in
+  [.vscode/extensions.json](../.vscode/extensions.json) (oxc, cspell, TypeScript
+  native-preview, EditorConfig, todo-tasks).
+- TypeScript 7 runs via the `typescriptteam.native-preview` extension.
+- The oxc extension provides oxlint squiggles and oxfmt format-on-save;
+  `.vscode/settings.json` pins it per language so a local `[language]` formatter
+  setting cannot override the project's choice.
+
+### `@spences10/pi-lsp` is pinned and read-only
+
+#### Decision (2026-09)
+
+`@spences10/pi-lsp` is pinned to `0.0.46` and used read-only.
+
+#### Why
+
+- It inspects `node_modules/typescript`, sees major >= 7 with no
+  `lib/tsserver.js` (true of the `typescript-go` / `tsgo` port), and spawns the
+  repo's own `tsc --lsp --stdio` — no `typescript-language-server` dependency is
+  needed.
+- Earlier releases (`<= 0.0.10`) hard-wire to `typescript-language-server
+--stdio` and are TS6-only.
+- It is _intermediate_ agent feedback (hover, references, definition, symbols,
+  diagnostics), with no rename / code-action / apply-edit surface, and is never a
+  gate — `npm run check` / `verify` are.
+- `.pi/settings.json` is the committed declaration; `.pi/npm/` is a gitignored
+  install cache that pi recreates on a trusted startup (running `npm install`
+  for any missing project package), so it is deliberately not tracked.
@@ -0,0 +1,143 @@
+# Workflow
+
+How work moves through the repository. The rules are in
+[CONTRIBUTING.md](../CONTRIBUTING.md); this file records why they are shaped the
+way they are.
+
+## Branching model
+
+The model is GitHub Flow (single-developer); the steps are in
+[CONTRIBUTING.md § Branching model](../CONTRIBUTING.md#branching-model). Context
+behind it: Gitea has no collaborative review UI in use, so it is the lab, and
+the project moves to GitHub once it is tested and ready.
+
+#### Decision (2026-09)
+
+Work is opened and closed by `create:branch` / `create:finish`, not by prose
+plus hand-written `git`.
+
+#### Why
+
+- The preconditions were prose, and prose rots: a rule nobody checks is a
+  suggestion. A script asserts, then acts, so the branch or merge only exists if
+  the assertions passed.
+- Type-driven work is only trustworthy if the baseline was green before the
+  first edit. Cheap checks run first and `npm run test` last, so the expensive
+  gate is not paid on an ineligible tree.
+- The merge half owns the post-merge `npm run verify`, so a merge cannot land
+  unverified. The push stays with `create:release` so the merge is reviewed
+  locally first.
+- Every failure is non-mutating except the baseline test, which runs on `main`
+  after switching there: a red `main` restores the branch you started on, and a
+  merge conflict aborts back to the feature branch rather than stranding a
+  half-merged `main`.
+
+#### Rejected
+
+- Hand-written `git switch -c` / `git merge`: same rules, no enforcement.
+- Reusing `pubv`'s preflight for `create:branch`: release-shaped, third-party,
+  and it would pay for a build and pack a new branch has no use for.
+- Leaving the merge to reviewer judgment: that judgment moved earlier, to the
+  handover review before `create:finish`, rather than living in a command anyone
+  can run from a dirty tree.
+- Fast-forward instead of `--no-ff`: `--no-ff` keeps each unit of work visible
+  in `git log`.
+
+#### Known issue
+
+- `create:finish` does not push, so `main` is ahead of `origin/main` between a
+  merge and the next push. `create:branch` requires `main` to match its upstream
+  and refuses until it is pushed; push `main` before starting the next branch.
+
+## Script prefix convention
+
+The prefix taxonomy is the rule, and it lives in
+[CONTRIBUTING.md § Script prefix convention](../CONTRIBUTING.md#script-prefix-convention).
+The design behind it: bare scripts are the tier entry points — a single tool
+(`build`, `clean`) or an aggregator of a `prefix:*` family (`check`, `fix`,
+`test`, `watch`, `maintain`, `setup`) — while `verify` composes `check` +
+`test:unit` into the whole-project gate (it uses `test:unit`, not `test`,
+because `check` already runs `check:tsc`).
+
+#### Decision (2026-09)
+
+`create:` is the prefix for workflow front doors, with no bare `create`
+aggregator.
+
+#### Why
+
+- Both members create something real: a branch, a release.
+- It joined both lists in [CONTRIBUTING.md](../CONTRIBUTING.md) alongside its
+  first members, so it could not go invisible the way the retired `use:` prefix
+  did.
+- `publish:*` already set the precedent for a prefix without an aggregator.
+
+#### Rejected
+
+- `run:` / `perform:`: they mean only "do the named thing", so every script fits
+  and the taxonomy collapses.
+- `git:`: names the tool, not the lifecycle moment, and implies passthrough
+  aliases.
+- `start:`: describes the branch half, not the release.
+- `cut:`: idiomatic but needs VCS slang to decode.
+- `flow:`: overloaded in a type-level matching library.
+- The existing families: `check:*` is read-only (CI would run a state-mutating
+  command), `fix:*` reviews as a diff not a branch, `maintain:*` is advisory and
+  never a gate.
+
+## Feedback tiers
+
+The table and invocation rules are in
+[CONTRIBUTING.md § Feedback tiers](../CONTRIBUTING.md#feedback-tiers); this
+section explains the split.
+
+#### Decision (2026-09)
+
+Fast, offline, staged-file checks sit in pre-commit; whole-project test runs in
+pre-push and `verify`; slow or network-bound scans under `maintain`.
+
+#### Why
+
+- `watch:*` runs until killed, in its own pane, so it is the earliest tier,
+  firing on save before staging or commit.
+- `check:tsc` / `check:oxlint` / `check:oxfmt` / `check:cspell` are fast
+  (~0.2–0.5s each), offline, and scope to staged files via `LEFTHOOK_FILES`, so
+  pre-commit gives instant feedback on what you typed.
+- `test` (and its `tsc`) runs the whole suite over the whole project, and the
+  staged-file convention does not apply to the test runner, so it belongs in
+  pre-push, after the commits exist but before the push leaves the machine.
+
+#### Rejected
+
+- `maintain:*` in `check` or pre-commit: advisory, whole-project and
+  network-bound scans are not correctness gates and would slow the fast tier.
+- Treating a green pre-commit as the definition of done: it sees only staged
+  files, hence `npm run verify`.
+- A separate `git push` hook for `verify`: the pre-push test tier already covers
+  it.
+
+## Commit messages
+
+The convention is in
+[CONTRIBUTING.md § Commit messages](../CONTRIBUTING.md#commit-messages).
+Examples: `:sparkles: Add watch tier with watch:test child`,
+`:recycle: Move type-aware config to .oxlintrc.json; use source-level disable
+directives`, `:memo: Restore unique maintainer content as CONTRIBUTING.md`. The
+body explains what and why, not how; link issues with `Resolves #...`.
+
+#### Decision (2026-09)
+
+Gitmoji subjects, imperative mood, wrapped 50/72, not Conventional Commits.
+
+#### Why
+
+- The history is gitmoji and predates any commit-lint tooling; switching would
+  rewrite the convention for no gain.
+- The body carries the reasoning a reviewer needs; the subject is a signpost,
+  not a semantic key.
+
+#### Rejected
+
+- Conventional Commits: the release flow uses hand-written Keep-a-Changelog
+  notes, not generated ones, so the prefix has no automation value here (see
+  [publishing.md](./publishing.md)).
@@ -0,0 +1,51 @@
+# CI job image for the Gitea act_runner: the runner's default job image with
+# Node pre-planted where actions/setup-node looks first.
+#
+# Why this layout: setup-node ignores `node` on PATH; its only fast path is a
+# probe of /opt/hostedtoolcache/node/<version>/<arch>. Without an entry there
+# it downloads the ~50 MB distribution on EVERY job (the runner's job
+# containers are ephemeral, so its tool cache never survives a job). The
+# official node images keep exactly the layout setup-node expects under
+# /usr/local, so this layer is a pure file overlay — no scripts, no env.
+#
+# Why not a host bind of /opt/hostedtoolcache: binds never self-prune. Docker
+# images are content-addressed: the base layers dedupe against the act image
+# the host already has, and `docker image prune` / re-pulls are the cleanup
+# story.
+#
+# NODE_VERSION must match `.node-version` exactly. setup-node resolves a float
+# like `26` to the latest known patch at runtime, so a bump silently busts the
+# baked entry; `.node-version` is pinned to x.y.z and scripts/runner-image.sh
+# guards the coupling. Rebuild + repoint `container.image` in
+# .gitea/workflows/ci.yml on every bump.
+#
+# The extra `nodebase` stage is load-bearing: `COPY --from=` resolves its value
+# as a *stage name* at parse time, before build args exist, so
+# `COPY --from=node:${NODE_VERSION}` collapses to the invalid `node:` on
+# frontends that do not expand args there. ARGs declared before the first FROM
+# *are* expanded in FROM, so routing through a named stage works everywhere.
+
+# Global scope: only visible to FROM lines, but that is exactly where we need it.
+ARG NODE_VERSION=26.8.2
+FROM node:${NODE_VERSION} AS nodebase
+
+FROM catthehacker/ubuntu:act-latest
+
+# ARGs do not cross stage boundaries; redeclare (with the same default, so a
+# bare `docker build -f docker/Dockerfile .` still works) for the paths below.
+# Keep this default in sync with the global one above.
+ARG NODE_VERSION=26.8.2
+
+# node image: bin/ + lib/ under /usr/local → tool cache: bin/ + lib/ under <ver>/x64.
+COPY --from=nodebase /usr/local /opt/hostedtoolcache/node/${NODE_VERSION}/x64
+
+# actions/tool-cache only accepts a cached tool when the sibling marker file
+# "<version>/<arch>.complete" exists — tc.find() checks it and falls back to
+# downloading otherwise, however complete the directory is. The marker is what
+# tc.cacheDir() writes after *it* installs a tool, so a pre-baked entry has to
+# reproduce it explicitly.
+RUN touch "/opt/hostedtoolcache/node/${NODE_VERSION}/x64.complete"
+
+# Fail the build (not CI) if the overlay or the version arg were wrong.
+# Shell form on purpose: exec form (`RUN [...]`) does not expand ARG values.
+RUN "/opt/hostedtoolcache/node/${NODE_VERSION}/x64/bin/node" --version
@@ -1,12 +1,12 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.1.1",
+    "version": "0.1.5",
    "lockfileVersion": 3,
    "requires": true,
    "packages": {
        "": {
            "name": "tiny-pattern-ts",
-            "version": "0.1.1",
+            "version": "0.1.5",
            "license": "MIT",
            "devDependencies": {
                "@arethetypeswrong/cli": "^0.18.5",
@@ -20,8 +20,8 @@
                "expect-type": "1.4.0",
                "knip": "^6.34.0",
                "lefthook": "^2.1.12",
-                "oxfmt": "^0.66.0",
-                "oxlint": "^1.81.0",
+                "oxfmt": "^0.68.0",
+                "oxlint": "^1.83.0",
                "oxlint-tsgolint": "^7.0.2001",
                "publint": "^0.3.24",
                "typescript": "^7.0.2"
@@ -1507,9 +1507,9 @@
            ]
        },
        "node_modules/@oxfmt/binding-android-arm-eabi": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-android-arm-eabi/-/binding-android-arm-eabi-0.66.0.tgz",
-            "integrity": "sha512-2Me9eoptv6ERdEuI2P8AOlYdHHraXebJaM6SC0kc2Dfb+mLrep2db+fedBPKaYn673h/vBgvP4tkOdAbaudX6w==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-android-arm-eabi/-/binding-android-arm-eabi-0.68.0.tgz",
+            "integrity": "sha512-dhfYPbzv/h9JgHjNkl2R6sOjUfxDyLGOZVb3g8/ScaTNwwJcYgmHh8kcYFDUhinuy1QAoANCWUvw1jlk+z6gAg==",
            "cpu": [
                "arm"
            ],
@@ -1524,9 +1524,9 @@
            }
        },
        "node_modules/@oxfmt/binding-android-arm64": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-android-arm64/-/binding-android-arm64-0.66.0.tgz",
-            "integrity": "sha512-u7O+bSSF0HGsDKkQQxBqvLGVepu93RA+JKu+ONqvfh4sCnCEbj31wZj4iG5gk3XfRwrmYj0/8catkO2LcblQKQ==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-android-arm64/-/binding-android-arm64-0.68.0.tgz",
+            "integrity": "sha512-v3Njdi6qY0O/5eGfg01ww2w6gTn2mUvZ72Bnx1/UN53A9wruh3Nk6otc3WkgJLkXD4Qgz1SOcVQieH1oD03V9Q==",
            "cpu": [
                "arm64"
            ],
@@ -1541,9 +1541,9 @@
            }
        },
        "node_modules/@oxfmt/binding-darwin-arm64": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-darwin-arm64/-/binding-darwin-arm64-0.66.0.tgz",
-            "integrity": "sha512-/ikyMIVjX/sdo7KtjxoEsSUosfPzveVhT9RWMx9yGqFDKFJ89JAEKuEeLBmurDjrkb4w8tOnAdSO3SBaplY3bw==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-darwin-arm64/-/binding-darwin-arm64-0.68.0.tgz",
+            "integrity": "sha512-ei4MCMzHFREmZwPJ7KuWUB4kBuHdsgDrnXGJVcEAopU7fj7S42I8BChdFILWdHvhFqR08FLJtOfbZIr2CDw0cA==",
            "cpu": [
                "arm64"
            ],
@@ -1558,9 +1558,9 @@
            }
        },
        "node_modules/@oxfmt/binding-darwin-x64": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-darwin-x64/-/binding-darwin-x64-0.66.0.tgz",
-            "integrity": "sha512-q5xUsKeFqawa9NXa6ZGXWimFV19m8MogKPdTaSVDAAk2EQKBmBZRDeluwcl1p8ty/OFc9s9888OKEh3xfPVH0g==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-darwin-x64/-/binding-darwin-x64-0.68.0.tgz",
+            "integrity": "sha512-UrKgzZxYhwB9DSvTX+vdgl9M32wLUNKJcAKIoiyx/Kzn/zveqi7W6kYVcRroFMhS3Kwz0KhTk3WBeSuQn4YCTg==",
            "cpu": [
                "x64"
            ],
@@ -1575,9 +1575,9 @@
            }
        },
        "node_modules/@oxfmt/binding-freebsd-x64": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-freebsd-x64/-/binding-freebsd-x64-0.66.0.tgz",
-            "integrity": "sha512-CR+x4VzMY0pRXLK/xFQ/RzsSFkP5t2Z2mef0QY6OP/rTRcMUoMLCOM62/3Fp/t0K+UDoBKxvMyeb6D0zPMjleA==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-freebsd-x64/-/binding-freebsd-x64-0.68.0.tgz",
+            "integrity": "sha512-6jrEKgpJbilM1QaRv7hEtKXr4p4AK4jvvyOtajwyhu0kOz3e0O7OLnSTk6tBotRqCcUC4ehZRJ1Zx+Y99wieLw==",
            "cpu": [
                "x64"
            ],
@@ -1592,9 +1592,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-arm-gnueabihf": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.66.0.tgz",
-            "integrity": "sha512-ZEYmO/LbH9tTQCADILHGZE4GeOXOAj2VzedHkASNwjmwlwtutJCLpCJbIs37wRGTFgWRoEcD72jpMX+IBJUGjQ==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.68.0.tgz",
+            "integrity": "sha512-YOIVnKOBaLeGullskS179N12hjSAdFYnzLjOaKiLhAKNWgnShq9w4xRdtmUm6BlnP65l2/EA9Aw/KlftNxDM7Q==",
            "cpu": [
                "arm"
            ],
@@ -1609,9 +1609,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-arm-musleabihf": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.66.0.tgz",
-            "integrity": "sha512-hNtR9/oU0CeTkq7JnRkmBQwqe17v2ZaAMLC4VcN7IIOWeRyWDk0knSPWS9iiLmtbZ2RRBBtsG01jQgkZmKCJeQ==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.68.0.tgz",
+            "integrity": "sha512-xW5XoEHVNqydPBv2KXvk9lmEzyAlOQHVEazKoXUuAacqekjya+OdiaFjjEBl0oJD02raG8g3TRl9OVCh9PDIHA==",
            "cpu": [
                "arm"
            ],
@@ -1626,9 +1626,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-arm64-gnu": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.66.0.tgz",
-            "integrity": "sha512-uwOVQ8i6I1LT/+eDzfsgrrcZp8Fn6NPVUPn8fF5gdFGekFf0PddF+LEuwsD0/pbNUcKZhDj2rQ5UpITh9gF4iQ==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.68.0.tgz",
+            "integrity": "sha512-QCvYwVVQieu6oyJglAgV9vH/YMDxZyR4cwVSYtoq9oOXd5N+D3TDUBjNwxFrLn5AdcJZOcvn/7IB17vJGp+2Og==",
            "cpu": [
                "arm64"
            ],
@@ -1646,9 +1646,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-arm64-musl": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.66.0.tgz",
-            "integrity": "sha512-tTkF2Dmx4nGAjmBlZb+UtTGqR/EK4ZrW9qBfzte07a9XWqzoGGKzpFFlyNDhQe+Uwql94+ReCTeNbhOXscw1Dg==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.68.0.tgz",
+            "integrity": "sha512-4TVz5iFQ8ndrHnhX50UXiz9BIWAtUSOHJ6Nus4qWFfJBXq/Ed/krXbF/ehJu42BXM5tIvBs99jNIM22s9agY5A==",
            "cpu": [
                "arm64"
            ],
@@ -1666,9 +1666,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-ppc64-gnu": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.66.0.tgz",
-            "integrity": "sha512-F3cKHUav4yXOHn6GFnwpBhSYsJOYKKf9eqO/9jlEuqPxNw9zb98E9ZFct79gcg8pibUGkbveEu9WDlmXJpDzKw==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.68.0.tgz",
+            "integrity": "sha512-qLe3ao0RP84bnPxBvRI+GnlK/jybo538NWu0Xrm+zYeTmJtpzqLhnnd5BH21NafqKnplbGZjtN1cnrOlWF73lw==",
            "cpu": [
                "ppc64"
            ],
@@ -1686,9 +1686,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-riscv64-gnu": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.66.0.tgz",
-            "integrity": "sha512-K5fDaNZfDyQMYA/3qL21bqyN0X9T15LLwwbFPt2aHc94+ZG7bh0vZEsy2y7NlRnjjHFSwN+Hzg6ldJtbOriH4Q==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.68.0.tgz",
+            "integrity": "sha512-Yvyl7a6gbb0vM6r925KW2dO+/CmXySO5TVbcX7o/uZJ+d108HFOG0TxIyHApmn5USuj5mhDPxzhiVwOlGP7uSA==",
            "cpu": [
                "riscv64"
            ],
@@ -1706,9 +1706,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-riscv64-musl": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.66.0.tgz",
-            "integrity": "sha512-44Yc+I+qOmTElRcEhm5hUKIUJEQIOugymz4ua4tB0Wox7tGAfIbjzmXz/HDAtw1Ij6gmBwZlzh4hc9679RhWeA==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.68.0.tgz",
+            "integrity": "sha512-mJlFuFVCxzrYM5sFStN433D/s/mb6Wq4aCQAM02vs/OudHywnaSAd2rb1vlYUJtqdYIciJtiasuxvfbYkv5fLg==",
            "cpu": [
                "riscv64"
            ],
@@ -1726,9 +1726,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-s390x-gnu": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.66.0.tgz",
-            "integrity": "sha512-1e29Eg9hEj2kRBB19M0seIehPbbXHCk35GvImjDvb79rjjYjXCRmtbUNHJcgoktZAMIzXrTbxDBKmTc1V4bg3A==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.68.0.tgz",
+            "integrity": "sha512-RlfSg++qs1hbKltRR6lYvV9EoI3MdlfSQD9w1hdHVYjHqjIn1tkH4FWOpMSmjKGN20zr+nI+W9o4ARogCDudGQ==",
            "cpu": [
                "s390x"
            ],
@@ -1746,9 +1746,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-x64-gnu": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.66.0.tgz",
-            "integrity": "sha512-vODY1UQo10gngn0+D4xHKU84F1Twm1LqrzV4SqPXvmQKSd87paehvZ6jqA5wKs6XQrlWul9clYMDVHcoW9CPMA==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.68.0.tgz",
+            "integrity": "sha512-nyzRB9U+dlYUKu3pMo3afHzZBUv/oTHZMG36ZfJViNVfOIzp70Q4GS8FFRGgYJ/p0zcyDCgpBvYISOdJOMh+jQ==",
            "cpu": [
                "x64"
            ],
@@ -1766,9 +1766,9 @@
            }
        },
        "node_modules/@oxfmt/binding-linux-x64-musl": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-x64-musl/-/binding-linux-x64-musl-0.66.0.tgz",
-            "integrity": "sha512-YDzXx2JsT4+HL4MdkVrYjO55NS5lUKNm8rLC4ZPou8+seu0v0jhecSh+ufoO6+xEa8gccEezMlI2WHJi4ApUgw==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-linux-x64-musl/-/binding-linux-x64-musl-0.68.0.tgz",
+            "integrity": "sha512-iCx3sbZRIvGrL1RafphEiUKBaW1lc0/tAjKOIB/Wjw2+STRBEdu5+fH1Gc1faEWEmc2k5Ks4iUUV54Zd5C9a1A==",
            "cpu": [
                "x64"
            ],
@@ -1786,9 +1786,9 @@
            }
        },
        "node_modules/@oxfmt/binding-openharmony-arm64": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-openharmony-arm64/-/binding-openharmony-arm64-0.66.0.tgz",
-            "integrity": "sha512-mJjUYd8lj0+j4JkYyEM+5qKBf1Rnrpgjn/SVYKJhicVDqLz566ooa7Fs8zflPqt+dnZDV7X054rVIQX6ZcQNlQ==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-openharmony-arm64/-/binding-openharmony-arm64-0.68.0.tgz",
+            "integrity": "sha512-x2X5AZez7OgyLLFpwIgItoXBUqudDM7yiaTsxv8R8vKQ6e81l0jVw0NFeUCXzcl1sAJq8h+tC8N4mY8EiMeL4w==",
            "cpu": [
                "arm64"
            ],
@@ -1803,9 +1803,9 @@
            }
        },
        "node_modules/@oxfmt/binding-win32-arm64-msvc": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.66.0.tgz",
-            "integrity": "sha512-soV+0vESv7e5ntCHWC61x4gg8OSak6IHHnWsZmHrJFlvMj2AK+kmldErCNkVkrvc1Ts2/++rJXn+IuAb2WMXhw==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.68.0.tgz",
+            "integrity": "sha512-AHVPjXkenLPQUh6kB8zSC8pX2ct9r4T1Edk9r/RNJyov6wPsS5uAfYtipwG4chn6+3bPFG5rI/3DxEeH8vib1w==",
            "cpu": [
                "arm64"
            ],
@@ -1820,9 +1820,9 @@
            }
        },
        "node_modules/@oxfmt/binding-win32-ia32-msvc": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.66.0.tgz",
-            "integrity": "sha512-YCPi23uRIEYuIKTZohAkKbPFpujQ5QBuUM5iDv+UqbCmTPAkaFsxjsSuB8xlBpRT0G7eP/4HMF+cPDSqHtOD9A==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.68.0.tgz",
+            "integrity": "sha512-n09SjEk5VH7z8Hl4WVP7hho+cCwGViENkQFiM45vbW85dJd7kEhWaHRUobaPzEmrWyu6uumd4EuNfNyDKLtzDA==",
            "cpu": [
                "ia32"
            ],
@@ -1837,9 +1837,9 @@
            }
        },
        "node_modules/@oxfmt/binding-win32-x64-msvc": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.66.0.tgz",
-            "integrity": "sha512-bwTQcv/JVRPkOqQtMF0X7vpvpncDQiBcXHxZ9S2hR12Hlo8bvBdUR5x5XnxzDZ3kM0qoZw1rv7KaD66Ly+pFWA==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/@oxfmt/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.68.0.tgz",
+            "integrity": "sha512-gPe+dJLXaPuWPWqlpklDAJp0k+K9KhQPYiQLHfb+i2rmFuUGfJ/5Qlj6tr1mO6of5g0DiLjG/XCFHIaPhotqqA==",
            "cpu": [
                "x64"
            ],
@@ -1938,9 +1938,9 @@
            ]
        },
        "node_modules/@oxlint/binding-android-arm-eabi": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-android-arm-eabi/-/binding-android-arm-eabi-1.82.0.tgz",
-            "integrity": "sha512-a3LB+C5Dsj5b/qtmG/mv5WrzuiXEpg1KF5nXWcEvaoN5TYAqkIvxPOwTPp3Jy/FoGpRo8zsTFhMElMXfeoOEzA==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-android-arm-eabi/-/binding-android-arm-eabi-1.83.0.tgz",
+            "integrity": "sha512-0yGY24EwsLk5YDe6F+VkmZyRHSwJDALa3nIrPpq7FXmp2lV2d0TzvBCGeZk+wgiULRGr5blhyr4QMp5KCXJUqA==",
            "cpu": [
                "arm"
            ],
@@ -1955,9 +1955,9 @@
            }
        },
        "node_modules/@oxlint/binding-android-arm64": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-android-arm64/-/binding-android-arm64-1.82.0.tgz",
-            "integrity": "sha512-OBlhRgNqFblGpGenno/aqOfJLOkQ2B8Ig3iDAalfn0H8hJGZKXPeexCRTDm6uwv6YUjSA9Xnwt1y/Bgj5ZH8uw==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-android-arm64/-/binding-android-arm64-1.83.0.tgz",
+            "integrity": "sha512-hHfJ0vc17A4iUjH5p9BsTUPYbYRNxGpvD2lbu1aBRk54bzNIx9o5TtYF39QPZcV95DagZd+4DEAw2RH3G2ZsMg==",
            "cpu": [
                "arm64"
            ],
@@ -1972,9 +1972,9 @@
            }
        },
        "node_modules/@oxlint/binding-darwin-arm64": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-darwin-arm64/-/binding-darwin-arm64-1.82.0.tgz",
-            "integrity": "sha512-dsopxqtY5ZdyT9uLHyGt1SyiLop6hi7hWI3PKpePodkRQOkLaCm+OE4fR9CAz9qdfjiFO8531tX/QDyP/psjFg==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-darwin-arm64/-/binding-darwin-arm64-1.83.0.tgz",
+            "integrity": "sha512-hsOjYjszLb/3zym/TkzUMPAoQlTJcuzSyEPOAyA+skXJIX9M0o+4JfOtqopX/Vf4hSLrJ98j0nvFo23gzk8auQ==",
            "cpu": [
                "arm64"
            ],
@@ -1989,9 +1989,9 @@
            }
        },
        "node_modules/@oxlint/binding-darwin-x64": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-darwin-x64/-/binding-darwin-x64-1.82.0.tgz",
-            "integrity": "sha512-94Lu0SgTClKColU66g1VDuigV3HkcbkJBnTtZjGYfE8UPugaWDgKrm2icjC6HJVUYler2OXaHP/X0TBy8+CowQ==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-darwin-x64/-/binding-darwin-x64-1.83.0.tgz",
+            "integrity": "sha512-mjh5oH2EA+wl5yRJYT9K9G61O2zFlpuv+yf2JwZOi0+dq2FnTUtm1h8i+5Ik0fXPWIu/k84I1psZR9aQsLAnyA==",
            "cpu": [
                "x64"
            ],
@@ -2006,9 +2006,9 @@
            }
        },
        "node_modules/@oxlint/binding-freebsd-x64": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-freebsd-x64/-/binding-freebsd-x64-1.82.0.tgz",
-            "integrity": "sha512-hne/V06ewhh1i0w8+l7GDNROAGCGPmyFuOwiP7YTRu0JycyStJ4785dmF8xU5p0uUwt2emvIF9vc7Xjis+cJ0g==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-freebsd-x64/-/binding-freebsd-x64-1.83.0.tgz",
+            "integrity": "sha512-fNHr64/YaO8YssuoDVC8+F4Uk5enR86q5uxfHkQrjAPs1dbAILOrD2uaud+J7MO8Fx774g44ERLD0IGIvZE48w==",
            "cpu": [
                "x64"
            ],
@@ -2023,9 +2023,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-arm-gnueabihf": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.82.0.tgz",
-            "integrity": "sha512-aWY2xtbZf1LneW9Qsv/n2Sp8gOu74JrlQzEtj4coHX2SHFrCfhmAumaU+sI/A5nr+yoTRTSmI/pL2s6ADlNSkw==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.83.0.tgz",
+            "integrity": "sha512-Qpwy3zzAwMj+8/lyYItHmkSMwbkprFNWTK7jPYDOxSyxEhaSLOWYUTCMkjF334J8/WD0nznCCsoBbIH6hpsuIw==",
            "cpu": [
                "arm"
            ],
@@ -2040,9 +2040,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-arm-musleabihf": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-1.82.0.tgz",
-            "integrity": "sha512-Fe+TtXCXMh/5f7kWlZ2VAwsMumZWtraFlKVk1NJlL52/beGwfDE7ov+/8gVirHzWokzGu7X65hSPq0ucPDskWQ==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-1.83.0.tgz",
+            "integrity": "sha512-s+BirYLFq7JL2k9sP0XI3ZXJ9dYvJ8sX3jLCLoag7tt+zrSHpZxP0jqznfL+Gdgwu7ay0dYgGYJXrQvq3iWloA==",
            "cpu": [
                "arm"
            ],
@@ -2057,9 +2057,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-arm64-gnu": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.82.0.tgz",
-            "integrity": "sha512-6azCZ6OJudlvipNttXCCQcyeFfcJ/NvUZdSN1z8elo73kCHtyQC7WTiUcSjWYvJ1jaq9KDUyMAoAS/vNzhBomA==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.83.0.tgz",
+            "integrity": "sha512-7lihXt3vKr+GIyapNbHrnFHm/biiW30le6Zv/DExbAFPF6YwCQXVFlONPFehxs0CpGO4CBfYPM9rdDT+XMoIlg==",
            "cpu": [
                "arm64"
            ],
@@ -2077,9 +2077,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-arm64-musl": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.82.0.tgz",
-            "integrity": "sha512-PLEaSD8IAIIlwW4dwOd9YaxuxeOpwiXL4J24rcnE4iNtyM5j9Q9/3+gti08oXpx0u2ygNjRDx9xjWWpQonuJEw==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.83.0.tgz",
+            "integrity": "sha512-q63JalLYVkZiZvls1z3PPUnpmQluOMXp0khqQMznCeAPLGydfNY8JhvuA4WlK57JfrvikU8wB5lPVveqpIXvew==",
            "cpu": [
                "arm64"
            ],
@@ -2097,9 +2097,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-ppc64-gnu": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.82.0.tgz",
-            "integrity": "sha512-D94em/BwknNTn4vqxjHh5wb2oL566eFhArabqKIr0cNZMHOJuiraFp1A8tXpH05bbE5tqwEfLXTI0MWEGtn3Dw==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.83.0.tgz",
+            "integrity": "sha512-krQmDF+dRbxvdqVPV88ZuOoPPu8X5BuqDA8Hd+qcS4YMRQCb+nexA57DazgGsc/rGdKBe3QmV0mnv0bdpW/p5g==",
            "cpu": [
                "ppc64"
            ],
@@ -2117,9 +2117,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-riscv64-gnu": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-1.82.0.tgz",
-            "integrity": "sha512-MOprxBaoYU2D4VgxXCl3ghydThWtx7Um1lL51kGYNeQ5Al7WzsH7/tqGdNtbLrIWnjq3bsm13+nz/gRIxjrOXw==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-1.83.0.tgz",
+            "integrity": "sha512-MmOl8Y6txEAXZU1RG8Rr264jQ6D7VPmqFsU/45x/FeWsGe32hklTqGrLE6UxHzp5Rjt0wP+20tY8YXKgSFB3mw==",
            "cpu": [
                "riscv64"
            ],
@@ -2137,9 +2137,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-riscv64-musl": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-1.82.0.tgz",
-            "integrity": "sha512-5h55QsfJ/luDXZzC20k6SNOY1Az+dCP9WvntKtcUWh2JhckAdwApY2ZusaBTwLENnReXU+A2fJtSrYvZJNKNPg==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-1.83.0.tgz",
+            "integrity": "sha512-u1rMymh0W3JZkq370kzQsYPULGWqhE09pZRqnZvUSoYaI9pVO5yVX+iYIslmWuEgwuzH9YAaOsScJiobWCHoOw==",
            "cpu": [
                "riscv64"
            ],
@@ -2157,9 +2157,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-s390x-gnu": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.82.0.tgz",
-            "integrity": "sha512-IE8NJNLlHr0CaXyGJPGVn0eTkUyoj1I2UfA8x7I4PSOYKsQ/6btVC7Pywrj5onk0cMH25r6Z38SoN3AvE5Zuog==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.83.0.tgz",
+            "integrity": "sha512-y0zK3HNwGysu7rqtE+BQG/d0bx5gh/KwlOtghN8oWeK1KcWzeaLqtZrbm8owqdma1lFyrce/hTO5ismuNu+INQ==",
            "cpu": [
                "s390x"
            ],
@@ -2177,9 +2177,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-x64-gnu": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.82.0.tgz",
-            "integrity": "sha512-XUUUxaBo9XKl+J1B9EmP1cTGQPddzeURvoGkfwh/94PGnbW+hBprDljneoI2M1jzC1bzrIV3ihc7iM9UXl8+tg==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.83.0.tgz",
+            "integrity": "sha512-rS5gM0NgD7ngmuJmbIehsidtrOwKkLFwCQbKEeb9KuyQrrWNq5Zkn0uV6AYdXOMJ0grrWEiLwBuvMxt8w5vsNw==",
            "cpu": [
                "x64"
            ],
@@ -2197,9 +2197,9 @@
            }
        },
        "node_modules/@oxlint/binding-linux-x64-musl": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-x64-musl/-/binding-linux-x64-musl-1.82.0.tgz",
-            "integrity": "sha512-SWLSFulX9TDuH6yvbPYp4+VNn6jkkIvvI+KiujDM5rWBRHEfkesCC/pCneIIUr6ovkxZ5fRtpi2v5Cz5FrMJZg==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-linux-x64-musl/-/binding-linux-x64-musl-1.83.0.tgz",
+            "integrity": "sha512-W2IH4EtpcPaWcvNGCA95YoDg4vxqE/ZiPCi3arrxEEpsK7+JQN9WYwrlYFx9pcdP6KPXqRqkv3zdQPHcx7b6YQ==",
            "cpu": [
                "x64"
            ],
@@ -2217,9 +2217,9 @@
            }
        },
        "node_modules/@oxlint/binding-openharmony-arm64": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-openharmony-arm64/-/binding-openharmony-arm64-1.82.0.tgz",
-            "integrity": "sha512-BQy35f6ZUdNr9a6c7B7orxQTcLjByGT2z3WAgmRovpRwmPYAaJ+NTplmMzhdjdJ4qSchfMNZy/Ukg+qRg6zseQ==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-openharmony-arm64/-/binding-openharmony-arm64-1.83.0.tgz",
+            "integrity": "sha512-6LyKkUyoajssTPLlZmDbZIbu4IZ5B4bGuRUnBgCGpEvHP3FQMaYITncHA/unPUo7q+Z+pIu2HhdkQ+8d1SG7iA==",
            "cpu": [
                "arm64"
            ],
@@ -2234,9 +2234,9 @@
            }
        },
        "node_modules/@oxlint/binding-win32-arm64-msvc": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.82.0.tgz",
-            "integrity": "sha512-V4QhSTg5gctZue8RJjsGi7NpQPThr/p1/HfmiMC5kfe1KFEup9SQRVub4A6kijQjdHfxj7bLL1KO3QO7/5bwMQ==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.83.0.tgz",
+            "integrity": "sha512-Uz/fObEtF0jmNJQJ8CGRBKfefYstS0/wjD3s6IGzP8nUwsJykHQJBiN3npHwKiGRGn/vvBEgNr4B3cCzmmatvg==",
            "cpu": [
                "arm64"
            ],
@@ -2251,9 +2251,9 @@
            }
        },
        "node_modules/@oxlint/binding-win32-ia32-msvc": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-1.82.0.tgz",
-            "integrity": "sha512-TUSCLaKB2yktpFAJ/r3HAUYsaV/3DT7JS4iNKyoh3a9YNwD0UG7Ezh4D8m23654vQcU6P/RQrCAjRPKe4peP/A==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-1.83.0.tgz",
+            "integrity": "sha512-u7XcvPW6Bk58tY5iWs2ESb0vJjoE/kuSpHxopbwp/p3ZtWVQXZ6wor5w3ssVTHOqd/v8b+QdhSFWQ4grEUNWpA==",
            "cpu": [
                "ia32"
            ],
@@ -2268,9 +2268,9 @@
            }
        },
        "node_modules/@oxlint/binding-win32-x64-msvc": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/@oxlint/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.82.0.tgz",
-            "integrity": "sha512-VTVoRIWJTb+wvUX8EYoPArfFH02whuR10goFXE/LHRRX33ajRrFgqbcONXZMiF4C5rnattfkm87HqYn8jb8hmQ==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/@oxlint/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.83.0.tgz",
+            "integrity": "sha512-LZRubd7ph13QmAg4fFecTYVZkiYbROR2Htaxh/ufWRkDhPOm2wrwaEYR89e0YpPFD3dqBrPoxS7myBw5hmYA7Q==",
            "cpu": [
                "x64"
            ],
@@ -4171,13 +4171,13 @@
            }
        },
        "node_modules/oxfmt": {
-            "version": "0.66.0",
-            "resolved": "https://registry.npmjs.org/oxfmt/-/oxfmt-0.66.0.tgz",
-            "integrity": "sha512-FfvqR8RFtV6JJpRrpkfqyVCQ7HDvZ/VriWFx7veftCgL1B5ZO9qNr+1rvPieycMQnNfVG0PWyJQiy7p0hq1I5w==",
+            "version": "0.68.0",
+            "resolved": "https://registry.npmjs.org/oxfmt/-/oxfmt-0.68.0.tgz",
+            "integrity": "sha512-Z0XMofcXCGUXbcpBHnWyUiX93BGiw1B+lcHNbQDWEtOhX06ewoFfu4zXkyiLhRrNnMq0twqXRHUcJetf+GsiQQ==",
            "dev": true,
            "license": "MIT",
            "dependencies": {
-                "tinypool": "2.1.0"
+                "tinypool": "2.1.2"
            },
            "bin": {
                "oxfmt": "bin/oxfmt"
@@ -4189,25 +4189,25 @@
                "url": "https://github.com/sponsors/oxc-project"
            },
            "optionalDependencies": {
-                "@oxfmt/binding-android-arm-eabi": "0.66.0",
-                "@oxfmt/binding-android-arm64": "0.66.0",
-                "@oxfmt/binding-darwin-arm64": "0.66.0",
-                "@oxfmt/binding-darwin-x64": "0.66.0",
-                "@oxfmt/binding-freebsd-x64": "0.66.0",
-                "@oxfmt/binding-linux-arm-gnueabihf": "0.66.0",
-                "@oxfmt/binding-linux-arm-musleabihf": "0.66.0",
-                "@oxfmt/binding-linux-arm64-gnu": "0.66.0",
-                "@oxfmt/binding-linux-arm64-musl": "0.66.0",
-                "@oxfmt/binding-linux-ppc64-gnu": "0.66.0",
-                "@oxfmt/binding-linux-riscv64-gnu": "0.66.0",
-                "@oxfmt/binding-linux-riscv64-musl": "0.66.0",
-                "@oxfmt/binding-linux-s390x-gnu": "0.66.0",
-                "@oxfmt/binding-linux-x64-gnu": "0.66.0",
-                "@oxfmt/binding-linux-x64-musl": "0.66.0",
-                "@oxfmt/binding-openharmony-arm64": "0.66.0",
-                "@oxfmt/binding-win32-arm64-msvc": "0.66.0",
-                "@oxfmt/binding-win32-ia32-msvc": "0.66.0",
-                "@oxfmt/binding-win32-x64-msvc": "0.66.0"
+                "@oxfmt/binding-android-arm-eabi": "0.68.0",
+                "@oxfmt/binding-android-arm64": "0.68.0",
+                "@oxfmt/binding-darwin-arm64": "0.68.0",
+                "@oxfmt/binding-darwin-x64": "0.68.0",
+                "@oxfmt/binding-freebsd-x64": "0.68.0",
+                "@oxfmt/binding-linux-arm-gnueabihf": "0.68.0",
+                "@oxfmt/binding-linux-arm-musleabihf": "0.68.0",
+                "@oxfmt/binding-linux-arm64-gnu": "0.68.0",
+                "@oxfmt/binding-linux-arm64-musl": "0.68.0",
+                "@oxfmt/binding-linux-ppc64-gnu": "0.68.0",
+                "@oxfmt/binding-linux-riscv64-gnu": "0.68.0",
+                "@oxfmt/binding-linux-riscv64-musl": "0.68.0",
+                "@oxfmt/binding-linux-s390x-gnu": "0.68.0",
+                "@oxfmt/binding-linux-x64-gnu": "0.68.0",
+                "@oxfmt/binding-linux-x64-musl": "0.68.0",
+                "@oxfmt/binding-openharmony-arm64": "0.68.0",
+                "@oxfmt/binding-win32-arm64-msvc": "0.68.0",
+                "@oxfmt/binding-win32-ia32-msvc": "0.68.0",
+                "@oxfmt/binding-win32-x64-msvc": "0.68.0"
            },
            "peerDependencies": {
                "svelte": "^5.0.0",
@@ -4223,9 +4223,9 @@
            }
        },
        "node_modules/oxlint": {
-            "version": "1.82.0",
-            "resolved": "https://registry.npmjs.org/oxlint/-/oxlint-1.82.0.tgz",
-            "integrity": "sha512-+iFM1BGw1ntYJt3QngbJmjbrGxPaKMUADOXOijpWGnYcBPq8YZnQftSS1C+pVcDYy9YxqDVJKQqQkTazTQMboQ==",
+            "version": "1.83.0",
+            "resolved": "https://registry.npmjs.org/oxlint/-/oxlint-1.83.0.tgz",
+            "integrity": "sha512-cyDzSzaw3uzP0TeCeq3lLRPPoaUxkbB4ZOXj+kn+5r+BX9V+4bNVGk9lxer+WrgcpebH4JxLlJ3KQjveVztOLQ==",
            "dev": true,
            "license": "MIT",
            "bin": {
@@ -4238,25 +4238,25 @@
                "url": "https://github.com/sponsors/oxc-project"
            },
            "optionalDependencies": {
-                "@oxlint/binding-android-arm-eabi": "1.82.0",
-                "@oxlint/binding-android-arm64": "1.82.0",
-                "@oxlint/binding-darwin-arm64": "1.82.0",
-                "@oxlint/binding-darwin-x64": "1.82.0",
-                "@oxlint/binding-freebsd-x64": "1.82.0",
-                "@oxlint/binding-linux-arm-gnueabihf": "1.82.0",
-                "@oxlint/binding-linux-arm-musleabihf": "1.82.0",
-                "@oxlint/binding-linux-arm64-gnu": "1.82.0",
-                "@oxlint/binding-linux-arm64-musl": "1.82.0",
-                "@oxlint/binding-linux-ppc64-gnu": "1.82.0",
-                "@oxlint/binding-linux-riscv64-gnu": "1.82.0",
-                "@oxlint/binding-linux-riscv64-musl": "1.82.0",
-                "@oxlint/binding-linux-s390x-gnu": "1.82.0",
-                "@oxlint/binding-linux-x64-gnu": "1.82.0",
-                "@oxlint/binding-linux-x64-musl": "1.82.0",
-                "@oxlint/binding-openharmony-arm64": "1.82.0",
-                "@oxlint/binding-win32-arm64-msvc": "1.82.0",
-                "@oxlint/binding-win32-ia32-msvc": "1.82.0",
-                "@oxlint/binding-win32-x64-msvc": "1.82.0"
+                "@oxlint/binding-android-arm-eabi": "1.83.0",
+                "@oxlint/binding-android-arm64": "1.83.0",
+                "@oxlint/binding-darwin-arm64": "1.83.0",
+                "@oxlint/binding-darwin-x64": "1.83.0",
+                "@oxlint/binding-freebsd-x64": "1.83.0",
+                "@oxlint/binding-linux-arm-gnueabihf": "1.83.0",
+                "@oxlint/binding-linux-arm-musleabihf": "1.83.0",
+                "@oxlint/binding-linux-arm64-gnu": "1.83.0",
+                "@oxlint/binding-linux-arm64-musl": "1.83.0",
+                "@oxlint/binding-linux-ppc64-gnu": "1.83.0",
+                "@oxlint/binding-linux-riscv64-gnu": "1.83.0",
+                "@oxlint/binding-linux-riscv64-musl": "1.83.0",
+                "@oxlint/binding-linux-s390x-gnu": "1.83.0",
+                "@oxlint/binding-linux-x64-gnu": "1.83.0",
+                "@oxlint/binding-linux-x64-musl": "1.83.0",
+                "@oxlint/binding-openharmony-arm64": "1.83.0",
+                "@oxlint/binding-win32-arm64-msvc": "1.83.0",
+                "@oxlint/binding-win32-ia32-msvc": "1.83.0",
+                "@oxlint/binding-win32-x64-msvc": "1.83.0"
            },
            "peerDependencies": {
                "oxlint-tsgolint": ">=7.0.2001",
@@ -4696,9 +4696,9 @@
            }
        },
        "node_modules/tinypool": {
-            "version": "2.1.0",
-            "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-2.1.0.tgz",
-            "integrity": "sha512-Pugqs6M0m7Lv1I7FtxN4aoyToKg1C4tu+/381vH35y8oENM/Ai7f7C4StcoK4/+BSw9ebcS8jRiVrORFKCALLw==",
+            "version": "2.1.2",
+            "resolved": "https://registry.npmjs.org/tinypool/-/tinypool-2.1.2.tgz",
+            "integrity": "sha512-9YodfrxS9g9IbFr/KOjE5bAeJ0p61n3bW6mqvy0jtoeKd1kTW1Cxm0oulm6KX2lyM9Gl6WIe8nEbY7LWv5ZJww==",
            "dev": true,
            "license": "MIT",
            "engines": {
@@ -1,6 +1,6 @@
 {
    "name": "tiny-pattern-ts",
-    "version": "0.1.1",
+    "version": "0.1.5",
    "description": "Pattern matching for TypeScript/ESM environments (F#-style, not regex)",
    "keywords": [
        "adt",
@@ -77,8 +77,8 @@
        "expect-type": "1.4.0",
        "knip": "^6.34.0",
        "lefthook": "^2.1.12",
-        "oxfmt": "^0.66.0",
-        "oxlint": "^1.81.0",
+        "oxfmt": "^0.68.0",
+        "oxlint": "^1.83.0",
        "oxlint-tsgolint": "^7.0.2001",
        "publint": "^0.3.24",
        "typescript": "^7.0.2"
@@ -4,43 +4,13 @@ set -eu

 # Branch front-door. Run as `npm run create:branch -- <prefix>/<desc>`.
 #
-# How we got here (short): the branching model says every change starts from a
-# clean, current `main`, and the type-driven loop only produces trustworthy
-# results if the baseline was green *before* the first edit. Both facts were
-# prose. Prose rots silently — a rule nobody checks is a suggestion — so the
-# precondition became this script: it asserts, then branches, and the branch
-# only appears if the assertions passed. Cheap checks run first, `npm run test`
-# runs last: the expensive gate is not paid on a tree that was never eligible.
+# Asserts the branch preconditions — clean tree, no in-progress operation,
+# current `main`, green baseline — and only then creates the branch, so the
+# expensive `npm run test` is not paid on a tree that was never eligible.
 #
-# Rejected for the prefix name: `run:` / `perform:` (both mean only "do the
-# thing named after them", so every script in the repo would fit under them and
-# the taxonomy collapses); `git:` (names the tool, not the lifecycle moment, and
-# advertises passthrough aliases); `start:` (describes this half, not the
-# release); `cut:` (idiomatic for both, but it needs VCS slang to decode, and a
-# signpost that has to be explained is not one); `flow:` (overloaded in a library
-# about type-level matching); and the existing families — `check:*` is read-only
-# and aggregated by `check`, so CI would run a command that mutates repo state;
-# `fix:*`'s review surface is a file diff, not a branch; `maintain:*` is advisory
-# and explicitly never a gate.
-#
-# `create:` was kept because both members really do create something: a branch,
-# a release. It was added to both prefix lists in CONTRIBUTING.md in the same
-# commit as its first members, because a prefix missing from those lists is
-# invisible — which was the `use:` mistake this repo carried in backlog.tasks (since retired into `setup:`).
-# There is deliberately no bare `create` aggregator: "run all the workflows"
-# describes nothing anyone wants, and `publish:*` already sets the precedent for
-# a prefix without one.
-#
-# Also rejected here: reusing `pubv`'s preflight (release-shaped, third-party,
-# and it would make branch start pay a build + pack it has no use for). The
-# merge half was originally rejected too ("review the diff yourself" is
-# judgment), but it now has its own front door — `create:finish` — which owns
-# the merge-side preconditions and the post-merge `verify`, so the start half
-# does not have to carry that burden.
-#
-# Every refusal is non-mutating except the baseline test, which runs on `main`
-# after we switch there — so a red `main` restores the branch you started on
-# rather than stranding you on it.
+# Why the front door exists, the rejected prefix names, and the `create:`
+# decision: development/workflow.md § Branching model and § Script prefix
+# convention.

 BASE="main"
 PREFIXES="feature fix chore"
@@ -4,29 +4,14 @@ set -eu

 # Feature-finish front door. Run as `npm run create:finish`.
 #
-# Why this exists: `create:branch` opens a unit of work, but the close half
-# (`git checkout main && git merge --no-ff <branch>`) stayed prose in the
-# branching model, so it drifted per contributor and per session. This is the
-# mirror image of `create:branch`: it asserts the same preconditions (clean
-# tree, no in-progress operation, `main` matching its upstream), merges the
-# current `feature/`/`fix/`/`chore/` branch into `main`, proves the result with
-# `npm run verify`, and only then deletes the branch.
+# Mirror image of `create:branch`: asserts the merge-side preconditions, merges
+# the current `feature/`/`fix/`/`chore/` branch into `main` with `--no-ff`,
+# proves the result with `npm run verify`, and only then deletes the branch. The
+# push is owned by `create:release`, so the merge stays local and reviewable.
+# On a conflict it aborts and returns to the feature branch.
 #
-# `create:branch`'s comment argued against wrapping the merge as "judgment —
-# review the diff yourself". That judgment still lives here, just moved: the
-# maintainer reviews the handover *before* invoking this, and the script only
-# commits the merge, never the push. The push is owned by `create:release`, so
-# the release commit and its tag leave together and a local merge stays
-# reviewable (and can be reverted with `git revert -m 1`) until then. `--no-ff`
-# keeps the unit of work visible in `git log`.
-#
-# Unlike `create:branch` a stale `main` is fast-forwarded instead of refused:
-# the tree is clean (checked above) and `main` is not the checked-out branch
-# yet, so there is no local state to lose. True divergence (local commits *and*
-# upstream commits) is still refused — that needs a human.
-#
-# On a merge conflict we abort and return to the feature branch, so a failed
-# finish never strands you on a half-merged `main`.
+# Rationale and the rejected alternatives: development/workflow.md § Branching
+# model.

 BASE="main"
 PREFIXES="feature fix chore"
@@ -9,6 +9,9 @@ import zlib from "node:zlib";
 * matching `Accept-Encoding` and falls back to the original for the rest.
 *
 * Usage: node --strip-types scripts/precompress.ts <dir> [<dir>...]
+ *
+ * Why sidecars rather than per-request compression: development/ci.md § Coverage
+ * serving.
 */

 /**
@@ -9,6 +9,8 @@ set -eu
 # `v1.2.3` and `1.2.3` match the `## [1.2.3]` heading. Prints to stdout and
 # exits non-zero when the tag has no section, so a release can never publish
 # with an empty body.
+#
+# Why: development/publishing.md § Release notes are extracted from the changelog.

 TAG="${1:-}"
 CHANGELOG="${CHANGELOG:-CHANGELOG.md}"
@@ -4,29 +4,13 @@ set -eu

 # Release front-door. Run as `npm run create:release`.
 #
-# How we got here (short): we want hand-written Keep-a-Changelog notes, an
-# [Unreleased] -> "## [x.y.z] - DATE" graduation, and a tag that marks the exact
-# commit on main that gets published. No single tool did BOTH the [Unreleased]
-# graduation AND the package.json bump. So split by strength: `pubv` (tiny,
-# changelog-driven) owns preflight + the interactive major/minor/patch heuristic
-# + graduating/committing CHANGELOG.md (no tag, no push); `npm version` syncs
-# package.json + the lockfile; `--amend` folds them into pubv's single commit;
-# tag AFTER the amend (so the tag is never orphaned) and push.
+# Graduates the [Unreleased] changelog notes, bumps package.json + the lockfile,
+# and commits then tags the exact SHA that CI publishes. The notes are finalized
+# in VS Code before pubv because pubv's bump heuristic reads the [Unreleased]
+# body.
 #
-# The notes are finalized in VS Code *before* pubv: the [Unreleased] body is
-# what pubv's bump heuristic reads, so editing afterwards would inform the
-# changelog only, not the version choice. pubv refuses a dirty tree, so that
-# edit is committed as a staging commit and folded back into the single release
-# commit below.
-#
-# Rejected: the conventional-commits family (our history is gitmoji, not
-# Conventional; and we want hand-written notes); changesets/rtk (config + a
-# heavier version/publish flow that fights our CI-only publish); knope/kacl/
-# bestikk (changelog-only — don't bump package.json; plus 5yr/2yr/brand-new
-# maintenance); pubv alone (verified it never writes package.json). We also
-# tried `versions` (silverwind) — great Gitea support — but pairing it with a
-# hand-rolled promote became a ~180-line script we'd have to maintain, which is
-# exactly what this ~30-line version replaces.
+# Tooling rationale, the rejected alternatives, and the version source of truth:
+# development/publishing.md.

 CHANGELOG="CHANGELOG.md"
 BASE="main"
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Build (and optionally push) the CI job image from docker/Dockerfile.
+# Run wherever docker + registry credentials live (the runner host, or any
+# machine that can reach the registry). The registry/repo below MUST match
+# the `container.image` references in .gitea/workflows/ci.yml — the runner
+# pulls the image by name.
+#
+# Usage: scripts/runner-image.sh [--push]
+#
+# Why the image is baked, its two invariants, and the coordinated Node-bump
+# steps: development/ci.md.
+
+IMAGE_REPO="gitea.e1nsnull.de/tmu/act-ci"
+
+NODE_VERSION="$(tr -d '[:space:]' < .node-version)"
+if [[ ! "${NODE_VERSION}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+    echo "error: .node-version must be pinned to an exact x.y.z, got '${NODE_VERSION}'." >&2
+    echo "       setup-node resolves floats like '26' to the latest patch at runtime," >&2
+    echo "       which silently busts the tool-cache entry baked into the image." >&2
+    exit 1
+fi
+
+IMAGE="${IMAGE_REPO}:${NODE_VERSION}"
+
+# --pull: refresh the act base layer so the derivative does not float on an
+# aging default image forever (layer dedup keeps this cheap).
+docker build --pull --build-arg "NODE_VERSION=${NODE_VERSION}" -t "${IMAGE}" -f docker/Dockerfile .
+
+if [[ "${1:-}" == "--push" ]]; then
+    docker push "${IMAGE}"
+fi
+
+echo "built ${IMAGE}"
+echo "reminder: bump container.image in .gitea/workflows/ci.yml to this tag"
Author	SHA1	Message	Date
tmu	9f038a230d	🔀 Merge chore/docs-restructure into main CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 20s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 16s Details	2026-09-15 21:51:33 +00:00
tmu	1465926783	📝 Check off the docs restructure and note it in the changelog	2026-09-15 21:51:21 +00:00
tmu	5e7d40b013	📝 Improve docs after split	2026-09-15 21:46:41 +00:00
tmu	74c39e1346	♻️ Tighten the development/ prose Same decisions, rationale, rejected alternatives and known issues, said with less padding: ~5,530 -> ~4,730 words (-15%). Every fact from the first draft is kept; only the wording, duplicated lead-ins and restated context are cut.	2026-09-15 13:56:49 +00:00
tmu	7ea84b66fa	♻️ Drop the last duplicated prose from development/ The GitHub Flow description and the type-first enforcement sentence still appeared in both CONTRIBUTING.md and development/. development/ now carries only the context and rationale that is not in CONTRIBUTING.md.	2026-09-15 13:47:01 +00:00
tmu	95d73d11b6	♻️ Single-home the actionable rules and the rationale development/ had restated the actionables that CONTRIBUTING.md owns: the branching step list, the script prefix list, the feedback-tier rule of thumb, the commit convention and the type-driven test loop. Those now live only in CONTRIBUTING.md; development/ keeps the decision blocks and links to the rule. development/README.md, CONTRIBUTING.md and AGENTS.md state the 'write each fact once' principle explicitly.	2026-09-15 13:46:31 +00:00
tmu	fe02317fc8	📝 Track code-fence testing and the finish/push tension Adds a Documentation task to validate Markdown code fences against src/, and a Workflow task for the create:finish / create:branch upstream mismatch recorded in development/workflow.md.	2026-09-15 13:40:04 +00:00
tmu	84d48c6e67	📝 Make the rule/rationale split explicit AGENTS.md and CONTRIBUTING.md now state that a decision, its rejected alternatives and its known issues belong in development/<category>.md, that the actionable rule stays in CONTRIBUTING.md, and that both change in the same commit. development/README.md names library.md in the category list and spells out that the sync runs in both directions.	2026-09-15 13:39:58 +00:00
tmu	c7372732ba	♻️ Move script-header rationale into development/ branch.sh, finish.sh, release.sh, runner-image.sh and release-notes.sh carried multi-paragraph 'how we got here / rejected' essays in comments. They now live in the matching development/ category file, and each script keeps a one-line pointer so the rationale is single-homed and cannot drift.	2026-09-15 13:27:21 +00:00
tmu	9faa0ecc55	📝 Rewrite README as the user entry point Follows the Perl/CPAN order: name + one-line description, Synopsis, Description, Examples, API reference, License. Tooling, CI and decision content moved to development/; the README keeps only user-facing material and a pointer to CONTRIBUTING.md and AGENTS.md. No version line and no package.json link.	2026-09-15 13:27:15 +00:00
tmu	73669ec5b6	📝 Rewrite CONTRIBUTING as the contributor entry point Adds Setup, Development commands, Code style and formatting (with the VSCode extension hint) and Submitting changes. The decision prose moves to development/; this file keeps the actionable rules (feedback-tier table, script prefix list, standards) and links to the category files for the why.	2026-09-15 13:27:05 +00:00
tmu	dc7ce22fc5	📝 Add development/ docs for decisions and known issues Category files under development/ replace the decision prose that was scattered through README.md and CONTRIBUTING.md. Each decision is a block with Decision (YYYY-MM) / Why / Rejected / Known issue; the new library.md records the public API contract and its limitations. AGENTS.md and backlog.tasks now point at the new home.	2026-09-15 13:26:59 +00:00
tmu	97dfe9e7b4	📝 Expand the docs-cleanup task into concrete subtasks	2026-09-15 13:21:58 +00:00
tmu	b92645faa1	🔀 Merge chore/runner-image-decision into main CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 19s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 15s Details	2026-09-15 12:09:13 +00:00
tmu	5bb58137c4	📝 Check off the Gitea release-page verification task	2026-09-15 12:07:34 +00:00
tmu	e1dec54363	📝 Cancel force-pull task and document the runner-image decision The act-ci image is rebuilt only when Node is bumped, which changes the tag, so the runner's default no-force-pull behavior already picks up every normal update. Forcing a pull would re-pull on every job and a missed runner-side image change is acceptable, so document that decision as a known issue with a manual docker rmi workaround instead of tracking a force-pull task.	2026-09-15 12:02:59 +00:00
tmu	c0bba0775c	🚀 Release 0.1.5 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 24s Details CI / maintain (push) Failing after 15s Details CI / publish (push) Failing after 17s Details	2026-09-15 09:33:17 +00:00
tmu	b8d235df89	🔀 Merge chore/improve-ci-publish into main	2026-09-15 09:32:04 +00:00
tmu	76fe8993a7	📝 Track the docs cleanup and docs-site task	2026-09-15 09:31:58 +00:00
tmu	f984576d4e	📝 Record the automatic-token publish design in the backlog Point 1 dropped the GITEA_TOKEN gate (the run's automatic github.token is always present), and point 2 added the all-or-nothing check; keep the checked task from claiming behavior the workflow no longer has.	2026-09-15 09:25:42 +00:00
tmu	79b4d8c005	♻️ Use the automatic token and fail closed on a partial release Drop the GITEA_TOKEN gate and pass no explicit token: gitea-release-action defaults to the run's automatic github.token, so the release page needs only contents: write. Keep the npm publish gated on NPM_TOKEN, but add a final always() step that fails the job unless both the release page and npm publish reported success, so a skipped npm half is an explicit red job instead of a silently green one.	2026-09-15 09:25:24 +00:00
tmu	60e416b0fe	📝 Check off the CI publish task The publish job was already tag-only; the coarse NPM_TOKEN assert is replaced by per-step env gates, so an unset secret now skips only its own step.	2026-09-15 09:06:48 +00:00
tmu	e90d2549e3	📝 Document the publish-step token gates Record the two optional secrets and why the job lifts them into env: the secrets context is unavailable in a step if, so env is the only place the gate can read them.	2026-09-15 09:06:39 +00:00
tmu	8915eb8faa	👷 Gate the publish steps on their tokens The publish job aborted at the top-of-job NPM_TOKEN assert, so every tag run since 0.1.1 failed before checkout and nothing was ever published. Lift both optional secrets into job-level env (the secrets context is not allowed in a step if) and gate each publish step: the Gitea release on GITEA_TOKEN, npm publish on NPM_TOKEN. An absent secret now skips only its step, so a tag without the maintainer's secrets stays green after the packaging checks.	2026-09-15 09:06:35 +00:00
tmu	75f2185b32	📝 Track the CI publish hardening task Also restores the runner force-pull task that the new entry had replaced; it is still open (CONTRIBUTING § CI runner image documents the stale-image failure).	2026-09-15 09:05:41 +00:00
tmu	9c472c88c2	🚀 Release 0.1.4 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 22s Details CI / maintain (push) Successful in 14s Details CI / publish (push) Failing after 3s Details	2026-09-14 16:20:46 +00:00
tmu	16962e947e	🔀 Merge chore/dependency-updates into main	2026-09-14 16:19:04 +00:00
tmu	be0ca717d0	⬆️ Upgrade oxfmt to 0.68.0 and oxlint to 1.83.0 Latest releases of the two oxc tools; both minor bumps within 0.x/1.x semver ranges. check-outdated now reports zero outdated dependencies and npm run verify passes with no rule or format fallout.	2026-09-14 16:18:02 +00:00
tmu	5a3ee3b8cc	🔀 Merge chore/remove-toolcache-diagnostics into main CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 18s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 14s Details	2026-09-14 16:07:52 +00:00
tmu	77fb604d7e	📝 Check off the CI Node-baking task All steps confirmed green in CI ('Found in cache @ /opt/hostedtoolcache/node/ 26.8.2/x64', no download). The runner-side force-pull item moves to its own task, since a changed image under an unchanged tag is still silently ignored.	2026-09-14 16:04:03 +00:00
tmu	1b2b50304e	♻️ Assert the baked tool cache instead of logging it The diagnostics did their job (missing <version>/<arch>.complete marker, now written by the image). Replace the noise with a fail-fast assert that names the same invariant, mirroring the publish job's NPM_TOKEN check: a stale tag on the runner would otherwise silently reintroduce the per-job download, with nothing in the repo to catch it.	2026-09-14 16:04:01 +00:00
tmu	048a8870e6	🐛 Write the tool-cache completion marker into the image CI / release-gate (push) Successful in 3s Details CI / build (push) Successful in 39s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 15s Details setup-node still downloaded although the image carried a perfect /opt/hostedtoolcache/node/26.8.2/x64/ tree. actions/tool-cache accepts a cached tool only when the sibling marker <version>/<arch>.complete exists (tc.find() tests it explicitly); a bare directory is ignored, so the probe fell through to the download. The marker is what tc.cacheDir() writes after installing a tool, so the baked entry must create it too. Job-container diagnostics also confirmed the path was never in question: RUNNER_TOOL_CACHE=/opt/hostedtoolcache, no mount over it, node -v from the baked path prints v26.8.2. CONTRIBUTING records both invariants — the marker, and the fact that a Dockerfile change keeps the same tag, which forcePull=false can hide.	2026-09-14 15:59:23 +00:00
tmu	f0b28c81c0	🔊 Log tool-cache state in the CI build job CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 40s Details CI / publish (push) Skipped Details CI / maintain (push) Failing after 42s Details The custom image provably carries /opt/hostedtoolcache/node/26.8.2/x64/bin/node (ls inside the image confirms the layout, modes and the 150 MB binary), yet setup-node still downloads. So the miss is runtime-only: either the runner is not running that image or something shadows the path inside the job container. This step prints mounts, the tool-cache listing, a direct node -v from the baked path and the RUNNER_* env, then setup-node runs unchanged. Temporary: remove once the cause is known.	2026-09-14 15:55:52 +00:00
tmu	1dfb979ebb	🚀 Release 0.1.3 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 43s Details CI / maintain (push) Failing after 33s Details CI / publish (push) Failing after 3s Details	2026-09-14 15:45:11 +00:00
tmu	f04ad3d5bc	🔀 Merge chore/fix-ci into main	2026-09-14 15:43:57 +00:00
tmu	93cbfcf6b1	🐛 Expand the node base image through a named stage CI / release-gate (pull_request) Successful in 2s Details CI / build (pull_request) Successful in 37s Details CI / publish (pull_request) Skipped Details CI / maintain (pull_request) Failing after 34s Details COPY --from= resolves its value as a stage name at parse time, before build args exist, so COPY --from=node:${NODE_VERSION} collapsed to the invalid 'node:' and docker failed with 'failed to parse stage name'. ARGs in global scope are expanded in FROM, so route through a named nodebase stage; the per-stage ARG redeclaration keeps the tool-cache paths expanding.	2026-09-14 13:28:29 +00:00
tmu	3e33b51d1b	📝 Document CI runner-image bump ritual build:runner-image broke the script prefix convention: build is a bare single-tool command, and no tier fits a docker-daemon + registry-cred action, so the script leaves package.json and is invoked directly. CONTRIBUTING gains a 'CI runner image' section recording where the image pushes (gitea.e1nsnull.de/tmu/act-ci:<version>), the .node-version coupling, and the three-step Node-bump ritual.	2026-09-14 12:51:34 +00:00
tmu	abbdf4410e	📝 Track CI Node-baking work in backlog Record chore/fix-ci's two done steps and the remaining ops step (build/push the image; first CI run is the acceptance test). Glyph/tag coupling honoured: every ✔ line carries @done, open parent stays ☐.	2026-09-14 12:40:22 +00:00
tmu	245dfaf198	💚 Bake Node into the CI job image setup-node never consults `node` on PATH; its only fast path is a probe of /opt/hostedtoolcache, which the ephemeral act_runner job containers always miss, so every job paid a ~50 MB Node download. docker/Dockerfile extends the runner's default catthehacker/act image with the Node distribution overlaid at the exact tool-cache layout, so setup-node finds 26.8.2 and skips the fetch while node-version-file, cache: npm and registry-url keep working unchanged. Image layers dedupe against the base the host already pulled and prune via normal docker hygiene — the cleanup story a host bind of /opt/hostedtoolcache lacks. To make the bake deterministic, .node-version is pinned to the exact 26.8.2 the image carries; scripts/runner-image.sh guards that coupling and builds/pushes the tag the three node jobs now reference via container.image. Ops follow-up (outside the repo): build once with `npm run build:runner-image -- --push` on a machine with registry creds. If the package is private, the runner needs container registry credentials in its config.	2026-09-14 12:37:58 +00:00
tmu	b9fe21175f	💚 Reuse npm cache in publish job The publish job ran npm ci against a cold cache on every release while build/maintain already share a warm node-cache key off the same lockfile. Tag runs can read caches saved on main, so wiring cache: npm here is free.	2026-09-14 12:13:38 +00:00
tmu	5292455dbc	🚀 Release 0.1.2 CI / release-gate (push) Successful in 2s Details CI / build (push) Successful in 36s Details CI / maintain (push) Successful in 27s Details CI / publish (push) Failing after 3s Details	2026-09-14 12:03:32 +00:00
tmu	d1ef039688	🔀 Merge chore/dependency-updates into main	2026-09-14 12:02:51 +00:00
tmu	c65f86e5d5	⬆️ Upgrade dependencies	2026-09-14 12:02:27 +00:00
@@ -1 +1 @@
 
 .8.2