@@ -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.
@@ -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
 
 
@@ -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
 
@@ -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