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

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.

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.