Add dataset library, extract-to-dataset, and render-time reference resolution

docs/architecture/10-interaction-and-feedback.md

@@ -180,6 +180,27 @@ contract; cite it, not the external source.)_
 other shows the text visually with no live role. Two live regions would announce the same
 message twice.
 
+**Resolved — feature-modal dismissal & initial focus.** A feature modal (Datasets, and
+later Settings/Chart Builder) is a **passive** `dialog-modal`: dismissed by the close
+button, Escape, or a backdrop click (a passive modal carries no in-flight transaction, so
+an outside click is a safe cancel — unlike the `alertdialog` confirm, where backdrop-dismiss
+is forbidden). `role="dialog"` + `aria-modal` + `aria-labelledby` the title; focus is trapped
+and **returns to the trigger** on close. Backdrop-dismiss stays correct even for the
+multi-view Datasets manager because an in-progress create/edit form is guarded separately by
+the discard prompt. **Initial focus depends on size** (APG dialog-modal): a large manager
+with semantic content (list + detail) focuses a **static title** (`tabindex="-1"`) so the
+content's start is perceived rather than skipped to the first control; a small form modal
+(Extract) focuses its **primary field**. _(Consulted via /council → WAI-ARIA APG
+`dialog-modal`. This bullet is the contract; cite it, not the APG file.)_
+
+**Resolved — an error names the right fix, not a boilerplate one.** Don't staple a generic
+remedy onto every failure. A missing dataset reference is **not** a JSON/spec syntax problem,
+so the preview gives it a tailored, fixable line — _"Dataset «X» not found. Create it from
+Datasets (⌘/Ctrl+K), or check the dataset name in your spec."_ — instead of the catch-all
+"check your JSON syntax" hint reserved for actual parse/Vega-Lite errors. The fix in the copy
+must match the actual cause (NN/g #9, GOV.UK error-message). The thrown
+`DatasetNotFoundError` carries `datasetName` so the surface can name it.
+
 ## 6. Motion & accessibility as default
 
 Not features to add later — the baseline every surface is built on.
@@ -212,6 +233,7 @@ Not features to add later — the baseline every surface is built on.
 - Treat loading/empty/error as three designed states for every data surface.
 - Adopt the APG keyboard pattern for new widgets; route all global keys through the one
   router.
+- Mark **optional** fields, not required ones (GOV.UK) — e.g. "Comment (optional)".
 - Consult `/council` when this contract is silent — then record the answer back here.
 
 **Don't**
@@ -224,3 +246,6 @@ Not features to add later — the baseline every surface is built on.
   disclosure, the next step in the message.
 - Don't invent a keyboard model, attach ad-hoc `window` listeners, or gate Escape behind
   the typing check.
+- Don't ship a **dead disabled control** as a placeholder for an unbuilt feature — a
+  disabled button explains nothing and is skipped by assistive tech (GOV.UK, NN/g). Omit the
+  action until it works, then show it enabled (e.g. "Build Chart" appears with M4).