Add mkdocs-material docs site scaffold + v0.7.x DiD guides

Introduce a proper documentation site for StatsPAI using mkdocs +
mkdocs-material, with a focused v0.7.x pass over the DiD module.
Build verified locally: `mkdocs build --clean --strict` succeeds in
~0.2 s with zero warnings.

* `mkdocs.yml` — site config (theme, nav, Pygments + MathJax extras).
* `docs/index.md` — project-level landing page; lead code block is the
  one-call `sp.cs_report(..., save_to=...)` pipeline.
* `docs/guides/callaway_santanna.md` — from-zero walkthrough of the
  CS2021 estimator: raw estimation, aggte with uniform bands, RCS
  mode, R-R sensitivity, pointer to `cs_report()`.
* `docs/guides/cs_report.md` — `CSReport` fields and all five export
  routes (text / markdown / latex / excel / plot / save_to= bundle).
* `docs/guides/repeated_cross_sections.md` — MathJax-rendered
  estimator + influence-function formulas + scope guardrails.
* `docs/guides/honest_did.md` — polymorphic usage across CS / SA /
  BJS / aggte event studies.
* `docs/reference/did.md` — API-reference tables for all public DiD
  entry points.
* `docs/changelog.md` — copy of the repo-root CHANGELOG so the site
  carries its own release history.

The new files are force-added because `.gitignore` blanket-excludes
`docs/` at line 23 (pre-existing user intent for everything that
used to live there).  Force-adding only the seven new files lets the
published site track them while leaving the blanket rule in place
for any future docs/ content the user wants to keep private by
default.

Full DiD suite unchanged: 161/161 green across 12 test files.

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

Author: brycewang-stanford

.gitignore

@@ -171,3 +171,7 @@ StatsPAI/statspai-推文-agent时代的统计包生态.md
 test-notebooks/ 
 /Users/brycewang/Documents/GitHub/StatsPAI/test-notebooks/demo_causal_inference.ipynb
 test-notebooks/demo_causal_inference.ipynb
+
+# mkdocs build output
+/site/
+

docs/changelog.md

@@ -0,0 +1 @@
+../CHANGELOG.md

docs/guides/callaway_santanna.md

@@ -0,0 +1,90 @@
+# Staggered Difference-in-Differences — Callaway & Sant'Anna (2021)
+
+StatsPAI implements the Callaway–Sant'Anna estimator from first
+principles, matching the R `did` package's core functionality while
+adding new convenience layers on top.
+
+## Basic usage
+
+```python
+import statspai as sp
+
+cs = sp.callaway_santanna(
+    df,
+    y='earnings',        # outcome
+    g='first_treat',     # first-treatment period (0 = never-treated)
+    t='year',            # time period
+    i='worker_id',       # unit id
+    estimator='dr',      # 'dr' (default), 'ipw', or 'reg'
+    control_group='nevertreated',  # or 'notyettreated'
+    anticipation=0,      # periods of anticipation (CS2021 §3.2)
+)
+
+print(cs.summary())
+cs.detail              # one row per (group, time) with ATT + pointwise CI
+cs.model_info['event_study']   # event-study aggregation
+cs.model_info['pretrend_test'] # joint Wald pre-trend test
+```
+
+## Aggregation with uniform bands
+
+The raw `callaway_santanna()` result is a grid of ATT(g, t) estimates.
+Collapse to a scalar or an event-study curve with `aggte()`, which
+layers the Mammen (1993) multiplier bootstrap on top and returns
+*simultaneous* confidence bands:
+
+```python
+es = sp.aggte(cs, type='dynamic',
+              n_boot=500, random_state=0,
+              balance_e=3)        # balance across cohorts for e ≤ 3
+
+print(es.detail)
+# relative_time  att  se  ci_lower  ci_upper  cband_lower  cband_upper ...
+```
+
+The `cband_lower` / `cband_upper` columns give a sup-t uniform band —
+valid for simultaneous inference across the entire event window,
+unlike the pointwise CI.
+
+Other aggregation types:
+
+| `type=` | Meaning |
+| --- | --- |
+| `'simple'` | cohort-share-weighted overall ATT |
+| `'dynamic'` | event-study curve ATT(e) |
+| `'group'` | per-cohort average ATT(g) |
+| `'calendar'` | per-calendar-time ATT(t) |
+
+## Repeated cross-sections
+
+Pass `panel=False` when observations are not matched across time
+(e.g. CPS pooled cross-sections).  The estimator switches to the
+unconditional 2×2 cell-mean DID with observation-level influence
+functions; downstream `aggte`, `cs_report`, `ggdid`, and `honest_did`
+all work unchanged.
+
+```python
+cs_rcs = sp.callaway_santanna(
+    survey_df,
+    y='wage', g='first_treat', t='year', i='respondent_id',
+    estimator='reg',         # only 'reg' supported in RCS mode
+    x=['age', 'education'],  # optional covariate residualisation
+    panel=False,
+)
+```
+
+## Sensitivity — Rambachan & Roth (2023)
+
+Every event-study result (from CS, SA, BJS, or `aggte`) feeds into
+the Rambachan–Roth sensitivity framework:
+
+```python
+sens = sp.honest_did(es, e=2)     # robust CI at e=2 across an M grid
+m_star = sp.breakdown_m(es, e=2)  # largest M* under which effect is significant
+```
+
+## One-call report
+
+For a ready-to-publish summary — raw estimation + four aggregations
+with uniform bands + pre-trend Wald + R-R breakdown M\* per post
+event time — call [`cs_report()`](cs_report.md).

docs/guides/cs_report.md

@@ -0,0 +1,69 @@
+# `cs_report()` — the one-call report card
+
+`sp.cs_report()` runs the full Callaway–Sant'Anna workflow under a
+single random seed and bundles the outputs into a `CSReport`
+dataclass that pretty-prints, plots, and exports.
+
+## Minimal example
+
+```python
+import statspai as sp
+
+rpt = sp.cs_report(
+    df,
+    y='y', g='g', t='t', i='id',
+    n_boot=500,
+    random_state=0,
+    verbose=True,              # prints the report to stdout
+)
+```
+
+## Structured fields
+
+```python
+rpt.overall      # dict: overall ATT, SE, CI, p
+rpt.simple       # DataFrame: simple aggregation
+rpt.dynamic      # DataFrame: event study with uniform bands
+rpt.group        # DataFrame: per-cohort θ(g)
+rpt.calendar     # DataFrame: per-calendar-time θ(t)
+rpt.pretrend     # dict: χ² pre-trend Wald test
+rpt.breakdown    # DataFrame: R-R breakdown M* per post event time
+rpt.meta         # dict: run metadata (n_units, estimator, …)
+```
+
+## Export formats
+
+```python
+rpt.to_text()         # fixed-width ASCII
+rpt.to_markdown()     # GitHub-flavoured Markdown (floatfmt configurable)
+rpt.to_latex()        # booktabs LaTeX fragment (no jinja2 needed)
+rpt.to_excel('out.xlsx')  # six-sheet workbook
+rpt.plot()            # 2×2 summary figure via matplotlib
+```
+
+### One-call bundle
+
+Pass `save_to='prefix'` to emit every format in one go:
+
+```python
+sp.cs_report(
+    df, y='y', g='g', t='t', i='id',
+    n_boot=500, random_state=0,
+    save_to='~/studies/cs_v1',
+)
+# writes:
+# ~/studies/cs_v1.txt   .md   .tex   .xlsx   .png
+```
+
+Missing parent directories are created on the fly; optional
+dependencies (`openpyxl`, `matplotlib`) are skipped silently.
+
+## From a pre-fitted result
+
+Skip re-running estimation if you already have a
+`callaway_santanna()` result:
+
+```python
+cs = sp.callaway_santanna(df, ...)
+rpt = sp.cs_report(cs, n_boot=500, random_state=0)
+```

docs/guides/honest_did.md

@@ -0,0 +1,45 @@
+# Sensitivity to parallel trends — Rambachan & Roth (2023)
+
+Parallel trends is an assumption, not a fact.  Rambachan & Roth
+(2023) answer the practical question: *how wrong could parallel
+trends be before my post-treatment conclusion flips?*  StatsPAI wires
+their tooling directly into every event-study object in the library.
+
+## Functions
+
+| Function | Purpose |
+| --- | --- |
+| `sp.honest_did(result, e, m_grid=None, method='smoothness')` | Robust CI at event time `e` across a grid of violation magnitudes `M` |
+| `sp.breakdown_m(result, e, method='smoothness')` | Largest `M*` at which the effect remains significant |
+
+Both functions are *polymorphic*: they accept
+
+- a `callaway_santanna()` result (event study in `model_info`),
+- a `sun_abraham()` result,
+- or an `aggte(type='dynamic')` result (event study in `detail` with
+  Mammen uniform bands).
+
+## Typical pipeline
+
+```python
+cs  = sp.callaway_santanna(df, y='y', g='g', t='t', i='id')
+es  = sp.aggte(cs, type='dynamic', n_boot=500, random_state=0)
+s   = sp.honest_did(es, e=1)          # robust CI table across M grid
+mst = sp.breakdown_m(es, e=1)         # scalar breakdown value
+```
+
+## Restriction types
+
+- `method='smoothness'` — bounds $|\Delta \delta_t| \le M$ for every
+  consecutive pair of periods (Δ^SD(M)).  The `M` parameter has units
+  of the outcome per period.
+- `method='relative_magnitude'` — post-period violation bounded as
+  `M̄ × max|δ_pre|`.  Useful when you want to express the sensitivity
+  relative to the magnitude of the observed pre-trend violations.
+
+## One-shot via `cs_report()`
+
+The [`cs_report`](cs_report.md) report card already runs
+`breakdown_m` at every post-treatment event time and stores the
+results in `rpt.breakdown`.  Column `robust_at_1_SE` flags whether
+the effect survives a violation equal to one pointwise standard error.

docs/guides/repeated_cross_sections.md

@@ -0,0 +1,69 @@
+# Repeated cross-sections (`panel=False`)
+
+Classic Callaway–Sant'Anna requires a balanced panel: every unit
+observed in every period.  Many causal-inference datasets are
+*repeated cross-sections* (RCS) — pooled surveys (CPS, ACS), rolling
+polls, independent samples per period — where no within-unit first
+difference is available.  StatsPAI's RCS path solves this with the
+unconditional 2×2 cell-mean DID.
+
+## Estimator
+
+For each (g, t, base) triple with never-treated control c = 0:
+
+$$
+\widehat{\text{ATT}}(g, t)
+  = (\bar{Y}_{g, t} - \bar{Y}_{g, b})
+  - (\bar{Y}_{c, t} - \bar{Y}_{c, b})
+$$
+
+and observation-level influence functions
+
+$$
+\psi_i
+  = \frac{\mathbf{1}\{G_i=g,\,T_i=t\}(Y_i - \bar{Y}_{g,t})}{p_{g,t}}
+  - \frac{\mathbf{1}\{G_i=g,\,T_i=b\}(Y_i - \bar{Y}_{g,b})}{p_{g,b}}
+  - \frac{\mathbf{1}\{G_i=c,\,T_i=t\}(Y_i - \bar{Y}_{c,t})}{p_{c,t}}
+  + \frac{\mathbf{1}\{G_i=c,\,T_i=b\}(Y_i - \bar{Y}_{c,b})}{p_{c,b}}
+$$
+
+where $p_{\cdot,\cdot}$ is the empirical cell share.  The influence
+functions are stacked into the same `inf_matrix` contract used by the
+panel estimator, so `aggte`, `cs_report`, `ggdid`, and `honest_did`
+work downstream without modification.
+
+## Usage
+
+```python
+sp.callaway_santanna(
+    df, y='y', g='first_treat', t='year', i='obs_id',
+    estimator='reg',          # required for panel=False
+    panel=False,
+)
+```
+
+## Covariate adjustment
+
+Add `x=[...]` for regression-adjusted RCS.  Y is residualised on X
+using OLS fit on the never-treated pool (with period fixed effects);
+the cell-mean DID then runs on the residualised outcome:
+
+```python
+sp.callaway_santanna(
+    survey_df, y='wage', g='g', t='year', i='obs',
+    estimator='reg', panel=False,
+    x=['age', 'education', 'female'],
+)
+```
+
+Influence functions treat β̂ as known (plug-in IF), which is
+asymptotically valid at √n.  A fully-coupled Sant'Anna–Zhao (2020)
+IF augmentation is planned.
+
+## Scope of the current implementation
+
+- `estimator` must be `'reg'`
+- `control_group` must be `'nevertreated'`
+- IPW / DR for RCS: planned for a future release
+
+All other paths raise `NotImplementedError` with an actionable message.

docs/index.md

@@ -0,0 +1,78 @@
+# StatsPAI
+
+**Python causal inference toolkit** — reimplemented from the original
+papers, zero upstream DID-package runtime dependencies.
+
+```python
+import statspai as sp
+
+rpt = sp.cs_report(
+    data, y='y', g='g', t='t', i='id',
+    n_boot=500, random_state=0,
+    save_to='~/study/cs_v1',   # writes .txt / .md / .tex / .xlsx / .png
+)
+```
+
+## What's inside
+
+StatsPAI brings the R `did` / `HonestDiD` + Python `csdid` / `differences`
+stack into a single consistent Python API, with every core algorithm
+reimplemented from the original paper (no wrappers).
+
+### Staggered Difference-in-Differences
+
+- **Callaway & Sant'Anna (2021)** — `sp.callaway_santanna()` with
+  DR / IPW / REG estimators, never-treated or not-yet-treated control,
+  `anticipation=δ`, and `panel=False` for repeated cross-sections
+  (with optional covariate regression adjustment).
+- **Four aggregations + Mammen uniform bands** — `sp.aggte()` with
+  `type='simple' | 'dynamic' | 'group' | 'calendar'` and simultaneous
+  sup-t confidence bands (Callaway–Sant'Anna 2021 §4.2).
+- **Sensitivity analysis** — `sp.honest_did()` and `sp.breakdown_m()`
+  (Rambachan–Roth 2023).  Both accept either a `callaway_santanna()`
+  result or an `aggte(type='dynamic')` result.
+- **One-call report** — `sp.cs_report()` runs the full pipeline under a
+  single seed and produces a structured `CSReport` with Markdown /
+  LaTeX / Excel export and a 2×2 summary figure (`.plot()`).
+- **Sun & Abraham (2021) IW** with Liang–Zeger cluster-robust SEs.
+- **Borusyak–Jaravel–Spiess (2024)** imputation estimator +
+  `sp.bjs_pretrend_joint()` cluster-bootstrap joint Wald pre-trend test.
+- **de Chaisemartin–D'Haultfoeuille** with joint placebo Wald and
+  average cumulative effect (dCDH 2024).
+
+### Broader toolkit
+
+OLS / GLM / quantile / survival / panel / spatial / RD / IV / matching /
+synthetic control / DML / DeepIV / neural causal / causal forests /
+policy learning / conformal causal / TMLE / Mendelian randomization /
+sensitivity analysis / reporting via `outreg2` + `modelsummary`.
+
+See the left-hand navigation for guides.
+
+## Installation
+
+```bash
+pip install statspai
+```
+
+Optional extras for exports:
+
+```bash
+pip install openpyxl matplotlib          # Excel + figures
+```
+
+## Citation
+
+If you use StatsPAI in research, please cite the underlying papers
+implemented by each estimator (every `CausalResult` carries a
+`.cite()` method that returns the correct BibTeX entry) and this
+package:
+
+```bibtex
+@software{statspai,
+  author  = {Wang, Bryce},
+  title   = {StatsPAI: Python Causal Inference Toolkit},
+  year    = {2026},
+  url     = {https://github.com/brycewang-stanford/StatsPAI}
+}
+```