Migrate docs from MyST to Quarto + prototype auto-generated reference

[MaxGhenis]

Two changes bundled:

1. MyST → Quarto toolchain swap

• Replace `docs/myst.yml` with `docs/_quarto.yml` (same navigation).
• Convert `{literalinclude}` directives in `docs/examples.md` to Quarto include syntax (`{.python include="..."}`) — the only MyST-specific construct in the existing docs.
• `make docs` now runs `quarto render docs`; `make docs-serve` runs `quarto preview docs`.
• `.github/workflows/pr_docs_changes.yaml` installs Quarto via the official action instead of npm-installing mystmd.
• Update `docs/.gitignore` for `_site` / `_freeze` instead of `_build`.

All 11 existing MyST pages render cleanly under Quarto without prose changes — CommonMark overlap is near-total.

2. Prototype: auto-generated reference

• `docs/_generator/build_reference.py` — introspects a country model's `TaxBenefitSystem` and writes one `.qmd` per variable.
• `make docs-generate-reference` target wires it into the build.
• Verified on `policyengine-us`: emits ~5k variable pages plus a program-coverage page derived from `programs.yaml`. CHIP filter produces 34 variable pages + 1 programs page + 56 tree indices; Quarto compiles all cleanly.

Generated pages are not yet committed to the repo — the generator is scaffolded, but when to run it (per-release vs in CI) is a follow-up decision.

Why Quarto

• One source, multiple outputs (HTML site + PDF paper from the same `.qmd`).
• Live code execution during build (tutorials track the installed package).
• Computational blocks can call PolicyEngine directly to regenerate reference on each release.
• Quarto reads MyST-flavored markdown natively; migration cost for the existing content was ~30 min.

Test plan

• `make docs` builds cleanly (11/11 pages render)
• CHIP-filtered reference generator runs and renders in Quarto
• CI passes

[MaxGhenis]

Quick take — I'd like to see this split before landing.

What's actually in the PR (pre-rebase)

Four distinct commits:

• 3216920 — new policyengine.graph module: AST-based variable dependency extractor (no runtime import of country code)
• 18cd8e2 — reference-generator prototype using the graph
• 7a421da — MyST → Quarto toolchain swap (~5 files)
• 7abae0a — full docs rewrite (2986 → 847 lines, user-journey split)

Strong positives

• policyengine.graph is genuinely useful. Static AST means no install needed, which matters for agent sessions. Solves the "grep shows mentions, but what's the dataflow DAG" gap.
• Docs rewrite direction is right. The user-journey split (getting-started → households → reforms → microsim → outputs) is better for fresh-session discoverability than the old 731-line core-concepts.md.
• Quarto swap is defensible — native multi-output (HTML + PDF from one source), better figure handling.
• Reference generator correctly scaffolded — prototype, generated pages not checked in.

Concerns

1. Too bundled. Four independent concerns in one PR. Review cost scales with coupling; each could stand alone:

   • (A) Quarto toolchain swap
   • (B) policyengine.graph + reference generator (depends on A if you want Quarto-native output)
   • (C) Docs rewrite (depends on A, independent of B)

   Suggest splitting so A lands first (small, mechanical), then B and C can review in parallel.

2. "Rewrite from scratch" may throw away [v4] Refresh docs + example for agent-first surface #295's work we just shipped this week (docs refreshed for v4). Need to confirm the new content isn't re-deriving things we already fixed (e.g., dict-reform-first examples, state_code not state_code_str, [N].amount indexing convention). Worth diffing commit 7abae0a against current docs/ to make sure the wins from [v4] Refresh docs + example for agent-first surface #295 carried over.

3. Timing. Branched pre-rebase so the 95-file diff is inflated. After Launch v4: agent-first surface, shared microsim base, dict reforms, refreshed docs #298 merges to main and this rebases, the real diff should be ~40 files and much easier to review.

4. src/policyengine/cli.py snuck in. Not mentioned in any of the 4 commit messages — looks like it got bundled accidentally. Verify intent before shipping; CLI is its own discussion (argparse vs typer, entry point registration, etc.).

5. Quarto install in CI. quarto render pulls the ~120MB Quarto binary. First-run cost is real. MyST was npm-light. Maybe fine, maybe not — depends on how often docs jobs run. Worth measuring a cold CI run before accepting the trade.

6. Graph module as PyPI surface. Should it be an optional extra (policyengine[graph])? It's useful but not core to tax-benefit microsim. Keeps the base install lean.

Recommendation

Don't merge as-is. Split into 2-3 PRs, rebase after #298. I'd review A (Quarto swap) in ~15 min, B (graph + generator) in ~45 min, C (docs rewrite) in ~1 hour — bundled, needs a full afternoon and approval confidence is lower.

[MaxGhenis]

All six points valid. Plan:

1. Close this PR. Confirmed the branch was based off a stale local main — that's why unrelated v4 work (cli.py, extra changelog fragments, half-edited core-concepts.md that [v4] Refresh docs + example for agent-first surface #295 already rewrote) showed up in the diff. Not salvageable by rebase alone; cleaner to restart.

2. After Launch v4: agent-first surface, shared microsim base, dict reforms, refreshed docs #298 merges, open three separate PRs stacked on current main:

   • PR A — Quarto toolchain swap. Just _quarto.yml replacing myst.yml, the Makefile change, the CI workflow change, the {literalinclude} → {.python include=} conversion in examples.md. ~5 files. Should review in ~15 min.
   • PR B — policyengine.graph + reference generator. Graph module as an optional extra (policyengine[graph] per your suggestion) so base install stays lean. Generator script under docs/_generator/ emits .qmd pages.
   • PR C — Docs rewrite. Starts from the Launch v4: agent-first surface, shared microsim base, dict reforms, refreshed docs #298 docs (not the pre-[v4] Refresh docs + example for agent-first surface #295 versions), diffs against my user-journey rewrite, keeps [v4] Refresh docs + example for agent-first surface #295's dict-reform-first examples / state_code naming / [N].amount indexing conventions. Essentially: use my new navigation + page structure, but port over the specific factual updates from [v4] Refresh docs + example for agent-first surface #295.

3. Measure Quarto CI cost before PR A lands — will add timing numbers to the PR description.

4. For PR C, once Launch v4: agent-first surface, shared microsim base, dict reforms, refreshed docs #298 is in I'll diff docs/ as-merged against my rewrites at file-by-file level and list specifically what's preserved, what's restructured, what's new. That way the review is "did the rewrite keep all the v4 correctness wins." Not "read 2000 lines of new prose."

Closing this and will reopen as A/B/C once #298 merges.