docs: address review feedback on seasonal documentation

- Add seasonal ±1% CI parity note to migration-from-r.md
- Fix season.duration param notation in compatibility-matrix.md
- Improve season_duration examples with clearer use cases
- Add nseasons=1 equivalence note and constraint rules to api.md
- Define Matching vs Supported status labels in README.md

Author: YuminosukeSato

README.md

@@ -122,6 +122,9 @@ Tests run on every commit with seed-fixed MCMC for deterministic reproduction.
 | Dynamic regression | Supported | Time-varying coefficients via random-walk FFBS; `dynamic_regression=True` |
 | Local linear trend | Supported | Opt in with `state_model="local_linear_trend"` |
 
+Matching = CI-enforced numerical equivalence with R bsts (±3% or tighter).
+Supported = Feature implemented, no R parity fixture yet.
+
 Covariate CI bounds are enforced twice: the legacy parity fixture remains tighter than
 Phase 2 requirements, and a separate Phase 2 acceptance test keeps the threshold at `±3%`.
 

docs/api.md

@@ -56,8 +56,8 @@ ci = CausalImpact(data, pre_period, post_period, model_args=opts)
 | `expected_model_size` | `int` | 2 | Expected number of active covariates for spike-and-slab prior |
 | `dynamic_regression` | `bool` | `False` | Enable time-varying regression coefficients |
 | `state_model` | `str` | `"local_level"` | `"local_level"` or `"local_linear_trend"` |
-| `nseasons` | `int \| None` | `None` | Seasonal cycle count |
-| `season_duration` | `int \| None` | `None` | Duration of each seasonal block; defaults to 1 when `nseasons` is set |
+| `nseasons` | `int \| None` | `None` | Seasonal cycle count. `nseasons=1` is equivalent to no seasonal component. |
+| `season_duration` | `int \| None` | `None` | Duration of each seasonal block; defaults to 1 when `nseasons` is set. Requires `nseasons` to be set. |
 
 ## `CausalImpactResults`
 

docs/compatibility-matrix.md

@@ -18,7 +18,7 @@ Comparison of features between R CausalImpact (bsts 1.4.1) and this Python imple
 |---|---|---|---|
 | niter | Yes | Yes | Same default (1000) |
 | nseasons | Yes | Yes | `ModelOptions.nseasons` or `model_args["nseasons"]` |
-| season.duration | Yes | Yes | `ModelOptions.season_duration` or `model_args["season.duration"]` |
+| season.duration | Yes | Yes | `ModelOptions.season_duration` or `model_args["season_duration"]` (R compat: `"season.duration"`) |
 | prior.level.sd | Yes | Yes | Same default (0.01) |
 | standardize.data | Yes | Yes | Same default (True) |
 | expected.model.size | Yes | Yes | Unified default `2` |

docs/examples.md

@@ -192,27 +192,28 @@ the negative sum of the previous `S-1` seasons plus noise.
 
 ### Using `season_duration`
 
-When each season spans multiple time steps (e.g., daily data with weekly
-seasonality where each day of the week lasts one step), set `season_duration`
-accordingly. The seasonal transition only fires at season boundaries
+Set `season_duration > 1` when each season spans multiple time steps.
+The seasonal transition only fires at season boundaries
 (`t % season_duration == 0`); in between, the seasonal state is frozen.
 
 ```python
+# Using the same data from the seasonal example above
+
 # Daily data with 7-day weekly pattern (default: season_duration=1)
 ci = CausalImpact(
     data, pre_period, post_period,
     model_args={"nseasons": 7, "season_duration": 1, "seed": 42},
 )
 
-# Bi-weekly data with 26 two-week seasons per year
+# Monthly data with quarterly pattern (each quarter = 3 months)
 ci = CausalImpact(
     data, pre_period, post_period,
-    model_args={"nseasons": 26, "season_duration": 2, "seed": 42},
+    model_args={"nseasons": 4, "season_duration": 3, "seed": 42},
 )
 ```
 
 When `season_duration` is omitted, it defaults to 1 (every time step is a new
-season).
+season). `nseasons=1` is equivalent to no seasonal component.
 
 ---
 

docs/migration-from-r.md

@@ -81,7 +81,9 @@ Key differences:
 
 ## Numerical Equivalence
 
-This library verifies ±3% agreement with R CausalImpact on point estimates and cumulative effects across multiple test scenarios, including a seasonal fixture. Tests run on every PR.
+This library verifies ±3% agreement with R CausalImpact on point estimates and cumulative effects across multiple test scenarios. Tests run on every PR.
+
+The seasonal model uses the same state-space algorithm as R bsts `AddSeasonal()`, achieving ±1% CI parity on the seasonal fixture.
 
 Differences arise from independent RNG implementations (R's `set.seed` vs Rust's `ChaCha8Rng`), not from algorithmic differences.