Improve docs quality: explanations, terminology, missing sections

[cweniger]

Summary

Second-pass documentation quality pass — all non-functional issues: missing explanations, confusing phrasing, stale terminology, and incomplete sections. No code logic changed (except one docstring fix in svd.py).

Wrong/misleading content fixed

• CLI override example had graph.theta.estimator.optimizer.lr — wrong path; correct flat path is graph.theta.estimator.lr
• buffer.max_samples description said "disfavoured" (ambiguous internal term); now says "permanently removed"
• gamma comment in configuration.md said "0=posterior, 1=prior" — inconsistent with flow.md; unified to "0=tight around posterior, higher=broader"
• DynamicSVD.forward docstring said "Returns zeros before first SVD update"; actual code returns torch.randn — fixed

Missing documentation added

• sample: config section was used in every example but never documented — added with posterior/ppd examples
• scaffolds and resample node keys had no explanation beyond a one-word comment — clarified inline
• flow-density.md: sbi/nflows net types (nsf, maf, etc.) require pip install falcon-sbi[sbi] — now stated; zuko_* types work by default
• ToeplitzWhitener: exported from falcon.embeddings but missing from embeddings.md — added with YAML example
• param_dim vs full_param_dim distinction in Product — added note in product.md
• gamma semantics differ between Flow and GaussianFullCov — added explicit note in gaussian.md

Terminology / naming fixes

• SNPE_gaussian → GaussianFullCov in examples/04_gaussian/config.yml and examples/05_linear_regression/config.yml (old internal name; class is GaussianFullCov)
• config.yaml → config.yml in examples/01_minimal/config.yml resume comment
• api/index.md package tree: flow_density, stepwise_base, networks, embedded_posterior now marked (internal)

Explanation improvements

• cosine/sine/uvol distribution types now include use-cases (e.g. "pdf ∝ sin(θ) — use for declination-like angles")
• lognormal restriction note now explains why (hypercube CDF path not implemented)
• DynamicSVD YAML example expanded with buffer_size and momentum; DiagonalWhitener dim clarified as "must match flattened input size"
• Getting started: simulator and observation code now have shape comments; note added explaining what happens when embedding: is omitted
• ppd CLI entry now has a description: "forward model evaluated at posterior samples"
• gamma in flow.md: removed "amortization" framing (has a different meaning in the SBI literature); replaced with plain description of proposal breadth

Test plan

• Verify falcon launch buffer.max_samples=32768 graph.theta.estimator.lr=0.001 accepted by CLI
• Verify docs build without broken references (mkdocs build)
• Verify from falcon.embeddings import ToeplitzWhitener succeeds

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 10.42%. Comparing base (2b137a6) to head (6a2e78a).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #107   +/-   ##
=======================================
  Coverage   10.42%   10.42%           
=======================================
  Files          30       30           
  Lines        3896     3896           
=======================================
  Hits          406      406           
  Misses       3490     3490           

Flag	Coverage Δ
unit	10.42% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.