overhaul: 01 foundation

[CS-5]

Layer 1 of the overhaul stack, on top of the plan branch (#14). plan/01-foundation.md.

An empty-but-real Astro project with the complete final toolchain, and the old site parked for reference. No UI yet — that starts in Phase 02.

What's here

Legacy parked. src/, data/, and every Next.js config file moved to legacy/ with a README saying reference-only. public/ and functions/ stay at root. Nothing in the new tree imports from it, and every tool ignores it.

Runtime + package manager. mise.toml pins node 26.7.0 and pnpm 11.22.0, with per-platform checksums committed to mise.lock. mise tasks are thin forwarders — package.json scripts are the single source of truth. pnpm-workspace.yaml sets a 7-day release cooldown and denies install scripts except sharp and esbuild.

Astro scaffold. Astro 7 static, sitemap integration, Tailwind v4 through @tailwindcss/vite (no config file), strictest tsconfig with the explicit strictness flags from the brief, @/* path alias, and src/lib/cn.ts as the only sanctioned cn import site.

Lint + format. oxlint (type-aware, with anti-slop vendored into tools/lint/anti-slop/) and oxfmt own .ts/.js/.json/.jsonc/.css. ESLint (strictTypeChecked + eslint-plugin-astro's jsx-a11y-strict) and Prettier own .astro and .md. Import sorting is on for both halves. clsx, classnames, tailwind-merge, and any legacy/ path are banned imports.

Agent + editor config. AGENTS.md (one screen) with CLAUDE.md symlinked to it; a PostToolUse hook that routes each edited file to its owning formatter and linter, exiting 2 with findings on failure; VS Code settings matching the same split.

CI. pnpm check → pnpm build → offline lychee link check over dist/, blocking, on every PR. Deploys stay with Cloudflare Pages' git integration (D14).

Verified

• mise install && pnpm install && pnpm check && pnpm build green.
• Seeding import clsx from "clsx" and a chained type assertion in a .ts file fails pnpm lint on both counts — the import ban and anti-slop are live.
• The hook formats a .ts with oxfmt and an .astro with Prettier, and returns oxlint findings to the agent with exit 2.
• Nothing under legacy/ is read by oxlint, oxfmt, Prettier, tsc, or knip.

CI blocking on a seeded lint error is the one criterion not verifiable locally — it gets checked on this PR.

Deviations from the phase brief

• typescript is 6.0.3, not 7.x. typescript-eslint peers <6.1.0 and @astrojs/check peers ^5 || ^6. oxlint-tsgolint bundles its own checker and is unaffected.
• Pins are the newest version at least a week old, not the newest version — that's minimumReleaseAge doing its job, and it applies to every dependency here.
• pnpm typecheck is astro check && tsc -p functions. functions/ gained strict and moved to moduleResolution: "bundler" (which is what Cloudflare's esbuild actually does) so its existing extensionless @/* imports resolve. That surfaced a real bug: an absent CF-Connecting-IP header was being sent to Turnstile as the string "null". The field is optional, so it's now omitted when missing.
• Three gitignore-semantics workarounds, all documented in docs/tooling.md: oxfmt needs --ignore-path .gitignore (it reads .prettierignore by default, which would make it skip every file it owns); Prettier is invoked against an explicit **/*.{astro,md} glob (a blanket * ignore prunes directories irreversibly); ESLint scopes via files: for the same reason.
• anti-slop is not re-registered as a local ESLint plugin for .astro frontmatter. Rationale in ADR 0001 — the rules are type-aware, frontmatter is thin by convention here, and the logic worth checking lives in .ts.
• ADR 0002 supersedes Phase 03's icon choice: icons come from @tabler/icons (plain SVG source, inlined at build) rather than astro-icon + @iconify-json/tabler. @tabler/icons-react can't be used at all — it ships React components, which breaks the zero-framework-runtime rule.

Docs added

docs/tooling.md (setup, ownership table, cooldown behavior, the corepack footgun, env vars), docs/adr/0001-toolchain-split.md (D24 + the exact steps to collapse onto oxc later), docs/adr/0002-tabler-icons-direct.md.

README.md still describes the Next.js workflow — Phase 11 rewrites it, per the plan.

---

Generated by Claude Code

[CS-5]

Code review of the Phase 01 foundation (a268397). I installed the lockfile and ran the whole gate locally to check the toolchain actually does what the docs claim: astro check, tsc -p functions, oxlint --type-aware, eslint, oxfmt --check, prettier --check, knip, and astro build all pass, and seeded-violation probes confirm the oxlint side is live (the clsx ban, anti-slop chained-assertion rules, and type-aware TS diagnostics all fire, in src/ and in functions/), the hook formats + feeds findings back with exit 2, oxfmt does own .css, and prettier's Tailwind class sorting works in .astro.

Four findings, all verified by running the tools rather than by reading:

1. eslint.config.ts:17 — jsx-a11y-strict registers zero rules. eslint-plugin-jsx-a11y is an optional peer of eslint-plugin-astro and is not installed, so accessibility linting is silently off repo-wide. Highest-impact item here, given ADR 0001's "do not drop accessibility coverage".
2. eslint.config.ts:36 — the clsx/tailwind-merge and legacy/* import bans don't apply to .astro. They exist only in oxlint, which ignores .astro.
3. functions/tsconfig.json:12 — the Pages Functions are typechecked more loosely than src/ (no noUncheckedIndexedAccess etc.), which is backwards for request-handling code.
4. .claude/hooks/format-lint.sh:37 — a missing binary is reported as a lint failure, so a pre-install edit is blocked with an empty error.

Nothing wrong with the one behavioral code change in the diff: the remoteip-when-null Turnstile fix in functions/util.ts is correct, and the noEmit addition to the functions tsconfig is a good catch.

---

Generated by Claude Code

[CS-5]

The clsx / tailwind-merge and legacy/* import bans are unenforced in .astro files.

Both bans live only in .oxlintrc.json, which ignores **/*.astro. ESLint is the only linter that reads .astro, and it sets no no-restricted-imports — so the two rules AGENTS.md leads with are off in the file type the entire site is built from (Phase 03 onward).

Verified on this branch — 0 findings, exit 0:

---
import { parseColor } from "../../legacy/src/styles/theme.ts";
const c = parseColor("yellow");
---
<p>{c}</p>

eslint --print-config on an .astro file shows no no-restricted-imports entry. Note the phase acceptance check git grep -l 'from "legacy' src also misses this, since the import is relative.

Fix: restate the same no-restricted-imports config in this files: ["**/*.astro"] block. It is a copy of the oxlint one, but unlike the anti-slop rules (whose omission ADR 0001 justifies) these two bans need no plugin to work.

---

Generated by Claude Code

[CS-5]

Half of this is fixed, half is now moot, and one loose end is left — leaving the thread open for that.

Fixed: eslint.config.ts restates no-restricted-imports for **/*.astro, so the legacy/* pattern ban is live there. Verified: an .astro file importing ../../legacy/src/styles/theme.ts now fails lint.

Moot: the clsx / classnames / tailwind-merge paths ban was removed from both .oxlintrc.json and eslint.config.ts in 235aa2f ("Manual cleanup"), alongside deleting src/lib/cn.ts. So there is nothing left to restate on that half.

Loose end: AGENTS.md still asserts the ban —

clsx, classnames, tailwind-merge are banned imports.

— and so does plan/00-overview.md D7. Nothing enforces it now, in either linter, for any extension. That is the same shape as the original finding: a documented rule with no mechanism behind it.

Two ways to close it, and I did not want to pick for you:

1. Re-add the paths ban to both configs, now pointing at @/lib/cn (see the note on overhaul: 03 primitives #17 — the file is back from Phase 03 because it stops being a re-export and becomes a configured merge). The docs stay as written.
2. Drop the claim from AGENTS.md and D7, and let the single-source rule rest on convention plus review.

Worth noting for either choice: the packages are not direct dependencies, so an accidental import { clsx } from "clsx" would fail knip's unlisted: "error" rule anyway. The ban's real value is catching someone adding one deliberately.

---

Generated by Claude Code

[CS-5]

/simplify pass — quality review (reuse · simplification · efficiency · altitude)

Quality only; correctness findings are in the separate review on this PR.

Three of the four angles came back empty for this PR, and that's a real result rather than a shrug — I'll say what was checked and cleared at the bottom. Two efficiency findings:

---

1. Tailwind scans legacy/, so every page ships ~32 KB of CSS generated from the retired Next.js site

src/styles/global.css:1

@import "tailwindcss";

Tailwind v4's automatic source detection walks up from the CSS file and scans the whole project, minus .gitignored paths. legacy/ is checked in, so all of the old Next.js JSX is a scan target and its classes are emitted into the one shared stylesheet that every page links.

Verified in built output further up the stack — dist/_astro/BaseLayout.*.css contains classes that exist nowhere in src/:

bg-[url(/image/metal-shavings.webp)]   from-green-900/95   bg-red-600
hover:bg-yellow-500   lg:right-[-225]   data-[active=true]:after:h-[2px]
dark:text-white   h-450   max-h-37.5

Cost, measured. Adding @source not "../../legacy"; took the shared bundle from 68,567 → 36,666 bytes (12,870 → 8,206 gzipped) — a 47% cut, 4.7 KB gzipped off every page load — plus that much less scanning and generation on every build. dist/index.html and dist/styleguide/index.html came out byte-identical in size, and every house utility (pocket, eyebrow, spec-label, ambient-pool, draw-on, text-h1) survived.

This is worth fixing here rather than later: legacy/ is reference-only per AGENTS.md, so nothing it contains should ever reach the build, and the exclusion belongs next to the import that creates the problem.

Fix: @source not "../../legacy"; beside the @import, or an explicit @source scoped to ../.

---

2. CI reinstalls the whole dependency tree from the network on every run

.github/workflows/ci.yml:21-29

      - name: Install mise tools
        uses: jdx/mise-action@v3
        with:
          version: 2026.8.14
          install: true
          cache: true

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

mise-action's cache: true covers mise-managed tool binaries (node, pnpm), not pnpm's content-addressable store, and there's no actions/cache step for it. Every PR run re-downloads and re-links the full tree — which by PR #17/#19 includes @tabler/icons (~12k files) and sharp's platform binaries.

Fix: cache the pnpm store keyed on pnpm-lock.yaml, install with --prefer-offline.

Separately, package.json:16 — pnpm check chains typecheck && lint && fmt:check && knip serially, but the last three are mutually independent. Running them concurrently uses the runner's second core for free. Worth weighing against the fact that serial output is easier to read when something fails; if you keep it serial, that's a deliberate call rather than an oversight.

---

Checked and cleared

• Reuse: ignoring the renames into legacy/, none of the new content (src/lib/cn.ts, tsconfig.json, .oxlintrc.json, eslint.config.ts, knip.jsonc, the vendored anti-slop rules) re-implements anything already in the tree. The ignore lists that repeat across the four configs are each required by their own tool and have no shared mechanism to reuse.
• Simplification: the mise.toml task list duplicates package.json scripts, but that's the stated single-source-of-truth forwarding design, not accidental duplication. tools/lint/anti-slop/ is a vendored upstream plugin (MIT, documented as copy-don't-fork in its VENDOR.md) — out of scope for restructuring.
• Altitude: the suppressions are all at the right depth and carry their justification. .oxlintrc.json's **/*.astro ignore and ESLint's files: ["**/*.astro"] scoping are the ownership split from ADR 0001; knip.jsonc's ignoreDependencies: ["tailwindcss"] names a real tool limitation. The plan/01-foundation.md edit adds an honest "Deviations from this brief" section rather than weakening a criterion — the one unmet box stays [ ] with a reason. That's the model the rest of the stack should follow.

---

Generated by Claude Code