docs(#72): Sphinx/RTD site + JOSS paper skeleton + coverage ratchet (slice 1) (#94)

* docs(#72): Sphinx/RTD site + JOSS paper skeleton + coverage ratchet 80->90

First bounded slice of roadmap issue #72 (docs + JOSS + coverage; SPEC 7 rng
was already landed on main and is out of scope here).

- Sphinx docs skeleton under docs/ (furo + MyST + autodoc/napoleon), Diataxis
  structure, autogenerated API reference from liouscope.__all__. Builds clean
  under `sphinx-build -W` (warnings-as-errors). Adds .readthedocs.yaml (v2,
  fail_on_warning) + docs/requirements.txt + a `docs` optional-dependency group.
- JOSS paper skeleton: paper/paper.md + paper/paper.bib (JOSS 2026 sections).
  All six bibliography DOIs resolver-verified; author ORCIDs and research-impact
  evidence flagged TODO (not fabricated).
- Coverage ratchet: fail_under raised 80 -> 90 in pyproject [tool.coverage.report]
  and CI --cov-fail-under; measured baseline branch coverage 94.61% (py3.14).
  CONTRIBUTING updated to match.

Local verification (Windows, py3.14, this branch):
  ruff check src tests benchmarks         -> exit 0
  mypy src/liouscope                       -> Success, 52 files
  pytest tests/test_anchors.py             -> 21 passed
  pytest --cov --cov-fail-under=90         -> 533 passed, 94.61% (gate reached)
  sphinx-build -W docs docs/_build/html    -> build succeeded, 0 warnings
  check_claim_safety.py / hardening.py     -> both pass

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* docs(#72): expand JOSS paper.md to full required section set

Bring paper/paper.md from a 585-word skeleton to a 1124-word (JOSS-style
body count) submission draft covering all 2026-required sections:

- State of the field: QuTiP/Trefethen-Embree context, complementary
  (generator characterisation vs time evolution), no abuse of QuTiP.
- Software design: public API (build_liouvillian/steady_state/diagnose/
  classify_mechanism), immutable typed result containers, six diagnostic
  layers, column-stacking order='F' + Roth's identity guard, non-Hermitian
  eigensolver (numpy.linalg.eig -> LAPACK zgeev), SPEC 7 rng keyword,
  A-N anchor regressions, D1-D20 submission set within D1-D24 schema,
  A1-A12-v3.1 taxonomy, fail-closed EnsembleEvidence claim gate (#78/E0706-13).
- Research impact: HONEST — first-party use/benchmarks only, no external
  adoption yet (stated plainly); Zenodo/PyPI archived+citable; QuTiP CI
  cross-check + anchors are internal verification, not external validation.
- AI usage disclosure: substantial — code/docs/paper co-developed with
  Claude agents under AGENTS.md, human review+merge gate, agent branch
  namespaces + labels, same required CI; cross-family review = independent
  model review, explicitly NOT external scientific validation.
- Acknowledgements filled (NumPy/SciPy/QuTiP, SPEC 7).

Claim discipline: every technical statement is checkable against the repo;
no benchmark numbers asserted that are not reproducible. Author ORCID/
affiliation and funding remain marked TODO (must not be fabricated).
paper.bib unchanged (6 Crossref-verified DOIs intact). Coverage ratchet
(fail_under=90) untouched. Local chain green: ruff/mypy 0, 533 pytest pass,
cov 94.61%, sphinx -W 0 warnings.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: marcohost33-maker

.github/workflows/ci.yml

@@ -43,7 +43,7 @@ jobs:
       - name: Run anchor regressions (must pass)
         run: pytest tests/test_anchors.py -v
       - name: Run full test suite
-        run: pytest --cov=liouscope --cov-report=xml --cov-fail-under=80 -v
+        run: pytest --cov=liouscope --cov-report=xml --cov-fail-under=90 -v
       - name: Upload coverage
         if: matrix.python-version == '3.12'
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4.6.2

.gitignore

@@ -53,3 +53,6 @@ benchmarks/output/
 *.npz
 
 .ipynb_checkpoints/
+
+# Sphinx documentation build output
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# Read the Docs configuration (v2).
+# Docs: https://docs.readthedocs.io/en/stable/config-file/v2.html
+# Introduced by issue #72 (Sphinx + furo + MyST docs site).
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  # Mirror the local `sphinx-build -W` gate: any warning fails the RTD build.
+  fail_on_warning: true
+
+python:
+  install:
+    # Install LiouScope itself so autodoc can import the package.
+    - method: pip
+      path: .
+    # Documentation-only tooling (Sphinx, furo, myst-parser).
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -7,6 +7,21 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Added
+- **Sphinx + Read the Docs documentation skeleton** (issue #72 item 2).
+  A `docs/` Sphinx site (furo theme, MyST Markdown, `autodoc` + `napoleon`
+  API reference) organised along the Diátaxis structure
+  (tutorials / how-to / reference / explanation), plus a `.readthedocs.yaml`
+  (v2) and `docs/requirements.txt` / a `docs` optional-dependency group.
+  Builds clean under `sphinx-build -W` (warnings-as-errors); RTD mirrors that
+  gate via `fail_on_warning: true`. The Reference section is auto-generated
+  from the public `liouscope.__all__` surface; tutorials / how-to /
+  explanation are intentional stubs for a follow-up slice.
+- **JOSS paper skeleton** (issue #72 item 3). `paper/paper.md` +
+  `paper/paper.bib` following the JOSS 2026 section requirements (Summary,
+  Statement of need, State of the field, Software design, Research impact, AI
+  usage disclosure). All six bibliography DOIs are resolver-verified; author
+  identities/ORCIDs and research-impact evidence are flagged TODO (not
+  fabricated) and must be completed before submission.
 - **SPEC 7 `rng` keyword, additive phase (a)** (issue #72 item 1).
   `diagnose()`, `seed_everything()` and the D18 surface
   (`compute_lep_layer` / `initial_state_sensitivity`) now accept a SPEC 7
@@ -24,6 +39,12 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   separate SPEC 7 phase. Contract pinned in `tests/test_spec7_rng.py`.
 
 ### Changed
+- **Coverage ratchet 80 → 90** (issue #72 item 4). Measured branch coverage on
+  the baseline (Python 3.14) was 94.61%. The `--cov-fail-under` gate in CI and
+  the new `[tool.coverage.report] fail_under` in `pyproject.toml` are both set
+  conservatively to 90 (up from the previous fixed 80), leaving headroom for
+  cross-version variation on the 3.10–3.14 matrix. `CONTRIBUTING.md` updated to
+  match.
 - **Release identity and provenance hardening.** Released `v0.5.0` remains
   immutable; default-branch VCS installs now report `0.6.0.dev0`. Manifest
   schema `1.4.0` adds the canonical structured-ensemble-evidence digest to

CONTRIBUTING.md

@@ -16,7 +16,7 @@ pip install -e .[dev,qutip]
 ## Running the test suite
 
 ```bash
-pytest --cov=liouscope --cov-fail-under=80
+pytest --cov=liouscope --cov-fail-under=90
 pytest tests/test_anchors.py            # correctness-anchor regression gate
 ```
 

docs/_static/.gitkeep

@@ -0,0 +1,76 @@
+"""Sphinx configuration for the LiouScope documentation site.
+
+Skeleton introduced by issue #72 (Sphinx + furo + MyST on Read the Docs).
+Only the curated pages under this directory participate in the build; the
+pre-existing standalone Markdown docs (release audits, ADRs, CANON status)
+are intentionally excluded via ``include_patterns`` so the Sphinx source tree
+stays scoped and ``-W`` (warnings-as-errors) builds clean.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+
+# -- Project information -----------------------------------------------------
+
+project = "LiouScope"
+author = "Coworker Research"
+copyright = "2026, Coworker Research"  # noqa: A001  (Sphinx-mandated name)
+
+# Single source of truth: read the installed package version. Falls back to a
+# sentinel so an uninstalled checkout still builds (RTD installs the package).
+try:
+    release = importlib.metadata.version("liouscope")
+except importlib.metadata.PackageNotFoundError:  # pragma: no cover - build-time guard
+    release = "0.0.0+unknown"
+version = release
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "myst_parser",
+]
+
+# Scope the Sphinx source scan to the curated Diataxis pages only. Without this
+# every pre-existing docs/*.md (RELEASE_AUDIT_*, CANON_STATUS, adr/**) would be
+# picked up and warn "document isn't included in any toctree", breaking -W.
+include_patterns = [
+    "index.md",
+    "tutorials/**",
+    "how-to/**",
+    "reference/**",
+    "explanation/**",
+    "_static/**",
+]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+templates_path = ["_templates"]
+
+# -- Autodoc / napoleon ------------------------------------------------------
+
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+autodoc_default_options = {
+    "members": True,
+    "show-inheritance": True,
+}
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+napoleon_use_rtype = True
+
+# -- MyST --------------------------------------------------------------------
+
+myst_enable_extensions = [
+    "colon_fence",
+    "deflist",
+]
+myst_heading_anchors = 3
+
+# -- HTML output -------------------------------------------------------------
+
+html_theme = "furo"
+html_title = f"LiouScope {release}"
+html_static_path = ["_static"]

docs/conf.py

@@ -0,0 +1,17 @@
+# Explanation
+
+*Understanding-oriented background and design rationale.*
+
+:::{note}
+Skeleton (issue #72). In-depth methodology lives in the module docstrings (see
+{doc}`../reference/index`) and in `docs/RELEASE_AUDIT_v0.5.0.md`. This section
+will collect the conceptual narrative in a follow-up slice.
+:::
+
+## Topics to cover
+
+- **Why "no single number"** — the Liouvillian gap versus non-normal transient
+  amplification and pseudospectra.
+- **The D1–D24 diagnostic layers** and the A1–A12 mechanism taxonomy.
+- **Auditable reproducibility** — run manifests, seeds and the SPEC 7 `rng`
+  keyword.

docs/explanation/index.md

@@ -0,0 +1,14 @@
+# How-to guides
+
+*Goal-oriented recipes for specific tasks.*
+
+:::{note}
+Skeleton (issue #72). Task recipes are planned for a follow-up slice. See
+`examples/` and `benchmarks/` in the repository for runnable references today.
+:::
+
+## Planned how-to guides
+
+- How to export and validate a run manifest.
+- How to supply `EnsembleEvidence` for A11 (quantum-Mpemba) confirmation.
+- How to cross-check a result against QuTiP.

docs/how-to/index.md

@@ -0,0 +1,36 @@
+# LiouScope documentation
+
+**LiouScope** is an open-source diagnostic framework for time-homogeneous
+Markovian open quantum systems described by Gorini–Kossakowski–Sudarshan–Lindblad
+(GKSL) generators. It quantifies *when and why* the Liouvillian gap fails as a
+relaxation-time predictor, replacing a single "decay rate" number with a layered,
+auditable `DiagnosticReport`.
+
+:::{note}
+This documentation site is an initial skeleton introduced by issue #72. It is
+organised along the [Diátaxis](https://diataxis.fr/) framework
+(tutorials / how-to / reference / explanation). The Reference section is
+auto-generated from the package docstrings; the Tutorials, How-to and
+Explanation sections are stubs to be filled in follow-up slices.
+:::
+
+## Where to start
+
+- **New to LiouScope?** Read the {doc}`tutorials/index`.
+- **Have a specific task?** See the {doc}`how-to/index`.
+- **Need the API?** Jump to the {doc}`reference/index`.
+- **Want the "why"?** Read the {doc}`explanation/index`.
+
+For installation, the design philosophy ("no single number", explicit
+uncertainty, auditable manifests) and the current citable release gates, see the
+project `README.md` and `docs/RELEASE_AUDIT_v0.5.0.md` in the repository.
+
+```{toctree}
+:hidden:
+:maxdepth: 2
+
+tutorials/index
+how-to/index
+reference/index
+explanation/index
+```