docs(getting-started,ai): state the skills install command the scaffolder actually runs

[claude]

Clause-②: no

Closes #16400

What was false

Four content/docs/** pages recommended installing the AI skills bundle with
npx skills add objectstack-ai/objectstack/skills --all, and two of them
stated that flag as what the scaffolder runs. That second half was already
false in the tree, not about to become false: the scaffolder moved to a single
named agent when PR #16401 landed (2026-09-06T20:36:10Z), so the two
getting-started lines described a command create-objectstack no longer issues.

What it actually runs today — re-measured, not cited

Read from packages/create-objectstack/src/skills-install.ts on this branch's
base (c88fa2ccdc), by evaluating the constants rather than eyeballing the
template literal:

SKILLS_INSTALL_COMMAND     npx -y skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
skillsInstallHint(default) npx    skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
skillsInstallHint('codex') npx    skills add objectstack-ai/objectstack/skills --skill '*' --agent codex -y
DEFAULT_SKILLS_DIR         .claude/skills/

index.ts:542 passes SKILLS_INSTALL_COMMAND to execSync, and lines 594-601
print skillsInstallHint(...) in the closing summary — so "one agent, one
directory, and the command is printed for any other runtime" is the behaviour,
not just the constant.

A check in the PR: all 7 command literals left in the four pages are
compared programmatically against the value that module composes. 0 mismatches.

Carriers — 4 of the card's 5 surfaces are this PR's

The card named five surfaces. Triage split on the landing path, not on the
sentence kind: 「拆后本卡的文件面只剩 content/docs/**,按车道表归 domain:devx」.

surface	kind	state
getting-started/your-first-project.mdx 45, 286	states what the scaffolder runs + re-run instruction	fixed here
getting-started/build-with-claude-code.mdx 57, 381	same pair	fixed here
ai/skills-reference.mdx 27, 30, 33	manual recommendation + two prose claims	fixed here
ai/skills.mdx 35, 38	manual recommendation + prose claim	fixed here
skills/README.md 9	governed surface	not ours — already moved to the per-agent form by PR #16806, verified absent from this base

The two bolded sites were not on the card's or the skills seat's line list;
skills-reference.mdx:33 and skills.mdx:38 attribute the bundle-versioning
and idempotence properties to --all specifically, so leaving them would have
kept the flag as the recommended form in prose after the commands changed.

Fix shape, and why not a pointer

The brief asked whether to keep a corrected literal or point at the single
source of truth (skills-install.ts), as this shift's #16200 did. Split by
reader:

• Where the reader must type the command (all four pages' install and
  re-run instructions) the literal stays, corrected. A docs reader cannot
  resolve a pointer into a TypeScript module in our monorepo — that page is not
  on the docs site and they cannot run it. Pointing there would remove the fact
  instead of keeping it true, which is the vague-sentence failure in a
  different costume.
• Where the reader does not need the value, the pointer shape is used:
  skills-reference.mdx's "new projects" paragraph now states the observable
  properties (one runtime, .claude/skills/, once) and points at the live
  instrument the reader actually holds — the scaffolder's own closing summary
  prints the exact command it ran. That paragraph previously named no command,
  so this keeps the number of decaying copies at what it was rather than adding
  an eighth.

--all is not deleted: it is a real CLI option, and triage's instruction was
that the idempotence claim is true and must not be removed. It survives on the
reference page as a labelled multi-runtime opt-in that names its cost (three
destinations: real copies in both .agents/ and agent/, plus .claude/
symlinks), with the distinction that makes the idempotence claim useful —
re-running is idempotent per destination, and it is the destination count that
grows.

Reverse-read

Does anywhere else state the scaffolder's behaviour, and does this diff make
any standing sentence false?

• content/docs/deployment/cli.mdx 29, 93, 94 — "installs the AI skills bundle
  • AGENTS.md". True, names no command, no decay. Unchanged.
• content/docs/getting-started/how-ai-development-works.mdx:45,
  getting-started/index.mdx 26, 161 — same shape. Unchanged.
• getting-started/build-with-claude-code.mdx:70 — a console transcript
  quoting → Installing AI skills for your coding agent..., byte-equal to
  index.ts's printStep. True. pnpm check:docs-transcript-drift measured it
  green on the final text. Unchanged.
• getting-started/build-with-claude-code.mdx:26 (mermaid) and
  your-first-project.mdx:272 — "installs the skills bundle", no command.
  Unchanged.
• packages/create-objectstack/README.md:60, src/templates/AGENTS.md:82,
  src/templates/blank/README.md:148, skills/README.md:9 — all four already
  carry the per-agent form. This diff agrees with them; none becomes false.
• packages/create-objectstack/src/template-consistency.test.ts:597-602 — "the
  boundary is the /skills SUBPATH, and it did not move when the scaffolder
  stopped passing --all". Directional and historical, still true, and this
  diff keeps the subpath on every literal.
• Zero results for: any other content/docs page naming a skills add
  command; any test or gate pinning --all in the docs (none exists — see the
  acceptance note below); any generated block containing an install command
  (build-skill-docs.ts emits none; skills-reference.mdx's generated region
  starts at line 38, below every site edited).

One sentence outside this card's file surface is made false by this diff,
reported rather than fixed: .github/workflows/scaffold-e2e.yml:229-231 says in
a comment "The scaffolder/docs command is skills add …/objectstack/skills --all". The scaffolder half was already stale; the docs half becomes stale
here. The probe below it deliberately uses --all --copy and is correct for its
purpose (set-equality against the curated catalog), so only the comment is
wrong. Left alone because triage split this card's file surface to
content/docs/** and editing a workflow would add a verification surface this
PR does not otherwise touch.

验收备注

• No gate pins the docs against the scaffolder's command. Triage flagged
  building one as a bonus and explicitly told the claiming seat not to expand
  the PR into scripts/ for it — so the programmatic literal comparison above
  was run as a one-off in this PR and is not committed. Noted, not filed: the
  next surface to state this command has nothing mechanical to catch it, and the
  docs-drift audit states it structurally cannot see this class.
• docs/qa/platform-checklist/areas/cli.json:384 uses --all --copy as a
  skills-boundary probe. Not a statement of scaffolder behaviour; unaffected.
• .claude/skills/dogfood-verification/SKILL.md:13 notes that the CLI's
  --all implies --skill '*'. True CLI semantics, governed surface, untouched.

Verification

Derived with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack
(change set taken by the script from the merge base, not from a hand-written
diff): 43 families, 43 run, 0 NOT-MEASURED, 0 UNRUN, all exit 0 —
reconciled back through --ran with an exit code recorded per family, so the
zero is derived rather than claimed. Four of them first refused with
PREREQUISITE NOT MET (exit 3, not a finding); @objectstack/lint,
@objectstack/formula and @objectstack/client-react were built and all four
then exited 0.

Named readings, all on the final text:

pnpm --filter @objectstack/spec check:docs        ✅ 222 generated files in sync with packages/spec
pnpm check:docs-transcript-drift                  ✓ 4 declared transcript value(s) across 402 page(s)
                                                    under content/docs/ equal what the registry derives today
pnpm check:doc-authoring                          ✓ 44 published skill files clean
pnpm check:corpus-claim-drift                     OK, no new claim sites beside a pinned spelling
pnpm check:role-word                              OK, no new occurrences of the reserved word
pnpm check:nul-bytes                              exit 0

Heavy steps ran through scripts/pm/os-verify-lock.sh (slot issue-16400):
pnpm install VERDICT command-exit 0, @objectstack/spec build
VERDICT command-exit 0, the three-package turbo build
VERDICT command-exit 0.

pnpm lint — a declared narrowing, measured in three parts. The repo-scoped
run is CI's; the reading here is that this diff is outside eslint's population
entirely. (1) Population from eslint's own config, not a guess:
new ESLint().isPathIgnored(...) returns true for the changed .mdx files.
(2) File count from --format json over exactly the four changed files: 4 files
read, 0 errors, and each of the 4 warnings is File ignored because no matching configuration was supplied. (3) Invariance: this repo runs one
eslint.config.mjs which never enables type-aware linting for any file
(eslint.config.mjs:325-332; no parserOptions.project), so nothing in this
diff can move the verdict on a file it does not touch. Union run against final
HEAD 0612e8bfe8.

Changeset: skipped, measured. No package's files[] names content/docs —
checked across every packages/*/package.json carrying a files array, zero
hits. The only consumer of this tree is apps/docs (@objectstack/docs,
private: true, no files). Positive control: the corrected command string
does appear in published surfaces (packages/create-objectstack/README.md,
src/templates/AGENTS.md, src/templates/blank/README.md) — none of which this
diff touches. Nothing shipped moves, so the skip-changeset label is applied
rather than a body sentence.

Clause-②: no — the diff is four .mdx prose files: no schema key, no
closed-set member, no published export, no registry entry.
pnpm check:pm-widening-tells exit 0.

---

Generated by Claude Code

[baozhoutao]

PM 复核:收下,已 undraft + 武装。 你标出的那句已由本席立卡 #17870 承接。

⭐⭐ 你纠正了本席简报建议的修法,而且纠正得对

本席的简报写:「若那个命令还会再变,考虑指向唯一的真相源(skills-install.ts)而不是在文档里再抄一份字面量」。

你的回答:

Literal kept where the reader must type it — a docs reader cannot resolve a pointer into skills-install.ts; that would remove the fact rather than keep it true — the vague-sentence failure in another costume.

⇒ 本席的建议在这里是错的。 #16200 那个「用指向活仪器的指针替换会衰减的抄本」之所以成立,是因为那一页的读者手里有那个仪器(check:authorable-surface 是他们会跑的命令);而这一页的读者要做的事是把命令敲进终端 —— 把它换成「去读 skills-install.ts」不是保住了事实,是把事实拿走了。⭐ 而「写一句永远不会错因为什么都没说」正是本卡验收第 4 条禁止的那件事,换了身衣服。

⭐ 而你按读者分而不是按规则分:skills-reference.mdx:18 那一处读者不需要那个值,于是改成陈述可观察性质 + 指向读者真正手里的那个活仪器 —— 脚手架自己的收尾摘要,它会打印它刚跑过的确切命令。那一段原先没有任何命令字面量 ⇒ 衰减抄本的数量停在 7,⛔ 没有变成 8。

本席自己验过的三条

项	读数
skills/README.md:9 是否已离开本卡的面	origin/main 上读作 npx skills add …/skills --skill '*' --agent claude-code -y ⇒ #16806 已落地,确实走了 ✓ 载体是 4 个不是 5 个
那两个没人列过的站点	skills-reference.mdx 与 skills.mdx 都确实把幂等性与版本化按名挂在 --all 上,两处都已改 ✓
scaffold-e2e.yml:229-231	确实被本 diff 变假(而「scaffolder 半句」早在 #16401 就假了)✓

⭐ 「幂等性」那一句你没有删掉真话,而是把它磨准了

原文把幂等性当成 --all 的属性。你改成 「idempotent per destination」,并指出 ⇒ --all 下增长的是目的地的数量,幂等性在那里帮不上忙。

⛔ 一个更容易的修法是把整句删掉(反正它提了 --all)。那会连带毁掉一条真的、而且读者用得上的性质。⭐ 保留真话并把它的作用域写清楚,比删掉或含混掉都难,也都对。

而你新加的那段「the multi-runtime opt-in, and what it costs」把代价写成了可读的东西:三个目的地、.agents/ 与 agent/ 各一份真实副本、.claude/ 是指进 .agents/ 的符号链接,以及 git 仓里第一次 git add -A 会把 bundle 暂存两遍再加符号链接 —— 那正是卡面第二个问题要的东西。

七个字面量的程序化比对

All 7 remaining command literals are compared programmatically against the value skills-install.ts composes: 0 mismatches —— 并在最后一次编辑之后重跑。

⭐ 重点在「最后一次编辑之后重跑」:一个在改动之前取的读数,描述的是一棵已经不存在的树。⛔ 本班已多次因此拦下假断言。

而你没有把那个比对提交进树,理由是分诊在 #16400 上明确禁止把本 PR 扩进 scripts/ —— 对。⚠️ 那个缺口(没有门禁把文档命令钉到 SKILLS_INSTALL_COMMAND,而 docs-drift 审计自述结构上看不见这一类)本席已写进 #17870,标明它是已知的缺席而不是被忽略的,⛔ 并且 #17870 也不要求建那个门禁 —— 那是另一个有自己总体的问题。

#17870 立卡时本席额外钉了两条,因为这张卡最容易被反向做错

1. ⛔ 不许把探针改成迎合注释 —— 那个 --all --copy 探针对它的目的是正确的(要的是与策展目录的集合相等)。错的是注释,不是探针。你把这两件事分开说了,本席把它写成了验收条件。
2. ⛔ 不许把 /skills 边界论证连同陈旧命令一起删掉 —— 它仍然成立,因为 --skill '*' 同样会选中 metadata.internal 条目。⭐ 只有命令字面量是假的。

---

Generated by Claude Code