Documentation site + 5 reproducible tutorials

[uwarring82]

Stand up a full documentation site for iontrap-structure, mirroring the sibling iontrap-dynamics 1:1 (tooling, structure, branding, reproducibility guarantees). Docs / tooling / tests only — no package source or public-API change. Decision/findings trail in docs/LOG.md.

Site (MkDocs + Material + mkdocstrings)

• Welcome (hero), Overview (the producer/consumer boundary diagram + the physics), Getting Started (install + runnable quick start), Conventions (§10/§11 mode contract), Validation (the oracle catalogue), Provenance, and an API Reference generated from docstrings via mkdocstrings.
• Branding (tokens.css / extra.css) is shared verbatim with the sibling for cross-project visual consistency (provenance in docs/LICENCE). The internal docs/LOG.md lab-notebook is excluded from the published site.

Reproducible tutorials — the FAIR core

• Markdown is the single source of truth; tools/build_tutorial_notebooks.py generates Colab notebooks (with a --check freshness guard), and tests/docs/test_tutorials_execute.py executes every tutorial end-to-end with its embedded asserts as the oracle.
• Five tutorials, each with a Colab badge and a self-test:
  1. Your first ion crystal — James-1998 positions, ω_z COM and √3·ω_z stretch to machine precision.
  2. The ModeConfig handoff — to_mode_configs() across the boundary; runs with or without iontrap-dynamics installed.
  3. Mixed-species crystals — the symmetric-D vs M⁻¹H contrast; generalized-eigenproblem residual ~8e-15.
  4. The plasma coupling parameter Γ — exact 1/T scaling, Γ(1 mK) ≈ 3728 ≫ 170, crossover ~22 mK.
  5. The linear→zigzag transition — a mode goes soft, critical aspect ratio ω_r/ω_z ≈ 2.5 (N=5), and the stability guard fires.

CI/CD and packaging

• ci.yml gains docs (mkdocs build --strict), tutorials (execute), and notebooks (Colab freshness) jobs; the unit matrix deselects tutorial.
• docs-deploy.yml publishes the site to GitHub Pages on main (needs Settings → Pages → Source: GitHub Actions set once).
• New [docs] / [plot] extras, a tutorial marker + --strict-markers, a Documentation URL. Docs are dual-licensed (docs/LICENCE): Coastline CC BY-SA 4.0, Sail tutorials CC BY-NC-SA 4.0; code stays MIT.

How it was built & verified

The five tutorials were drafted and self-verified in parallel by a workflow (each agent ran the actual pytest tutorial harness on its page until green), then manually reviewed for voice/consistency (two cosmetic Next-steps formatting fixes applied).

Verified locally: ruff clean · mypy clean · mkdocs build --strict clean · notebook freshness clean · pytest 58 passed / 1 skipped (53 unit + 5 tutorials; the skip is the optional iontrap-dynamics interop export).

Note: a one-time repo setting (Settings → Pages → Source: GitHub Actions) is required before the first Pages deploy succeeds.

🤖 Generated with Claude Code