skills(objectstack-upgrade, catalog READMEs): the upgrade preflight re-installs the catalog from @objectstack/skills on a 17.x to 18 move; both READMEs give the scaffolder's pinned --copy sync

.changeset/23276-upgrade-skill-skills-step.md

@@ -0,0 +1,11 @@
+---
+"@objectstack/skills": patch
+---
+
+docs(skills): the upgrade skill's preflight re-installs the catalog from `@objectstack/skills` when a 17.x project moves to 18, and both READMEs give the scaffolder's pinned `--copy` sync (#23276)
+
+Clause-②: no
+
+`objectstack-upgrade`'s §0 Preflight gains one step for the skills themselves. A 17.x project's skills were installed with `skills add` from the repository's `main`; their `skills-lock.json` entries read `sourceType: github`, and `experimental_sync` skips them (it prints `Skipped … installed with skills add` and exits 0), so a project that only bumps its packages keeps its 17.x-era skill text. The step removes the eleven `objectstack-*` skills the catalog carried during 17.x (a name not installed is skipped; `--all` when they are the project's only skills), installs `@objectstack/skills` at the installed `@objectstack/spec`'s version, and copies it with `npx skills@1.7.2 experimental_sync --agent claude-code --copy -y` — the command `create-objectstack` runs. The step is paid under the token ratchet by deleting text the same file restates elsewhere; the ceiling is unchanged.
+
+`README.md` (the npm page) and `dist/skills/README.md` (the catalog's front page, copied from the repository's `skills/README.md`) replace the unpinned linked sync (`npx skills experimental_sync --agent claude-code -y`) with that pinned `--copy` spelling and say why: without `--copy` the sync writes links into `node_modules`, which a clone of a project that commits its skills does not have.

packages/skills/README.md

@@ -27,16 +27,18 @@ agent's own skills directory (`.claude/skills/` for Claude Code, and so on):
 # 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")"
 
-# 2 · link it from node_modules into your agent's skills directory
-npx skills experimental_sync --agent claude-code -y
+# 2 · copy it from node_modules into your agent's skills directory
+npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
 `experimental_sync` discovers the skills at `dist/skills/<skill>/SKILL.md` of
-every dependency and links each one into the named agent's skills directory
-(`--agent <name>` names the runtime — `codex`, `cursor`, …; `--copy` writes real
-files instead of links). 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.
+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.
 
 **Updating.** The catalog moves only with your ObjectStack version: bump
 `@objectstack/skills` with the other `@objectstack/*` packages, then re-run the

skills/README.md

@@ -5,18 +5,20 @@ working in **any ObjectStack app** — this monorepo *and* third-party projects.
 They 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
-sync it from `node_modules` into your agent's directory:
+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")"
-npx skills experimental_sync --agent claude-code -y
+npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
 ```
 
-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);
-`--copy`, projects scaffolded by `npm create objectstack` and the rest are in the
-[Skills reference](https://objectstack.ai/docs/ai/skills-reference#installing-skills).
+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

@@ -75,8 +75,6 @@ os migrate meta --from 17 --json # `applied` must be [] (see §3.3)
 # → write .upgrade/REPORT.md (template in §3.4)
 ```
 
-Everything below is the long form of those four steps.
-
 ---
 
 ## 0 · Preflight
@@ -102,8 +100,7 @@ one installed. Three sources, in order of authority:
 
 Arriving several majors late is the designed-for case: `os migrate meta --from 16`
 replays every step in order, with no requirement to upgrade one major at a time —
-down to the chain's support floor, 16 today. Below the floor, upgrade to it by
-the older route first, then run the chain.
+down to the chain's support floor, 16 today.
 
 ### Make the work reviewable before you change anything
 
@@ -117,6 +114,22 @@ The `.upgrade/` directory is the deliverable's workspace: the machine outputs
 and the human output (`REPORT.md`). Keeping them in the repo for the review, and
 deleting them on merge, is the usual arrangement — decide it with the owner.
 
+### Re-install the skills from the moved catalog
+
+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:
+
+```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")"
+npx skills@1.7.2 experimental_sync --agent claude-code --copy -y
+```
+
 ---
 
 ## 1 · Mechanical layer — invoke the chain
@@ -157,9 +170,6 @@ other with the reason it was not written, never writes a semantic change, and
 if re-running the chain over the written files disagrees, restores every file
 and exits 1.
 
-Porting the edits left unwritten is yours, one `conversionId` at a time; use
-`--out` as the oracle you diff against, never as the file you ship.
-
 ### Stored rows: rehydration replays the same conversions
 
 A deployment's `sys_metadata` rows are the other subject. They are handled for
@@ -318,16 +328,9 @@ os migrate meta --from 16 --json | node -e "
 grep -rn "<surface-token>" src/ app/ --include='*.ts' --include='*.tsx'
 ```
 
-Two traps that have cost real upgrades a lap:
-
-- **A renamed context field keeps compiling.** When a read moves from one key to
-  another and the old key is simply absent afterwards, the code reads
-  `undefined` and every branch quietly takes its false path. Verify against a
-  real dispatch, not a fixture — invoke the path and assert the value observed
-  under the canonical key.
-- **A rename is not always the fix.** If the old read was itself wrong, renaming
-  it migrates the defect rather than the code. Read the semantic entry's
-  `reason` before applying its `replacement`.
+One trap that has cost real upgrades a lap: **a rename is not always the fix.**
+If the old read was itself wrong, renaming it migrates the defect rather than
+the code. Read the semantic entry's `reason` before applying its `replacement`.
 
 ### 2.6 Working an R3 — the prose sweep
 
@@ -383,9 +386,7 @@ the author-time rule set. Read the two separately — a rule finding about a
 missing sharing model or an options-less choice field is a **pre-existing**
 project-quality issue, not upgrade residue. Establish which is which by running
 `os validate` **once before you start**, on the un-upgraded source, and keeping
-that output as the control. Fixing the project's standing lint debt may be a
-welcome side-effect, but it is not this upgrade, and it must not be reported as
-part of it.
+that output as the control.
 
 > ### ⚠ A green `validate` does NOT mean the chain has nothing left to do
 >
@@ -408,8 +409,6 @@ part of it.
 > build carries a step for, which is one PAST the installed major for most of a
 > release line, so `todos` carries the next major's semantic residue — real, but
 > not this upgrade's business.
->
-> Run both. A report that cites only `validate` cannot see this class at all.
 
 → Moved verbatim to [references/examples-upgrade.md](./references/examples-upgrade.md) § 3.4 The report — the human half.