📝 Add AGENTS.md as the agent entry point

AI coding agents read AGENTS.md automatically, not README. Make AGENTS.md
a thin pointer: the stable first-action facts plus links to CONTRIBUTING.md,
README.md, and package.json#scripts. Keep the rules prose in CONTRIBUTING.md
so humans and agents don't diverge (same anti-drift move as dropping
project-specs.md).

Clarify the agent's verification loop: npm run test is the mandatory gate;
the pre-commit hook already runs the fast offline checks (tsc, oxlint, oxfmt,
cspell) on staged files, and npm run check (knip + outdated) is repo-maintenance,
not part of the feature loop. Forbid type-system escape hatches (@ts-nocheck,
oxlint-disable, as-casts) as agent-only rules; a human may still add a
review-visible disable as a last resort, so the location convention stays in
CONTRIBUTING.md with a forward reference.

AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+Machine entry point for AI coding agents working in this repo. The authoritative
+guidance for humans lives in [CONTRIBUTING.md](./CONTRIBUTING.md) and
+[README.md](./README.md); this file only points at it and states the stable
+first-action facts. Do not restate evolving prose here — it will drift.
+
+## First action
+
+- Project: F#-style pattern matching for TypeScript/ESM. Node `>=26` (pinned via `.node-version`), ESM-only (no CommonJS shim).
+- **Mandatory while iterating:** `npm run test` (runs `check:tsc`, then the unit suite). This is the gate you are responsible for.
+- **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 (`tsc` + `oxlint` + `oxfmt` + `cspell`) — don't run them by hand. If the hook fails on style, `npm run fix`, restage, recommit.
+- **`npm run check` is NOT part of the feature loop.** It adds `knip` (dead-code/deps) and `check:outdated` (registry) — repo-maintenance scans. Run it only on an explicit maintenance / update-deps branch; CI runs it on the PR regardless.
+
+    ```sh
+    npm run test   # the bot's definition of done; commit normally after
+    ```
+
+## Never do
+
+Don't silence the type system to force a green run. As an agent these are forbidden:
+
+- `// @ts-nocheck`, `// @ts-ignore`, `// @ts-expect-error`
+- `// oxlint-disable` / `// oxlint-disable-next-line`
+- `as` casts used to push an expression through (type-aware oxlint already flags unsafe assertions)
+
+Fix the root cause with the type system instead — narrowing, generics, `satisfies`, conditional / mapped types, utility types (`NonNullable`, `Exclude`, …). TypeScript can express it; that's the intended tool. The `oxlint-disable`-location rule in [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) is a **human** last-resort convention (so a reviewer can spot a deliberate suppression) — it is not permission for you to add one. If the types genuinely cannot express something, stop and surface the conflict (commit message / MR) rather than suppress it.
+
+## Read these
+
+- [CONTRIBUTING.md § Rules the tools don't enforce](./CONTRIBUTING.md#rules-the-tools-dont-enforce) — the constraints the linters don't catch; CI/review bounce these. **The most important section.**
+- [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 (`watch` / pre-commit / pre-push / `check` / `fix` / CI).
+- [README.md § Tooling decisions](./README.md#tooling-decisions) — 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).