@dextinity/agent-features 2.0.0-canary-20260729062014

package/skills/comet-major-migration/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: comet-major-migration
+description: Migrates a Comet project across a major version (e.g. v4 → v5, v5 → v6). Use when the user asks to upgrade Comet, follow a Comet migration guide, or bump @dextinity/* packages to a new major.
+---
+
+# Major Comet Version Migration Skill
+
+## When to use
+
+Upgrading `@dextinity/*` packages across a major version in a project (root, API, Admin, Site). A Comet major typically bundles breaking changes across React / Next.js / MUI X and may require updating peer/third-party packages.
+
+Do NOT use for minor or patch upgrades, or for ongoing feature work on a project already on the target major.
+
+## Locate the migration guide
+
+1. **Find out the target major** from the user if not specified.
+2. **Browse the index:** https://github.com/vivid-planet/comet/tree/main/docs/docs/7-migration-guide — use a GitHub MCP tool if available, otherwise `WebFetch`.
+3. **Download the raw Markdown** so all content is in context:
+    ```
+    https://raw.githubusercontent.com/vivid-planet/comet/refs/heads/main/docs/docs/7-migration-guide/migration-from-v{N}-to-v{N+1}.md
+    ```
+4. **If no guide exists** for the target version, stop and tell the user. Don't migrate without an official guide.
+
+## Choose the target version
+
+When bumping the `@dextinity/*` packages, **do not pin to `{N+1}.0.0`.** The `.0.0` release is rarely what you want — the new major accumulates bug fixes and patches after release. Bump to the **newest minor/patch release within the new major** instead.
+
+Find it with `npm view` (filter to the new major, drop pre-releases like `-canary`/`-beta`/`-rc`):
+
+```bash
+npm view @dextinity/cms-api versions --json | \
+  python3 -c "import json,sys; v=json.load(sys.stdin); \
+    stable=[x for x in v if x.startswith('{N+1}.') and '-' not in x]; \
+    print(stable[-1])"
+```
+
+Substitute `{N+1}.` with the target major (e.g. `9.`). Pin every core `@dextinity/*` package to that exact version — no caret or tilde. The migration guide's own examples may show `{N+1}.0.0`; treat those as illustrative and use the newest release instead.
+
+## Detect the project shape
+
+Before starting, figure out what's in this project. Comet projects vary — **anywhere between 0 and N sites is possible**:
+
+- **0 sites** — admin-only/headless. **Skip every site step in the guide** (package.json edits, codemods, config, verification). Don't treat the missing site as an error.
+- **1 site** — run the site section once.
+- **2+ sites** — **run the site section once per site.** Each site has its own `package.json`, etc. Skipping the duplicates is the most common multi-site migration miss.
+
+**Check whether the project has a page tree** (e.g. grep the admin source for its page-tree page like `PagesPage`, or the API for `PageTreeModule`). Skip page-tree-specific steps if it's absent.
+
+Sites can live under `site/`, `sites/<tenant>/`, or any custom path. Discover them by scanning `package.json` files for `@dextinity/site-nextjs`:
+
+```bash
+grep -l '"@dextinity/site-nextjs"' $(find . -name package.json -not -path '*/node_modules/*' -not -path '*/.next/*')
+```
+
+Record the resolved site list durably (e.g. a note on the first `TaskCreate` task) so every site-section pass references the same list. If empty, write "no site package — skip site sections".
+
+## Workflow
+
+1. **Read the guide end-to-end first.** Note every section, code change, codemod, and verification command. Breaking changes hide in sub-bullets.
+2. **Create tasks** with `TaskCreate` — one per major section. For the site section, create **one task per resolved site**, or skip site tasks if none. Mark `in_progress`/`completed` as you go.
+3. **Ensure a clean working tree.** Confirm with the user if not.
+4. **Work through the guide section-by-section, in order.**
+    - Apply every change in the section.
+    - **Site section: repeat every step once per resolved site.** Skip entirely if no site package.
+    - Run any codemods the section prescribes — they catch edge cases hand-fixing misses.
+    - Run any verification commands.
+    - **A green build is not proof a section is complete.** Hand-written types can mask a missing runtime change — a type that no longer matches a value's real shape (e.g. a synchronous type over what is now a `Promise`) lets `tsc` pass while the code breaks at runtime. When a guide step makes an API async or is otherwise runtime-only, scan **every** affected file in **every** site by hand instead of trusting `tsc`/lint to flag them.
+    - After each section: `npm run lint` (and `npm run test` if present) in the affected package. Multi-site: lint each site after its pass.
+    - **Commit after each section** with a message naming the section. For multi-site, either commit per-site or bundle the site section — pick one and be consistent.
+5. **Do not combine sections.** Keep commits separate to make bisecting trivial.
+
+## When the guide is unclear
+
+If a step is ambiguous or doesn't match the project, consult before guessing:
+
+- **https://github.com/vivid-planet/comet** — the monorepo. Check the source of the package the guide discusses for the new public API shape.
+- **https://github.com/vivid-planet/comet-starter** — the canonical reference project, always kept on the current major. Use it for questions like "how should `tsconfig.json` look after this migration?"
+
+Prefer the GitHub MCP; fall back to `WebFetch` on `raw.githubusercontent.com`. If still unclear, ask the user — don't guess.
+
+## When to stop and ask the human
+
+Stop immediately — don't work around — in any of these cases:
+
+- **`npm install` fails** (auth, peer-deps, sandbox-write, etc.). Hand the user the exact command and wait.
+- **A codemod fails** (panic, missing binary, transform error). Hand off the command.
+- **A shell command is blocked by the sandbox.** Hand off.
+- **A migration step references a file or symbol that doesn't exist.** Ask for clarification.
+
+**Commit signing failures are not a blocker.** If `git commit` fails with a signing error (1Password socket, GPG unavailable), retry with `--no-gpg-sign` and continue.
+
+After the user confirms, resume from the same step.
+
+## Final verification via clean subagent
+
+After the full migration is committed:
+
+1. Dispatch a fresh subagent (`Agent` tool, `general-purpose` or `Explore`) with no session context.
+2. Give it the migration guide URL and `git log main..HEAD`.
+3. Ask it to cross-reference: for every section/step, does a commit implement it? Report gaps or deviations.
+4. Review findings with the user and resolve.
+
+Example prompt:
+
+```
+The branch <branch> migrates this project from Comet v{N} to v{N+1}.
+The migration guide is at <raw-md-url>.
+
+For every section and sub-bullet in the guide, verify that a commit in
+`git log main..<branch>` implements the required change. Report every
+gap, skipped step, or deviation with the relevant file path and a
+quote from the guide. Report in under 300 words.
+```
+
+Running this fresh keeps the audit independent of the session that produced the changes.
+
+## Offer a smoke test
+
+Once committed and audited, **offer the user a smoke test**. Lint/tsc green is necessary but not sufficient — React/Next/MUI majors introduce dev-only warnings, hydration mismatches, silent routing breakage, and broken embedded webcomponents that only surface in the browser.
+
+Before starting, tell the user:
+
+- The smoke test drives admin and site(s) in a real browser via **Playwright MCP** (`browser_*` tools). Confirm MCP is available.
+- The **app must be running** — admin, api, codegens, and **every site service** all `Running` per `dev-pm status`. Multi-site projects run each site on its own port. Ask them to start whatever isn't running.
+
+The project shape was already detected (see [Detect the project shape](#detect-the-project-shape)). **Pass it to the subagent** rather than making it re-run discovery.
+
+If the user agrees and prerequisites are met, **dispatch the smoke test in a fresh subagent** (`Agent` tool, `general-purpose`) — the procedure walks dozens of routes per site and would burn the main session's context inline. The subagent gets the Playwright MCP tools automatically.
+
+Two things to substitute in the prompt:
+
+- The **absolute path** to `references/migration-smoke-test.md` inside this skill. The skill lives wherever Claude Code installed it (typically `~/.claude/skills/comet-major-migration/` or `<project>/.claude/skills/comet-major-migration/`). Resolve `references/migration-smoke-test.md` relative to the SKILL.md you're reading.
+- The **detected site list** with dev URLs, and **whether the project has a page tree** (see [Detect the project shape](#detect-the-project-shape)).
+
+```
+Run the smoke-test procedure defined in
+`<absolute path to references/migration-smoke-test.md within this skill>`
+against this project end-to-end. Read that file first, then execute the
+procedure (prerequisites, inventory, admin pass, site pass per site,
+triage).
+
+Sites (already detected — do NOT re-run the discovery grep):
+<e.g. "none — no site package, skip site pass" |
+"1 site at site/, dev URL http://localhost:3000" |
+"2 sites: sites/de/ at http://localhost:3000, sites/at/ at http://localhost:3001">
+
+Page tree: <present | not present>.
+
+Apply the site pass once per listed site (or skip if none).
+Run page-tree CRUD only if the page tree is present.
+
+Write findings to `test-report.md` at the repo root as you go — that
+file is the deliverable. When done, reply with a <200 word summary:
+how many routes/URLs you covered (per site if multi-site), the top 3-5
+findings by user impact, and whether anything blocked you. Don't paste
+the full report back; I'll read test-report.md directly.
+```
+
+When the subagent returns, read `test-report.md` and walk the top findings with the user.
+
+If the user declines, skip — the migration is otherwise complete.

package/skills/comet-major-migration/references/migration-smoke-test.md

@@ -0,0 +1,196 @@
+# Migration Smoke-Test
+
+Run after a major migration finishes (lint/tsc green, all commits pushed) to catch runtime regressions that lint and tsc can't see.
+
+## Project shape
+
+The dispatching prompt should tell you the project shape — the list of sites with their dev URLs/ports. **Use what's in the prompt; don't re-run discovery `grep`.**
+
+The dispatching prompt states the site list and whether a page tree is present. Decide each pass on its own signal:
+
+| Pass           | Run it when...                               |
+| -------------- | -------------------------------------------- |
+| Admin pass     | always                                       |
+| Page-tree CRUD | the prompt says a page tree is present       |
+| Site pass      | one or more sites are listed (once per site) |
+
+For multi-site projects, the site pass runs **once per site** — each has its own sitemap and regression surface. A Next.js major can break one site while leaving another working.
+
+Note the shape (verbatim from the prompt) at the top of `test-report.md` so the reader knows what was and wasn't covered.
+
+**Fallback if the prompt is missing this info:** scan `package.json` files for `@dextinity/site-nextjs` and flag the gap in your summary.
+
+```bash
+grep -l '"@dextinity/site-nextjs"' $(find . -name package.json -not -path '*/node_modules/*' -not -path '*/.next/*')
+```
+
+## Prerequisites
+
+1. **Services running.** `dev-pm status`; admin, api, and codegens must be `Running`. Site only matters if `@dextinity/site-nextjs` exists. Restart any that aren't.
+2. **Fixtures loaded.** `npm --prefix api run fixtures` — for projects with a page tree, this seeds the sitemap URLs. Re-run if the migration changed seed/slug logic.
+3. **Drive via Playwright MCP** (`browser_*` tools) so console errors are captured. `curl` is fine for HTTP-status sweeps but won't see hydration/DOM-prop errors.
+4. **Fresh repo-root `test-report.md` ready to write to.** Append findings as you go.
+
+## Inventory the surface
+
+Skip if the project already has an authoritative inventory file. Otherwise:
+
+- **Admin routes:** read `admin/src/common/MasterMenu.tsx` (or equivalent), list every `path:` entry, group by section.
+- **Admin grids/forms:** for each route, identify writable entities (Add/Edit/Delete) — those need a full CRUD pass.
+- **Site URL buckets** _(skip if no site package)_: fetch the site's `sitemap.xml` (find the dev URL/port it listens on via `dev-pm status`). Parse `<loc>` entries, classify into buckets by URL pattern.
+
+Keep inventory in scratch; don't write to `test-report.md` yet.
+
+## Admin pass
+
+For each admin route:
+
+1. `browser_navigate` to it.
+2. `browser_snapshot` to confirm rendering — `<main>` with content vs empty/error fallback.
+3. `browser_console_messages level=error` and `level=warning`. Record error/warning counts and one-line excerpts (~120 chars).
+4. For writable entities, run CRUD:
+    - **Add:** open form, fill required fields with `playwright-smoke-<timestamp>`. Save.
+    - **Edit:** change one field, save.
+    - **Delete:** remove the record. If no delete control, verify the underlying mutation works via console `fetch('/api/graphql', ...)` before declaring the API broken.
+    - If Save fails, capture the error and skip Edit/Delete to avoid half-state.
+
+### Page Tree CRUD is mandatory (when a page tree is present)
+
+**Skip if the project has no page tree** (the dispatching prompt says whether it does).
+
+Otherwise: the page tree exercises the most upstream code paths (block editor, RTE, file picker, page-tree GraphQL, route-tab navigation). Run a full Add → Edit → Delete on at least one page-tree category:
+
+1. Open the page tree in the admin (find it via the menu). Pick any category.
+2. **Add:** create a page, fill the required fields, save. Confirm the row appears and the URL is clean.
+3. **Edit:** open the page. **Walk every tab the page-edit view exposes.** Capture console after each tab switch. Change one field, save, reload, verify it persisted.
+4. **Delete:** remove the page and confirm the row is gone.
+
+If any step fails, that's a blocker for the PR.
+
+After the run, delete any test records (or note them in `test-report.md`).
+
+### Baseline errors
+
+A project may have a few errors that fire on _every_ admin page. Identify these once and call them "baseline" — count per-route errors _above_ baseline rather than reporting baseline N times.
+
+## Site pass
+
+**Skip this section entirely if no `@dextinity/site-nextjs` package.** Note "no site package, site pass skipped" in `test-report.md` and stop here.
+
+**For multi-site projects, run once per site.** Each has its own sitemap, routes, and regression surface. Sites typically expose themselves:
+
+- Each site config declares its `domains` (a main domain plus any additional ones). Locally these resolve to `localhost`, usually as distinct subdomains (e.g. `<site>.localhost:<port>`); check the site configs and `dev-pm status` for each site's dev URL.
+- Hit a specific site with its dev URL.
+
+Write per-site results under their own subheading (e.g. `### Site: <site-name> (<dev-url>)`).
+
+1. Fetch `sitemap.xml`, parse `<loc>` entries.
+2. **Bucket URLs** by pattern (locale-prefixed, fixture/scaffold, normal pages, ...). Some buckets need sampling; small ones can be exhausted.
+3. **Pick a seeded sample.** Common shape: 20 normal + all of any small bucket the user cares about. Use a deterministic shuffle for reproducible runs.
+4. For each picked URL: navigate, snapshot, collect errors/warnings.
+5. For high-volume buckets, **bulk-fetch HTTP status first**: `curl -s -o /dev/null -w "%{http_code}"` catches blanket 404s in seconds. Browser-walk 200s plus a handful of 404s to see the error page.
+6. **Bytes-check sitemap URLs with special characters.** If a `<loc>` contains `:`, `?`, `#`, `&`, or other RFC 3986 sub-delims, verify it resolves. Use `od -c` to confirm a colon is real, not a `&#58;` artifact.
+
+### Embedded webcomponents (high-risk)
+
+If the site embeds third-party **webcomponents** / micro-frontends — a block that loads an external `<script>` mounting a widget owned by another team — treat every page that renders one as high-risk and test each webcomponent **individually in the browser**.
+
+Webcomponents can crash at runtime while lint, `tsc`, and the build all pass.
+
+1. **Detect:** `grep -rnE "customElements|next/script|<script" site/src`, plus any block whose job is to embed an external widget.
+2. **Browser-test each webcomponent type** (not just each page): navigate to a page that renders it, confirm it actually **mounts and is interactive** — a 200 status or a rendered page shell is not enough — and capture console errors.
+3. A crash here is a **production blocker**, not a warning.
+4. Call out every webcomponent and its result explicitly in `test-report.md`, and tell the user to verify each one on staging **before deploying to production**.
+
+### Side effect of 404s
+
+Any URL that falls through to not-found may produce _additional_ errors from the not-found page itself. Don't count these against the per-URL budget — they're a single not-found bug surfacing N times.
+
+## Triage findings
+
+Apply one of three labels _while_ walking, not after:
+
+1. **Project-fixable** — broken code is under `admin/src`, `site/src`, `api/src`. Belongs in the migration PR or a follow-up.
+2. **Comet upstream** — broken code is under `node_modules/@dextinity/*`. Surface to the user; don't workaround.
+3. **Pre-existing / out-of-scope** — same warning pre-existed the migration. Note once at the bottom; don't itemize per-route.
+
+If you can't tell which bucket, grep for the symbol in the project source — if absent, it's upstream or a transitive dep.
+
+## Output: `test-report.md`
+
+Write findings to `test-report.md` at the repo root as you go. The file is the deliverable.
+
+```markdown
+# Smoke-test findings — <date>
+
+Tool: Playwright MCP (Chromium). Branch: `<branch>`.
+Sites detected: <none | list of site dirs + dev URLs>.
+Page tree: <present | absent>.
+Scope: <admin route count> admin routes; per site, <URL count> sampled from <total>.
+
+## TL;DR — biggest problems first
+
+<5–8 numbered bullets, ordered by user impact, each with file path or error excerpt>
+
+## Session-global console errors (every admin page)
+
+<the 0–2 baseline errors, called out once>
+
+## Admin
+
+### <route>
+
+- **Screen**: clean | "<visible error>"
+- **Console**: <n> errors, <m> warnings (above baseline)
+    - <one-line excerpt of each>
+- **CRUD** (if applicable): create/edit/delete: ok | failed (<why>)
+
+## Sites
+
+(One block per site. Skip the section entirely if no sites.)
+
+### Site: <site-name> (<dev-url>)
+
+#### Sampling
+
+- Sitemap total: <n> URLs in <bucket-count> buckets.
+- Sample: <breakdown by bucket>.
+
+#### Per-URL results
+
+<grouped by error class, e.g. "0 errors", "1 error — <error string>">
+
+## Hand off to Comet upstream
+
+<numbered list of upstream bugs with @dextinity/\* module paths>
+
+## Numbers
+
+- Admin routes visited: <n>. Broken: <n>. With extra console errors: <n>.
+- Site URLs sampled: <n total>. HTTP 200: <n>. HTTP 404: <n>.
+
+## Cleanup
+
+- Test records left in DB: <list or "none">.
+```
+
+Avoid one heading per URL when most look the same — group by failure mode. Five URLs with the same console warning are one finding with five examples.
+
+## Re-verify after fixes
+
+After the engineer fixes project-fixable findings:
+
+1. **Re-run failing scenarios in the browser** — not just the unit test. Green `tsc` doesn't tell you if the URL resolves.
+2. **For each "Fixed" item**: load a previously-broken URL, capture console, confirm the specific error string is gone. A different error could have replaced it.
+3. **Re-run fixtures if the migration changed seed/slug logic** before re-checking site URLs.
+4. **Bytes-check the sitemap** for previously-broken patterns (use `od -c`, not just `grep`).
+5. **Update `test-report.md`** with a "Fixed in this branch" section. Keep upstream/out-of-scope findings in place.
+
+Useful pattern: ask "commit each fix atomically?" before starting — answer is almost always yes — and re-run the smoke test after to confirm hooks didn't revert anything.
+
+## When to stop and ask the human
+
+- **Hundreds of URLs in a bucket all 404.** Route-group regression, not N bugs. Stop after the first 5–10 confirm the pattern.
+- **A console error mentions a file you can't locate** under `src/` or `node_modules/@dextinity/*`. Ask, don't guess.
+- **CRUD test fails with a 500 suggesting data corruption** (FK violation, dangling reference). Stop before continuing; test data may be polluting subsequent runs.
+- **Playwright MCP can't reach the dev server** (timeouts, ECONNREFUSED). Check `dev-pm status`; if everything is `Running` but unreachable, surface the discrepancy before random restart commands.

package/skills/comet-minor-update/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: comet-minor-update
+description: Performs a minor or patch version bump of all @dextinity/* packages across a Comet project (root, api, admin, and any site packages — zero, one, or many) to the newest version within the current major from npm, then installs. Use when the user asks to update Comet, bump Comet packages, do a minor Comet update, or upgrade Comet to the latest patch/minor of the current major.
+---
+
+# Comet Minor/Patch Update Skill
+
+A Comet project is not an npm workspace — the repo root, `api/`, `admin/`, and any site packages (zero, one, or many) each have their own `package.json` and `package-lock.json`. A minor or patch Comet update therefore means updating every occurrence of every `@dextinity/*` dependency across those files to the same new version, then running `npm install` in each directory so each lockfile picks up the new version.
+
+This skill covers **minor and patch** updates within the current major only (e.g. `8.20.4 → 8.21.0`). Major upgrades (e.g. `8.x → 9.x`) are different — they typically ship breaking changes, codemods, and migration guides, and are out of scope here.
+
+## Invariants
+
+Two rules hold across every `@dextinity/*` core package in the project, before and after the update:
+
+- **Pinned versions only.** Every core `@dextinity/*` entry must be an exact version (e.g. `8.21.0`), never a range (`^8.21.0`, `~8.21.0`, `>=…`). If you see a caret or tilde on a core package, the project is in a broken state — stop and tell the user.
+- **All core packages on the same version.** Every core `@dextinity/*` package in the project must be pinned to the same version across every `package.json`. There is no supported mix-and-match.
+
+These rules apply only to the core set (packages released together from the Comet monorepo). Satellite packages like `@comet/dev-process-manager` are out of scope — see Step 1.
+
+## When to use
+
+- "Do a minor comet update"
+- "Update comet" / "bump comet" / "update all comet packages"
+- "Upgrade to the latest patch of the current major"
+- "Update `@dextinity/cms-api` and friends to the newest 8.x"
+
+If the user asks for a **major** bump (crossing major versions), stop and tell them this skill only covers minor/patch updates.
+
+---
+
+## Workflow
+
+1. [Find all `@dextinity/*` dependencies and their current version](#step-1--find-all-comet-dependencies)
+2. [Find the newest version in the current major on npm](#step-2--find-the-newest-version-in-the-current-major)
+3. [Update every `package.json`](#step-3--update-every-packagejson)
+4. [Install](#step-4--install)
+5. [Verify](#step-5--verify)
+6. [Report the result](#step-6--report-the-result)
+
+---
+
+## Step 1 — Find all @dextinity dependencies
+
+The repo root, `api/`, and `admin/` always have a `package.json`. Site packages are variable: a project may have none (api/admin only), a single site at `site/`, or several sites — often under `sites/`, though the location is not guaranteed. Discover them by content rather than path — any `package.json` outside `node_modules` that depends on `@dextinity/site-nextjs` or `@dextinity/site-react` is a site package.
+
+```bash
+grep -rl --include='package.json' --exclude-dir=node_modules \
+  -E '"@dextinity/site-(nextjs|react)"' . | xargs -n1 dirname
+```
+
+Save the resulting list of site directories — Steps 3, 4, and 5 reuse it. **A project with no site packages is valid** — the grep returns nothing and the rest of the workflow only touches the root, `api/`, and `admin/`. Don't treat the empty result as an error.
+
+Then collect every `@dextinity/*` entry across the root, `api/`, `admin/`, and each site directory's `package.json`:
+
+```bash
+grep -n '"@dextinity/' package.json api/package.json admin/package.json \
+  <site-dir>/package.json ...
+```
+
+Notes:
+
+- Not every `@dextinity/*` package follows the core release cadence. Packages that live outside the core monorepo (for example `@comet/dev-process-manager`) may use a different versioning scheme (often `^x.y.z`). **Only** bump packages whose current version matches the core Comet version (the one shared by `@dextinity/cms-api`, `@dextinity/admin`, `@dextinity/site-nextjs`, etc.). Leave the others untouched.
+- Use the invariants to tell core from satellite: core packages are all pinned to the same exact version, with no caret or tilde. Anything with a range or a different version is not core — verify before touching it.
+- If you find core packages on different versions, or any core package using a range (`^`, `~`), the project violates the invariants. Stop and tell the user — don't paper over it by bumping.
+
+Confirm the **current major** from the version string (e.g. `8.20.4` → major `8`).
+
+---
+
+## Step 2 — Find the newest version in the current major
+
+Use `npm view` on any single core package to list versions, then filter to the current major and drop pre-releases (anything containing `-canary`, `-beta`, `-rc`, etc.):
+
+```bash
+npm view @dextinity/cms-api versions --json | \
+  python3 -c "import json,sys; v=json.load(sys.stdin); \
+    stable=[x for x in v if x.startswith('8.') and '-' not in x]; \
+    print(stable[-1])"
+```
+
+Substitute `8.` with whatever the current major is. The last entry in the filtered list is the target version.
+
+Sanity check: the target must be **greater than or equal to** the current version. If it is lower or equal, there is nothing to do — tell the user and stop.
+
+Core `@dextinity/*` packages are always released together at the same version, so checking any single one is enough — no need to verify the target version for each package individually.
+
+---
+
+## Step 3 — Update every package.json
+
+Update every occurrence of the current version to the new version inside `@dextinity/*` entries across every `package.json` from Step 1 (the root, `api/`, `admin/`, and each site directory). Write the new version **pinned** (e.g. `8.21.0`) — never add a caret or tilde, even if one was present before. Every core package must end up on the same target version (see Invariants).
+
+Before editing, do a quick check that the old version string doesn't appear elsewhere in those files (i.e. on non-`@dextinity` packages pinned to the same version by coincidence):
+
+```bash
+grep -n '<OLD_VERSION>' package.json api/package.json admin/package.json \
+  <site-dir>/package.json ...
+```
+
+If every match is a `@dextinity/*` line, you can safely edit each file. If there are non-`@dextinity` matches, edit the `@dextinity` lines individually.
+
+**Do not touch** packages like `@comet/dev-process-manager` that don't share the core version — see Step 1.
+
+---
+
+## Step 4 — Install
+
+Install in the root first, then in each sub-package. In a sandboxed environment you may not be able to run the sub-installs in parallel (`&` can fail) — run them sequentially if parallel fails.
+
+```bash
+npm install
+npm --prefix api install
+npm --prefix admin install
+# Then, for each site directory discovered in Step 1:
+npm --prefix <site-dir> install
+```
+
+What a successful run looks like:
+
+- npm prints `changed N packages` or `up to date` (both are fine — "up to date" means the lockfile was already correct for the new version range).
+- No `ERESOLVE`, `EBADENGINE`, `404`, or `EACCES` errors.
+- Harmless warnings you can ignore:
+    - `npm warn tar TAR_ENTRY_ERROR ENOENT …` during extraction
+    - `npm fund` / `npm audit` summaries
+    - Deprecation warnings on transitive deps
+
+After each install, verify the lockfile actually moved:
+
+```bash
+grep '"@dextinity/cms-api":' api/package-lock.json | head -3
+```
+
+The direct-dependency line should show the new version.
+
+### If install fails
+
+If any install fails because of the **sandbox** (no network access to the npm registry, read-only filesystem on `node_modules`, EPERM/EACCES on a lockfile, etc.): **stop and ask the user to run the installs themselves**. Do not try to work around it by retrying with different flags or disabling the sandbox — this is an environment problem, not a dependency problem. The `package.json` files are already edited, so the user just needs to run the `npm install` commands from Step 4.
+
+If any install fails with a real error (peer-dependency conflict, missing version, registry auth, etc.): **stop immediately and tell the user**. Do not attempt `--force`, `--legacy-peer-deps`, manual lockfile edits, or destructive resets — the user needs to diagnose the failure, often because it indicates a broader incompatibility (e.g. a peer dep that also needs bumping, or a transitive regression).
+
+In either case, report: which directory failed, the exact error lines, and the state of the `package.json` files (they have already been edited — mention this so the user knows).
+
+---
+
+## Step 5 — Verify
+
+Run lint and tests in each sub-package that defines them, and report the results. Do **not** start the dev server — that's the user's job (see Step 6 for why).
+
+For each of `api/`, `admin/`, and every site directory discovered in Step 1, check the `package.json` `scripts` block and run whatever is defined:
+
+```bash
+npm --prefix <dir> run lint --if-present
+npm --prefix <dir> test --if-present
+```
+
+`--if-present` makes npm exit 0 silently when the script is missing, so you can run the full set without first checking which scripts exist.
+
+If a project has a top-level lint/test script in the root `package.json`, run that too.
+
+What to do with the output:
+
+- **All green:** mention it briefly in the report.
+- **Failures:** report the failing command, the directory, and the first few error lines. Do not attempt to fix lint/test failures — they may indicate a real regression in the new Comet version, or pre-existing issues unrelated to the bump. The user decides.
+- **Type errors specifically:** these often come from stale generated files (`block-meta.json`, GraphQL schema) that only refresh when the app boots. Flag this possibility in the report so the user knows to start the dev server before assuming the bump broke types.
+
+---
+
+## Step 6 — Report the result
+
+Tell the user:
+
+- The old version → the new version
+- Which `package.json` files were touched
+- That each lockfile was updated and install succeeded
+- The verify results (lint/tests green, or which ones failed and where)
+- Anything suspicious you noticed (e.g. "the api/ install emitted a peer-dep warning about X — probably benign but worth a look")
+- **Remind the user to start the app once** (`npm run dev`). A minor Comet release can ship changes to generated artifacts like `block-meta.json` or the GraphQL schema, which are only regenerated when the app boots. Without this step, stale generated files can cause confusing type errors or runtime mismatches.
+
+---
+
+## Common pitfalls
+
+| Pitfall                                                       | How to avoid                                                                                        |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Picking a canary/beta as "newest"                             | Filter out any version containing `-` in Step 2.                                                    |
+| Bumping `@comet/dev-process-manager` (or similar) by accident | Only bump packages pinned to the shared core version — see Step 1.                                  |
+| Forgetting the root `package.json`                            | The repo root has its own `package.json` with `@dextinity/cli`. Always include it in the grep.      |
+| Assuming "up to date" means the install did nothing           | It means the lockfile already satisfies the new range. Verify with `grep` against the lockfile.     |
+| Running installs in parallel in a sandbox                     | If `&` backgrounding fails, just run the installs sequentially. Takes a bit longer, works reliably. |
+| Crossing a major version                                      | This skill is minor/patch only. Stop and warn the user.                                             |

package/skills/dev-pm/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: dev-pm
+description: Run, restart, stop, and inspect logs/status of long-running development processes via dev-pm (dev-process-manager). Use when starting/stopping/restarting services, tailing logs of those processes, or checking which services are running. Do not use for one-off scripts (`npm run X` is fine for those) — dev-pm is for processes that stay alive.
+---
+
+# dev-pm Skill
+
+`dev-pm` (`@comet/dev-process-manager`) supervises long-running dev processes (servers, watchers, codegen, storybook, docker, …). Available scripts and groups are defined in `dev-pm.config.ts` at the repo root — read it to discover what can be started.
+
+## Critical rules
+
+1. **Always invoke through the package manager:** `npm exec -- dev-pm <command>`. Never call `dev-pm` directly. If `pnpm` is the active package manager for the project (e.g. a `pnpm-lock.yaml` is present), use `pnpm exec -- dev-pm <command>` instead.
+2. **Never use streaming flags from a tool call — they hang.** `logs` requires `-n` / `--lines <N>`; `status` must not get `--interval`; `start` / `restart` must not get `--follow`.
+3. **Services may already be running.** dev-pm runs as a daemon across sessions — check `status` before starting things again. Same applies to build watchers ("the build watcher is running" means dev-pm is supervising a `build:watch` script); if absent, build the affected package manually.
+4. **dev-pm owns _all_ long-running tasks — including docker.** If a project uses dev-pm, assume every long-lived process (servers, watchers, codegen, **and** `docker compose up`) is wired into `dev-pm.config.ts`. Don't reach for `docker compose up` / `docker compose down` directly — start/stop the corresponding dev-pm script (commonly named `docker`). Exceptions exist; only treat something as outside scope after confirming it's not in `dev-pm.config.ts`.
+
+## Commands
+
+Script/group names below are placeholders; the authoritative list is `dev-pm.config.ts`.
+
+### `start [patterns...]`
+
+```bash
+npm exec -- dev-pm start <script>      # one script
+npm exec -- dev-pm start @<group>      # a group
+npm exec -- dev-pm start <a> <b>       # multiple patterns
+```
+
+- `@`-prefix → group name (from `group: [...]` in the config). Bare → script `name`. Globs (minimatch) work too, e.g. `api-*`.
+- Already-running scripts are a no-op — safe to call again. To force a restart, use `restart`.
+
+### `status` / `list`
+
+```bash
+npm exec -- dev-pm status              # all scripts
+npm exec -- dev-pm status <pattern>    # filter
+```
+
+First stop when troubleshooting "is X running?".
+
+**Reading the output:**
+
+- **Status:**
+    - `Running` — script is up.
+    - `Waiting` — `waitOn` condition unmet (e.g. api waiting for the database, site waiting for the api). Will start when the dependency is ready; if it stays here, the dependency failed — check its logs.
+    - `Backoff` — process crashed; dev-pm is sleeping before respawn. Wait grows as `min(1.3 ^ restartCount, 10)` seconds, capped at 10s. Flapping `Backoff` means broken — read logs and fix the cause; restarting won't help.
+    - `Stopped` — not running (never started or manually stopped).
+- **Restarts:** healthy scripts sit at `0`. Anything `> 0` means dev-pm respawned a crash — pull logs (`logs --lines 300 <name>`).
+
+### `logs` / `log`
+
+```bash
+npm exec -- dev-pm logs --lines 200 <script>
+npm exec -- dev-pm log -n 500 <pattern>
+```
+
+Pick a line count for the question — 100–200 for a quick check, 500+ for startup/error history.
+
+### `restart [patterns...]`
+
+```bash
+npm exec -- dev-pm restart <script>
+npm exec -- dev-pm restart @<group>
+```
+
+Use after rebuilding a package whose consumers cache the old build, or after editing config the running process loaded at startup.
+
+### `stop [patterns...]`
+
+```bash
+npm exec -- dev-pm stop <script>
+npm exec -- dev-pm stop @<group>
+```
+
+Stops the matched scripts; the daemon stays alive.
+
+### `shutdown` / `halt`
+
+```bash
+npm exec -- dev-pm shutdown
+```
+
+Stops everything and shuts down the daemon. Only when the user explicitly asks to "stop everything" / "kill dev-pm". Don't use as a "reset state" hammer — prefer `restart <pattern>`.
+
+## Discovering scripts and groups
+
+`dev-pm.config.ts` exports a `scripts` array. Each entry has:
+
+- `name` — identifier for start/stop/logs.
+- `group` — group names usable with the `@` prefix.
+- `script` — underlying shell command (informational; don't run directly).
+- `waitOn` — files / TCP ports the script waits for (explains startup ordering).
+
+When the user names a service vaguely ("the api"), grep `dev-pm.config.ts` for the matching `name` rather than guessing.
+
+## Common workflows
+
+- **"Why isn't service X responding?"** → `status` → `logs --lines 200 <name>` → `restart <name>` after fixing the cause.
+- **"Edited a package, running service isn't picking it up"** → confirm the package's build watcher is in `status`; if not, build the package or start its watcher; then `restart` the consumer.
+- **"Verify service X still boots"** → `start <name>`, poll `logs --lines N` until the ready line or an error appears.