Repoint migration references ahead of retiring RAC-MIGRATION.md

AGENTS.md now points at the playbook's gotcha catalog (which is where
the retired doc's transferable lessons moved); the fidelity harness
comments cite the playbook; the density preset comment carries its
revisit context inline.

Author: microbit-matt-hillsdon

AGENTS.md

@@ -1,12 +1,15 @@
 # AI agent notes
 
-## RAC/Panda migration
+## Styling/theming
 
-This app is migrating from Chakra UI to react-aria-components + Panda CSS
-via `@microbit/ui`. **Read `RAC-MIGRATION.md` at the repo root before any
-styling/theming/UI work** — it is the status log and app-specific plan; the
-method and gotcha catalog are in `../ui/docs/migration-playbook.md`. The
-private theme package is the sibling repo `../python-editor-v3-microbit`.
+This app uses react-aria-components + Panda CSS via `@microbit/ui`
+(migrated from Chakra UI, July 2026). **Read the gotcha catalog in
+`../ui/docs/migration-playbook.md` before styling/theming/UI work** —
+Panda's static extraction rules and RAC behaviours catalogued there still
+apply to new code. The private theme package is the sibling repo
+`../python-editor-v3-microbit` (consumed via a manual `node_modules`
+symlink locally — re-create it after `npm install`). The visual fidelity
+harness is `npm run fidelity` (see `bin/fidelity.mjs`).
 
 ## Commands
 

bin/fidelity.mjs

@@ -23,7 +23,8 @@
 //   npm run fidelity -- --compare-only
 //
 // The split flags support cross-boundary runs that need paired
-// sibling-package versions (see RAC-MIGRATION.md): rebuild the private
+// sibling-package versions (see ../ui/docs/migration-playbook.md §6,
+// "Fidelity, both sides"): rebuild the private
 // package at the old commit, record the baseline half, restore everything,
 // then run the compare half.
 //

src/deployment/default/panda-preset.ts

@@ -16,9 +16,11 @@ const toTokens = (values: Record<string, string | number>) =>
 // spacing/size scale is Chakra's 0.25rem grid × 0.88, and fontSizes from
 // `md` up are × 0.9 (xs/sm kept full-size so text never gets too small).
 // The adjacent common-sizes.ts/font-sizes.ts are the (only) home of the
-// values now Chakra is gone. The team may revisit whether
-// this density stays after the migration (see RAC-MIGRATION.md notes) —
-// for now the port replicates it.
+// values now Chakra is gone. The team may revisit whether this bespoke
+// density stays or aligns with the family scale (the editor is more
+// information-dense than the other apps, so there may be grounds to keep
+// it); if alignment wins, delete these overrides and re-run the visual
+// pass. For now the port replicates it.
 const shrunkenScale = toTokens(commonSizes);
 const shrunkenFontSizes = toTokens(fontSizes);
 

src/e2e/fidelity.spec.ts

@@ -7,7 +7,8 @@
  * of the default e2e project; bin/fidelity.mjs runs it twice — once against
  * a baseline git ref with --update-snapshots, then against the working tree
  * — and the Playwright HTML report shows the diffs. Baselines are per-run
- * artefacts in .fidelity/, never committed. See RAC-MIGRATION.md.
+ * artefacts in .fidelity/, never committed. Method and lessons:
+ * ../ui/docs/migration-playbook.md, "Fidelity harness".
  */
 import { expect, Locator, Page } from "@playwright/test";
 import { test } from "./app-test-fixtures.js";