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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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