fix: make the astra_scope override work and warn on store-less pages with astra content

[EiffL]

Fixes #10.

MyST validates page frontmatter against its own schema and drops unknown keys before transforms run (⚠️ 'frontmatter' extra key ignored: astra_scope), so the documented astra_scope override never reached scopeForFile — a page outside the dotted-filename convention had no way into the scope map, and every astra element on it silently degraded to its neutral fallback in rich themes (no hover cards, no rich panels), even though the directive/role content itself resolves fine.

Changes

1. astra_scope now works. scopeForFile falls back to reading the override from the raw source file's frontmatter block (via the SDK's parseYamlString), preferring the validated vfile frontmatter if a future MyST passes the key through. Both documented forms work — dotted string ("" selects the root analysis) and list.

2. Explicit failures are loud. An astra_scope that names an unknown scope is reported as an error through the diagnostics channel (strict builds gate on it) instead of silently yielding no store.

3. Silent fallback is no longer silent. A page that maps to no scope but still carries astra elements gets a build warning naming both fixes:

   page has 3 astra elements but maps to no analysis scope — rich themes will render them as neutral fallbacks (no resolved store). Name the file after its scope (e.g. "reconstruction.md") or set "astra_scope" in its frontmatter ("" for the root analysis).

   Pages with no astra content stay silent, and the filename-convention miss itself is not an error (that's how non-ASTRA pages are supposed to work).

4. Docs: multi-page.md documents the root ("") override and the new diagnostics.

Testing

• 6 new tests pin all three behaviors (raw-file read incl. dotted/list/root forms, vfile-frontmatter precedence, explicit-override error, warning present/absent) — npx vitest run 100/100, npx tsc --noEmit clean.
• Verified against the DESI DR1 BAO prototype with a bundled build: the warning fires and is attributed to the page; adding astra_scope: "" to an arbitrarily-named page emits the root store and clears the warning.

Independent of #11 (touches src/index.ts scope/transform code only; no overlap with the carrier rendering files).

The remaining item from #10 — the produced-metric carrier type contract (v0.0.6 OutputType: metric) — is not addressed here; it's tied to the metric-materialization work and worth its own issue if it doesn't land with v0.0.6.

🤖 Generated with Claude Code

https://claude.ai/code/session_013EE6NiwH2UhVAUT6cdAQJ4