AF calendar-adapter estimator + measurement families (supersedes #89)

docs/explanations/names_and_concepts.md

@@ -96,17 +96,16 @@ tuning knob differs between estimators.
 `AFEstimationOptions` (from `skillmodels.af`) controls the sequential MLE:
 
 - **n_halton_points**, **n_halton_points_shock**: quadrature counts.
-- **n_mixture_components**: number of components in the latent-factor mixture.
 - **optimizer_algorithm**: the optimagic algorithm name passed to
   `optimagic.minimize(algorithm=...)` (default `"fides"`; use
   `"scipy_lbfgsb"` for MC sweeps).
-- **initialization_strategy**: `"amn"`, `"spearman"`, or `"constant"`. Same
-  meaning as in CHS.
+- **start_params_strategy**: `"amn"`, `"spearman"`, `"constant"`, or `"none"`.
+  Same meaning as in CHS. (The mixture-component count is not an estimator option;
+  it is the structural field `ModelSpec.n_mixtures`.)
 
 `AMNEstimationOptions` (from `skillmodels.amn`) controls the three-stage
 pipeline:
 
-- **n_mixture_components**: Stage-1 EM components.
 - **em_max_iter**, **em_tol**, **em_n_init**, **em_reg_covar**: Stage-1 EM
   numerical knobs.
 - **n_simulation_draws**: Stage-3 synthetic-panel size.
@@ -115,17 +114,11 @@ pipeline:
   full covariance matrices, and is currently the only implemented option.
   `"optimal"` is reserved for a future Avar-weighted criterion and raises
   `NotImplementedError`.
-- **investment_endogeneity**: apply the AMN (2020) eq. 7-8 / AF Sec. 3.5
-  investment control-function correction in Stage 3. Defaults to `False`. When
-  `True` and the model has an endogenous (investment) factor, a first-stage
-  investment equation is OLS-fit per period and its residual is added as an
-  additive `cf` covariate (coefficient `kappa_t`) to each state factor's
-  production regression; observed factors are then excluded from the production
-  function and act as instruments (at least one observed instrument is
-  required). The default stays `False` because `estimate_af` calls
-  `estimate_amn` for start values and the AF likelihood implements only
-  `kappa=0`; opt into the correction at the application call site. A no-op for
-  models without endogenous factors.
+- Investment-endogeneity correction is no longer an estimation-option flag.
+  Attach a `CorrectionSpec` to the endogenous investment `FactorSpec`
+  (`FactorSpec.correction`); its presence triggers the Stage-3 control-function
+  correction. See
+  [Endogeneity Corrections](../reference_guides/endogeneity_corrections.md).
 
 The shared structural field — number of mixture components in the latent
 distribution — lives directly on `ModelSpec.n_mixtures`, since it changes the

docs/explanations/notes_on_factor_scales.md

@@ -74,17 +74,30 @@ However, we don't have formal identification results for this. **We advise cauti
 when using CES or log_CES functions—think carefully about your normalizations rather
 than relying on automatic generation.
 
-## Normalizations and Development Stages
-
-When using development stages (periods with identical transition parameters), the
-normalization requirements change.
-
-The key insight: you can identify scale from the first period of a stage, so no later
-normalizations are needed until the next stage begins.
-
-**Recommendations:**
-- Normalize only in the first period of each stage
-- For the initial stage, normalize the first two periods
-- Use automatic normalizations when working with stages to avoid confusion
-
-This reveals another type of over-normalization in the original CHS paper.
+## Normalizations and Identification
+
+The library distinguishes three separate things, and only the first two are
+mechanical:
+
+1. a **syntactic normalization** you supply through `Normalizations` or
+   `fixed_params`;
+2. an estimator **precheck** that catches some missing initial scale/location
+   anchors — it is a precheck, **not** a proof of identification;
+3. a **transition-family identification argument**, which the library does not
+   establish for arbitrary models.
+
+Because step 3 is on you, there is no single stage-level rule of thumb that is safe
+across transition functions. Use the template that matches your production function:
+
+- **Direct trans-log** (`translog`, `translog_af`): anchor one nonzero loading and
+  one intercept/location for every independently scaled factor-period.
+- **Restricted CES** (`log_ces_af` with $\psi_t = 1$): relative skill/investment
+  scales are identified through the production restrictions, so pinning *every* first
+  loading can impose testable restrictions — follow the CES templates in the
+  estimator-specific guides rather than normalizing mechanically.
+- **Intentionally restricted (original-AMN) benchmark**: a deliberately
+  over-restricted spec used only as a comparison point; label it as such so the extra
+  restrictions are not mistaken for identification requirements.
+
+For custom transitions you must establish identification yourself (or add a
+model-specific diagnostic); the automatic checker will not do it for you.