Handover — documentation chat (living status file)

Owner: the documentation / tutorials / examples chat. Branch: claude/awesome-kapitsa-d5e97d (pushes to main). Purpose: single source of truth for the docs chat’s progress. Always kept current — any agent or session can resume from this file alone.

Last updated: 2026-05-21 (round 14 — session wrap / archive).

Mission

Own docs/ — the Sphinx site (tutorials, user guide, top-level pages), README.md, and the example-input narrative. Keep every user-facing page coherent with what has actually shipped. Utilize the runtime citation database (python/vibeqc/output/citations/) the output chat maintains; do not hand-curate citation lists that the database already renders.

Working conventions (from CLAUDE.md):

  • Rebase-then-push to main; never force-push.

  • Every commit ships green (docs changes are low-risk but the Sphinx toctree must stay valid — no orphaned pages).

  • Lightweight ongoing doc cadence: fix what you see while you’re there; new behaviour → cross-reference same session.

Completed work (this chat, chronological)

Round 1 — citation surface (commit 9866ab8)

  • docs/user_guide/citations.md — NEW. Full reference for the vibeqc.output citation database: routing semantics, the vibeqc-cite CLI, dry-run pre-flight, schema for extending.

  • docs/tutorial/40_auto_citations.md — NEW. End-to-end manuscript-bibliography workflow.

  • citing.md, functionals.md, output_files.md — pivoted to the auto-emission model; hand-curated tables demoted to backup.

Round 2 — v0.8.0 flagship features (commit 775d4ca)

  • docs/tutorial/41_ediis_diis_hybrid.md — NEW. Stiff molecular SCF with the EDIIS+DIIS hybrid.

  • docs/tutorial/42_fermi_dirac_smearing.md — NEW. Periodic metals / small-gap smearing.

  • docs/user_guide/bipole.md — NEW. BIPOLE periodic-RHF status page (note: substantially rewritten by the periodic-dev chat since — now documents the Ewald-J multi-k path).

Round 3–6 — migration quartet + troubleshooting + refreshes

  • docs/troubleshooting.md — NEW (commit 860afdd).

  • docs/user_guide/from_pyscf.md — NEW (commit 9cc518d).

  • docs/tutorial/43_vq_queue_remote_job.md — NEW (commit b1cf866).

  • Tutorials 31/32/37/38 — refreshed with theory + refs + output snippets (commit 23aac93).

  • docs/user_guide/from_crystal.md — NEW (commit bc88ee8).

  • docs/user_guide/from_orca.md — NEW (commit 2eb7c9f).

  • docs/user_guide/from_gaussian.md — NEW (commit d399c11).

  • README.md — full refresh, was pinned to v0.1.0 (commit eb2d512).

  • docs/tour.md — banner sample refreshed to v0.8.1 (commit 8f23544).

Round 7 — post-rebase toctree fix (commit e1e62bd3)

  • docs/user_guide/index.md — added non_hf_solvers and settings to the toctree (both were orphaned — Sphinx warnings, pages unreachable).

  • docs/handover_docs_chat.md — THIS FILE created.

Round 8 — wavefunction-methods coverage (commit beaa8403)

  • docs/features.md — added a “Wavefunction methods” section (FCI / selected-CI / DMRG / v2RDM / transcorrelated-CI table, active-space note, parity note). Fixed the stale “~1000+ tests” line → ~1800 functions / ~190 files.

  • docs/user_guide/non_hf_solvers.md — replaced the stale “run_job only exposes rhf/uhf/rks/uks” claim with a proper “run_job integration” section (the FCI / selected-CI / DMRG / v2RDM / transcorrelated-CI methods + active_space= kwarg all reach through run_job now).

Round 9 — run_job method table + ωB97X tutorial (commit 71e4f947)

  • docs/tour.md — added a “Methods run_job understands” table to the § “The simple way: run_job” section (the wavefunction methods + active_space= were invisible from the high-level entry-point docs).

  • docs/tutorial/44_range_separated_wb97x.md — NEW. Worked tutorial for the v0.8.0 first range-separated hybrid: theory of position-dependent exact exchange, the HOMO ≈ −IP property as a ground-state-only demonstration (B3LYP/PBE0 underestimate the water IP by 4-5 eV; ωB97X lands within ~0.5 eV), the direct-SCF-only requirement, the stiff-open-shell level-shift recipe, shipped-vs-queued table, references. Wired into tutorial/index.md after 15_functional_comparison.

Round 10 — examples audit + FCI example (commit 8d51674d)

  • examples/molecular/input-h2-fci.py — NEW runnable example: exact Full CI vs RHF on H2 / 6-31G, the basis-set correlation energy. The first examples/ script for the wavefunction solvers.

  • examples/README.md — added a “Correlated + wavefunction methods” section (UMP2 / SCS-MP2 / B2PLYP / RI-MP2-residual / FCI — none were listed before); added the SCF-modes + initial-guess examples to the SCF-infrastructure section; fixed the stale “run_job is molecular-only” claim (run_periodic_job exists).

  • docs/tour.md, docs/user_guide/output_files.md — fixed the stale “Four runnable example inputs” claim (there are ~19 under examples/molecular/ alone).

Round 11 — homepage capabilities refresh (commit 7fb1771f)

  • docs/index.md § “Capabilities today” — the plain-prose capability summary (NOT an admonition — docs-chat-owned) had drifted badly: it omitted double hybrids, the meta-GGA family, ωB97X, the wavefunction solvers, RIJK/RIJCOSX, ECPs, CPCM solvation, D4, hybrid periodic DFT, the citation surface, and the vq queue; claimed “90 basis sets” (actual 142). Rewritten to match the current feature matrix.

Round 12 — multi-k GDF status refresh (commit 021d9356)

  • docs/features.md — the periodic table KRHF/KRKS rows said “non-Γ pending … true multi-k still raises”. Commits 8f7d3b51 (multi-k GDF wired into run_periodic_job via gdf_kmesh) and 204b8faa (multi-k Ewald gauge fix, 0.000 mHa vs Γ) make that stale. Rewrote the two rows + the reference-benchmark paragraph.

  • docs/user_guide/multi_k_scf.md — moved the run_krhf_periodic_gdf / run_krks_periodic_gdf non-Γ entry out of “Not native yet” into the available list; rewrote the roadmap closing paragraph (remaining work is perf / dense-solid scaling, not multi-k correctness).

Round 14 — session wrap (current)

  • The citation chat landed 3e4086fd (“route the v0.9.0 meta-GGA + RSH functionals”) — wb97x / tpss / scan / r2scan / … now have routes. Next-step item 4 below is RESOLVED by that sibling commit.

  • docs/tutorial/44_range_separated_wb97x.md — updated the closing citation note: the wb97x route is now registered, so the “until the route is registered, vibeqc-cite flags it unrouted” caveat was dropped.

State of the docs after the 2026-05-20 rebase

The rebase pulled 87 commits from sibling chats. Doc-relevant landings and their current coverage status:

Feature (sibling chat)

Docs status

FCI / selected-CI / DMRG / v2RDM (vibeqc.solvers, method='fci')

user_guide/non_hf_solvers.md + tutorial/non_hf_solvers.md exist (sibling-authored). Gap: not in features.md.

Meta-GGA (TPSS, M06-2X, SCAN, r²SCAN)

functionals.md table updated by sibling. ✅

Range-separated hybrid ωB97X

functionals.md § “Range-separated hybrids” updated by sibling. ✅ for user guide; no dedicated tutorial.

Native D4 dispersion (Phase D4b)

In progress (sibling). compute_d4 already in features.md. handover_d4_native.md tracks it. No user-facing change needed yet.

Direct SCF

user_guide/scf_modes.md exists (sibling). ✅

Γ-point COSX for molecular crystals

NEW driver; not yet documented in density_fitting.md periodic section.

CIF writer + vibeqc-outputs CLI

output_files.md updated by sibling (Phase D2/D3). ✅

Next steps / priorities (ordered)

  1. CCSD — landing now, NOT doc-ready. Coupled cluster is in active debug on main (commits cccc108b T1-dressed Fock builder, cd38c315 “DIIS converges”, many fix(ccsd) — status “converges roughly”). When it goes green it is a large doc job: a features.md wavefunction-section row, and every migration guide (from_pyscf / from_orca / from_gaussian) currently lists “no CCSD / vibe-qc tops out at MP2” under “what the other code does better” — all four need updating. Watch the CCSD handover doc; do not document until it is stable + tested.

  2. Native D4 (Phase D4b) — in progress (commits bac8f32e molecular_c6 pipeline, c225ead1 reference-system catalogue, 3eb9e170 CN weighting, etc.). When D4b replaces the optional dftd4 dependency with the in-tree implementation, the features.md D4 row + functionals.md dispersion notes need a “native, no dftd4 dependency” update. Watch handover_d4_native.md.

  3. ADIIS accelerator (aecde53f, D1b) — already documented in scf_convergence.md by the SCF chat. ✅ No action; spot it firing in tutorial/41_ediis_diis_hybrid.md’s accelerator table on a future refresh.

  4. ✅ RESOLVED (2026-05-21, sibling commit 3e4086fd) — the meta-GGA + RSH functionals (wb97x, tpss, scan, r2scan, …) are now routed in database.toml. tutorial/44 updated to drop the now-stale “unrouted” caveat.

  5. Γ-point COSX for molecular crystals (b2b8f33c): make_periodic_gamma_cosx_jk_builder is still C++-only — not exported in python/vibeqc/__init__.py. No user-facing Python API → no doc action until a binding lands.

  6. Ongoing: keep features.md / README.md / homepage in sync as sibling chats land features.

Blockers / assumptions / decisions

  • No blockers. Docs work is not gated on any sibling chat.

  • Assumption: features.md is docs-chat-owned (per CLAUDE.md § 5 — per-quarter features.md regen is a docs cadence item). Editing it to add the wavefunction section is in scope.

  • Decision: the homepage admonitions in docs/index.md (known-issues block, version banners) are treated as release-chat-owned — the docs chat does not edit them. The release chat refreshes them per the per-tag mechanical sprint.

  • Decision: CHANGELOG promotion ([Unreleased] → tagged) is release-chat-owned per CLAUDE.md § 13. The docs chat does not touch CHANGELOG section structure.

  • Decision: citation lists are NOT hand-curated where the runtime database covers them — docs/citing.md and functionals.md § Citations point at the auto-emitted .bibtex and keep only backup tables.

  • The shared parent-checkout venv has a stale compiled _vibeqc_core.so — import vibeqc fails with an ImportError on missing symbols. Citation-database code was verified by importing the pure-Python vibeqc.output.citations submodules in isolation (stubbing the banner module). Anything needing the C++ extension cannot be run-verified from this worktree without a rebuild (pip install -e . --no-build-isolation --force-reinstall).

How to resume

  1. git fetch origin && git pull --rebase origin main.

  2. Read this file’s “Next steps” list; pick the top item.

  3. Check the sibling handover files in docs/handover_*.md for any feature that landed since this file’s “Last updated” date and needs doc coverage.

  4. Do the work in small increments; after each milestone: commit with a meaningful message, rebase, push.

  5. Update this file’s “Completed work”, “Next steps”, and “Last updated” fields before the final push of each session.