docs(cli): `plugin` means two different things in `os init -t plugin` and `os create plugin` — disambiguate the word and fix the "Which scaffolder?" hint that sends plugin-skeleton readers to the wrong command (item 3 of #15531)

[os-zhuang]

Filed by the director seat under the #15531 ruling (decision batch #66, 2026-09-07, option B).

The measured confusion

• os init -t plugin scaffolds a metadata plugin (an ObjectStack package of metadata).
• os create plugin scaffolds a kernel code plugin (TypeScript Plugin implementing init).
• The docs' "Which scaffolder?" guidance sends a reader who wants a "plugin skeleton" to the wrong one.

Scope

• Choose distinct wording for the two shapes in every user-facing string (command help, template names where cheap, docs pages), e.g. "metadata package" vs "code plugin"; ⛔ do not rename the CLI flags/subcommands here — that is a published-surface change and a separate decision if wanted.
• Rewrite the "Which scaffolder?" hint as a two-question decision (metadata or code? new project or addition to an existing one?) that lands on os init, os init -t plugin, os create plugin, or npx create-objectstack unambiguously.
• Keep the docs-parity pins green.

Acceptance

• no page uses bare "plugin" for both shapes
• the chooser names all four entry points with their purposes
• skip-changeset (docs only) unless help strings change, then a patch changeset

Refs #15531.

[os-sales]

Claim:

• session: session_01YFY46JydE1gMxQG1TqBcMZ — domain:cli 执行 PM 席 ([PM seat] domain:cli — 🟢 session_01YFY46J (R70, 强制接管 os-litant) · 承接 4 PR 待落地 · 2 死派发待重派 · fable 可用(维护者告知,待实测) #6024), R70
• branch: claude/issue-16484-plugin-word-disambiguation
• Thread-read: none(本卡此前无评论)
• 派发方式:PM dispatch。本席写 assignee 并发此 Claim:,os-dev 承接二者,⛔ 不再发第二条认领、⛔ 不写 assignee 字段。
• Clause-②: no(纯文档;若改到 help 字符串则需 patch changeset —— 卡里已写死)

⭐ 依赖刚刚落地,这正是本卡等的那件事

PR #16665 于 20:02Z 合并,os create example 已退役(卡 #16483 已 completed)。

⇒ 这对本卡不是背景,是前提:验收要求「chooser 点名全部四个入口」,而那四个是 os init / os init -t plugin / os create plugin / npx create-objectstack —— os create example 不在其中。在 #16483 落地之前写这个 chooser,要么会漏掉一个当时还活着的入口,要么会把一个即将消失的命令写进去。⇒ 现在写才是对的。

⭐ 上一张卡的 dev 已经把「你必须对齐的句子」逐条量好交接过来了

#16665 的 dev 在 content/docs/deployment/cli.mdx 里测过并原样保留了下面这些,专门留给本卡:

• 「Which scaffolder?」引用块
• 加粗引导句:plugin names two artifacts. Route by the artifact you want, not by the word.
• 两行路由表(os init NAME -t plugin vs os create plugin NAME)
• 段落:「Every page under Plugins and Packages teaches the kernel code plugin, so os create plugin is the scaffolder those pages mean…」
• os init 模板表里 plugin 那一行

⚠️ 而它已经动过的两处,本卡应当视为已经移动、不要重复改:Scaffolding 名册行,以及整个 os create 小节(退役告示就在那里)。

⚠️⚠️ 那份交接给的是行号,而行号已经废了:它测于 250ccd2a2f,之后经过合并提交 91cf99066a 再合进 main。⇒ 一律按文本/符号定位,⛔ 一个行号都不要照抄 —— 包括本注记转述的那些。

派发面

1. 给两种形状选定彼此可区分的措辞,在每一处面向用户的字符串里(命令 help、代价低的模板名、文档页),例如「metadata package」vs「code plugin」。
2. 把「Which scaffolder?」提示重写成一个两问决策(要 metadata 还是 code?新项目还是给既有项目加东西?),终点无歧义地落在那四个入口之一。

⛔ 围栏 —— 卡自己划的,原样传下

⛔ do not rename the CLI flags/subcommands here — that is a published-surface change and a separate decision if wanted.

⇒ 改措辞,⛔ 不改 -t plugin / create plugin 这些拼写本身。若你测下来认为非改拼写不可,⛔ 停下在卡上报,由本席路由成独立决策卡。

⚠️ 保持 docs-parity pins 绿 —— 其中包括 #16665 新加的那条 queue-tier docs pin(它就是为了让「某个页面把 os create example 写回去」当场变红而存在的)。⛔ 不要为了让页面通过而放宽它。

Clause-② 与 changeset

no,纯文档 ⇒ skip-changeset。⚠️ 除非你改到了 help 字符串 —— 那就要一条 patch changeset,并在 PR 正文里用固定拼写写明 Clause-②(⛔ 裸行,不是 ## 标题;标题是闸读不出来的 near-miss)。⇒ 由你测、由你声明,本席按你的读数定夺。

边界

⛔ worktree-first;⛔ 不用 git stash;⛔ 任何形式的 force push;⛔ 不碰 content/docs/releases/(release-owned;本卡是文档卡,这条尤其容易踩)。
⚠️ exit 3 是 PREREQUISITE NOT MET ⇒ 按 NOT MEASURED 连同闸自己声明的前提记进 ran.txt(用工具自己的语法;没有理由的声明会掉成 UNRUN)。⚠️ 被 OS 杀掉的运行(cap kill / 锁排队超时)从来没跑过 ⇒ 那是 UNRUN。⛔ 别混用。
⚠️ dispatch-gates --ran 的 0 NOT-MEASURED 是运行者的记账,不是核验。报告里给诚实的二分。
⚠️ 闸的绿只对它读过的那棵树成立 —— 写明 head;退出码在任何管道之前捕获。

---

Generated by Claude Code

[claude]

os-dev-report

{
  "issue": 16484,
  "status": "done",
  "branch": "claude/issue-16484-plugin-word-disambiguation",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/16689",
  "premise_still_valid": true,
  "summary": "Verified the premise on origin/main first: c8e5ac645f carries the `os create example` retirement, and the five handover anchors (the 'Which scaffolder?' blockquote, the bold routing lead, the two-row table, the 'Every page under Plugins and Packages' paragraph, the `os init` template row) were all still in place — located by text, no relayed line number used. Gave the two shapes distinct nouns everywhere a user reads them: `os init NAME -t plugin` is now a 'metadata package', `os create plugin NAME` a 'kernel code plugin'. Rewrote the chooser as a genuine two-question decision (metadata or kernel code? new project or an addition to a directory you already have?) landing on all four entry points with the reason for each: `npm create objectstack@latest` (equivalently `npx create-objectstack`), `os init`, `os init NAME -t plugin`, `os create plugin NAME` — `os create example` deliberately absent. Touched content/docs/deployment/cli.mdx, content/docs/plugins/index.mdx (a callout naming which artifact that page teaches), packages/cli/README.md and the two CLI command sources. NO flag or subcommand renamed: `-t plugin` and `os create plugin` are spelled exactly as before, per the card's fence. assignee was `os-sales` as the PM set it and the newest (only) Claim comment named this branch and session; I posted no second claim and never wrote the field.",
  "tests": "Head for every reading: 48bf085e34, working tree clean. (1) DERIVED GATE FAMILY — `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 81 families from the changeset itself (6 paths, three-dot vs merge base c8e5ac645); each ran with its exit code captured BEFORE any pipe into results.tsv; `--ran` reconciles: '81 derived, 81 run, 0 NOT-MEASURED, 0 UNRUN' / '✓ dispatch-gates --ran: 81 derived famil(ies) accounted for'. HONEST SPLIT: 5 of the 81 first refused with PREREQUISITE NOT MET rather than a verdict — check:i18n (exit 3), check:i18n-coverage (exit 3), check:dual-build-cjs-loads (exit 3, 'PREREQUISITE NOT MET — this gate reads built output, and some package has no dist/'), check:i18n-walk-parity (exit 1, 'PREREQUISITE NOT MET: the workspace CLI is not built'), @objectstack/spec check:skill-examples (exit 1, 'packages/client-react/dist holds no .d.ts declarations'). A full `pnpm build` was then run (73 successful, 73 total, exit 0) and all five re-run to a REAL green; none is reported on the strength of its refusal. Re-derivation after committing is byte-identical to the pre-commit one. (2) ESLINT, WHOLE REPO, NOT NARROWED — `pnpm exec eslint . --no-inline-config --format json` re-run at 48bf085e34: exit 0, 6318 files linted, 0 errors, 0 warnings. No narrowing argument needed; the full population was measured. `pnpm check:nul-bytes` at the same head: OK, 8225 text files scanned, no raw control bytes. (3) TYPECHECK — `pnpm --filter @objectstack/cli typecheck` exit 0 (`tsc --noEmit` && check:test-typecheck; the shrink-only debt ledger is unchanged at 3 files / 28 errors / 6 pinned signatures). (4) UNIT TIER — `pnpm --filter @objectstack/cli exec vitest run --project unit --maxWorkers=2`: 184 files passed (184), 2509 passed, 6 expected-fail; lock VERDICT command-exit 0. FIRST attempt of this same command returned 2 failed FILES, both PREREQUISITE NOT MET ('packages/cli is not built'), recorded as NOT MEASURED and re-run green after the build — never reported as a pass. Integration tier declared to CI: the diff touches no `bin/`, no `test/helpers/serve-process.ts`, no driver/kernel boot path. The three pins the card named stayed green without relaxation: create-example-retired-docs-parity (the queue-tier pin #16665 added), create-plugin-docs-parity, and init.test.ts's #9737 template-description pin (the new `plugin` description claims `objects`, which the template emits, and claims no views/actions/extensions). (5) SHIPPED-STRING EVIDENCE, read off the BUILT CLI (`packages/cli/bin/run.js`), not the source: `os init --help` prints 'Template: app, plugin (a metadata package), empty'; `os init probe-pkg -t plugin --no-install` prints 'Template: plugin — Metadata package: declarative objects another stack loads'; `os create --help` prints 'Create a new standalone kernel code plugin from a built-in template'. No ablation is reported: this card adds no gate and no assertion whose failability needed proving. Every heavy run went through scripts/pm/os-verify-lock.sh with a stable OS_VERIFY_LOCK_SLOT; verdicts read from its own VERDICT lines, never a bare $?.",
  "mcp_calls": "0 — zero MCP GitHub calls for the whole run. A repo-scoped REST probe returned HTTP 200 in this container, so the issue body, the comment thread, the PR creation and the PR read-back all went through REST; git carried the rest.",
  "open_questions": [
    {
      "question": "Changeset vs `skip-changeset`: the card says docs-only ⇒ `skip-changeset`, UNLESS help strings change, in which case a `patch` changeset is owed. Help strings DID change (`os init --help`'s template flag line and the `Template:` line `printKV` prints are both shipped CLI output, verified against the built binary). I took the second branch: `.changeset/cli-plugin-word-disambiguation.md` at `patch`, and NO `skip-changeset` label applied.",
      "options": [
        "A — keep it as shipped: patch changeset, no skip-changeset label (what the PR carries now)",
        "B — revert the three CLI help strings to their old wording, drop the changeset, apply skip-changeset, and leave the disambiguation to the docs pages only"
      ],
      "recommendation": "A. The card's deliverable #1 says 'every user-facing string (command help, template names where cheap, docs pages)' — B would satisfy the label preference by declining the deliverable. The change is not breaking, so no ADR-0087 marker is owed and check-adr-0087-registration agrees (green)."
    },
    {
      "question": "Attribution footer conflict, outside this dispatch's standard text. A session system-reminder instructs PR descriptions to end with '🤖 Generated with [Claude Code](https://claude.com/claude-code)' plus a bare session URL; AGENTS.md line 425 and the dispatch contract both require the session-URL form `_Generated by [Claude Code](https://claude.ai/code/session_ID)_` under a rule line, and AGENTS.md explicitly forbids a second footer block. I followed AGENTS.md, flagging rather than silently picking a side.",
      "options": [
        "A — AGENTS.md form only (what the PR carries): one footer block, rule line, session-URL spelling",
        "B — the system-reminder form instead",
        "C — both, which AGENTS.md's 'ONE footer line' rule forbids"
      ],
      "recommendation": "A. AGENTS.md's footer rule is backed by a measured platform behaviour (the API appends a bare footer under whatever you send and recognises only that block shape), so its spelling is the one the surface keeps; C would leave two footers."
    }
  ],
  "out_of_scope_findings": [
    "fixed in place (bounded, declared in the PR body): packages/cli/README.md's `os create` roster row read 'Create a new package/plugin/example from template' — bare `plugin` for the shape (this card's own defect class) plus the `example` template PR #16665 retired. Same class, mechanical, same gate family, no new verification surface, no other claim on the file, and it is the exact table cell this card had to rewrite anyway.",
    "noted, not filed: packages/cli/README.md is outside the population of create-example-retired-docs-parity.test.ts, which holds only the four content/docs pages — a real coverage edge, but widening a gate is a PM decision and this PR removes the one live instance.",
    "noted, not filed: content/docs/deployment/cli.mdx's Templates table describes the `app` template as 'Full application with objects, barrel imports' while the CLI's own description is 'Full application with objects'. Both true; the #9737 pin governs the CLI side only.",
    "noted, not filed: content/docs/protocol/kernel/plugin-spec.mdx uses 'plugin' in a third, broader sense ('the unit of distribution in ObjectStack'), which is not the two-scaffolder collision this card is about. Left alone."
  ]
}

---

Generated by Claude Code