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

package/dist/skills/adaptable-debug/references/devtools-api.md

@@ -0,0 +1,36 @@
+---
+sources:
+  docs: [dev-guide-support-devtools-api, dev-guide-support-devtools, dev-guide-support-logging]
+  paths: [packages/adaptable/src/setupDevTools.ts]
+---
+
+# DevTools in-page API
+
+`window.__ADAPTABLE_DEVTOOLS__` is installed by the running AdapTable (its
+implementation is `createDevToolsGlobal()` in
+`packages/adaptable/src/setupDevTools.ts`). Any browser tool that can
+evaluate JavaScript on the page can call it; results are plain JSON. `id`
+is an instance id from `listInstances()` and is optional when exactly one
+instance is mounted. When unsure of a signature, call `help()` first — the
+global prints its own usage text.
+
+| Call | Purpose | Note |
+| --- | --- | --- |
+| `help()` | the global's own usage text | first call when a signature is unsure |
+| `listInstances()` | mounted instances as `{ adaptableId, adaptableVersion, agGridVersion, adaptableStateKey, primaryKey, userName, gridRuntime }` — the `adaptableId` is the `id` every other call takes | ask which one when several |
+| `getGridInfo(id)` | versions, options summary, environment | drop the licence key before saving or quoting |
+| `getState(id, 'Layout')` | one State section | never call without a section |
+| `getPersistentState(id)` | persisted State as stored | compare against source `initialState` |
+| `getColumns(id)` | effective columns with ids and data types | save to `columns.json` for `check state --columns` |
+| `getColumnInfo(id, columnId)` | read-only Column Info: summary plus the Settings Panel tags for every object scoped to that column | the "why is this one column wrong" call; cheaper than `getColumns` |
+| `getLogs(id, { level, channel, limit })` | buffered logs including init warnings and `(needs migration)` markers | errors + warnings first; default limit 100 |
+| `getRecentActions(id, n)` | last state actions | explains "who changed the Layout"; default 50 |
+| `restoreState(id, state)` | replace State | experiment only, with explicit confirmation — it discards the user's saved State |
+| `openSettingsPanel(id, module)` | open the UI for a module | guided manual checks |
+| `setLogging(pattern \| null)` | sets `localStorage.debug` (e.g. `'Adaptable:<id>:*'`) during a repro; returns the previous value; global, not per instance | restore the returned value afterwards |
+
+Notes from the implementation: log buffers hold the last 500 entries per
+instance and actions the last 200 — collect early in a long repro. An empty
+`listInstances()` almost always means "called before mount" or "init failed
+before registration"; check the page's console and `check setup` before
+reading State that does not exist.

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

@@ -0,0 +1,36 @@
+---
+sources:
+  docs: [getting-started-ai-skills]
+  paths: []
+---
+
+# Feedback template — `ADAPTABLE_FEEDBACK.md`
+
+For feedback about the AdapTable agent tooling itself (a skill that misled,
+a check that missed, a docs gap the agent fell into) — not a product bug;
+that is the support case (`ticket-template.md`). Destination: the form on
+the `adaptable-support-ticket` support page. The skill writes this file and
+stops; the user reviews and sends it.
+
+```markdown
+# AdapTable agent-tooling feedback
+
+**Destination:** adaptable-support-ticket (form)
+**Skill:** <adaptable-setup | adaptable-dev | adaptable-debug | adaptable-upgrade> · **Skill version:** <VERSION.md>
+**Project:** AdapTable <major> · AG Grid <version> · <framework> (from detect; versions only, no keys)
+
+## What the agent did
+<the steps taken, the commands/tools run, the result produced>
+
+## What the user corrected
+<each correction, and the file or answer it changed>
+
+## What would have prevented it
+- Docs page: <slug that should have been read, or "missing — <topic>">
+- Skill text: <section that misled, or "missing — <guidance>">
+- Checker: <rule that should have caught it, or "missing — <check>">
+```
+
+Keep it factual: transcripts and corrections, no project source, no licence
+keys, no row data. One feedback file per incident; several corrections in one
+session belong in the same file when they share a cause.

package/dist/skills/adaptable-debug/references/symptoms.md

@@ -0,0 +1,37 @@
+---
+sources:
+  docs: [handbook-calculated-column, dev-guide-adaptable-state-persistence, dev-guide-adaptable-state-updating-initial-state, dev-guide-support-devtools-api, getting-started-integration]
+  paths: [packages/adaptable/src/setupDevTools.ts]
+---
+
+# Symptom table
+
+Start from what the user sees. "Look at" names the DevTools read (see
+`devtools-api.md`); validate what you collect before concluding — a matching
+row here is a hypothesis, the `check` run is the proof.
+
+| Symptom | Look at | Likely causes | Docs |
+| --- | --- | --- | --- |
+| Layout not applied | `getState(id,'Layout')`, `getColumns` | `CurrentLayout` name mismatch; columns missing from `TableColumns`; column id ≠ field; persisted State overriding source | layouts |
+| Column missing | Layout `TableColumns`, `getColumns`, entitlements | hidden by Layout; not in grid; auto-group column; `colDef.hide` fighting the Layout | layouts, entitlements |
+| Format Column not styling | `getState(id,'FormatColumn')`, `check expression` on `Rule` | Scope excludes column; Rule invalid or wrong kind; later rule overriding; conflicting Styled Column; custom cell renderer | format column |
+| Calculated Column empty | expression kind, referenced ids, row model | scalar vs aggregated mismatch; wrong column id; aggregation without grouping; SSRM | calculated column |
+| Alert never fires | `getState(id,'Alert')` | rule/type mismatch; data changes not through the API; alert suspended | alerts |
+| Filter not applied | Grid Filter vs Column Filter vs Layout-embedded filter | wrong filter kind; SSRM filtering server-side; persisted filter | filters |
+| State "lost" on reload | `getPersistentState`, logs | state key / user name changed; persistence hook failing; `(needs migration)` entries | state persistence |
+| Edits to `initialState` have no effect | source vs `getPersistentState` | persisted State wins; bump the section's `Revision` (or `reloadInitialState` with user awareness) | state persistence, updating initial state |
+| Grid blank / no instance | logs, console, `check setup` | not mounted yet; init failed (modules, licence, CSS, container height); AG Grid instantiated directly | integration |
+| Grid resets on every render (React) | `check setup` `react-stable-refs` | options / rowData recreated each render | react integration |
+
+Two rows deserve emphasis because they present as something else:
+
+- **"Edits to `initialState` have no effect" is persistence, not caching.**
+  Persisted State merges over `initialState`; until the saved section is
+  replaced, source edits to that section stay invisible. The designed way to
+  replace it is the section's `Revision` in `initialState` (a higher number,
+  or `{ Key, UpdateStrategy }` to keep what the user added); clearing the
+  store or `reloadInitialState` is a user decision (guards.md). Compare
+  `getPersistentState()` with the source before editing anything.
+- **"Grid blank" is a mount problem until proven otherwise.** An empty
+  `listInstances()` plus console errors points at modules, licence, CSS or
+  container height — `check setup` names the wiring ones without a browser.

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.