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

package/dist/mcp/index.js

@@ -1,21 +1,109 @@
 /**
- * MCP entry. A6.1 replaces this with the stdio server generated from the
- * registry (plan §9); until then `adaptable mcp` fails with `NOT_FOUND` and
- * exit 2 so a client configuration that points here reports a clear error
- * instead of hanging.
+ * `adaptable mcp [--cwd <dir>] [--major <n>] [--framework <fw>] [--offline] [--docs-host <url>]`
+ * — the stdio MCP server (plan §8.14, §9). The flags are defaults for every tool
+ * call; a tool argument of the same name wins. stdout belongs to the transport, so
+ * everything else goes to stderr. The returned promise settles when the client
+ * closes the connection.
  */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { exitCodeFor } from '../core/index.js';
-export async function runMcp(_argv, io) {
-    const envelope = {
-        schemaVersion: 1,
-        ok: false,
-        error: {
-            code: 'NOT_FOUND',
-            message: 'The MCP server is not available in this build of @adaptabletools/adaptable-mcp.',
-            hint: 'Use the `adaptable` CLI (`adaptable --help`), or upgrade to a version whose `adaptable --capabilities` lists MCP tools.',
-        },
-    };
-    io.stderr(`${JSON.stringify(envelope, null, 2)}\n`);
-    return exitCodeFor(envelope);
+import { createServer, mcpCapabilities } from './server.js';
+const FRAMEWORKS = ['vanilla', 'react', 'angular', 'vue'];
+const usage = (message) => ({
+    schemaVersion: 1,
+    ok: false,
+    error: { code: 'USAGE', message, hint: 'Usage: adaptable mcp [--cwd <dir>] [--major <n>] [--framework <fw>] [--offline] [--docs-host <url>]' },
+});
+/** Parses the server flags; returns a usage envelope for anything it does not know */
+export function parseMcpArgs(argv) {
+    const defaults = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        const [flag, inline] = arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined];
+        const value = () => inline ?? argv[++i];
+        switch (flag) {
+            case '--help':
+            case '-h':
+                return { help: true };
+            case '--offline':
+                defaults.offline = true;
+                break;
+            case '--cwd': {
+                const v = value();
+                if (!v) {
+                    return { error: usage('--cwd needs a folder.') };
+                }
+                defaults.cwd = v;
+                break;
+            }
+            case '--docs-host': {
+                const v = value();
+                if (!v) {
+                    return { error: usage('--docs-host needs a URL.') };
+                }
+                defaults.docsHost = v;
+                break;
+            }
+            case '--major': {
+                const v = value();
+                const n = Number(v);
+                if (!v || !Number.isInteger(n)) {
+                    return { error: usage(`--major needs a whole number${v ? ` (got "${v}")` : ''}.`) };
+                }
+                defaults.major = n;
+                break;
+            }
+            case '--framework': {
+                const v = value();
+                if (!v || !FRAMEWORKS.includes(v)) {
+                    return { error: usage(`--framework must be one of ${FRAMEWORKS.join(', ')}${v ? ` (got "${v}")` : ''}.`) };
+                }
+                defaults.framework = v;
+                break;
+            }
+            default:
+                return { error: usage(`Unknown option "${arg}".`) };
+        }
+    }
+    return { defaults };
+}
+export function mcpHelp() {
+    const tools = mcpCapabilities('stdio').map((c) => `  ${c.mcp.tool.padEnd(26)} ${c.description}`);
+    return [
+        'Usage: adaptable mcp [options]',
+        '',
+        'Starts the AdapTable MCP server on stdio. Configure it in your MCP client as',
+        '  { "command": "npx", "args": ["-y", "@adaptabletools/adaptable-mcp@^1", "mcp"] }',
+        '',
+        'Options (defaults for every tool call; a tool argument of the same name wins):',
+        '  --cwd <dir>         Project folder; defaults to the current directory',
+        '  --major <n>         AdapTable major to assume instead of detecting it',
+        '  --framework <fw>    Framework to assume instead of detecting it (vanilla, react, angular, vue)',
+        '  --offline           Never touch the network; use caches and bundled snapshots',
+        '  --docs-host <url>   Docs host to read instead of the default one',
+        '',
+        'Tools:',
+        ...tools,
+        '',
+    ].join('\n');
+}
+export async function runMcp(argv, io) {
+    const parsed = parseMcpArgs(argv);
+    if ('help' in parsed) {
+        io.stderr(mcpHelp());
+        return 0;
+    }
+    if ('error' in parsed) {
+        io.stderr(`${JSON.stringify(parsed.error, null, 2)}\n`);
+        return exitCodeFor(parsed.error);
+    }
+    const server = createServer({ defaults: parsed.defaults, transport: 'stdio' });
+    const transport = new StdioServerTransport();
+    const closed = new Promise((resolve) => {
+        server.server.onclose = () => resolve();
+    });
+    await server.connect(transport);
+    await closed;
+    return 0;
 }
 //# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,WAAW,EAAiB,MAAM,kBAAkB,CAAC;AAO9D,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,KAAe,EAAE,EAAS;IACrD,MAAM,QAAQ,GAAoB;QAChC,aAAa,EAAE,CAAC;QAChB,EAAE,EAAE,KAAK;QACT,KAAK,EAAE;YACL,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,iFAAiF;YAC1F,IAAI,EAAE,yHAAyH;SAChI;KACF,CAAC;IACF,EAAE,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;IACpD,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"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"}

package/dist/mcp/server.js

@@ -0,0 +1,110 @@
+/**
+ * The MCP server, generated from the capability registry (plan §9): one tool per
+ * capability with an `mcp` binding, the input schema taken from the capability's
+ * zod schema plus the global options, the result the same envelope the CLI prints
+ * with `--json`. No prompts, no resources, no write tools.
+ *
+ * Freshness (§9): the server outlives docs deploys, so every call passes the 60 s
+ * manifest re-validation window to core; the engine and types packages are
+ * resolved per call by core itself (§7.3), never from a cache keyed on the first
+ * project the server saw.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { CLI_PACKAGE, CLI_VERSION, SCHEMA_VERSION, listCapabilities, runCapability, } from '../core/index.js';
+/** How long the long-lived server trusts a validated docs manifest before the next conditional GET (§9) */
+export const MANIFEST_MAX_AGE_MS = 60_000;
+/**
+ * The global options a tool call may carry (plan §7.1). `--json` and `--quiet`
+ * are CLI rendering flags with no meaning over MCP. Mirrors the CLI's
+ * `GLOBAL_FLAGS`; the names are the `GlobalOptions` keys core validates.
+ */
+export const TOOL_GLOBALS = {
+    cwd: z.string().optional().describe('Project folder (absolute path); defaults to the folder the server was started in'),
+    major: z.number().int().optional().describe('AdapTable major to assume instead of detecting it from the project'),
+    framework: z.enum(['vanilla', 'react', 'angular', 'vue']).optional().describe('Framework to assume instead of detecting it'),
+    offline: z.boolean().optional().describe('Never touch the network; use caches and bundled snapshots'),
+    docsHost: z.string().optional().describe('Docs host to read instead of the default one'),
+};
+export const GLOBAL_KEYS = Object.keys(TOOL_GLOBALS);
+const SERVER_INSTRUCTIONS = [
+    `AdapTable developer tooling (${CLI_PACKAGE} ${CLI_VERSION}, response schema ${SCHEMA_VERSION}).`,
+    'Every tool returns the same envelope as the `adaptable` CLI with `--json`: `ok`, `data`, `issues`, `warnings`, `resolvedContext`, or `error { code, message, hint }`.',
+    'Call `detect_environment` first so later calls run against the project\'s AdapTable version; pass `cwd` when the project is not the server\'s working directory.',
+    'Workflows (setup, development, debugging, upgrades) live in the adaptable-* skills, not in this server.',
+].join(' ');
+/** The zod object a capability's input is declared with; the registry only accepts objects */
+function inputShape(capability) {
+    const input = capability.input;
+    if (!input.shape || typeof input.shape !== 'object') {
+        throw new Error(`Capability "${capability.name}": the MCP binding needs an object input schema.`);
+    }
+    return input.shape;
+}
+/** The tool's input schema: the capability's fields plus the global options (a capability field of the same name wins) */
+export function toolInputSchema(capability) {
+    return z.object({ ...TOOL_GLOBALS, ...inputShape(capability) });
+}
+/** Splits the raw tool arguments into the capability input and the global options */
+export function splitArguments(args, capability) {
+    const own = new Set(Object.keys(inputShape(capability)));
+    const input = {};
+    const globals = {};
+    for (const [key, value] of Object.entries(args)) {
+        if (value === undefined) {
+            continue;
+        }
+        if (!own.has(key) && GLOBAL_KEYS.includes(key)) {
+            globals[key] = value;
+        }
+        else {
+            input[key] = value;
+        }
+    }
+    return { input, globals: globals };
+}
+/** The envelope as a tool result: the JSON as text (what the skills parse), the object as structured content */
+export function toolResult(envelope) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(envelope) }],
+        structuredContent: envelope,
+        isError: !envelope.ok,
+    };
+}
+/** The capabilities the server exposes for a transport, in registry order */
+export function mcpCapabilities(transport = 'stdio') {
+    return listCapabilities().filter((c) => c.mcp && (transport === 'stdio' || !c.mcp.stdioOnly));
+}
+/** Network-reading tools get `openWorldHint`; every tool is read-only and idempotent */
+function annotationsFor(capability) {
+    const reachesDocs = ['docs', 'compat', 'changes', 'detect'].includes(capability.cli.command[0]);
+    return {
+        title: `adaptable ${capability.cli.command.join(' ')}`,
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: reachesDocs,
+    };
+}
+/** Builds the server; the caller connects a transport */
+export function createServer(options = {}) {
+    const transport = options.transport ?? 'stdio';
+    const defaults = options.defaults ?? {};
+    const manifestMaxAgeMs = options.manifestMaxAgeMs ?? MANIFEST_MAX_AGE_MS;
+    const server = new McpServer({ name: CLI_PACKAGE, version: CLI_VERSION }, { instructions: SERVER_INSTRUCTIONS });
+    for (const capability of mcpCapabilities(transport)) {
+        const tool = capability.mcp.tool;
+        server.registerTool(tool, {
+            title: annotationsFor(capability).title,
+            description: capability.description,
+            inputSchema: toolInputSchema(capability),
+            annotations: annotationsFor(capability),
+        }, async (args) => {
+            const { input, globals } = splitArguments(args, capability);
+            const envelope = await runCapability(capability.name, input, { ...defaults, ...globals }, { manifestMaxAgeMs });
+            return toolResult(envelope);
+        });
+    }
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,145 @@
+---
+name: adaptable-debug
+description: "Use when a running AdapTable grid misbehaves or the user asks what the grid is doing right now: a Layout, Column Filter, Grid Filter, Format Column, Styled Column, Calculated Column or Alert not applied; wrong columns or rows; State not persisting, loading or migrating; AdapTable console errors; or to extract Adaptable State, columns, logs or Grid Info from a page — and, when a problem cannot be resolved, to assemble an anonymised support case or feedback package. Works through window.__ADAPTABLE_DEVTOOLS__ with whatever browser tool is available. Not for compile/type errors or new features (adaptable-dev)."
+---
+
+# adaptable-debug — diagnose a running AdapTable grid
+
+The grid is the evidence. Everything below reads it through
+`window.__ADAPTABLE_DEVTOOLS__` before touching source. Shared protocol, read
+once: [grounding](references/_shared/grounding.md) (always first),
+[validation loop](references/_shared/validation-loop.md),
+[conversation](references/_shared/conversation.md),
+[guards](references/_shared/guards.md). Command bindings are in
+[capabilities](references/_shared/capabilities.md); the in-page API is
+[devtools-api](references/devtools-api.md); the triage table is
+[symptoms](references/symptoms.md).
+
+## Phase 1 — Ground
+
+Run `detect` (see grounding) so the checks later target the installed major.
+**Tell** the user which app and page you expect the grid on, and confirm it
+is running; a stale dev server diagnoses a grid that is not the one on screen.
+
+## Phase 2 — Access
+
+Use the harness's browser tool when one exists — any tool that can evaluate
+JavaScript on the page can call the DevTools global.
+
+With no browser tool, **tell** the user to paste these three calls into the
+browser console and paste the results back (the global is `window.__ADAPTABLE_DEVTOOLS__`):
+
+```js
+__ADAPTABLE_DEVTOOLS__.getPersistentState()
+__ADAPTABLE_DEVTOOLS__.getColumns()
+__ADAPTABLE_DEVTOOLS__.getLogs(undefined, { level: ['error', 'warn'] })
+```
+
+Save whatever comes back to scratch files. Files the user already collected
+with these calls (a support bundle: `persistent-state.json`, `columns.json`,
+`logs.json`, `grid-info.json`) are the same evidence — start at phase 4 with
+them rather than asking for a fresh capture. Never write ad-hoc in-page
+scripts that reach into grid internals — the DevTools calls are the
+supported surface; `help()` on the global prints its own usage.
+
+## Phase 3 — Collect
+
+Save each result to a scratch file (not into the conversation):
+
+1. `listInstances()` — several ids means **ask** which grid is misbehaving;
+   diagnosing the wrong instance wastes the whole cycle.
+2. `getGridInfo(id)` — versions, options summary, environment. **Strip the
+   licence key before the file is shown, quoted or attached** (guards).
+3. `getLogs(id, { level: ['error', 'warn'], limit: 100 })` — errors and
+   warnings first; widen only when they are empty.
+4. `getRecentActions(id, 50)` — what changed last ("who moved the Layout").
+5. `getColumns(id)` → `columns.json` — the effective columns, the file every
+   later check uses. `getColumnInfo(id, '<colId>')` when one column is
+   implicated; it is cheaper than reading everything.
+6. Only the implicated section: `getState(id, '<Section>')`. **Never** fetch
+   the whole State when one section is in question.
+7. `getPersistentState(id)` when the symptom concerns persistence or
+   migration, or whenever live behaviour contradicts the source.
+
+Calling any of these before the grid mounts returns nothing useful — if the
+instance list is empty, the problem is mounting, not State (symptoms.md).
+
+## Phase 4 — Validate what you collected
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary check state persistent.json --columns columns.json --kind persistent
+npx -y @adaptabletools/adaptable-mcp@canary check expression "<suspect rule>" --module <Module> --columns columns.json
+```
+
+A persisted State that fails explains most "impossible" behaviour in one
+run. Rules extracted from live State get the same expression check a new one
+would (validation loop).
+
+## Phase 5 — Triage
+
+Work the symptom through [symptoms](references/symptoms.md): symptom →
+where to look → likely causes → docs.
+
+Always compare the live State against the source `initialState`. Persisted
+State shadowing source edits is the most common impossible bug: the user (or
+an earlier session) saved a Layout, and every source edit since has merged
+*underneath* it. When that is the story, explain in plain terms before
+proposing anything — the user's saved work is in that State (guards): the
+state key decides which saved State loads; a section's `Revision` in
+`initialState` (a number, or `{ Key, UpdateStrategy: 'Override' |
+'KeepUserDefined' }`) is how a source change deliberately replaces that one
+persisted section on the next load
+(`docs get dev-guide-adaptable-state-updating-initial-state`); and
+`stateApi.reloadInitialState()` discards the whole saved State. The usual fix
+is a `Revision` bump on the section the user is editing, not a cleared store.
+
+Distinguish AdapTable's Layout from AG Grid's own column state: a column
+AG Grid reports as moved is not evidence the Layout changed; `getState(id,
+'Layout')` is.
+
+## Phase 6 — Fix at the source
+
+Fixes land where the behaviour is owned: `initialState` for State, Options
+for wiring, `columnDefs` for typing (adaptable-dev rules). Hand-editing
+persisted State in storage is not a fix — it desynchronises the user from
+their own saved State and the next save overwrites it.
+
+When wiring is suspect (modules, wrapper, direct grid use, ColDef
+ownership), run `check setup` and fix what it names.
+
+## Phase 7 — Verify
+
+Reload the page and repeat the phase-3 reads that showed the problem: the
+section now matches the source, the logs are clean, the column set is the
+expected one. `restoreState` is an experiment, not a fix — only with the
+user's explicit confirmation, and say what it discards before running it
+(guards).
+
+## Phase 8 — Support case or feedback (unresolved, or on request)
+
+After one full collect → validate → triage cycle without a root cause, or
+whenever the user asks, assemble the package from
+[ticket-template](references/ticket-template.md): symptom, expected vs
+actual, steps; the relevant State section and `columns.json`; the Options
+snippet with keys stripped; the logs.
+
+**Ask** before including any row-data values. The default is scrubbed:
+
+```bash
+npx -y @adaptabletools/adaptable-mcp@canary anonymise <bundle file> --out anonymised.json
+```
+
+Try to reproduce the symptom in the public support template linked from
+`getting-started-integration` before filing. Write
+`ADAPTABLE_SUPPORT_CASE.md` (destination: the form on the
+`adaptable-support-ticket` support page). **The skill never sends anything**
+— the user reviews the file and submits it.
+
+For feedback about this tooling itself, use
+[feedback-template](references/feedback-template.md) →
+`ADAPTABLE_FEEDBACK.md`: which skill and its `VERSION.md`, what the agent
+did, what the user corrected, and the docs page that would have prevented it.
+
+**Done when:** the root cause is stated with the evidence that proves it, a
+source fix is applied or proposed, and verification ran or is handed over —
+or a reviewed `ADAPTABLE_SUPPORT_CASE.md` / `ADAPTABLE_FEEDBACK.md` exists.

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

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

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