docs: say pnpm run setup for the first-time install and spec build (#24370)

Fixes #24357
Clause-②: no

## What changed

One line in each of two files, net ±0 lines per file:

- `AGENTS.md`, Build & Test block: `pnpm setup` becomes `pnpm run
setup`, and the comment now ends ``(bare `pnpm setup` is pnpm's own
built-in)``, so the next edit does not tidy the `run` away. The comment
column stays aligned with the lines around it.
- `examples/README.md`, Getting started block: `pnpm setup` becomes
`pnpm run setup`. The comment column stays aligned.

Nothing else is touched. The root `package.json` `setup` script is
unchanged.

## Why: measured on pnpm 10.31.0

10.31.0 is both the root `packageManager` pin and the container's `pnpm
--version`. Every probe of the bare form ran with `HOME`,
`SHELL=/bin/bash` and `XDG_DATA_HOME` / `XDG_CONFIG_HOME` /
`XDG_CACHE_HOME` / `XDG_STATE_HOME` pointed at a throwaway directory in
the session scratchpad, with `PNPM_HOME` unset. I read the sha256 of the
container's real `~/.bashrc`, `~/.zshrc` and `~/.profile` before and
after every probe, and none of them changed.

| probe | where | what ran | exit |
|---|---|---|---|
| bare `pnpm setup` | a fixture project whose only script is `setup`,
which writes a marker file | pnpm's built-in. It created the throwaway
`.bashrc` with the `# pnpm` ... `export PNPM_HOME=...` ... `# pnpm end`
block and printed "To start using pnpm, run: source ...". No marker
file. | 0 |
| `pnpm run setup` | the same fixture | the script. It printed
`SETUP_SCRIPT_RAN` and wrote the marker file. | 0 |
| bare `pnpm setup` | this repo's root at `a2a3777bf5` | the built-in
again, with the same rc block. No install output. `packages/spec/dist`
was absent before and after. | 0 |
| `pnpm run setup` | this repo's root, with the real `HOME` so it uses
the real store | `pnpm install && pnpm --filter @objectstack/spec
build`. It printed `Already up to date`, ran the spec build to
`check-dts-emitted: 38/38` and stamped
`packages/spec/dist/.build-input-hash`. | 0 (`os-verify-lock` `VERDICT
command-exit 0`) |

So the failure is silent. Bare `pnpm setup` exits 0, prints text that
looks like success, and edits the contributor's shell rc. It leaves no
install and no spec build behind. `pnpm help setup` agrees: "Usage: pnpm
setup. Sets up pnpm".

## Every `pnpm setup` hit and its disposition

On the base, `git grep -nE 'pnpm setup\b' a2a3777 -- .
':!**/CHANGELOG.md'` found 3 hits. The excluded `CHANGELOG.md` files
have 0 hits, and they are release-owned anyway.

| hit | disposition |
|---|---|
| `AGENTS.md:40` | a first-time setup command: changed |
| `examples/README.md:42` | a first-time setup command: changed |
| `.github/workflows/lint.yml:157` | YAML comment prose ("checkout, Node
and pnpm setup, the caches, the install, ...") about setting pnpm up,
not the command: untouched, and outside this card's file surface |

After the change, the same grep finds 2 hits: `lint.yml:157`, and the
new `AGENTS.md` comment, which names the bare form on purpose. On the
base, `git grep -nE 'pnpm run setup'` found 0 hits.

I also intersected the 206 root `package.json` script names with pnpm
10's command names. The only other collisions are `test`, where pnpm's
built-in runs the script so nothing breaks, and `version`, which every
tracked caller already spells `pnpm run version`.

## The open choice I settled: the comment clause

Should the `AGENTS.md` line say why it is `run`? I judged it on the four
axes. **Business need:** the readers are first-time contributors and
every new agent session, and bare `pnpm setup` is exactly what they ran.
**Long-term soundness:** the clause states the trap once, where the
command lives, with no gate and no new file. **Making AI mistakes
structurally harder:** an agent that knows `pnpm SCRIPT` normally runs a
script will shorten `pnpm run setup` back to `pnpm setup`. The clause
names why this one must keep `run`, and that shortening is how the
defect got in. **No scope spread:** one line, no number, no incident
narrative (`check:pm-skill-id-lint` is green). `examples/README.md` gets
only the `run`, because its readers follow it rather than edit it.

## Changeset

None. The PR carries the `skip-changeset` label: both files are
repo-root docs, and no package's `files[]` ships either of them. The
devx lane rule says root `scripts/`, docs and test-only changes get
`skip-changeset`.

## Gates (local subset, at `2601bcc81`)

`node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 42 commands for the two paths, the
same list as the dispatch-time reading. I ran each one in the worktree
and captured its exit code before any pipe:

- 40 exited 0. That includes `check:pm-governed-prose`,
`check:pm-governed-merges`, `check:pm-skill-id-lint` (87 files clean),
`check:pm-skill-ratchet`, `check:nul-bytes`,
`check:cross-package-test-inputs`, `check:published-files`,
`check:test-source-alias` and `check:examples-live-imports`, plus every
`node scripts/check-*.mjs` row and its `--self-test`.
- 2 exited 3 with `PREREQUISITE NOT MET`, which reads as NOT MEASURED,
not as a failure: `pnpm check:dual-build-cjs-loads` and `pnpm
check:lean-entry-closure`. Both load built output of packages this diff
does not touch, and only `packages/spec` is built in this worktree. CI's
Build Core and Lint jobs run them over a full build.
- `check:dts-closure` and `check:sourcemap-no-sources-content` exited 0
but swept 1 built package (`@objectstack/spec`) for the same reason.
- `dispatch-gates --ran` with `COMMAND :: exit CODE` lines printed: "42
derived famil(ies) accounted for — 40 run, 2 NOT-MEASURED (2 DERIVED
from a recorded exit 3)".

No package is touched, so no package build closure, `pnpm test` or `pnpm
typecheck` is owed. No tested behaviour changed, so there is no
ablation. Every family CI runs on the PR is read from the PR's
check-runs, not re-run here.

## Acceptance notes

- `examples/README.md` runs `pnpm install` on the line above `pnpm run
setup`, and the script runs `pnpm install` again. That is redundant but
harmless, since the second install is a no-op. It is polish, not a
defect, so I left it as written. Carrier: none.
- Renaming the root script to a name pnpm does not own would remove the
trap at its source instead of documenting it. I did not take that route.
It changes `package.json` outside this card's file surface, objectui
kept the `setup` name and moved its docs to `pnpm run setup`, and
nothing in this repo calls the script by any other spelling. Carrier:
none.

## 维护者速读(草稿)

**改了什么**:`AGENTS.md`「Build & Test」段和 `examples/README.md`「Getting
started」段里首次安装的那一行,`pnpm setup` 改成 `pnpm run setup`。`AGENTS.md`
那一行的注释补了半句,说明裸 `pnpm setup` 是 pnpm 自带的命令。每个文件只改一行,行数不变。

**为什么改**:pnpm 10 下,裸 `pnpm setup` 跑的是 pnpm 自带的 setup 命令,它往 shell 配置文件里写
`PNPM_HOME`。仓库根 `package.json` 里的 setup 脚本(装依赖 + 构建 spec)根本不会跑。这个命令以 0
退出,打印的提示看起来像成功了,所以照 `AGENTS.md` 做首次安装的新同事或新 agent 会以为已经装好,实际上依赖没装、spec
没构建,shell 配置还被改了。两种写法都在本仓根目录和一个隔离夹具里实测过,全程没碰真实的 rc 文件。

**风险与代价(含回滚)**:只改两行文档,不碰代码,没有发布面,不加门禁。代价是首次安装命令多了 4 个字符。回滚就是 revert 这个
PR。`AGENTS.md` 是 Tier H 治理面,所以整个 PR 要等你批准才能落地。

**席位意见**:

**你要做的**:看一下这两行 diff,同意就给一次批准(APPROVED
review),之后由席位落地。如果不想要注释里那半句,告诉席位只保留 `pnpm run setup` 即可。

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

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 setup            # first-time: install + build spec
+pnpm run setup        # first-time: install + build spec (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

examples/README.md

@@ -39,7 +39,7 @@ pnpm verify         # validate + typecheck + coverage tests
 ```bash
 # From the repo root
 pnpm install
-pnpm setup                      # first-time: install + build spec
+pnpm run setup                  # first-time: install + build spec
 
 # Beginner path
 cd examples/app-todo && pnpm typecheck