refactor: remove the inline comments the codebase was told never to carry

[jouwdan]

Closes MEI-143.

AGENTS.md has forbidden inline code comments since it was written. 1,743 had accumulated across 189 source files anyway, 1,281 of them written by agents, because nothing loaded the rule and nothing checked it. #254 fixed the second half. This is the backlog it left behind.

1,743 → 1. 2,455 lines deleted across 187 files. The one survivor is a turbopackIgnore directive.

Removed, not moved

MEI-143 was originally written to move each comment into the docs/ page that covers it, per AGENTS.md. That was overruled, and I think correctly: pouring 1,700 lines of function-level commentary into the docset would bloat the thing readers actually use to answer questions about running a board.

Nothing that mattered is lost — every removed line is in git log -p. Some were real "why" notes (the SameSite=Lax reasoning on the SSO cookie; why presence counts a guest only once the client has proved it keeps cookies; why a headline is split into blocks so text-wrap: balance runs per sentence). Recording that here so the trade-off is on the record.

What was kept, and why

Read by a tool rather than a person: biome-ignore, @ts-expect-error, compiler-read type annotations, triple-slash references, and turbopackIgnore in locate-wasm.ts — which changes how the bundler treats a dynamic read.

The comment is the published page: the six files pnpm theme:docs and pnpm plugin:docs build the theme-slot and plugin-hook references from. packages/theme-kit/src/view-models.ts alone is 739 lines of it.

Not this codebase's code: the comments inside create-meith's template literals are the scaffolded board's files. A comment orienting somebody in the project they just created is a different thing from a comment in ours.

Two things the verification caught

1. Generated files carry // GENERATED FILE — do not edit. banners. Stripping them broke pnpm board:gen:check, because the generator compares its output byte for byte against what is on disk. community.plugins.ts (×2) and packages/api/src/reference.ts are restored. The gate did its job.
2. The scanner from feat(agents): make the no-inline-comments rule enforceable by every tool #254 counted turbopackIgnore as an ordinary comment, so the hook would have refused any edit to locate-wasm.ts and pushed the next person toward deleting a load-bearing bundler directive. Fixed here, with a test, along with webpackIgnore, __PURE__, @vitest-environment, @jsxImportSource and @deprecated.

The second is why this branch carries a fix(agents): commit as well as the sweep: one comment surviving a pass that took 1,742 others is worth asking about, and the answer was a gap in the guardrail.

Verification

pnpm lint, typecheck, typecheck:app, typecheck:site, guards, guards:probe, depcruise, and every generator and structural gate — workspace:check, root:check, release:check, i18n:check, slots:check, hooks:wired, board:gen:check, theme:docs:check, plugin:docs:check, perf:docs:check, api:docs:check, site:docs:check, marketplace:gen:check, board-installer:gen:check, vercel-template:gen:check, docs:index:check, docs:links:check, ci:parity:check.

Directive counts checked before and after: all 37 biome-ignore and all 11 real @ts-expect-error survive. Four apparent @ts-expect-error losses were prose mentions inside removed comments, not directives.

The unit suite is left to CI here. I started it three times locally and disturbed the tree under it twice (a git stash while comparing counts, then merging main in); rather than report a run I had compromised, the honest thing is to let the Static checks job run it on a settled tree.

---

Generated by Claude Code