docs: development.md drifted from Makefile; make verify needs pnpm

[EricAndrechek]

Surfaced by the docs-reviewer gate on the cache-split PR that fixes #443. None of it is caused by that branch — it's pre-existing drift between docs/src/content/docs/development.md / CONTRIBUTING.md / SUPPORT.md and the Makefile + internal/ tree. Filed rather than folded into a CI-only PR.

Ordered by impact.

1. make verify / make lint understate what they run — and hide a pnpm requirement

docs/src/content/docs/development.md:479,481 describes:

• make lint → "Run linters across Go (golangci-lint) + TS (Biome)"
• make verify → "Repo-wide static checks: Go (tidy + fmt + vulncheck + lint) + TS (Biome + tsc typecheck)"

Actual (Makefile:359, Makefile:486):

lint:            lint-go lint-ts lint-md lint-prose
verify-parallel: tidy fmt-go lint-go lint-ts lint-md lint-prose lint-sh
                 lint-gha test-classify-paths vulncheck check-docs typecheck-ts

Undocumented: markdownlint, misspell, shellcheck (lint-sh), actionlint (lint-gha), test-classify-paths, check-docs (astro check).

Why it matters: development.md:21 lists the pnpm-requiring targets as build-ts, test-ts, test-e2e, build-docs, dev-docs, preview-docs — omitting make verify and make lint, both of which depend on pnpm-install via lint-ts / lint-md / typecheck-ts / check-docs (Makefile:355,370,486,569). make verify is what the pre-commit hook runs, so a Go-only contributor who follows this page skips pnpm and fails on their first commit.

Fix: mirror the Makefile help text in both rows, and add make verify / make lint / make ci to the pnpm prerequisite list.

2. make tools silently installs the git hooks — undocumented on the setup page

development.md:24-31,464 lists only golangci-lint, air, the go.mod tool deps and pnpm deps. Makefile:877-889 also installs misspell v0.8.0, shellcheck v0.11.0, actionlint v1.7.12, and runs git config core.hooksPath .githooks.

The hooks omission is the material one: CONTRIBUTING.md:40 and docs/src/content/docs/claude-code.md:18 both state the pre-commit/pre-push gates come from make tools, but the page README calls the authoritative setup source never says so — so a contributor who bootstraps by hand has no gate and doesn't know it.

Fix: add the three tools, and state that make tools sets core.hooksPath (and how to opt out).

3. Project Structure tree omits internal/stream/

development.md:413-447 enumerates internal/ but skips internal/stream/, which holds the SSE fan-out Hub / Subscriber / Bucket / Heartbeater / metrics. It landed with the #294 hub refactor, which updated architecture.md:65,84-92 and AGENTS.md but not this tree — so a reader looking for the SSE delivery path is pointed at internal/api/.

Fix: insert between query/ and testutil/:

│   ├── stream/    # SSE fan-out: Hub, Subscriber, Bucket, Heartbeater, metrics

4. Stale .md pointers to pages that are now .mdx

• CONTRIBUTING.md:46 — "Configuration options → update docs/src/content/docs/configuration.md" → .mdx. The three sibling paths on lines 45/47/48 are correct, which makes this one read as authoritative.
• SUPPORT.md:26 — "especially getting-started.md, api.md, configuration.md" → configuration.mdx.
• deployments/compose/dev-policy.yaml:19 — "See docs/src/content/docs/access-control.md" → .mdx. This one ships in the quickstart stack, so users actually read it.

Fix: correct the extensions (or drop them). While in CONTRIBUTING.md, consider adding the CHANGELOG.md row from AGENTS.md §Documentation Sync, which that four-item list drops.

5. go run vs go tool for pinned tools

development.md:291 — "the Makefile uses go run so no global installation is needed". Makefile:144-154 uses go tool (GOTESTSUM := go tool gotestsum); go run is only for in-repo ./scripts/... programs. This also contradicts line 30 of the same page, which correctly says go tool <name>.

Fix: go run → go tool.

Verified clean

For the record, the same review spot-checked and found accurate: api.md routes/methods/admin gating vs internal/api/router.go, filter ops vs internal/query/builder.go, body caps and the ingest envelope, configuration.mdx against every struct tag/env var/default in internal/config/config.go, access-control.mdx against internal/policy/policy.go, pipes.mdx, ingest-pipeline.md constants, durability.md, and the SDK docs against clients/ts/src/.

6. golangci-lint documented as a manual install — it isn't

docs/src/content/docs/development.md:385-391 says golangci-lint "is installed separately… If not found, make lint prints install instructions", then offers three manual options including go install …/golangci-lint@latest.

Actual: Makefile:362 (lint-go: $(GOLANGCI_LINT)) plus the file target at Makefile:899 download the pinned GOLANGCI_LINT_VERSION := v2.11.4 (Makefile:158) into .bin/<os>_<arch>/golangci-lint-v2.11.4. make lint installs it silently and never prints instructions. It also contradicts line 28 of the same page.

Worse, a contributor who follows the @latest bullet gets an unpinned binary the Makefile will never invoke (it looks for the version-suffixed path), then re-downloads v2.11.4 on the next make lint anyway.

Fix: replace the paragraph and bullet list with: make lint (and make tools) download the pinned golangci-lint into .bin/ automatically — no manual install needed; bump GOLANGCI_LINT_VERSION in the Makefile to change it; a globally installed golangci-lint is ignored.

7. make fix row is also stale

development.md:482 — "Go … and TS (Biome --write)". Makefile:433-436 fans out fix-go fix-ts fix-md fix-prose. Same class as item 1; fix alongside it.

Also on that table: the "(parallel-safe: make -j verify)" parenthetical is outdated — Makefile:480-483 self-parallelizes a bare make verify.

[coderabbitai]

🔗 Related PRs

#129 - ci: kill coverage Docker pull on PR runs + tighten claude-review group [merged]
#147 - chore: claude code native improvements [closed]
#174 - refactor(table names): handle unsafe table names [closed]
#187 - docs: prep docs for publishing [closed]
#312 - ci: split ci into a job dag and isolate docs deploys from pr code [closed]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!