rafatahmed · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -56,3 +56,15 @@ jobs:
         with:
           name: phreeqc-live-evidence
           path: phreeqc-validation.log
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.13"
+      - name: Install package and docs tooling
+        run: python -m pip install . -r docs/site/requirements.txt
+      - name: Build documentation (warnings are errors)
+        run: python -m sphinx -W --keep-going -b html docs/site build/docs-html
diff --git a/.gitignore b/.gitignore
@@ -64,5 +64,8 @@ tests/fixtures/phreeqc/**/phreeqc.log
 
 # User-supplied manufacturer references are local-only until redistribution
 # permission is established; findings and SHA-256 hashes are versioned in
-# docs/source-sheet-review.md. This covers every PDF in docs/sources/.
+# docs/site/guide/source-sheet-review.md. This covers every PDF in docs/sources/.
 docs/sources/*.pdf
+
+# Internal design specs and plans (local only)
+docs/superpowers/
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+sphinx:
+  configuration: docs/site/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+    - requirements: docs/site/requirements.txt
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,7 +5,7 @@
 - Add experimental irrigation EC25 from speciation (McCleskey 2012 Eq. 8) with explicit partial results, envelope checks and provenance; no accuracy claim.
 - Irrigation EC (M2a): species without a McCleskey coefficient now give a bounded `estimated` result (`bounded`, `ec25_range_ms_cm`, midpoint `ec25_ms_cm`, `uncertainty_ms_cm`, audit `uncovered_bound_ms_cm`; upper limit from 80 S cm2/mol per charge) instead of `partial`; `MODEL_VERSION` is now m2a and `compare_measured_ec` reports `ec25_range_ms_cm` and `within_range`.
 - Irrigation EC (M2b): H2PO4- and HPO4-2 now contribute through 25 C coefficients fitted to Pethybridge, Talbot and House (2006) Table III (`tools/fit_phosphate_conductivity.py`, `supplementary` block of the coefficient file, data to I = 0.014); the audit records `supplementaryCoefficients` and `phosphate_fit_max_ionic_strength`, and `MODEL_VERSION` is now m2b. Minor phosphate pairs and PO4-3 stay under the bound.
-- Add the material traceability API (`docs/materials.md`): shipped identity records (`load_identities`, `identity_for_product`), user grades and lots (`make_grade`, `make_lot`), `resolve_material` (per-nutrient basis, band ends, flags, provenance) and `nutrient_band`; `catalogue_dose_totals` and `calculate_irrigation_ec` take `materials=`, undisclosed blends raise or report `composition_undisclosed` in chemistry, and EC and equilibrium-delivery audits carry material provenance.
+- Add the material traceability API (`docs/site/guide/materials.md`): shipped identity records (`load_identities`, `identity_for_product`), user grades and lots (`make_grade`, `make_lot`), `resolve_material` (per-nutrient basis, band ends, flags, provenance) and `nutrient_band`; `catalogue_dose_totals` and `calculate_irrigation_ec` take `materials=`, undisclosed blends raise or report `composition_undisclosed` in chemistry, and EC and equilibrium-delivery audits carry material provenance.
 - Link every catalogue product in `library.json` to its chemical identity (`identityId`) and record its `analysisBasis` (`declared_catalogue`, `identity_theoretical` or `grade_typical`) and `source` document reference. Product `id` and `name` values are unchanged.
 - Correct Mg Nitrate to Mg(NO3)2·6H2O theory (owner decision D1): formula `Mg(NO3)2` → `Mg(NO3)2.6H2O`; N_NO3 11 → 10.92564 %, Mg 9.65 → 9.47931 %; basis `identity_theoretical`. Its declared-form charge residual at 1 g/kg water goes from +0.5532 % to ~0 %, so it no longer trips the EC O5 gate on its own.
 - Correct Phosphoric Acid (75%) to the 75 % w/w solution: P 31.61 → 23.706035 % (0.75 × 31.608046, product-mass dosing); PO4 delivered per gram falls to 0.74995 × the old value. Its stored assay is now reported as drifting from the H3PO4 formula, as intended for a solution.
@@ -15,6 +15,7 @@
 - `recommend` results (and the workflow recommendation) now carry per-salt `provenance` (recordId, identityId, analysisBasis, documents, flags; `unattributed` when the record has none) and `identitiesSha256`; `solve_weights` and `forward` are unchanged.
 - Formulation rows now report formula counterion sodium not already assayed as elemental Na (chelate sodium, D2, and CH - micro's borax and molybdate sodium), added to the `Na` row and incidental review after the fit, with an `Na` target's `deltaPct` recomputed (pepper workflow incidental Na 0.048 -> 1.722 ppm; Tomatoes U of Florida clusters 2.1923 -> 2.7548, Lettuce General 2.2258 -> 2.5774, Generic Wet Season 2.5403 -> 2.7161 mg/L with CH - micro's borax/molybdate share); a tight Na maximum can make such recipes require review or be infeasible.
 - Add `calculate_irrigation_ec_band`: irrigation EC25 chemistry (pH, precipitation, EC) at nominal and nutrient band minimum and maximum ends; an end with an open band returns `not_supported` / `band_end_open`.
+- Documentation is published at https://flahax.readthedocs.io/ (Sphinx + MyST, versioned from the next release); internal specs and plans are no longer in the repository.
 
 ## 0.4.0 — 2026-10-17
 

diff --git a/INTEGRATION.md b/INTEGRATION.md
@@ -4,7 +4,7 @@ FlahaFAST integration is owned by the separate **FlahaFAST project**, by project
 
 ## Supported package interfaces
 
-- Python: `recommend`, explicit catalogue-equilibrium functions and delivery-planning types; see [usage](docs/usage.md) and [equilibrium delivery](docs/package-verification.md).
+- Python: `recommend`, explicit catalogue-equilibrium functions and delivery-planning types; see [usage](docs/site/guide/usage.md) and [equilibrium delivery](docs/site/api/package-verification.md).
 - CLI: `python -m flahax` or `flahax` consumes one JSON object on standard input and returns a JSON recommendation. A nonempty `salts` array is required; the CLI does not silently choose the packaged catalogue. Check process exit status and the result's `feasible` value; an error is not an empty successful recommendation.
 - Nutrient targets/water use elemental ppm; recipe doses use g/L final solution. Equilibrium inputs use explicitly converted g/kg water and molal totals. Do not pass arbitrary application product rows into catalogue-only equilibrium APIs.
 

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -7,6 +7,7 @@ include CONTRIBUTING.md
 include INTEGRATION.md
 include pyproject.toml
 recursive-include docs *.md *.jpg *.png *.pdf
+recursive-include docs/site *.csv
 exclude docs/sources/04_Fertilizer.pdf
 exclude docs/sources/165357805552.pdf
 exclude docs/sources/215057776303.pdf
@@ -26,3 +27,4 @@ prune examples/tutorial
 global-exclude __pycache__
 global-exclude *.py[cod]
 prune docs/publication
+prune docs/superpowers
diff --git a/docs/audit/2026-10-18-materials-identity/README.md b/docs/audit/2026-10-18-materials-identity/README.md
@@ -0,0 +1,3 @@
+# Materials identity audit, 2026-10-18: maintainer review
+
+This page moved to the FlahaX documentation: <https://flahax.readthedocs.io/>, section "Evidence and audits".
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Materials identity audit, 2026-10-18: maintainer review

		This page moved to the FlahaX documentation: <https://flahax.readthedocs.io/>, section "Evidence and audits".