@@ -18,17 +18,20 @@ The catalog ships as the npm package [`@objectstack/skills`](https://www.npmjs.c
 
 ```bash
 # 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')`.
+
 Step 2 is the [skills CLI](https://www.npmjs.com/package/skills)'s sync from `node_modules`: it finds the skills under `node_modules/@objectstack/skills/dist/skills/`, copies each one into your agent's directory — for `claude-code`, real files in `.claude/skills/<skill>` and nowhere else — and records the source and version in `skills-lock.json`. Commit both with the project. Keep `--copy`: without it the sync writes links into `node_modules`, which is not committed, so a clone of the project gets dangling links and no skills. The CLI is pinned because `experimental_sync` is that tool's own unstable interface; `create-objectstack` runs the same version. Name your own runtime after `--agent` (`codex`, `cursor`, …), one runtime per run — never `--agent '*'`, which copies the catalog into dozens of agent directories at once. A bare `npm install --save-dev @objectstack/skills` installs whichever version the registry tags `latest`, not your spec's — keep the version in step 1.
 
 **Updating.** The catalog is versioned as **one bundle**, and it moves only with your ObjectStack version — you never track or update a skill on its own: bump `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the sync (step 2, same flags) and commit what it changed.
 
-**Which versions exist.** `@objectstack/skills` is published from `18.0.0-next.0` on; there is no 17.x release of it. A project on `@objectstack/spec` 17.x therefore has no catalog bound to its version: step 1 refuses with `ETARGET` (`No matching version found`), and moving it to 18 includes [a skills step](/docs/upgrading#moving-the-dependency-pins). One scaffolder is the exception to the next paragraph: `create-objectstack@18.0.0-next.0` still installed the skills from the repository's `main` with `skills add`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … installed with skills add` and exits 0), so in a project it scaffolded run `npx skills remove --all` — or remove the `objectstack-*` skills by name, as the [upgrade step](/docs/upgrading#moving-the-dependency-pins) does, if you added others — and then steps 1 and 2.
+**Which versions exist.** `@objectstack/skills` is published from `18.0.0-next.0` on; there is no 17.x release of it. A project on `@objectstack/spec` 17.x therefore has no catalog bound to its version: step 1 refuses with `ERR_PNPM_NO_MATCHING_VERSION` (npm: `ETARGET`; both print `No matching version found`), and moving it to 18 includes [a skills step](/docs/upgrading#moving-the-dependency-pins). One scaffolder is the exception to the next paragraph: `create-objectstack@18.0.0-next.0` still installed the skills from the repository's `main` with `skills add`, and step 2 skips every skill a `skills add` installed (it prints `Skipped … installed with skills add` and exits 0), so in a project it scaffolded 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 remove those by name, as the [upgrade step](/docs/upgrading#moving-the-dependency-pins) does, if you added others — and then steps 1 and 2.
 
 **New projects.** `create-objectstack` runs both steps while it scaffolds: the `package.json` it writes depends on `@objectstack/skills` at the same version as `@objectstack/spec`, its dependency install puts the catalog in `node_modules`, and step 2 copies it for one agent runtime, into `.claude/skills/`. Its closing summary prints step 2 again — to re-run after an upgrade, and with another `--agent` for any other runtime you use.
 
 
@@ -29,10 +29,13 @@ See [Agents](/docs/ai/agents#you-extend-the-platform-with-skills-not-agents) for
 Skills ship as the npm package `@objectstack/skills`, released with the other `@objectstack/*` packages at one shared version. Install it at your installed `@objectstack/spec`'s version — the catalog's version is then your spec's — and copy it from `node_modules` into your agent's directory, the two steps `create-objectstack` runs when it scaffolds a project:
 
 ```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
 ```
 
+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')`.
+
 The skills land as real files in `.claude/skills/`; commit them with the project, and keep `--copy` — without it they are links into `node_modules`, which a clone does not have. Name your own runtime after `--agent` (`codex`, `cursor`, …). The catalog is versioned and updated as **one unit**, with ObjectStack itself: 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); for what the sync writes, the versions, the one scaffolder that is an exception and the `next` channel, see the [AI Skills Reference](/docs/ai/skills-reference#installing-skills).
 
 ---
 
@@ -108,10 +108,14 @@ command for this move; it is four steps you run yourself.
    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
    ```
 
+   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')`.
    The list names every skill the catalog carried during 17.x, and a name that
    is not installed is skipped; `npx skills remove --all` does the same when
    these are the only skills the project has. Run `npx skills list` first: