Docs: new-entity persistence stack, modal size tiers, spec anchor stability, test harness notes

AGENTS.md

@@ -131,3 +131,9 @@ source of truth is `version` in `package.json`, injected as `__APP_VERSION__`.
 High coverage on `src/core/` (parsing, detection, profiling, reference resolution, fit
 transforms, import normalization). Lighter on components. Extract testable logic out of
 components into core/stores where practical.
+
+Component tests (happy-dom) share a harness shape: `createRoot` + `act` with
+`IS_REACT_ACT_ENVIRONMENT = true` set at module level, stores reset in `beforeEach`, and
+`vi.mock('../services/chart-renderer', …)` for anything that embeds a chart (vega-embed is
+integration-heavy; a resolved no-op handle suffices) — see any `components/*.test.tsx`.
+Infrastructure tests that touch IndexedDB run against `fake-indexeddb`.

docs/architecture/03-modal-system.md

@@ -610,12 +610,16 @@ share the open/close/snapshot/URL logic rather than reimplementing it.
 
 1. Add the name to the `ModalName` union.
 2. Add one `MODAL_REGISTRY` entry (title, component; `getState`/`hasError`/
-   `getError` if it edits; `isUrlNavigable` + `init(arg)` if navigable).
+   `getError` if it edits; `isUrlNavigable` + `init(arg)` if navigable;
+   `dismissOnBackdrop: false` if it holds in-progress work).
 3. Write the body component; it reads/writes its feature store (e.g.
    `useDatasetStore`, `useChartBuilderStore`) via a narrow selector.
-4. If navigable, add its hash form to the URL sync and restore logic.
-5. If it has a keyboard shortcut or workflow trigger, wire that to
+4. If it isn't a small form, add its name to the **size-tier mapping in
+   `ModalShell`** (`isLarge`/`isXLarge`) — the one shell edit a new modal can
+   need; without it the modal renders at the small-form size.
+5. If navigable, add its hash form to the URL sync and restore logic.
+6. If it has a keyboard shortcut or workflow trigger, wire that to
    `openModal(name, arg)` — never to `activeModal` directly.
 
-No edits to the shell render, the close logic, or the change-detection code are
-needed: those are generic and driven entirely by the registry.
+The shell render, close logic, and change detection need no edits: those are
+generic and driven entirely by the registry.

docs/spec/README.md

@@ -7,6 +7,7 @@ A UX/behavioral specification of **Astrolabe**, a browser-based snippet manager
 - Start with [00 · Product Overview](00-product-overview.md) for orientation and the glossary.
 - Each subsequent file is one feature area and can be read on its own; they cross-reference each other by title.
 - Every section describes intended behavior plus testable acceptance points ("The user can…", "When X, the system…").
+- Section numbers and lettered headings (e.g. `§03G`, `§09B`) are **stable anchors** — code comments reference them. Extend by appending the next letter/number; never renumber existing ones.
 
 ## What this spec deliberately omits