@adaptabletools/adaptable-mcp 0.1.0-canary.0 → 0.1.0-canary.2

package/dist/skills/adaptable-setup/references/_shared/capabilities.md

@@ -0,0 +1,35 @@
+<!-- Generated by scripts/generate-bindings.ts from the capability registry. Do not edit; run `npm run generate`. -->
+
+# Capabilities and their bindings
+
+Every capability of `@adaptabletools/adaptable-mcp` (response schema 1) has a CLI command and, where listed, an MCP tool. Both run the same code and return the same envelope.
+
+| Capability | MCP tool | CLI command | What it does |
+| --- | --- | --- | --- |
+| `anonymise` | — | `adaptable anonymise <file>` | Replaces the values of a State, Options, Grid Info, columns or row-data JSON with shape-preserving placeholders — names, column ids, expressions and structure kept, licence keys and user names redacted, row data scrubbed — for a support case. |
+| `check-expression` | `check_expression` | `adaptable check expression <expression>` | Validates an AdapTableQL expression with the 24 engine: syntax, functions, kinds the module accepts, column references; exact rewrites for JavaScript-style operators and pre-24 syntax. |
+| `migrate-expression` | `migrate_expression` | `adaptable migrate expression <expression>` | Rewrites one pre-24 AdapTableQL expression to the target major's syntax with the library's own migration (brace aggregations, named operands, legacy observable rules) and validates the result. |
+| `aql-functions` | `list_expression_functions` | `adaptable aql functions` | Lists the AdapTableQL functions, aggregations, observable functions and clauses the engine accepts, with signatures, examples and docs slugs; filter by group, module or text. |
+| `changes` | `list_changes` | `adaptable changes` | Lists the changes between two AdapTable majors from the release-note records; with --repo keeps the ones the project's code hits (file:line) and the ones that always apply. |
+| `compat` | `get_compatibility` | `adaptable compat` | AG Grid pairing, wrapper packages and environment requirements for an AdapTable major, from the docs manifest. |
+| `detect` | `detect_environment` | `adaptable detect` | Detects the AdapTable projects at or below the folder: versions, framework, AG Grid, source layout hints. |
+| `convert-coldefs` | — | `adaptable convert coldefs <file>` | Turns AG Grid columnDefs into an AdapTable Layout (order, hidden columns, sizing, pinning, sorts, row groups, aggregations, pivots), lists the ColDef properties to remove with file:line, and the cellStyle / valueFormatter / valueGetter / cellRenderer snippets to re-express as Format, Calculated, Styled or Action Columns. The Layout is run through check state first. |
+| `docs-list` | — | `adaptable docs list` | Lists the docs pages for the project’s AdapTable version, grouped by sidebar section: the feature index. |
+| `docs-search` | `search_docs` | `adaptable docs search <query>` | Searches the docs for the project’s AdapTable version and framework; returns matching sections with slugs and URLs. |
+| `docs-get` | `get_doc` | `adaptable docs get <pages...>` | Reads docs pages as Markdown for the project’s version and framework; one section with --section, demo code trimmed unless --full. |
+| `docs-demos` | — | `adaptable docs demos <page>` | Lists the demos embedded in a docs page, with the files each demo owns. |
+| `docs-demo` | `get_demo` | `adaptable docs demo <name>` | Returns one demo’s own files (adaptableOptions.ts by default; --files for others). Template files are never returned. |
+| `migrate-state` | `migrate_state` | `adaptable migrate state <file>` | Migrates Adaptable State between majors with the library's own migration engine; reports the log, what the target major does not know (leftovers) and the check state result for the target. |
+| `cache-add` | — | `adaptable cache add <spec>` | Downloads a @adaptabletools/adaptable version into the cache so checks and migrations for that major work offline. |
+| `cache-list` | — | `adaptable cache list` | Shows cached library packages, bundled entries and docs corpora with sizes and ages. |
+| `cache-clear` | — | `adaptable cache clear` | Removes cached docs corpora and/or library packages (with their entry bundles); everything when no flag is given. |
+| `scaffold` | — | `adaptable scaffold` | Overlays the AdapTable files the docs demos run on onto a creator project (Vite or Angular CLI): columns, row data and an Initial State inferred from a CSV / JSON / XLSX file, dependencies pinned from the docs manifest, an AGENTS.md snippet. Never overwrites without --force. |
+| `check-setup` | `check_setup` | `adaptable check setup` | Audits how AdapTable is wired into a project: stylesheet, required options, licence literal, version skew, AG Grid modules, column typing, direct grid use, ColDef ownership, React refs, ready hook, and the Options shape against the major’s types. |
+| `check-state` | `check_state` | `adaptable check state <file>` | Validates Adaptable State (a JSON file or the literal in a .ts/.tsx/.js/.jsx/.vue file) against the checked major: shape, semantics, column references and AdapTableQL. |
+
+## Choosing a binding
+
+- Prefer the MCP tool when the harness has the `adaptable` MCP server configured. Otherwise run the CLI command as `npx -y @adaptabletools/adaptable-mcp@canary <command> [options]`; add `--json` to read fields instead of Markdown.
+- If neither binding exists for what you need — the capability is not in this table, not in `adaptable --capabilities`, or not in the MCP tool list — say so and fall back to the docs (see `docs-protocol.md`). Never improvise the result a missing capability would have produced.
+- All bindings return the same envelope: `ok`, `data`, `issues`, `warnings`, and on failure `error { code, message, hint }`. CLI exit codes: `0` ok, `1` findings, `2` usage, `3` environment.
+- Skill scripts cannot reach the agent's MCP session: a script only ever runs the CLI. When the CLI is unavailable, the agent performs the fallback itself.

package/dist/skills/adaptable-setup/references/_shared/conversation.md

@@ -0,0 +1,20 @@
+# How to talk to the user
+
+The skills mark instructions **Tell** and **Ask**; treat them literally.
+
+- **"Tell the user X"** → show X in the conversation and continue working.
+- **"Ask the user X"** → show the question and stop. Use the harness's
+  question tool when one exists. Do not answer your own question from context,
+  however obvious the answer looks — every Ask in these skills guards a choice
+  that is expensive to reverse (licence handling, ColDef migration, persisted
+  State, a package upgrade).
+
+Phases that produce an artefact **write the file before the next phase
+starts**, so a long task can be resumed from disk rather than from memory.
+
+Never dump whole State objects, whole `getGridInfo()` results or full log
+buffers into the conversation: extract the one section or the few lines the
+decision needs, and keep the rest in the scratch file it was saved to.
+
+End in plain prose: what changed, what was validated (name the check and its
+result), and what remains manual. No envelope JSON in the final message.

package/dist/skills/adaptable-setup/references/_shared/docs-protocol.md

@@ -0,0 +1,36 @@
+# Reading the docs — don't guess
+
+Training data is wrong for the installed version surprisingly often: option
+names, State shapes and AdapTableQL syntax all move between majors. The docs
+for the *detected* major are the source of truth, and they are one command
+away. The bindings (CLI or MCP) are listed in `capabilities.md`.
+
+## The lookup order
+
+1. **Find the feature.** `docs list --section` groups every page by sidebar
+   section; `docs search "<topic>"` ranks matching sections. Start here —
+   AdapTable usually has a feature for what looks like a hand-rolled job.
+2. **Behaviour.** `docs get <handbook slug> --section "<heading>"` for how a
+   feature behaves; read the whole page only when the section is not obvious.
+3. **Shape.** `docs get technical-reference-<feature>` for the exact
+   State / Options object: property names, types, which are required.
+4. **A working example.** `docs demos <page>` lists a page's demos;
+   `docs demo <name>` returns the demo's own files. Adapt a demo's shape to
+   the project's columns rather than inventing one.
+5. **Expressions.** Before using an AdapTableQL function you are not certain
+   exists for the installed version, ask the engine: `aql functions --module
+   <Module> --query <text>` returns the name, call form and signatures the
+   version actually accepts.
+
+With no shell, fetch `https://<docs host>/docs/<slug>/index.md` directly.
+
+## Rules
+
+- Unfamiliar does not mean unsupported. If a page or function is absent from
+  the detected version's docs and catalogue, say so plainly instead of
+  writing it from memory.
+- Before building anything from a primitive — a `valueGetter`, a custom cell
+  renderer, hand-rolled persisted state — check the feature index for an
+  AdapTable feature that already does it. Initial State, not code, is where
+  user-facing grid behaviour belongs.
+- Cite the slug you used when reporting, so the user can read the same page.

package/dist/skills/adaptable-setup/references/_shared/grounding.md

@@ -0,0 +1,54 @@
+# Grounding — do this first in every skill
+
+AdapTable's Options, State shapes, API and AdapTableQL differ between majors,
+and recalled knowledge is unreliable for any of them. Before writing, changing
+or diagnosing anything, establish what is actually installed.
+
+## 1. Detect the project
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary detect --json
+```
+
+(or the `detect_environment` MCP tool when the `adaptable` MCP server is
+configured). Record from the result:
+
+- the AdapTable major and exact version, and the paired AG Grid version,
+- the framework (React, Angular, Vue or vanilla) and the wrapper package,
+- the row model when one can be told (client-side vs server-side),
+- every project found — in a monorepo, work in the project the task is about.
+
+If detection reports no AdapTable (exit 3), the project either has AG Grid only
+or nothing yet; the calling skill says which path to take from there.
+
+With no shell and no MCP server, read `package.json` and the lockfile by hand —
+`@adaptabletools/*` and `ag-grid-*` entries — and say in the report that the
+versions were read by hand rather than detected.
+
+## 2. Freshness of this skill
+
+Compare this skill's `VERSION.md` with
+`https://<docs host>/.well-known/skills/VERSION` (best effort — skip silently
+when it cannot be fetched). The docs host is the one `detect` resolved for the
+project's major; a browser fetch or the shell both work.
+
+- Skill older by a **minor**: tell the user, suggest
+  `npx skills add https://<docs host>`, then continue.
+- Skill older by a **major**: tell the user to update the skill and stop —
+  instructions written for another major are worse than none.
+
+One caveat on a project whose AdapTable major is not yet released (a canary
+build, or a `24.x` range before the 24 release): the default docs host still
+serves the current released major's docs. The symptoms are a `docs` command
+failing with `DOCS_NOT_AVAILABLE`, or a warning that the docs host "is for
+AdapTable N, not M". Pass `--docs-host https://<branch>.adaptabletools.com`
+(or set `ADAPTABLE_MCP_DOCS_HOST`) on every command from then on so each
+lookup below reads the pre-release docs.
+
+## 3. AG Grid siblings
+
+Note whether the `ag-dev` and `ag-update` skills are installed. Column
+definitions, AG Grid modules, row models, themes and the grid API belong to
+AG Grid: hand that work to `ag-dev`, and AG Grid version bumps to `ag-update`,
+rather than improvising either here. Everything that imports from
+`@adaptabletools/*` stays in these skills.

package/dist/skills/adaptable-setup/references/_shared/guards.md

@@ -0,0 +1,20 @@
+# Guards — never cross these
+
+- **No licence keys in source.** AdapTable and AG Grid keys come from
+  environment variables (`VITE_ADAPTABLE_LICENSE_KEY` /
+  `VITE_AG_GRID_LICENSE_KEY` in a Vite shell, the shell's own convention
+  elsewhere). A key pasted into a file, an example or a chat answer stays in
+  version control forever. When the user pastes a key, use it to configure the
+  environment file and do not echo it back.
+- **Persisted State is the user's.** Never call `restoreState`, clear
+  `localStorage`, or change the state key (`adaptableId` / `stateKey` /
+  user name) without explicit confirmation in this conversation. Each of
+  those discards or orphans a user's saved Layouts, filters and settings.
+- **Planning phases do not touch source.** A phase whose artefact is a plan
+  or a report writes only its own artefacts; application source changes wait
+  for the apply step the user approved.
+- **Never echo a licence key out of a running grid.** `getGridInfo()` results
+  are saved with the key stripped before they are shown, attached or quoted.
+- **Upgrade discovery does not read the codebase.** During an upgrade plan,
+  the CLI searches the code; reading whole source files defeats that and
+  burns context. Read a file only when a named change record points at it.

package/dist/skills/adaptable-setup/references/_shared/validation-loop.md

@@ -0,0 +1,42 @@
+# The validation loop
+
+Nothing AdapTable-shaped is "done" until the checker for the project's
+detected major has seen it. The commands below are the CLI bindings; the MCP
+tools named in `capabilities.md` return the same envelope.
+
+## What gets checked
+
+- **Every AdapTableQL string** → `check expression "<expr>" --module <Module>`,
+  with `--columns <file>` when a columns file exists. The module matters: the
+  same text can be valid in one module and the wrong expression kind in
+  another.
+- **Every State literal** (Initial State in source, or a persisted State
+  export) → `check state <file> [--columns <file>]`; persisted exports add
+  `--kind persistent`.
+- **Setup and wiring** — after any change to Adaptable Options, the wrapper
+  components, `columnDefs` or modules → `check setup`.
+
+## The loop
+
+1. Run the check with `--json` and read `issues`, not just the exit code.
+2. Fix what it names. Each issue carries a rule id and, for the common cases,
+   an exact fix — apply that fix rather than a paraphrase.
+3. Re-check while the result shows `requiresAnotherCheckAfterFix`, at most
+   **three rounds**. If issues remain after that, stop and report the
+   remaining issues verbatim; do not summarise them into a false "clean".
+
+## Column lists
+
+Column references are checked against a columns file: the `columnDefs` source
+file, or `getColumns()` output from the running grid (debug skill) saved to a
+file. Never retype a column list from memory or from the conversation — a
+retyped list silently drifts from the grid it describes.
+
+A `columnDefs` file knows the grid's own columns only. Ids that the State
+defines — Calculated Columns above all — are known to `check state`, which
+reads them from the literal it checks, but not to a standalone
+`check expression --columns <columnDefs file>`: an `AQL_UNKNOWN_COLUMN` on a
+Calculated Column id there is the missing context, not a wrong expression.
+Validate such expressions through `check state` on the literal that holds
+them, or pass `getColumns()` output (which lists Calculated Columns) as the
+columns file.

package/dist/skills/adaptable-setup/references/paths.md

@@ -0,0 +1,45 @@
+---
+sources:
+  docs: [getting-started-integration, react-integration, angular-integration, vue-overview, getting-started-license-key, dev-guide-adaptable-state-persistence]
+  paths: [packages/adaptable-mcp/data/templates/manifest.json, packages/adaptable-mcp/src/core/scaffold/overlay.ts]
+---
+
+# Framework paths
+
+Where the AdapTable files live per framework. `scaffold` writes exactly this
+layout; on path A (existing grid) add the same files beside the existing
+`columnDefs` / `gridOptions` rather than moving them.
+
+| Framework | Source folder | Entry the wiring lands in | Wrapper |
+| --- | --- | --- | --- |
+| React (Vite) | `src/` | `src/App.tsx` | `@adaptabletools/adaptable-react-aggrid` — `Adaptable.Provider` + `Adaptable.AgGridReact` |
+| Angular | `src/app/` | the root standalone component (`src/app/app.ts`, or `src/app/app.component.ts`) | `@adaptabletools/adaptable-angular-aggrid` — `<adaptable-provider>`, `<adaptable-ui>`, `<ag-grid-angular *adaptable>` |
+| Vue (Vite) | `src/` | `src/App.vue` | `@adaptabletools/adaptable-vue-aggrid` — `AdaptableProvider` + `AdaptableAgGridVue` |
+| Vanilla (Vite) | `src/` | `src/main.ts` | `@adaptabletools/adaptable` — `Adaptable.init(options, { gridOptions, modules })` |
+
+Generated files in the source folder: `columnDefs.ts`, `rowData.ts`,
+`adaptableOptions.ts`, `gridOptions.ts`, `agGridModules.ts`, `licenses.ts`,
+`onAdaptableReady.ts`, plus `styles.css` carrying the AdapTable stylesheet
+import. The exact per-framework file set is recorded in
+`packages/adaptable-mcp/data/templates/manifest.json` (`srcDir`,
+`indexHtmlPath`, wrapper package) — when this table and the manifest disagree,
+the manifest wins and this file is stale.
+
+Framework specifics that bite:
+
+- **React:** keep the Adaptable Options, `gridOptions` and `rowData`
+  references stable across renders (module scope or `useRef`); recreating
+  them per render remounts the grid.
+- **Angular:** the stylesheet goes to the global `src/styles.css`, not a
+  component stylesheet (component style budgets reject it). A production
+  build of AG Grid Enterprise + AdapTable exceeds the default 1 MB `initial`
+  budget — raise the budget in `angular.json`; that is expected, not an error.
+- **Vue:** the AdapTable stylesheet imports are added in `App.vue` because
+  the creator's `main.ts` is left untouched.
+- **Vanilla:** `Adaptable.init` returns the API asynchronously through the
+  ready handler; do not hold the grid API from before it fires.
+
+Licence keys are read from environment variables in `licenses.ts` (Vite:
+`VITE_ADAPTABLE_LICENSE_KEY` / `VITE_AG_GRID_LICENSE_KEY`); Angular reads its
+environment file — the generated file names the variables. Keys never appear
+as literals in any of these files.

package/dist/skills/adaptable-upgrade/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: adaptable-upgrade
+description: "Use when moving @adaptabletools/* packages to a newer major (from 21 or later, to 22, 23 or 24 — one step or several), including the coupled AG Grid upgrade, Adaptable State migration, and Adaptable Options, API, object-type, CSS and AdapTableQL changes. Plans first, writing ADAPTABLE_UPGRADE_*.md files; applies the plan in a separate session. Not for persisted-State problems in an otherwise current app (adaptable-debug)."
+---
+
+# adaptable-upgrade — plan an AdapTable major upgrade, then apply it
+
+Two modes, two sessions. **Plan mode** writes `ADAPTABLE_UPGRADE_SCOPE.md`,
+`ADAPTABLE_UPGRADE_CHANGES.md` and `ADAPTABLE_UPGRADE_STATE/` and touches
+nothing else. **Apply mode** starts from those files in a fresh session and
+changes the application. You are in apply mode only when the user asks to
+apply an existing plan; everything else is plan mode.
+
+Shared protocol, read once: [grounding](references/_shared/grounding.md)
+(always first), [conversation](references/_shared/conversation.md),
+[guards](references/_shared/guards.md),
+[validation loop](references/_shared/validation-loop.md). Command bindings
+are in [capabilities](references/_shared/capabilities.md). The file
+templates are in [plan-preamble](references/plan-preamble.md); the apply
+sequence is [apply-order](references/apply-order.md).
+
+## Rules
+
+- Phases run in order and each writes its file before the next starts. Do
+  not combine phases or use a later phase's information in an earlier one.
+- **Tell** the user X → show it and continue. **Ask** the user X → show the
+  question and stop until answered (use the harness's question tool if any).
+- Change discovery does not read application source. The CLI searches the
+  repository; read a file only when a change record names it (guards).
+- Use no AdapTable tooling other than this skill and the `adaptable` CLI or
+  its MCP tools — not the State Migration Tool's UI, not hand-written
+  migration scripts, not recalled release notes.
+- AG Grid is coupled but not yours: its version bump goes through `ag-update`
+  or AG Grid's own upgrade guide. Never recommend AG Grid's codemod as part of
+  an AdapTable upgrade, and never copy AG Grid change content into the plan.
+- Plan mode never edits application source or `package.json` (guards). Apply
+  mode never bumps a package without the plan that names the target.
+
+Every command below is shown as the CLI; the MCP tool of the same name is
+equivalent except `list_changes`, which returns records only (no repository
+search, no `--with-docs`) — change discovery therefore runs the CLI. File
+paths passed to the CLI resolve from the shell's working directory; run it
+from the repository root and pass paths from there.
+
+## Plan mode
+
+### Phase 1 — Ground and freshness
+
+Run `detect` as grounding describes and the freshness check against
+`.well-known/skills/VERSION`. A skill older by a **major** is a hard stop:
+tell the user to run `npx skills add https://<docs host>` and do nothing
+else. Older by a minor: tell, then continue.
+
+### Phase 2 — Resume check
+
+Look for `ADAPTABLE_UPGRADE_*.md` and `ADAPTABLE_UPGRADE_STATE/` at the
+repository root. If any exist, **ask**: start fresh (delete them) or resume
+(skip every phase whose file already exists, in order). Never resume
+silently — a stale SCOPE from another target poisons every later phase.
+
+### Phase 3 — Scope → `ADAPTABLE_UPGRADE_SCOPE.md`
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary detect --all-projects --json
+```
+
+Record per project: path, framework and wrapper package, AdapTable range and
+major, AG Grid package / version / edition, package manager, the
+`initialStateLiterals` and `columnDefsFiles` lists (phase 5 uses them). In a
+monorepo the user may want a subset — list them all and let them choose.
+
+**Floor.** A project below major 21 stops the skill: tell the user the
+change records start at 21 → 22 and point at the release notes for the
+earlier steps (`https://www.adaptabletools.com/support/version-<N>0-release-note`,
+one per major), then stop. `changes` says the same with exit 3 if it is ever
+run against such a project.
+
+**Target.** The user's choice when given; otherwise the `latest` the
+manifest reports:
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary compat --adaptable <target>
+npx -y @adaptabletools/adaptable-mcp@canary compat --adaptable <target> --ag-grid <installed AG Grid major>
+```
+
+`compat` returns the target's AG Grid pairing, wrapper packages and
+environment minimums (Node, TypeScript, framework). Compare the minimums
+with what `detect` found (`typescript`, `frameworkVersions`, the running
+Node) and write every shortfall into SCOPE next to the minimum — a
+TypeScript below the target's floor fails the type-check in apply mode
+before any record is applied. When the installed AG Grid cannot move (a platform constraint, another team's grid), run `compat`
+once per candidate major between the current one and `latest` and tell the
+user which targets the installed AG Grid allows; a target whose pairing the
+installed AG Grid does not satisfy needs phase 4.
+
+**Ask** the user to confirm: the projects in scope, each project's current
+versions as detected, and the target major (and tag — a pre-release target
+is installed by its dist-tag, e.g. `canary`). Write
+`ADAPTABLE_UPGRADE_SCOPE.md` in the format of [plan-preamble](references/plan-preamble.md),
+recording the answers and the target's environment minimums from `compat`.
+
+### Phase 4 — AG Grid coupling (appended to SCOPE)
+
+Compare each project's installed AG Grid with the target's pairing from
+phase 3. When it already satisfies the pairing, write "no AG Grid change" and
+continue. Otherwise **tell** the user:
+
+> AdapTable <target> pairs with AG Grid <pairing>; this project has AG Grid
+> <installed>. The AG Grid upgrade is separate work.
+
+and **ask** which of these to record:
+
+1. **Run `ag-update` now** (only when grounding found it installed) — its
+   `AG_UPDATE_*.md` plan joins this one and apply mode applies both, AG Grid
+   first. Run it before continuing, in this session, so its plan exists when
+   SCOPE is written.
+2. **Bump only** — the plan includes the AG Grid version bump plus the link
+   to AG Grid's own upgrade guide for the installed → required majors, and
+   the user handles AG Grid's breaking changes themselves.
+3. **Already handled** — AG Grid is being upgraded elsewhere; the plan
+   assumes the pairing is met when apply mode starts.
+
+Append the answer under `## AG Grid plan` in SCOPE, with the exact AG Grid
+version to install (the pairing's minimum, or AG Grid's latest patch of
+that major when the user prefers).
+
+### Phase 5 — Changes → `ADAPTABLE_UPGRADE_CHANGES.md` and `ADAPTABLE_UPGRADE_STATE/`
+
+Start the file with the preamble from [plan-preamble](references/plan-preamble.md),
+then append the CLI's Markdown from its `# Changes <n> → <m>` heading onward
+**verbatim** — do not summarise, reorder or drop the "Not matched" lists.
+What precedes that heading (the context line, warnings, the `## Issues`
+index) is the CLI's own chrome: read it, act on the warnings, leave it out
+of the plan.
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary changes --from <current> --to <target> \
+  --repo <repository root> --projects <project folders from SCOPE> --with-docs
+```
+
+One call covers every transition in order (`21 → 22`, `22 → 23`, `23 → 24`
+as needed), sectioned per transition and, inside each, ordered Packages &
+CSS → State → Options → API → Objects → AdapTableQL → Deployment. Each
+record carries its type (`BREAKING` / `BEHAVIOUR` / `DEPRECATED`), whether
+State migration handles it, the `before → after` rows, the remedy note, the
+release-note anchor and the `file:line` matches in the repository.
+`--with-docs` inlines the release-note section behind each kept record so
+apply mode reads the remedy from the plan file instead of paying one
+`docs get` per record. Offline, the CLI skips it with a warning: keep going
+and write under the preamble that the release-note sections were not inlined
+and apply mode must `docs get` each record's anchor. A pre-release target
+needs `--docs-host https://<branch>.adaptabletools.com` (grounding); the
+CLI then warns that this host is not the one for the lower transitions —
+expected, the release notes of every major are served there too. Projects
+on different current majors: one call per distinct current major, with that
+major's projects in `--projects`, appended in ascending order.
+
+Then, for every file in each project's `initialStateLiterals`:
+
+```bash
+mkdir -p ADAPTABLE_UPGRADE_STATE
+npx -y @adaptabletools/adaptable-mcp@canary migrate state <project>/<file> --from <current> --to <target> \
+  --kind initial --columns <project>/<columnDefs file> --out ADAPTABLE_UPGRADE_STATE/<project>--<file>.json \
+  > ADAPTABLE_UPGRADE_STATE/<project>--<file>.md
+```
+
+(`--columns` takes the project's first `columnDefsFiles` entry; omit it
+when the project has none — the post-check then skips the column rules.)
+The `.json` is the migrated State (the engine's own output, functions and
+imports stubbed and listed as `unverifiable`); the `.md` is the report:
+migration log, `leftovers` (keys the target does not know, with their
+position in the source — exit 1 when any exist), the `unverifiable` list to
+re-attach, and the `check state --major <target>` result. Exit 2 with
+`EXTRACTION_FAILED` means the State is built at run time (a function call,
+a fetched file): record the file under `## State literals` as "not
+extractable — migrate at run time or export the built State and migrate the
+export", and move on. Link every pair under `## State literals` in
+`ADAPTABLE_UPGRADE_CHANGES.md` with its leftover count. Never paste a
+migrated State into the conversation — the files are the artefact.
+
+### Phase 6 — Trim
+
+In `ADAPTABLE_UPGRADE_CHANGES.md`, list every record whose type line reads
+`**BEHAVIOUR**` or `**DEPRECATED**` (title, type and the `before → after`
+rows only — not the note). `BREAKING` records are not up for discussion,
+and neither are the records under a `### Deployment` heading: those are
+release gotchas (Team Sharing roll-out, duplicate `Name`s in stores), not
+code changes — they stay in the plan whatever their type, and apply mode's
+final report quotes them.
+
+None: **tell** the user "No behaviour changes or deprecations apply to this
+project" and go to phase 7. Otherwise **tell** the user the counts and what
+each type means — a `BEHAVIOUR` change is the same code giving a different
+result, and the note says how to restore the former result; a `DEPRECATED`
+item still works on the target and is removed in a later major — then
+**ask**, per record, whether to **accept** it (take the new behaviour /
+defer the deprecation; the record is removed from the plan) or **mitigate**
+it (the record stays and apply mode performs the note). Offer to explain any
+of them first. With many records, do this as a conversation rather than one
+form; wait for a decision on every record.
+
+Edit the file: delete the accepted records (heading through its last bullet
+and inlined section); keep the rest. When any `BEHAVIOUR` / `DEPRECATED`
+record remains, append the `# Validation` section from
+[plan-preamble](references/plan-preamble.md). Confirm the file now holds
+either no such record or a `# Validation` section before continuing.
+
+### Phase 7 — Report
+
+**Tell** the user the plan is ready, where the three artefacts are, how many
+`BREAKING` records and State files it holds, and show this text verbatim:
+
+```
+Start a new agent session (or clear this one) and ask it to apply the plan in
+ADAPTABLE_UPGRADE_CHANGES.md with the adaptable-upgrade skill. It will bump AG Grid
+per ADAPTABLE_UPGRADE_SCOPE.md and every @adaptabletools/* package to the target,
+install, apply the BREAKING records file by file, replace each initialState literal
+with its migrated copy from ADAPTABLE_UPGRADE_STATE/, apply the BEHAVIOUR and
+DEPRECATED mitigations you kept, then validate with check state, check expression
+and check setup, type-check, build and a run of the application. Read the browser
+console on that run: AdapTable logs every State object it migrated and marks what
+it could not convert "(needs migration)".
+```
+
+Plan mode ends here. Nothing in the application has changed.
+
+## Apply mode
+
+Read `ADAPTABLE_UPGRADE_SCOPE.md` and `ADAPTABLE_UPGRADE_CHANGES.md` first;
+the plan, not the repository, is the list of work. Follow
+[apply-order](references/apply-order.md) step by step:
+
+1. **Packages.** AG Grid per SCOPE's `## AG Grid plan` (an `AG_UPDATE_*.md`
+   plan first when one exists), then every `@adaptabletools/*` package to the
+   same target version; install; the wrapper package names come from
+   `compat --adaptable <target> --framework <fw>`.
+2. **`BREAKING` records**, in the plan's order, file by file through their
+   `file:line` matches. For State: replace each `initialState` literal with
+   its `ADAPTABLE_UPGRADE_STATE/*.json`, re-attach the functions and imports
+   the report lists as `unverifiable`, re-author every leftover from the
+   record it belongs to. For AdapTableQL strings outside State:
+   `migrate expression "<aql>" --from <n> --to <m> --module <Module>`.
+3. **Kept `BEHAVIOUR` / `DEPRECATED` mitigations**, then the `# Validation`
+   double-check the plan asks for.
+4. **Validate** (validation loop, three rounds at most): `check state` on
+   every rewritten literal with `--major <target>` and the project's
+   columns, `check expression` on every rewritten string (targets 24 and
+   later), `check setup`, type-check, build.
+5. **Run** the application and read the console — `getLogs(id, { level:
+   ['warn', 'error'] })` through a browser tool, or the paste-back call —
+   for `(needs migration)` markers and migration warnings. Report them as
+   the manual leftovers list; they are objects the runtime could not
+   convert, not tool failures.
+6. **Persisted State.** The team decides and tests, explicitly: how user
+   State stored under each state key migrates on first load, remote
+   persistence payloads, Team Sharing roll-out
+   (`persistMigratedSharedEntities`, all clients together), and whether
+   `autoMigrateState` stays on. Tell, do not do: nothing in storage is
+   touched without confirmation (guards).
+7. **Final report** in prose: packages moved, files changed, what was
+   validated, the leftovers list, and the `Deployment` records from the plan
+   as the release gotchas.
+
+**Done when (plan):** the three artefacts exist, SCOPE records the user's
+confirmed projects, target and AG Grid decision, CHANGES holds the CLI
+output verbatim plus the trim decisions, no application file changed.
+**Done when (apply):** build green; `check state` / `check expression` /
+`check setup` clean; the application starts; the leftovers list is in the
+report.

package/dist/skills/adaptable-upgrade/VERSION.md

@@ -0,0 +1 @@
+0.1.0-canary.1

package/dist/skills/adaptable-upgrade/references/_shared/agents-snippet.md

@@ -0,0 +1,3 @@
+<!-- BEGIN:adaptable-agent-rules -->
+AdapTable (`@adaptabletools/*`) is used in this project. Its Options, State shapes, API and AdapTableQL change between majors, so do not rely on recalled knowledge. Before writing or changing AdapTable code use the `adaptable-dev` skill; for first-time integration `adaptable-setup`; for a misbehaving running grid `adaptable-debug`; for version upgrades `adaptable-upgrade`. Validate State, expressions and setup with `npx -y @adaptabletools/adaptable-mcp@canary check …` (or the `check_*` MCP tools when configured); read the docs for the installed version with `npx -y @adaptabletools/adaptable-mcp@canary docs search "<topic>"`. Pure AG Grid questions go to the `ag-dev` skill or AG Grid's documentation.
+<!-- END:adaptable-agent-rules -->

package/dist/skills/adaptable-upgrade/references/_shared/capabilities.md

@@ -0,0 +1,35 @@
+<!-- Generated by scripts/generate-bindings.ts from the capability registry. Do not edit; run `npm run generate`. -->
+
+# Capabilities and their bindings
+
+Every capability of `@adaptabletools/adaptable-mcp` (response schema 1) has a CLI command and, where listed, an MCP tool. Both run the same code and return the same envelope.
+
+| Capability | MCP tool | CLI command | What it does |
+| --- | --- | --- | --- |
+| `anonymise` | — | `adaptable anonymise <file>` | Replaces the values of a State, Options, Grid Info, columns or row-data JSON with shape-preserving placeholders — names, column ids, expressions and structure kept, licence keys and user names redacted, row data scrubbed — for a support case. |
+| `check-expression` | `check_expression` | `adaptable check expression <expression>` | Validates an AdapTableQL expression with the 24 engine: syntax, functions, kinds the module accepts, column references; exact rewrites for JavaScript-style operators and pre-24 syntax. |
+| `migrate-expression` | `migrate_expression` | `adaptable migrate expression <expression>` | Rewrites one pre-24 AdapTableQL expression to the target major's syntax with the library's own migration (brace aggregations, named operands, legacy observable rules) and validates the result. |
+| `aql-functions` | `list_expression_functions` | `adaptable aql functions` | Lists the AdapTableQL functions, aggregations, observable functions and clauses the engine accepts, with signatures, examples and docs slugs; filter by group, module or text. |
+| `changes` | `list_changes` | `adaptable changes` | Lists the changes between two AdapTable majors from the release-note records; with --repo keeps the ones the project's code hits (file:line) and the ones that always apply. |
+| `compat` | `get_compatibility` | `adaptable compat` | AG Grid pairing, wrapper packages and environment requirements for an AdapTable major, from the docs manifest. |
+| `detect` | `detect_environment` | `adaptable detect` | Detects the AdapTable projects at or below the folder: versions, framework, AG Grid, source layout hints. |
+| `convert-coldefs` | — | `adaptable convert coldefs <file>` | Turns AG Grid columnDefs into an AdapTable Layout (order, hidden columns, sizing, pinning, sorts, row groups, aggregations, pivots), lists the ColDef properties to remove with file:line, and the cellStyle / valueFormatter / valueGetter / cellRenderer snippets to re-express as Format, Calculated, Styled or Action Columns. The Layout is run through check state first. |
+| `docs-list` | — | `adaptable docs list` | Lists the docs pages for the project’s AdapTable version, grouped by sidebar section: the feature index. |
+| `docs-search` | `search_docs` | `adaptable docs search <query>` | Searches the docs for the project’s AdapTable version and framework; returns matching sections with slugs and URLs. |
+| `docs-get` | `get_doc` | `adaptable docs get <pages...>` | Reads docs pages as Markdown for the project’s version and framework; one section with --section, demo code trimmed unless --full. |
+| `docs-demos` | — | `adaptable docs demos <page>` | Lists the demos embedded in a docs page, with the files each demo owns. |
+| `docs-demo` | `get_demo` | `adaptable docs demo <name>` | Returns one demo’s own files (adaptableOptions.ts by default; --files for others). Template files are never returned. |
+| `migrate-state` | `migrate_state` | `adaptable migrate state <file>` | Migrates Adaptable State between majors with the library's own migration engine; reports the log, what the target major does not know (leftovers) and the check state result for the target. |
+| `cache-add` | — | `adaptable cache add <spec>` | Downloads a @adaptabletools/adaptable version into the cache so checks and migrations for that major work offline. |
+| `cache-list` | — | `adaptable cache list` | Shows cached library packages, bundled entries and docs corpora with sizes and ages. |
+| `cache-clear` | — | `adaptable cache clear` | Removes cached docs corpora and/or library packages (with their entry bundles); everything when no flag is given. |
+| `scaffold` | — | `adaptable scaffold` | Overlays the AdapTable files the docs demos run on onto a creator project (Vite or Angular CLI): columns, row data and an Initial State inferred from a CSV / JSON / XLSX file, dependencies pinned from the docs manifest, an AGENTS.md snippet. Never overwrites without --force. |
+| `check-setup` | `check_setup` | `adaptable check setup` | Audits how AdapTable is wired into a project: stylesheet, required options, licence literal, version skew, AG Grid modules, column typing, direct grid use, ColDef ownership, React refs, ready hook, and the Options shape against the major’s types. |
+| `check-state` | `check_state` | `adaptable check state <file>` | Validates Adaptable State (a JSON file or the literal in a .ts/.tsx/.js/.jsx/.vue file) against the checked major: shape, semantics, column references and AdapTableQL. |
+
+## Choosing a binding
+
+- Prefer the MCP tool when the harness has the `adaptable` MCP server configured. Otherwise run the CLI command as `npx -y @adaptabletools/adaptable-mcp@canary <command> [options]`; add `--json` to read fields instead of Markdown.
+- If neither binding exists for what you need — the capability is not in this table, not in `adaptable --capabilities`, or not in the MCP tool list — say so and fall back to the docs (see `docs-protocol.md`). Never improvise the result a missing capability would have produced.
+- All bindings return the same envelope: `ok`, `data`, `issues`, `warnings`, and on failure `error { code, message, hint }`. CLI exit codes: `0` ok, `1` findings, `2` usage, `3` environment.
+- Skill scripts cannot reach the agent's MCP session: a script only ever runs the CLI. When the CLI is unavailable, the agent performs the fallback itself.

package/dist/skills/adaptable-upgrade/references/_shared/conversation.md

@@ -0,0 +1,20 @@
+# How to talk to the user
+
+The skills mark instructions **Tell** and **Ask**; treat them literally.
+
+- **"Tell the user X"** → show X in the conversation and continue working.
+- **"Ask the user X"** → show the question and stop. Use the harness's
+  question tool when one exists. Do not answer your own question from context,
+  however obvious the answer looks — every Ask in these skills guards a choice
+  that is expensive to reverse (licence handling, ColDef migration, persisted
+  State, a package upgrade).
+
+Phases that produce an artefact **write the file before the next phase
+starts**, so a long task can be resumed from disk rather than from memory.
+
+Never dump whole State objects, whole `getGridInfo()` results or full log
+buffers into the conversation: extract the one section or the few lines the
+decision needs, and keep the rest in the scratch file it was saved to.
+
+End in plain prose: what changed, what was validated (name the check and its
+result), and what remains manual. No envelope JSON in the final message.

package/dist/skills/adaptable-upgrade/references/_shared/docs-protocol.md

@@ -0,0 +1,36 @@
+# Reading the docs — don't guess
+
+Training data is wrong for the installed version surprisingly often: option
+names, State shapes and AdapTableQL syntax all move between majors. The docs
+for the *detected* major are the source of truth, and they are one command
+away. The bindings (CLI or MCP) are listed in `capabilities.md`.
+
+## The lookup order
+
+1. **Find the feature.** `docs list --section` groups every page by sidebar
+   section; `docs search "<topic>"` ranks matching sections. Start here —
+   AdapTable usually has a feature for what looks like a hand-rolled job.
+2. **Behaviour.** `docs get <handbook slug> --section "<heading>"` for how a
+   feature behaves; read the whole page only when the section is not obvious.
+3. **Shape.** `docs get technical-reference-<feature>` for the exact
+   State / Options object: property names, types, which are required.
+4. **A working example.** `docs demos <page>` lists a page's demos;
+   `docs demo <name>` returns the demo's own files. Adapt a demo's shape to
+   the project's columns rather than inventing one.
+5. **Expressions.** Before using an AdapTableQL function you are not certain
+   exists for the installed version, ask the engine: `aql functions --module
+   <Module> --query <text>` returns the name, call form and signatures the
+   version actually accepts.
+
+With no shell, fetch `https://<docs host>/docs/<slug>/index.md` directly.
+
+## Rules
+
+- Unfamiliar does not mean unsupported. If a page or function is absent from
+  the detected version's docs and catalogue, say so plainly instead of
+  writing it from memory.
+- Before building anything from a primitive — a `valueGetter`, a custom cell
+  renderer, hand-rolled persisted state — check the feature index for an
+  AdapTable feature that already does it. Initial State, not code, is where
+  user-facing grid behaviour belongs.
+- Cite the slug you used when reporting, so the user can read the same page.