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

package/dist/skills/adaptable-debug/references/ticket-template.md

@@ -0,0 +1,50 @@
+---
+sources:
+  docs: [getting-started-integration, dev-guide-support-devtools-api]
+  paths: [packages/adaptable-mcp/src/core/anonymise/anonymise.ts]
+---
+
+# Support case template — `ADAPTABLE_SUPPORT_CASE.md`
+
+Destination: the form on the `adaptable-support-ticket` support page
+(https://adaptabletools.zendesk.com/hc/en-us/requests/new). The skill writes
+this file and stops; the user reviews and submits it. Anonymise the bundle
+before attaching — `adaptable anonymise <bundle>` keeps names, column ids
+and expressions, redacts licence keys and user names, and scrubs row values.
+
+```markdown
+# AdapTable support case
+
+**Destination:** adaptable-support-ticket (form)
+**AdapTable:** <version from getGridInfo> · **AG Grid:** <version> · **Framework:** <framework>
+**Skill:** adaptable-debug <VERSION.md>
+
+## Symptom
+<what the user sees, in their words where possible>
+
+## Expected vs actual
+- Expected: <…>
+- Actual: <…>
+
+## Steps to reproduce
+1. <…>
+Reproduced in the public support template (from getting-started-integration): <yes — link / no — why not>
+
+## Evidence
+- State section: `<Section>` (anonymised export attached)
+- Columns: `columns.json` (anonymised)
+- Options snippet: <adaptableOptions excerpt, licence keys and user names stripped>
+- Logs: `getLogs(id, { level: ['error', 'warn'], limit: 100 })` excerpt
+- `check state --kind persistent` result: <clean / issues verbatim>
+
+## What was already ruled out
+<the triage rows tried and what each showed>
+```
+
+Never attach: licence keys, user names, or un-anonymised row data. When row
+values matter to the symptom, ask the user, then attach the `anonymise`
+output (its placeholders preserve length, type and cardinality, so the shape
+of the data survives without the data). Row field names are renamed
+`field1`, `field2`, … by default, which breaks the link to the Layout's
+column ids; when the symptom is about specific columns, ask whether the field
+names are sensitive and pass `--keep-keys` if not.

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

@@ -0,0 +1,97 @@
+---
+name: adaptable-dev
+description: "Use BEFORE writing or changing any code that imports from @adaptabletools/* — Adaptable Options, Initial State, Layouts, Format or Styled Columns, Alerts, Calculated Columns, Column Filters, Exports, AdapTableQL expressions, Adaptable API calls, custom toolbars, menus, tool panels or settings panels — and when planning such work. Grounds the code in the installed AdapTable version's docs and demos and validates State, expressions and setup before presenting them. Not for first-time integration (adaptable-setup), a misbehaving running grid (adaptable-debug), version upgrades (adaptable-upgrade) or pure AG Grid work (ag-dev)."
+---
+
+# adaptable-dev — feature work on an existing AdapTable
+
+Shared protocol, read once: [grounding](references/_shared/grounding.md)
+(always first), [docs protocol](references/_shared/docs-protocol.md),
+[validation loop](references/_shared/validation-loop.md),
+[conversation](references/_shared/conversation.md),
+[guards](references/_shared/guards.md). Every command binding is in
+[capabilities](references/_shared/capabilities.md). Known agent failure modes
+are in [recommendations](references/recommendations.md) — apply them before
+writing, not after a failed check.
+
+## 1. Ground
+
+Run `detect` (see grounding) and record the AdapTable major, AG Grid pairing,
+framework and project. All docs reads, checks and shapes below are for that
+major. On a pre-release (canary) project, pass `--docs-host` as grounding
+describes, or you will design against the released major's docs.
+
+## 2. Design from the docs, not from memory
+
+For the feature at hand, in this order (docs protocol has the commands):
+
+1. `docs list --section` / `docs search` — confirm the feature exists for
+   this major and find its pages.
+2. `docs get <handbook slug> --section` — behaviour and gotchas.
+3. `docs get technical-reference-<feature>` — the exact State / Options shape.
+4. `docs demo <name>` — one working example; copy its shape, adapt its
+   column ids.
+
+### The ownership matrix — where each thing belongs
+
+| The thing is… | It belongs in… |
+| --- | --- |
+| a persistable, user-facing object (Layout, Format/Styled/Calculated/Action Column, Alert, Filter, Export…) | `initialState`, with a unique `Name`, column ids and a `Scope` |
+| a design-time callback, permission or custom function | `AdaptableOptions` (functions do not serialise into State) |
+| a runtime mutation | `adaptableApi.<module>Api`, called after `adaptableReady` |
+| column visibility, order, width, pinning, sorting, grouping, aggregation | the Layout in `initialState` — **not** ColDef `hide` / `pinned` / `width` / `sort` / `rowGroup` / `aggFunc` |
+| conditional styling, formats, sparklines, badges, derived values | Format / Styled / Calculated Columns in `initialState` — **not** `cellStyle`, `valueFormatter`, `valueGetter` or a custom renderer |
+| column typing | stays in the ColDef (`cellDataType`) |
+
+`check setup` flags ColDef properties AdapTable owns; `convert coldefs`
+turns an existing set into a Layout when a brownfield file needs it.
+
+### Working rules
+
+- **Declarative first.** If the user can see it, toggle it or save it, it is
+  Initial State. Code (Options, API calls) is for what State cannot express.
+- **Persisted State merges over `initialState`.** Editing `initialState`
+  does not reset what users already saved; reach runtime changes through the
+  State API (`adaptableApi.<module>Api`), and never fight persistence by
+  changing ids or the state key (guards).
+- **Expressions are AdapTableQL, validated per module.** Every expression
+  string goes through `check expression --module <Module>` before it is
+  presented; the module decides which expression kinds and functions are
+  legal there. Look functions up with `aql functions --module <Module>`
+  rather than recalling them.
+- **Column references are ids from the project**, taken from the `columnDefs`
+  source or `getColumns()` — never invented header names.
+- **AG Grid-only work goes to `ag-dev`** (ColDefs, modules, row models, the
+  grid API); **package bumps go to `adaptable-upgrade`**, never inside a
+  feature task.
+
+## 3. Apply the recommendations
+
+Read [recommendations](references/recommendations.md) for the feature area
+you are touching — expression kinds, State shapes, framework traps (React
+stable references, `adaptableReady`, Angular standalone components, Vue
+reactivity), and testing through `adaptableApi`. These are the mistakes this
+codebase's tooling keeps catching; the checkers catch the rest.
+
+## 4. Validate everything produced
+
+Per the validation loop: `check expression` for every AdapTableQL string
+(with its module), `check state --columns <columnDefs file>` for every State
+literal, `check setup` after touching Options, wrappers, `columnDefs` or
+modules. Fix and re-check, at most three rounds, then report remaining issues
+verbatim.
+
+When the app is running and a browser tool exists, verify the result in the
+page: `getState(id, '<Section>')` shows the section as the grid holds it and
+`getLogs(id, { level: ['error', 'warn'] })` shows whether it applied. A clean
+check on source plus a silent grid is `adaptable-debug` territory.
+
+## 5. Report
+
+In prose: what was added or changed and where it lives (State section,
+Options property, API call), which docs page or demo each new shape came
+from, and the checks that ran clean. Mention anything left unverified and why.
+
+**Done when:** the code compiles; `check state` / `check expression` /
+`check setup` are clean for everything produced; every new API, Option and
+State key is traceable to a docs page or demo for the installed major.

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

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

package/dist/skills/adaptable-dev/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-dev/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-dev/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-dev/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-dev/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-dev/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-dev/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-dev/references/recommendations.md

@@ -0,0 +1,93 @@
+---
+sources:
+  docs: [technical-reference-calculated-column, technical-reference-alerting, technical-reference-styled-column, handbook-calculated-column, handbook-grid-filter, getting-started-testing, react-integration, angular-integration, vue-overview]
+  paths: [packages/adaptable-mcp/evals/seed/known-wrong/state-format-column.md, packages/adaptable-mcp/evals/seed/known-wrong/state-calculated-column.md, packages/adaptable-mcp/evals/seed/known-wrong/state-layout-basic.md, packages/adaptable-mcp/evals/seed/known-wrong/placement-custom-function.md, packages/adaptable-mcp/evals/seed/known-wrong/aql-cumulative-pnl.md, packages/adaptable-mcp/evals/seed/known-wrong/setup-react.md]
+---
+
+# Recommendations — the mistakes agents keep making
+
+Each entry is a failure mode the checkers or support keep seeing, the form
+that works, and the capability that proves it. Shapes are stated for the
+current major; `check state` against the *detected* major is always the
+arbiter.
+
+## Expressions
+
+- **Wrong kind for the module.** A Format Column or Alert `Rule` is a
+  *Boolean* expression over one row (`[pnl] < 0`); a Calculated Column that
+  aggregates needs the aggregated scalar form with its grouping inside the
+  expression. Putting an aggregation in a rule, or a row expression where an
+  aggregation belongs, parses and then silently does nothing. Let
+  `check expression --module <Module>` judge the kind.
+- **Aggregation modifiers live inside the call.** Cumulative and windowed
+  aggregations are written inside the aggregation function as a modifier
+  (ordered by a date column), not as a wrapper around it. `aql functions
+  --module CalculatedColumn --query cumulative` shows the call form the
+  installed engine accepts.
+- **Change-count observables are functions, not wrappers.** "Alert me when
+  the price changed N times in 5 minutes" is a change-count function with a
+  timeframe compared against the threshold — not a `ROW_CHANGE(COUNT(...))`
+  wrapper. Search `aql functions --module Alert` before composing one.
+- **Percentages and weighted averages are single expressions.** A share of a
+  group total divides the value by the same aggregation over the group; a
+  weighted average is `SUMPRODUCT`-style numerator over weight denominator.
+  Two Calculated Columns referencing each other is the smell that one
+  expression was split in half.
+- **Custom functions are Options, registered once.**
+  `expressionOptions.customBooleanFunctions` (and its scalar/aggregation
+  siblings) takes `{ handler, description, signatures, examples }`; the
+  function is then callable in every expression of that kind. Do not invent
+  a ColDef-level registration, and do not hard-code the test in each rule.
+- **JavaScript habits in AdapTableQL.** `&&`, `||`, `===`, `SUM{[col]}`
+  and function names from memory all fail or mis-evaluate; the checker
+  rewrites the mechanical ones exactly — apply its fix, then re-check.
+
+## State shapes
+
+- **`Rule` is a string.** In the current major a Format Column, Styled
+  Column or Alert carries `"Rule": "[pnl] < 0"` — an expression string —
+  not an object wrapping one. `check state` names the right shape per major.
+- **Layout is `TableColumns` plus maps.** Order and visibility are the
+  `TableColumns` id list; width/flex in `ColumnSizing`, pinning in
+  `ColumnPinning`, sorts in `ColumnSorts`, grouping in `RowGroupedColumns`,
+  aggregation in `TableAggregationColumns`. A `CurrentLayout` whose `Name`
+  matches no Layout in the list applies nothing.
+- **Filters live in their module, referenced by the Layout.** Column Filters
+  hold an `Expression`; a Layout's Grid Filter references filter state — do
+  not embed a second, competing filter definition inside the Layout.
+- **Every user-facing object gets a stable, unique `Name`** and a `Scope`
+  that names column ids (`Scope.ColumnIds`), not header text. Two objects
+  sharing a `Name` in one section overwrite each other on save.
+- **Calculated Columns join the Layout like real columns** — add the column
+  name to `TableColumns` or the user never sees the value you computed.
+- **An Alert needs its trigger semantics stated**: row change, data change
+  or aggregation, with the rule kind to match. An alert that "never fires"
+  is usually a rule written for a different trigger.
+
+## Framework traps
+
+- **React: stable references.** Adaptable Options, `gridOptions` and
+  `rowData` recreated on every render remount the grid and lose State.
+  Module scope, `useMemo` or `useRef` — and all AdapTable work happens in
+  `onAdaptableReady`, where the API exists, not in an effect racing it.
+- **Angular: standalone wiring.** `<adaptable-provider>` +
+  `<adaptable-ui>` + `<ag-grid-angular *adaptable>`; the grid is not
+  instantiated directly beside the provider. Styles belong in the global
+  stylesheet.
+- **Vue: reactivity boundaries.** Pass options as stable objects; deep
+  reactive proxies around `gridOptions` fight the grid's own mutation of
+  them. Let the wrapper own the grid instance.
+- **Testing goes through `adaptableApi`.** Tests drive the grid through the
+  API from `adaptableReady` (`docs get getting-started-testing`), not by
+  dispatching DOM events at cells or by editing persisted State in
+  `localStorage`.
+
+## Process
+
+- **One demo beats three guesses.** When a shape is uncertain, `docs demo`
+  the closest demo and adapt it; the golden corpus passes `check state`, so
+  a shape copied from a demo starts life valid.
+- **`unverifiable` is information, not failure.** A State literal the
+  extractor cannot resolve statically (spread, computed keys) is reported as
+  such; restructure the literal into a checkable one where the task allows,
+  and say plainly what could not be checked where it does not.

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

@@ -0,0 +1,158 @@
+---
+name: adaptable-setup
+description: "Use when adding AdapTable to a project for the first time: creating a new AdapTable + AG Grid app from nothing, from a dataset (CSV, Excel, JSON, a REST endpoint) or from a description, or wiring AdapTable onto an existing AG Grid Enterprise grid (including moving ColDef-level layout and styling into AdapTable Initial State). Covers packages, AG Grid modules, licence keys, containers, Adaptable Options, Initial State and a first verified run. Not for upgrades (adaptable-upgrade) or for adding features to an existing AdapTable instance (adaptable-dev)."
+---
+
+# adaptable-setup — first-time AdapTable integration
+
+Work through the phases in order. Shared protocol, read once:
+[grounding](references/_shared/grounding.md) (always first),
+[docs protocol](references/_shared/docs-protocol.md),
+[validation loop](references/_shared/validation-loop.md),
+[conversation](references/_shared/conversation.md),
+[guards](references/_shared/guards.md). Every command binding is in
+[capabilities](references/_shared/capabilities.md); framework file layouts are
+in [paths](references/paths.md).
+
+## Phase 1 — Ground
+
+Run `detect` (see grounding). Record the AdapTable major if any, the AG Grid
+version, the framework and every project found. Everything after this phase
+targets the detected versions, never the newest you remember.
+
+## Phase 2 — Qualify
+
+Classify the project from the `detect` result:
+
+- **A** — an AG Grid Enterprise app already exists. AdapTable is wired onto it.
+- **B** — a project exists but has no grid. A grid plus AdapTable are added.
+- **C** — nothing exists. A shell is created first (phase 3).
+
+Run `compat` for the target major to get the AG Grid pairing, the wrapper
+package and the environment minimums.
+
+**Gate — AG Grid edition and version.** AdapTable needs AG Grid Enterprise at
+the paired version. If `detect` shows AG Grid Community, or an AG Grid below
+the pairing: **ask** — upgrade AG Grid first (hand over to `ag-update` when it
+is installed) or stop. Do not install AdapTable onto an unpaired grid and hope.
+
+**Ask once, for everything this phase needs:** the AdapTable and AG Grid
+licence keys (or confirmation to use trial placeholders — keys go to the
+environment file, never into source; see guards), the data source for B/C (a
+file, an endpoint URL, or "demo data"), and the primary key when the data has
+no obvious unique column. One round of questions, then proceed.
+
+## Phase 3 — Shell (path C only)
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary scaffold --dry-run --framework <framework> --out <dir> [--data <file> | --sample <file.json> | --source-url <url>]
+```
+
+Pass the data source agreed in Phase 2 (without it the dry run previews the
+shared demo dataset's columns and `id` key, not the user's). **Tell** the
+user the framework creator command the `Shell: missing` line prints
+(`npm create vite@latest …` or `ng new …`) and run it (or let the user run
+it). `scaffold` overlays onto a creator shell; it does not create one. Then
+re-run `detect` in the new folder.
+
+## Phase 4 — Install and wire
+
+### Path A — onto the existing grid
+
+1. Keep the existing `columnDefs` and `gridOptions`. Add `adaptableId` and
+   `primaryKey` to the Adaptable Options, and hand grid instantiation to the
+   framework wrapper exactly as `docs get <framework>-integration` shows for
+   the detected major — the grid is created through the wrapper, not
+   alongside it.
+2. Move logic that ran after grid creation into the `adaptableReady` handler
+   (React: `onAdaptableReady`); that is where the `adaptableApi` exists.
+3. Migrate ColDef-owned layout and styling:
+
+   ```bash
+   npx -y @adaptabletools/adaptable-mcp@canary convert coldefs <columnDefs file>
+   ```
+
+   It returns a Layout for the new Initial State, a `remove[]` list of
+   ColDef properties AdapTable now owns (visibility, order, width, pinning,
+   sorting, grouping, aggregation) and `candidates[]` (`cellStyle`,
+   `valueFormatter`, `valueGetter`, renderers) to re-express as Format,
+   Calculated, Styled or Action Columns.
+
+   **Gate — ColDef migration.** **Ask** which Layout-owned properties to move
+   (default: all — leaving them in the ColDef means the Layout and the ColDef
+   fight) and which candidates to re-express now (default: none; they keep
+   working and can move later with `adaptable-dev`). Apply the agreed edits,
+   then `check setup` and `check state` on the new Initial State.
+
+### Paths B/C — scaffold the overlay
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary scaffold --dry-run --out <dir> [--data <file> | --sample <file.json> | --source-url <url>]
+```
+
+**Gate — columns and primary key.** **Show** the inferred columns (field,
+type, nullability) and the primary-key choice from the dry run and **ask**
+the user to confirm or correct them — a wrong type or key here is baked into
+every file. Then run without `--dry-run` (add `--force` only for files the
+user has agreed to overwrite). The run writes `columnDefs.ts`, `rowData.ts`,
+`adaptableOptions.ts`, `gridOptions.ts`, `agGridModules.ts`, `licenses.ts` and
+`onAdaptableReady.ts` into the framework's source folder, pins the paired
+dependencies in `package.json`, and writes the `AGENTS.md` snippet when the
+project has none. Licence keys are read from environment variables in the
+generated code — tell the user which variables to set.
+
+## Phase 5 — Initial State
+
+`scaffold` (B/C) or `convert coldefs` (A) already produced a minimal Initial
+State: one Layout with every column, a Dashboard with the Layout and Export
+toolbars. Keep it minimal.
+
+**Gate — showcase set.** Offer the `suggestions[]` from the scaffold report:
+for each candidate, `docs demo <name>`, adapt that demo's State to the
+confirmed columns (column ids and Scopes change; shapes come from the demo),
+and validate the merged Initial State:
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary check state <adaptableOptions file> --columns <columnDefs file>
+```
+
+**Ask** which suggestions to include (default: none — a clean minimal grid
+the user grows with `adaptable-dev` beats a showcase they delete).
+
+## Phase 6 — Persistence
+
+**Tell** the user that Adaptable State persists to `localStorage` by default
+— Layouts, filters and settings survive reloads with no code.
+
+**Gate — remote persistence.** **Ask** whether to wire remote persistence
+now, following `docs get dev-guide-adaptable-state-persistence` (default:
+no). If yes, keep the state key and user name stable and say what changing
+them later would orphan.
+
+## Phase 7 — Run and verify
+
+1. `check setup` on the project; fix what it names and re-check.
+2. Typecheck and build with the project's own commands; start the dev server.
+3. With a browser tool, evaluate on the page: `listInstances()`, then
+   `getGridInfo(id)` — strip the licence key before showing or saving it —
+   and `getLogs(id, { level: ['error', 'warn'] })`. One instance, no
+   AdapTable errors, is the bar.
+4. Without a browser tool, **tell** the user the same three calls to paste
+   into the browser console against `window.__ADAPTABLE_DEVTOOLS__` and to
+   paste the results back.
+
+Licence banner warnings in the console are expected until real keys are set;
+AdapTable errors are not.
+
+## Phase 8 — Hand-off
+
+Close in prose (see conversation): the Adaptable Options in two sentences
+(where they live, the `adaptableId` and `primaryKey`), the Initial State in
+two sentences (the Layout, where to add features), the API in two sentences
+(`adaptableApi` from `adaptableReady`, never before it), where the licence
+keys live (environment variables), and where State persists. From now on the
+project uses `adaptable-dev`.
+
+**Done when:** the app builds and runs; one AdapTable instance mounts with no
+AdapTable errors; `check setup` and `check state` are clean; the user knows
+where the keys and the State live.

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

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

package/dist/skills/adaptable-setup/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 -->