finding: AGENTS.md documents the docs dev server on port 3001; npm run dev is bare next dev and binds 3000 #97

Observation, found while browser-verifying #87. Low severity — it costs one wasted fetch per agent, not correctness.

What is there

AGENTS.md, § Commands:

From `apps/docs/`:
- `npm run dev` — dev server on http://localhost:3001

apps/docs/package.json line 8:

"dev": "next dev",

Bare next dev with no -p, so it binds Next's default 3000. Measured — the dev server started for #87 logged:

▲ Next.js 16.2.6 (Turbopack)
- Local:         http://localhost:3000
✓ Ready in 1033ms

A fetch against the documented 3001 returns nothing (status=000); against 3000 it returns 200.

Why it is worth recording

It is agent-facing instruction rather than published docs, so it misdirects exactly the reader who cannot check it cheaply: an agent following AGENTS.md polls 3001, gets connection-refused, and has to go read the log to discover the real port. The AGENTS.md rule it sits under is "test in a real browser before claiming UI work is done" — the friction lands on the one step the repository most wants agents to actually perform.

Two ways to close it, and they are not equivalent

• Fix the doc (3001 → 3000). One line, matches today's behaviour.
• Fix the script (next dev -p 3001). Also one line, and it makes the documented port true rather than the doc follow the default. Worth considering because several agents share one container here: pinning the port makes a collision fail loudly on start instead of silently handing the next agent 3001, 3002, … while every log still says "Local:".

Not folded into #87 — that card's surface is two content pages, and this is a repository-instruction change with a script option behind it.

Checked for duplicates first: no open issue in this repository covers the dev-server port.

Generated by Claude Code