Improve task guidance, runnable examples, and pinned book links

[stefan-jansen]

Reader problem

The home page and Quickstart lead with a large IPCA run, while the six Chapter 14 files named in the Book Guide have no direct links. The guides explain model families but do not consistently show a complete task with a verifiable result. The public book's Chapter 14 notebooks implement the methods manually, so their relationship to the released API needs clear labels.

Capability inventory at intake

Supported workflow	Current guide	API reference	Runnable repository example	Public book match
Latent factors and forecasting (PCA, RP-PCA, IPCA, CAE)	Latent-Factor Pipelines and Models	API Reference: models, pipelines, contracts	examples/latent_factor_pipeline.py covers PCA only	Chapter 14 notebooks 04-06 teach the corresponding methods manually; 09 compares outcomes
SDF estimation and projection	Stochastic Discount Factor	API Reference: model, config, state, mapper	examples/stochastic_discount_factor.py	Chapter 14 notebook 07 teaches the method manually
Direct asset prediction (SAE)	Direct Asset Prediction	API Reference: model, config, signal result	examples/direct_asset_prediction.py	Chapter 14 notebook 08 teaches supervised autoencoders manually
Portfolio allocation	Portfolio Learning	API Reference: portfolio models, configs, results, pipeline	examples/portfolio_learning.py covers the linear baseline	Chapter 17 notebooks 11-13 illustrate related deep allocation methods, not this API
Data contracts and long-frame adapters	Data Contracts and Integration	API Reference: contracts and integration	Examples construct batches; no standalone adapter example	No exact teaching notebook match established
Diagnostic/backtest handoff	Integration	API Reference: integration	No standalone handoff example	Case-study library bridge exists; exact direct notebook mapping needs verification

Neural families require the deep extra and can have long training runs. integration adds Polars and Specs helpers. Execution, diagnostics, and broker or data acquisition are outside this package. Internal modules prefixed with _ are not stable API.

Acceptance

• Put a bounded, observable first workflow before IPCA and neural training; route home and navigation to it, task guides, generated API reference, and Book Guide.
• Complete task guidance and runnable examples for the principal supported workflows, including input contracts, result checks, dependencies, and limits.
• Link direct public book files at one verified companion commit. State whether each manually teaches the method, calls the library, or illustrates a related workflow; make guide and Book Guide links reciprocal.
• Run representative examples from a built wheel in a clean environment, check rendered/internal links, and pass strict MkDocs build and repository quality gates.
• Record the capability inventory, executed checks, pinned revision, and exceptions in the PR. Keep sidecar evidence private.

Source: the 2026-09-24 six-library documentation review and Models documentation-quality handoff.