docs(skills): give the @objectstack/skills install line for the project's own package manager (#25023)

Fixes #24974
Clause-②: no

## What changed

The published `@objectstack/skills` README (the npm page and tarball
text), the catalog's front page (`skills/README.md`, shipped as
`dist/skills/README.md`) and the `objectstack-upgrade` skill's
re-install step each printed `npm install --save-dev
"@objectstack/skills@$(node -p …)"` as the only install line. In a
pnpm-installed project that line exits 1 with `npm error Cannot read
properties of null (reading 'edgesOut')` and writes nothing, and
`create-objectstack` installs with pnpm when it is available. Each site
now carries the shape PR #24973 gave `content/docs/**` (merged as
`3a7a60af8`): the pnpm line in the block, one comment line with the npm
and yarn spellings, and the rule "add the package with the manager that
installed the project".

| site | old → new | notes |
|:--|:--|:--|
| `packages/skills/README.md`, step 1 (was L28) | `npm install
--save-dev "…"` → `pnpm add -D "…"`, plus the npm/yarn comment line,
plus the rule paragraph with the measured npm error | the npm page;
patch changeset `.changeset/24974-skills-install-line.md` (`README.md`
is in the package's `files`) |
| `packages/skills/README.md`, "Keep the version in step 1" (was L40) |
the bare spelling it warns about is now `pnpm add -D
@objectstack/skills`, the manager step 1 prints | same sentence, same
warning |
| `packages/skills/README.md`, "Which versions exist" (was L49) |
`ETARGET` → `ERR_PNPM_NO_MATCHING_VERSION` (npm: `ETARGET`; both print
`No matching version found`) | step 1 is pnpm now, so the npm-only code
would have become a false statement this PR introduced; the docs' exact
wording (PR #24973, M5) |
| `packages/skills/README.md`, scaffolded projects (was L54) | `npx
skills list` first, because `npx skills remove --all` removes every
installed skill without asking | the card's second "Wanted" line; H2's
only shipped hit |
| `skills/README.md` (was L11) | pnpm line plus the comment line; the
rule sentence opens the next paragraph in its short form, without the
error text, because the page already defers every detail to the Skills
reference | governed, Tier H; net +3 lines |
| `skills/objectstack-upgrade/SKILL.md`, re-install step (was L129) |
pnpm line plus the comment line; the step's own sentence carries the
rule ("with the manager that installed the project"); the `--all`
shortcut leaves the prose | governed, Tier H; net −1 line; the token
ratchet is paid in the same file (H3) |

No other shipped page prints the npm-only line: `git grep -n "npm
install --save-dev" origin/main` hits the three sites above, the
`content/docs/**` pages PR #24973 and PR #24922 already changed, and two
release-owned `CHANGELOG.md` files a code PR never edits.

## H1 to H4, measured

- **H1 holds.** On `origin/main` `62bc12930`:
`packages/skills/README.md:28` and `:40`, `skills/README.md:11`,
`skills/objectstack-upgrade/SKILL.md:129` all carried the npm-only line.
- **H2 holds, one site.** `git grep -n "skills remove --all" origin/main
-- skills/ packages/skills/` hits `packages/skills/README.md:54` and the
release-owned `packages/skills/CHANGELOG.md` only. The upgrade skill
named `--all` as a prose alternative beside its by-name command, never
as a printed `npx skills remove --all` (see H4).
- **H3: every skills gate green; the ratchet had 16 tokens of headroom,
not zero.** `check-skills-token-ratchet` reads
`skills/objectstack-upgrade/SKILL.md` at 6172 / 6188 before and 6171 /
6188 after. The ledger: the comment line (+109 bytes) and the rule
clause (+44), less the shorter prefix (−11), the dropped `--all` clause
(−52) and one deleted sentence in § 2.1 (−96): "Their consumer-facing
projection is `spec-changes.json` and the chain's own `--json` output",
which restated the table two paragraphs above it (its "Chain result" and
"D4 projection" rows). `skills/README.md` is outside the ratchet's
population by construction (population 3 in its header).
`check:skill-docs`, `check:skill-compatibility`,
`check:skill-identifier-liveness`, `check:skill-frame-sync`,
`check:published-files`, `check:doc-authoring`,
`check:pm-skill-id-lint`, `check:closed-ceremony-text` all exit 0 on
`f0b0ddc2d`.
- **H4: the docs' shape, with the rule in the step's own sentence.** The
sentence an agent reads before it copies the block now ends "add
`@objectstack/skills` at the installed spec's version with the manager
that installed the project, copy it:", and the block's comment line
gives the npm and yarn spellings as a prefix swap on an identical
argument. The one silent wrong path is running `pnpm add` in an npm or
yarn project, and the sentence closes it; a literal copy of the
comment's `@…` fails loudly (`No matching version found`), never
silently. A three-line form (one full line per manager) was weighed and
dropped: two more lines and about 50 more tokens than the file has
headroom for, bought for a substitution an agent already makes. The
`--all` shortcut leaves the prose because the by-name command the block
prints is always safe (a missing name is skipped), while `--all` needs
the judgment the docs now guard with `npx skills list`: one command, no
branch.

## Line budget: `skills/**`, +4 allowed

| file | + / − | net |
|:--|:--|:--|
| `skills/README.md` | +11 / −8 | +3 |
| `skills/objectstack-upgrade/SKILL.md` | +6 / −7 | −1 |
| **total** | | **+2** |

`git diff --numstat 62bc129 --
skills/`. The lines were paid for by deleting content (the § 2.1
sentence and the `--all` clause), not by re-wrapping.

## Tests and gates

All readings on `f0b0ddc2d`, this PR's only commit; exit codes captured
before any pipe.

- `bash scripts/pm/os-verify-lock.sh -c
'NODE_OPTIONS=--max-old-space-size=4096 pnpm --filter @objectstack/spec
build'` (what `check:skill-docs` reads): `VERDICT command-exit 0 · held
the lock 94s · waited 0s`.
- `pnpm --filter @objectstack/skills build` (sync-catalog, byte-equality
against `skills/**`): exit 0. The package declares no `test` or
`typecheck` script.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` (no paths, change set from the merge base):
71 commands; every one run; `--ran` verdict: `71 derived famil(ies)
accounted for — 68 run, 3 NOT-MEASURED (3 DERIVED from a recorded exit
3)`.
- `node scripts/check-skills-token-ratchet.mjs`:
`skills/objectstack-upgrade/SKILL.md is 6171 tokens (ceiling 6188;
headroom 17)`; `54 authored bundle file(s) within their ceilings`.
- `pnpm --filter @objectstack/spec run check:skill-docs`: `✓
skills/README.md`, exit 0. `pnpm check:doc-authoring`: `53 published
skill files clean`, exit 0. `pnpm check:published-files`: exit 0. `pnpm
check:skill-identifier-liveness`: `457 citation(s) over 53 published
file(s)`, exit 0.
- `grep -naP` for control characters over the four files: none.
- No ablation: the diff changes prose and a changeset, no tested
behaviour.

## Acceptance notes

- Base `62bc12930`; `origin/main` moved to `05b28c199` (4 commits)
during the run, none touching `packages/skills/`, `skills/` or
`.changeset/`; not merged (no conflict, no main-red; the merge base is
unchanged).
- Three derived gates are NOT MEASURED locally (exit 3, `PREREQUISITE
NOT MET`: unbuilt packages this diff never touches,
`@objectstack/formula`, `@objectstack/objectql`, and the apps/adapters
`dist/`): `check:doc-formula-expressions`, `check:dual-build-cjs-loads`,
`check:lean-entry-closure`. None reads the four files here; CI's `Lint &
Repo Gates` is their reading.
- `check-plugin-teardown-shape --self-test` refused once on the shallow
clone (its fixture is pinned to `621a48760`); deepened to that commit
and re-run: `48 cases pass`, exit 0.
- Out of scope, noted and not filed: `packages/skills/CHANGELOG.md` and
`packages/create-objectstack/CHANGELOG.md` print the npm-only line
inside released entries; both are release-owned, so a correction would
be a dedicated docs-only PR. Carrier: none.

## 维护者速读(草稿)

**改了什么。** 三处面向客户的安装说明(npm 包页 README、技能目录首页 README、升级技能里的重装步骤)原本只给 `npm
install --save-dev …` 这一行;现在改为给 pnpm 的那一行,旁边一行注释列出 npm 与 yarn
的拼法,并写明规则「用安装这个项目的包管理器来加包」。npm 包页另外把 17.x 项目的报错码补上 pnpm 的那个,并在 `npx
skills remove --all` 之前加上 `npx skills list`。附一条 `@objectstack/skills` 的
patch changeset。

**为什么改。** `create-objectstack` 有 pnpm 就用 pnpm 装项目,所以脚手架出来的项目大多是 pnpm
项目;在这种项目里照抄原来那一行会直接报错退出(实测 exit 1,`edgesOut`),什么也装不上。文档站的三页上一轮已改(PR
#24973),这三处是同一问题剩下的、归本车道(受管面与 npm 包页)的行。

**风险与代价(含回滚)。** 纯文字改动,不碰代码、不加门禁。代价:`skills/**` 两个文件合计净 +2 行(预算
+4);升级技能文件的 token 棘轮 6171/6188,靠删掉 §2.1 一句与上方表格重复的话付账,无信息损失。风险:注释行里的
`@…` 若被逐字照抄会报「找不到版本」,是响亮失败不是静默错装。回滚:revert 本 PR 唯一的一个 commit
即可,无状态、无生成物。

**席位意见。**

**你要做的。** 一个动作:在本 PR 上给出 APPROVED review(`skills/**` 是 Tier H
受管面),席位随后落地。

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

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

Author: objectstack-fleet[bot]

.changeset/24974-skills-install-line.md

@@ -0,0 +1,12 @@
+---
+'@objectstack/skills': patch
+---
+
+docs(skills): the npm page and the catalog's front page give the install line for the project's own package manager
+
+Clause-②: no
+
+`README.md` (the npm page) and `dist/skills/README.md` (the catalog's front page, copied from the repository's `skills/README.md`) printed `npm install --save-dev "@objectstack/skills@$(node -p …)"` as the only install line. In a pnpm-installed project that line exits `1` with `npm error Cannot read properties of null (reading 'edgesOut')` and writes nothing, and `create-objectstack` installs with pnpm when it is available, so a scaffolded project is commonly a pnpm project.
+
+- **Both pages** now print `pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"`, with the npm and yarn spellings on a comment line beside it, and the rule: add the package with the manager that installed the project. The `objectstack-upgrade` skill's re-install step, which an agent follows for this exact move, prints the same line.
+- **The npm page** names pnpm's `ERR_PNPM_NO_MATCHING_VERSION` beside npm's `ETARGET` for a project on `@objectstack/spec` 17.x, and runs `npx skills list` before `npx skills remove --all`, which removes every installed skill without asking.

packages/skills/README.md

@@ -25,34 +25,42 @@ agent's own skills directory (`.claude/skills/` for Claude Code, and so on):
 
 ```sh
 # 1 · the catalog, at the version of your installed @objectstack/spec
-npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+#   npm: npm install --save-dev "@objectstack/skills@…"   ·   yarn: yarn add -D "@objectstack/skills@…"
 
 # 2 · copy it from node_modules into your agent's skills directory
 npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
+Add the package with the manager that installed the project: in a pnpm project,
+`npm install --save-dev` exits `1` with
+`npm error Cannot read properties of null (reading 'edgesOut')`.
+
 `experimental_sync` discovers the skills at `dist/skills/<skill>/SKILL.md` of
 every dependency and copies each one into the named agent's skills directory
 as real files, recording the source in `skills-lock.json` (`--agent <name>`
 names the runtime — `codex`, `cursor`, …). Keep `--copy`: without it the sync
 writes links into `node_modules`, which a clone of the project does not have;
 the CLI is pinned to the version `create-objectstack` runs. Keep the version
-in step 1: a bare `npm install --save-dev @objectstack/skills` installs
-whichever version the registry tags `latest`, not your spec's.
+in step 1: a bare `pnpm add -D @objectstack/skills` installs whichever version
+the registry tags `latest`, not your spec's.
 
 **Updating.** The catalog moves only with your ObjectStack version: bump
 `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the
 sync (step 2, same flags).
 
 **Which versions exist.** The package is published from `18.0.0-next.0` on;
 there is no 17.x release of it, so on a project whose `@objectstack/spec` is
-17.x step 1 refuses with `ETARGET` (`No matching version found`).
+17.x step 1 refuses with `ERR_PNPM_NO_MATCHING_VERSION` (npm: `ETARGET`; both
+print `No matching version found`).
 
 **Projects scaffolded by `create-objectstack`.** Through `18.0.0-next.0` the
 scaffolder installs the skills from the `next` channel below with `skills add`,
 and step 2 skips every skill a `skills add` installed (it prints `Skipped …
-installed with skills add`). Remove them first — `npx skills remove --all`, or
-name the `objectstack-*` skills if you added others — then run steps 1 and 2.
+installed with skills add`). Run `npx skills list` first, because
+`npx skills remove --all` removes every installed skill without asking: run that
+when the list shows only the `objectstack-*` skills, or name those if you added
+others — then run steps 1 and 2.
 
 ## The `next` channel
 

skills/README.md

@@ -8,17 +8,20 @@ They ship as the npm package `@objectstack/skills`, released with the other
 copy it from `node_modules` into your agent's directory:
 
 ```bash
-npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+#   npm: npm install --save-dev "@objectstack/skills@…"   ·   yarn: yarn add -D "@objectstack/skills@…"
 npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
-Keep `--copy`: the skills land as real files in `.claude/skills/`, to commit with
-the project; without it they are links into `node_modules`, which a clone does
-not have. Name your own runtime after `--agent` (`codex`, `cursor`, …). To update,
-bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run
-the sync. The package is published from `18.0.0-next.0` on (there is no 17.x
-release); scaffolded projects, the move from a `skills add` install and the rest
-are in the [Skills reference](https://objectstack.ai/docs/ai/skills-reference#installing-skills).
+Add the package with the manager that installed the project: in a pnpm project,
+`npm install --save-dev` exits `1`. Keep `--copy`: the skills land as real files
+in `.claude/skills/`, to commit with the project; without it they are links into
+`node_modules`, which a clone does not have. Name your own runtime after
+`--agent` (`codex`, `cursor`, …). To update, bump `@objectstack/skills` with the
+other `@objectstack/*` packages, then re-run the sync. The package is published
+from `18.0.0-next.0` on (there is no 17.x release); scaffolded projects, the move
+from a `skills add` install and the rest are in the
+[Skills reference](https://objectstack.ai/docs/ai/skills-reference#installing-skills).
 
 **The `next` channel.** `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`
 reads the catalog straight from the repository's unreleased `main` — for trying

skills/objectstack-upgrade/SKILL.md

@@ -118,15 +118,16 @@ deleting them on merge, is the usual arrangement — decide it with the owner.
 
 A 17.x project's skills came from `skills add`; their `skills-lock.json` entries
 read `sourceType: github`, so the sync skips them (exit 0) and the agent keeps
-reading 17.x skill text. Remove them (a missing name is skipped; `--all` when
-they are the project's only skills), add `@objectstack/skills` at the installed
-spec's version, copy it:
+reading 17.x skill text. Remove them (a missing name is skipped), add
+`@objectstack/skills` at the installed spec's version with the manager that
+installed the project, copy it:
 
 ```bash
 npx skills remove objectstack-ai objectstack-api objectstack-automation \
   objectstack-data objectstack-formula objectstack-i18n objectstack-platform \
   objectstack-pm-dispatch objectstack-query objectstack-ui objectstack-upgrade -y
-npm install --save-dev "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+pnpm add -D "@objectstack/skills@$(node -p "require('@objectstack/spec/package.json').version")"
+#   npm: npm install --save-dev "@objectstack/skills@…"   ·   yarn: yarn add -D "@objectstack/skills@…"
 npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
@@ -253,9 +254,7 @@ upgrade and again in the report.
 > **Not reachable from a consumer project**, so do not send anyone there: the
 > conversion and migration registries (`src/conversions/registry.ts`,
 > `src/migrations/registry.ts`) and the platform repo's generated upgrade guide
-> are **not** in the published package — only `src/**/*.zod.ts` is. Their
-> consumer-facing projection is `spec-changes.json` and the chain's own `--json`
-> output.
+> are **not** in the published package — only `src/**/*.zod.ts` is.
 
 ### 2.2 The three residue classes