docs(AGENTS.md): the dev-server port is a default, not hard-wired, and the three contributor lines agree with the code (#27094)

Fixes #26088
Clause-②: no
Metadata-protocol: none

## 维护者速读

- 改了什么:AGENTS.md 三处贡献者说明改成与代码一致 —— 开发服务端口是默认 3000、不是写死的;`pnpm run setup`
只装依赖并构建 spec,不是首次完整准备;前端快速迭代段改用文档名 `OS_PORT`。
- 为什么改:照 AGENTS.md 操作的贡献者或 agent 会以为端口必须是 3000、改不了,并把 `pnpm run setup`
当作首次准备,随后 `pnpm dev` 因未构建被拒;README / CONTRIBUTING / getting-started
已在先前一单改好,这一单收尾 AGENTS.md。
- 风险与回滚:纯文档,不发布任何包;行数不变(1112),无新增行;回滚即 revert 这一个 commit。
- 先看:`AGENTS.md` L138(开发服务表格那一行,改动最大的 hunk);其次 L40 与 L170–171。
- 两分钟验证:`grep -n 'hard-wired\|PORT=3000\|pnpm run setup' AGENTS.md`,预期只见
L40 新说明、L138 的「not hard-wired」与 `OS_PORT=3000`、L170 的
`OS_PORT=3000`,不再出现「must be 3000」。
- 需要你做的:作为 GOVERNED_APPROVERS 审阅并批准(AGENTS.md 属 Tier H 受管面)。

## What changes

Three contributor lines in `AGENTS.md`, each edited in place; no line
added or removed (1112 lines before and after).

| Line | Before | After | Bytes before → after |
|:---|:---|:---|:---|
| L40 (fenced) | `pnpm run setup # first-time: install + build spec
(...)` | `pnpm run setup # install + build spec only; pnpm dev needs
pnpm build (...)` | 99 → 123 (fenced line: exempt from the 120-byte
prose rule) |
| L138 (table row) | `PORT=3000 pnpm dev` · "Port **must** be 3000 (UI
hard-wired)" · `PORT=3000 pnpm dev:crm` | `OS_PORT=3000 pnpm dev` ·
"Port 3000 is the default, not hard-wired: the Console dev proxy targets
it unless `DEV_PROXY_TARGET` says otherwise, and a busy port shifts to
the next free one, so read the port it prints (`PORT` is the legacy
alias of `OS_PORT`)" · `OS_PORT=3000 pnpm dev:crm` | 307 → 506
(widest-row pin is 768, held by L709; unchanged) |
| L170 | `... on :3000** (PORT=3000 pnpm dev for` | `... on :3000**
(OS_PORT=3000 pnpm dev` | 117 → 116 |
| L171 | `showcase) and browse :5180 ...` | `for showcase) and browse
:5180 ...` | 114 → 118 |

The code line that decided each fact:

- **Setup.** Root `package.json:18`: `"setup": "pnpm install && pnpm
--filter @objectstack/spec build"`, so the line's "install + build spec"
was accurate; "first-time" was not. `pnpm dev` runs
`scripts/check-dev-prereqs.mjs`, which requires every workspace
package's dist entry and prescribes `pnpm install && pnpm build`
(`scripts/check-dev-prereqs.mjs:579`), the same sequence `README.md`,
`CONTRIBUTING.md` and getting-started give. The line now says what
`setup` does and that `pnpm dev` needs `pnpm build`.
- **Port.** `packages/cli/src/commands/dev.ts:481` reads `flags.port ??
readEnvWithDeprecation('OS_PORT', 'PORT', { silent: true })`, `:537`
defaults it to `'3000'`, and `:562` runs `getAvailablePort` over the
requested port: dev shifts off a busy port even when the port was asked
for explicitly (`serve.ts:2307`, dev mode only). The Console dev server
proxies `/api` to `process.env.DEV_PROXY_TARGET ||
'http://localhost:3000'` (`ui/apps/console/vite.config.ts:1509`).
Nothing is hard-wired; 3000 is the default on both sides.
- **Spelling.** `OS_PORT` is the documented name (`--port` flag help:
"overrides $OS_PORT; $PORT is the legacy alias";
`content/docs/getting-started/index.mdx:211-212`;
`CONTRIBUTING.md:70-71`), so both AGENTS.md command spellings now use
it.

Left as is, on purpose: L145 "never run two backends on port 3000". It
does not repeat the "hard-wired" claim. With auto-shift it still gives
sound advice: a second backend would silently land on 3001 while the
proxy keeps hitting the first.

## Tests

Docs-only diff to one governed instruction file. No package code
changed, so no package test or typecheck is owed and no ablation applies
(no tested behaviour moved). Card acceptance grep at `596cd15e`: `grep
-n 'PORT=3000\|OS_PORT\|npx create-objectstack\|npm create
objectstack\|pnpm run setup' AGENTS.md` matches only L40 (`pnpm run
setup`, now described accurately), L138 and L170 (both `OS_PORT=3000`);
no bare `PORT=3000` remains.

## Acceptance notes

- `examples/README.md:42` carries the same `pnpm run setup # first-time:
install + build spec` label. It is outside this card's file surface
(AGENTS.md only) and outside the card's acceptance grep. Noted here, not
filed.
- `ui/AGENTS.md:221` (Tier H, outside this surface) still spells the
legacy `PORT=3000 pnpm dev` / `PORT=3000 pnpm dev:crm`. The legacy alias
still works (`readEnvWithDeprecation`), so this is a spelling drift, not
a defect. Noted here, not filed.

## Verification

All local readings were taken at head `596cd15e` (the final commit).

Derived gates came from `node scripts/pm/dispatch-gates.mjs --commands
--repo objectstack-ai/objectstack`, with no paths and a change set of 1
path vs merge base `fbc16563a`. It derived 15 gates, and every one
exited 0. I also ran three named gates outside the derivation:
`check:doc-authoring`, `check-published-list-mirrors` and its
`--self-test`.

The `--ran` reconciliation reports: 15 derived, 15 run, 0 NOT-MEASURED,
0 UNRUN. That zero is derived from recorded exit codes.

`pnpm check:pm-skill-ratchet` exits 0. Its reading for AGENTS.md: "1112
lines (ceiling 1112; headroom 0)", "widest table row is 768 bytes (pin
768; headroom 0)", and every prose line is within the 120-byte budget.

The CI families on this PR are not awaited by the author.

<details><summary>Gate exit codes (head 596cd15)</summary>

```text
node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
pnpm check:agent-test-spelling :: exit 0
pnpm check:docs-audit-scope :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:pm-governed-merges :: exit 0
pnpm check:pm-governed-prose :: exit 0
pnpm check:pm-skill-id-lint :: exit 0
pnpm check:pm-skill-ratchet :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:required-contexts :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm check:doc-authoring :: exit 0
node scripts/check-published-list-mirrors.mjs --self-test :: exit 0
node scripts/check-published-list-mirrors.mjs :: exit 0
```

</details>

Session: `session_01QSeKYmhU5KEj1nukYhp1Tg` (os-dev subagent,
`mode:subagent`).

---
_Generated by [Claude
Code](https://claude.ai/code/session_01QSeKYmhU5KEj1nukYhp1Tg)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

AGENTS.md

@@ -37,7 +37,7 @@ stated once here and the script's own header is the authority on detail.
 
 ```bash
 pnpm install          # deps
-pnpm run setup        # first-time: install + build spec (bare `pnpm setup` is pnpm's own built-in)
+pnpm run setup        # install + build spec only; `pnpm dev` needs `pnpm build` (bare `pnpm setup` is pnpm's own built-in)
 pnpm build            # turbo build (excludes docs)
 pnpm test             # turbo test
 pnpm typecheck        # turbo typecheck — per-package `tsc --noEmit`; tsup/vitest never type-check
@@ -135,7 +135,7 @@ layer at least as close to the code (ruling record 6120820653).
 
 | Scenario | Command | Notes |
 |:---|:---|:---|
-| **Frontend debug** (the Console in `ui/` calls backend) | `PORT=3000 pnpm dev` | `pnpm dev` = the **showcase** kitchen-sink app (default; best for exercising the platform). Port **must** be 3000 (UI hard-wired); persistent state; leave running. For the minimal CRM app instead: `PORT=3000 pnpm dev:crm`. |
+| **Frontend debug** (the Console in `ui/` calls backend) | `OS_PORT=3000 pnpm dev` | `pnpm dev` = the **showcase** kitchen-sink app (default; best for exercising the platform). Port 3000 is the default, not hard-wired: the Console dev proxy targets it unless `DEV_PROXY_TARGET` says otherwise, and a busy port shifts to the next free one, so read the port it prints (`PORT` is the legacy alias of `OS_PORT`); persistent state; leave running. For the minimal CRM app instead: `OS_PORT=3000 pnpm dev:crm`. |
 | **Backend-only debug** | `pnpm dev -- --fresh -p <random>` | Random high port; ephemeral tempdir; **you must kill it** when done |
 
 `--fresh`: ephemeral tempdir (auto-deleted on exit) + `--seed-admin` (POSTs sign-up, prints creds — default
@@ -167,8 +167,8 @@ ships that same tracked file in `packages/console/dist/`. Full procedure: `docs/
 
 **Fast iteration on `ui/` src (no rebuild loop):** run the Console dev server —
 `pnpm --filter @object-ui/console dev` (Vite on **:5180**, HMR). Its `/api` proxy targets
-`DEV_PROXY_TARGET || http://localhost:3000`, so **run the backend you're testing on :3000** (`PORT=3000 pnpm dev` for
-showcase) and browse `:5180`. Note `:3001/_console` (or whatever the backend serves) is the **built** console, not
+`DEV_PROXY_TARGET || http://localhost:3000`, so **run the backend you're testing on :3000** (`OS_PORT=3000 pnpm dev`
+for showcase) and browse `:5180`. Note `:3001/_console` (or whatever the backend serves) is the **built** console, not
 your `ui/` src — only `:5180` reflects local UI edits. See `ui/AGENTS.md` for the app-id /
 localStorage / auth gotchas.