diff --git a/docs/ClassDefinitions.md b/docs/ClassDefinitions.md
index 4ef19cf1..7da9db12 100644
--- a/docs/ClassDefinitions.md
+++ b/docs/ClassDefinitions.md
@@ -1,26 +1,255 @@
 # Class Definitions
 
 The Python port preserves the MATLAB-facing class names as canonical imports or
-compatibility adapters.
-
-| MATLAB-facing name | Python target | Primary example surface |
-|---|---|---|
-| `SignalObj` | `nstat.SignalObj` | `notebooks/SignalObjExamples.ipynb` |
-| `Covariate` | `nstat.Covariate` | `notebooks/CovariateExamples.ipynb` |
-| `ConfidenceInterval` | `nstat.ConfidenceInterval` | `notebooks/ConfidenceIntervalOverview.ipynb` |
-| `CovColl` | `nstat.CovColl` | `notebooks/CovCollExamples.ipynb` |
-| `Events` | `nstat.Events` | `notebooks/EventsExamples.ipynb` |
-| `History` | `nstat.History` | `notebooks/HistoryExamples.ipynb` |
-| `Trial` | `nstat.Trial` | `notebooks/TrialExamples.ipynb` |
-| `TrialConfig` | `nstat.TrialConfig` | `notebooks/TrialConfigExamples.ipynb` |
-| `ConfigColl` | `nstat.ConfigColl` | `notebooks/ConfigCollExamples.ipynb` |
-| `nspikeTrain` | `nstat.nspikeTrain` | `notebooks/nSpikeTrainExamples.ipynb` |
-| `nstColl` | `nstat.nstColl` | `notebooks/nstCollExamples.ipynb` |
-| `Analysis` | `nstat.Analysis` | `notebooks/AnalysisExamples.ipynb` |
-| `FitResult` | `nstat.FitResult` | `notebooks/FitResultExamples.ipynb` |
-| `FitResSummary` | `nstat.FitResSummary` | `notebooks/FitResSummaryExamples.ipynb` |
-| `CIF` | `nstat.CIF` | `notebooks/PPSimExample.ipynb` |
-| `DecodingAlgorithms` | `nstat.DecodingAlgorithms` | `notebooks/DecodingExample.ipynb` |
+compatibility adapters. Each class below lists its key public methods grouped by
+category.
+
+## Signal and Covariate Primitives
+
+### `SignalObj` (`nstat.SignalObj`)
+
+Primary notebook: `notebooks/SignalObjExamples.ipynb`
+
+**Construction and metadata**:
+`copySignal`, `setName`, `setXlabel`, `setYLabel`, `setUnits`, `setXUnits`,
+`setYUnits`, `setSampleRate`, `setDataLabels`, `setPlotProps`, `with_metadata`
+
+**Accessors**:
+`getTime`, `getData`, `getOriginalData`, `getOrigDataSig`, `getPlotProps`,
+`getValueAt`, `getSubSignalFromInd`, `getSubSignalFromNames`, `getSubSignal`,
+`findNearestTimeIndex`, `findNearestTimeIndices`, `dataToMatrix`,
+`dataToStructure`, `toStructure`, `signalFromStruct`
+
+**Masking**:
+`setDataMask`, `setMaskByInd`, `setMaskByLabels`, `setMask`, `resetMask`,
+`restoreToOriginal`, `findIndFromDataMask`, `isMaskSet`
+
+**Time windowing**:
+`setMinTime`, `setMaxTime`, `getSigInTimeWindow`, `makeCompatible`
+
+**Math and transforms**:
+`abs`, `log`, `power`, `sqrt`, `median`, `mode`, `mean`, `std`, `max`, `min`,
+`derivative`, `derivativeAt`, `integral`, `resample`, `resampleMe`,
+`filter`, `filtfilt`, `merge`
+
+**Shift and alignment**:
+`shift`, `shiftMe`, `alignTime`
+
+**Correlation**:
+`autocorrelation`, `crosscorrelation`, `xcorr`, `xcov`
+
+**Spectral analysis**:
+`periodogram`, `MTMspectrum`, `spectrogram`
+
+**Peak-finding**:
+`findPeaks`, `findMaxima`, `findMinima`, `findGlobalPeak`
+
+**Plotting**:
+`plot`
+
+### `Covariate` (`nstat.Covariate`)
+
+Primary notebook: `notebooks/CovariateExamples.ipynb`
+
+Inherits from `SignalObj`. Adds confidence interval support:
+`setConfInterval`, `mu`, `sigma`
+
+### `ConfidenceInterval` (`nstat.ConfidenceInterval`)
+
+Primary notebook: `notebooks/ConfidenceIntervalOverview.ipynb`
+
+### `CovColl` (`nstat.CovColl`)
+
+Primary notebook: `notebooks/CovCollExamples.ipynb`
+
+**Collection management**:
+`add`, `addCovariate`, `addCovCollection`, `addToColl`, `removeCovariate`,
+`copy`, `get`, `getCov`, `getCovIndFromName`, `getCovIndicesFromNames`,
+`isCovPresent`
+
+**Time and sample rate**:
+`findMinTime`, `findMaxTime`, `findMaxSampleRate`, `setMinTime`, `setMaxTime`,
+`restrictToTimeWindow`, `setSampleRate`, `resample`, `enforceSampleRate`
+
+**Masking**:
+`resetMask`, `getCovDataMask`, `isCovMaskSet`, `flattenCovMask`,
+`getSelectorFromMasks`, `generateSelectorCell`, `setMasksFromSelector`,
+`setMask`, `nActCovar`, `maskAwayCov`, `maskAwayOnlyCov`, `maskAwayAllExcept`
+
+**Shift and restore**:
+`setCovShift`, `resetCovShift`, `restoreToOriginal`
+
+**Data export**:
+`getAllCovLabels`, `getCovLabelsFromMask`, `matrixWithTime`, `dataToMatrix`,
+`dataToStructure`, `toStructure`, `fromStructure`
+
+---
+
+## Spiking Data Structures
+
+### `nspikeTrain` (`nstat.nspikeTrain`)
+
+Primary notebook: `notebooks/nSpikeTrainExamples.ipynb`
+
+### `nstColl` (`nstat.nstColl`)
+
+Primary notebook: `notebooks/nstCollExamples.ipynb`
+
+**Collection management**:
+`addSingleSpikeToColl`, `addToColl`, `merge`, `length`, `get_nst`, `getNST`,
+`getNSTnames`, `getUniqueNSTnames`, `toSpikeTrain`
+
+**Time operations**:
+`shiftTime`, `setMinTime`, `setMaxTime`
+
+**SSGLM (state-space GLM)**:
+`ssglm`, `ssglmFB`
+
+**Basis generation**:
+`generateUnitImpulseBasis`
+
+### `History` (`nstat.History`)
+
+Primary notebook: `notebooks/HistoryExamples.ipynb`
+
+### `Events` (`nstat.Events`)
+
+Primary notebook: `notebooks/EventsExamples.ipynb`
+
+---
+
+## Experiment and Configuration Objects
+
+### `Trial` (`nstat.Trial`)
+
+Primary notebook: `notebooks/TrialExamples.ipynb`
+
+**Partitioning**:
+`getTrialPartition`, `setTrialPartition`, `setTrialTimesFor`,
+`updateTimePartitions`
+
+**Time and sample rate**:
+`setMinTime`, `setMaxTime`, `setSampleRate`, `resample`,
+`makeConsistentSampleRate`, `makeConsistentTime`, `isSampleRateConsistent`,
+`findMaxSampleRate`, `findMinTime`, `findMaxTime`
+
+**Covariate and neuron masks**:
+`setCovMask`, `resetCovMask`, `setNeuronMask`, `resetNeuronMask`,
+`setNeighbors`, `setHistory`, `resetHistory`, `setEnsCovHist`, `setEnsCovMask`,
+`resetEnsCovMask`, `isNeuronMaskSet`, `isCovMaskSet`, `isMaskSet`, `isHistSet`,
+`isEnsCovHistSet`
+
+**Data access**:
+`addCov`, `removeCov`, `getSpikeVector`, `get_covariate_matrix`,
+`getDesignMatrix`, `getHistForNeurons`, `getHistMatrices`,
+`getEnsembleNeuronCovariates`, `getEnsCovMatrix`, `getNeuronIndFromMask`,
+`getNumUniqueNeurons`, `getNeuronNames`, `getUniqueNeuronNames`,
+`getNeuronIndFromName`, `getAllCovLabels`, `getCovLabelsFromMask`,
+`getHistLabels`, `getEnsCovLabels`, `getLabelsFromMask`, `flattenCovMask`,
+`flattenMask`
+
+**Utilities**:
+`shiftCovariates`, `resampleEnsColl`, `restoreToOriginal`, `plot`
+
+### `TrialConfig` (`nstat.TrialConfig`)
+
+Primary notebook: `notebooks/TrialConfigExamples.ipynb`
+
+### `ConfigColl` (`nstat.ConfigColl`)
+
+Primary notebook: `notebooks/ConfigCollExamples.ipynb`
+
+---
+
+## Modeling and Inference
+
+### `CIF` (`nstat.CIF`)
+
+Primary notebook: `notebooks/PPSimExample.ipynb`
+
+Conditional intensity function (CIF) primitives and point-process simulation
+via thinning.
+
+### `Analysis` (`nstat.Analysis`)
+
+Primary notebook: `notebooks/AnalysisExamples.ipynb`
+
+**Core fitting**:
+`GLMFit`, `run_analysis_for_neuron`, `run_analysis_for_all_neurons`,
+`RunAnalysisForNeuron`, `RunAnalysisForAllNeurons`
+
+**PSTH**:
+`psth`
+
+**Diagnostics**:
+`computeKSStats`, `computeInvGausTrans`, `computeFitResidual`,
+`KSPlot`, `plotFitResidual`, `plotInvGausTrans`, `plotSeqCorr`, `plotCoeffs`
+
+**History and model selection**:
+`computeHistLag`, `computeHistLagForAll`, `compHistEnsCoeff`,
+`compHistEnsCoeffForAll`
+
+**Network and Granger causality**:
+`computeGrangerCausalityMatrix`, `computeNeighbors`, `spikeTrigAvg`
+
+### `FitResult` (`nstat.FitResult`)
+
+Primary notebook: `notebooks/FitResultExamples.ipynb`
+
+**Coefficient access**:
+`getCoeffs`, `getHistCoeffs`, `getCoeffIndex`, `getHistIndex`, `getParam`,
+`getCoeffsWithLabels`, `computePlotParams`, `getPlotParams`
+
+**Lambda (conditional intensity) access**:
+`lambdaSignal`, `lambda_obj`, `lambda_model`, `lambda_result`, `lambdaObj`,
+`lambdaCov`, `lambda_sig`, `lambda_data`, `lambda_values`, `lambda_time`,
+`lambda_rate`, `evalLambda`
+
+**Diagnostics and statistics**:
+`computeKSStats`, `computeInvGausTrans`, `computeFitResidual`
+
+**Plotting**:
+`plotResults`, `KSPlot`, `plotResidual`, `plotInvGausTrans`, `plotSeqCorr`,
+`plotCoeffs`, `plotCoeffsWithoutHistory`, `plotHistCoeffs`, `plotValidation`
+
+**Serialization**:
+`toStructure`, `fromStructure`, `CellArrayToStructure`, `mergeResults`
+
+### `FitResSummary` (`nstat.FitResSummary`)
+
+Primary notebook: `notebooks/FitResSummaryExamples.ipynb`
+
+Alias of `FitSummary`. Aggregates multiple `FitResult` objects.
+
+**Information criterion**:
+`getDiffAIC`, `getDiffBIC`, `getDifflogLL`
+
+**Coefficient extraction**:
+`getCoeffs`, `getHistCoeffs`, `getSigCoeffs`, `binCoeffs`, `setCoeffRange`,
+`mapCovLabelsToUniqueLabels`
+
+**Plotting**:
+`plotIC`, `plotAIC`, `plotBIC`, `plotlogLL`, `plotResidualSummary`,
+`plotSummary`, `boxPlot`
+
+### `DecodingAlgorithms` (`nstat.DecodingAlgorithms`)
+
+Primary notebook: `notebooks/DecodingExample.ipynb`
+
+**Point-process decode filters**:
+`PPDecodeFilterLinear`, `PPDecodeFilter`, `PPHybridFilterLinear`,
+`ComputeStimulusCIs`
+
+**Kalman and unscented Kalman filters**:
+`kalman_filter`, `PP_fixedIntervalSmoother`, `ukf`
+
+**State-space GLM (SSGLM) — EM algorithm**:
+`PPSS_EStep`, `PPSS_MStep`, `PPSS_EM`, `PPSS_EMFB`
+
+**SSGLM utilities**:
+`estimateInfoMat`, `prepareEMResults`
+
+---
 
 See [Examples](Examples.md) for the full help-style index and
 [API Reference](api.rst) for the module layout.
diff --git a/docs/Examples.md b/docs/Examples.md
index b5bfbe76..b036aaa1 100644
--- a/docs/Examples.md
+++ b/docs/Examples.md
@@ -49,7 +49,26 @@ Paper cross-reference:
 
 ## Consolidated Paper Workflow
 
-- `nSTATPaperExamples`: `notebooks/nSTATPaperExamples.ipynb`
-- Canonical standalone scripts: `examples/paper/example01_mepsc_poisson.py`
-  through `examples/paper/example05_decoding_ppaf_pphf.py`
+All five paper examples are self-contained scripts mirroring their MATLAB
+counterparts:
+
+| Example | Script | What it demonstrates |
+|---|---|---|
+| 01 — mEPSC Poisson | [example01_mepsc_poisson.py](../examples/paper/example01_mepsc_poisson.py) | Constant vs piecewise Poisson under Mg2+ washout |
+| 02 — Whisker Stimulus | [example02_whisker_stimulus_thalamus.py](../examples/paper/example02_whisker_stimulus_thalamus.py) | Explicit-stimulus GLM with lag and history selection |
+| 03 — PSTH and SSGLM | [example03_psth_and_ssglm.py](../examples/paper/example03_psth_and_ssglm.py) | PSTH comparison and state-space GLM dynamics |
+| 04 — Place Cells | [example04_place_cells_continuous_stimulus.py](../examples/paper/example04_place_cells_continuous_stimulus.py) | Gaussian vs Zernike receptive-field models |
+| 05 — PPAF and PPHF | [example05_decoding_ppaf_pphf.py](../examples/paper/example05_decoding_ppaf_pphf.py) | Adaptive and hybrid point-process decoding |
+
 - Generated gallery and figure index: [Paper Examples](paper_examples.md)
+- Master notebook: `notebooks/nSTATPaperExamples.ipynb`
+
+## Supplementary (README) Examples
+
+These smaller demos serve as quick install and plotting checks:
+
+| Example | Run command |
+|---|---|
+| Multitaper spectrum + spectrogram | `python examples/readme_examples/example1_multitaper_and_spectrogram.py` |
+| Simulated CIF spike train | `python examples/readme_examples/example2_simulate_cif_spiketrain_10s.py` |
+| Spike-train raster | `python examples/readme_examples/example3_nstcoll_raster_from_example2.py` |
diff --git a/docs/NeuralSpikeAnalysis_top.md b/docs/NeuralSpikeAnalysis_top.md
index f810c061..bebca6b3 100644
--- a/docs/NeuralSpikeAnalysis_top.md
+++ b/docs/NeuralSpikeAnalysis_top.md
@@ -1,33 +1,56 @@
 # Neural Spike Train Analysis Toolbox (nSTAT)
 
 `nSTAT-python` is the standalone Python port of the neural spike-train analysis
-toolbox. It preserves the MATLAB toolbox's public API naming, paper-example
+toolbox. It implements a range of models and algorithms for neural spike train
+data analysis, with a focus on point-process generalized linear models (GLMs),
+model fitting, model-order analysis, and adaptive decoding. In addition to
+point-process algorithms, nSTAT also provides tools for Gaussian signals — from
+correlation analysis to the Kalman filter — applicable to continuous neural
+signals such as LFP, EEG, and ECoG.
+
+The port preserves the MATLAB toolbox's public API naming, paper-example
 structure, and help/example coverage wherever a Python equivalent is
 reasonable.
 
 ## Documentation Navigation
 
-- [Paper-Aligned Toolbox Map](PaperOverview.md)
-- [Class Definitions](ClassDefinitions.md)
-- [Example Index](Examples.md)
-- [nSTAT Paper Examples](paper_examples.md)
-- [Documentation Setup](DocumentationSetup.md)
-- [API Reference](api.rst)
-
-## Purpose
-
-The toolbox consolidates point-process and GLM-based neural data analysis into
-a coherent Python package with:
-
-- MATLAB-compatible public entry points such as `Analysis`, `TrialConfig`,
-  `FitResult`, `DecodingAlgorithms`, `nSTAT_Install`, and `getPaperDataDirs`
-- Canonical paper examples exported as `examples/paper/example01` through
-  `example05`
-- Notebook-backed help workflows mirroring the MATLAB helpfiles
-- A generated figure gallery under `docs/figures/`
+- [Paper-Aligned Toolbox Map](PaperOverview.md) — maps classes and methods to
+  the 2012 paper's sections
+- [Class Definitions](ClassDefinitions.md) — all classes with grouped method
+  listings
+- [Example Index](Examples.md) — full help-style index of notebooks and scripts
+- [nSTAT Paper Examples](paper_examples.md) — generated gallery with figures
+  from all 5 paper examples
+- [Documentation Setup](DocumentationSetup.md) — installation, build, and
+  troubleshooting
+- [Data Installation](data_installation.rst) — example dataset download
+- [API Reference](api.rst) — module layout
+
+## Key Capabilities
+
+- **GLM fitting and assessment**: Point-process GLMs with stimulus, history,
+  and ensemble covariates. AIC/BIC model selection, KS goodness-of-fit,
+  residual analysis.
+- **SSGLM (state-space GLM)**: Full EM algorithm (`PPSS_EMFB`) for estimating
+  across-trial coefficient dynamics with forward-backward Kalman smoothing.
+- **Adaptive decoding**: Point-process adaptive filter (PPAF) for real-time
+  stimulus and state decoding from neural spike trains.
+- **Hybrid filter**: Joint discrete/continuous state estimation combining
+  point-process observations with hidden Markov models.
+- **UKF support**: Unscented Kalman filter for nonlinear state estimation.
+- **Signal processing**: Multi-taper spectral estimation, spectrograms,
+  cross-covariance, peak-finding, and time-domain signal manipulation.
+- **Granger causality**: Ensemble Granger causality analysis for network
+  connectivity inference.
 
 ## Citation
 
 Cajigas I, Malik WQ, Brown EN. *nSTAT: Open-source neural spike train analysis
 toolbox for Matlab*. Journal of Neuroscience Methods 211:245-264 (2012).
 DOI: [10.1016/j.jneumeth.2012.08.009](https://doi.org/10.1016/j.jneumeth.2012.08.009)
+PMID: [22981419](https://pubmed.ncbi.nlm.nih.gov/22981419/)
+
+## Lab Websites
+
+- Neuroscience Statistics Research Laboratory: [neurostat.mit.edu](https://www.neurostat.mit.edu)
+- RESToRe Lab: [cajigaslab](https://www.med.upenn.edu/cajigaslab/)
diff --git a/docs/PaperOverview.md b/docs/PaperOverview.md
index 72585a2f..92423dc9 100644
--- a/docs/PaperOverview.md
+++ b/docs/PaperOverview.md
@@ -27,46 +27,136 @@ Related navigation pages:
 
 ## Fitting and Assessment Workflow
 
-The paper's core GLM workflow maps to Python as:
+The paper's core GLM workflow (Section 2.3) maps to Python as:
 
 1. Build trial data with `Trial`, `CovColl`, and `nstColl`.
 2. Define model configurations with `TrialConfig` and `ConfigColl`.
 3. Fit and evaluate analyses with `Analysis` and `FitResult`.
 4. Summarize across fits with `FitResSummary`.
 
+Key `Analysis` methods for model selection:
+
+- `computeHistLag` / `computeHistLagForAll` — sweep spike-history window
+  configurations and select optimal lag via AIC/BIC/KS.
+- `computeGrangerCausalityMatrix` — ensemble Granger causality analysis.
+- `compHistEnsCoeff` / `compHistEnsCoeffForAll` — ensemble history coefficients.
+- `computeNeighbors` — identify functionally connected neighbors.
+
+Key `FitResSummary` plotting methods:
+
+- `plotIC`, `plotAIC`, `plotBIC`, `plotlogLL` — information criterion plots.
+- `plotSummary`, `plotResidualSummary` — aggregate diagnostics.
+- `boxPlot`, `binCoeffs` — coefficient distribution analysis.
+
 Representative notebooks are indexed in [Examples](Examples.md), especially
 `AnalysisExamples`, `FitResultExamples`, and `FitResSummaryExamples`.
 
 ## Simulation Workflow
 
 The simulation workflow remains centered on conditional intensity functions
-and thinning-based point-process simulation:
+and thinning-based point-process simulation (Section 2.2):
 
-- `CIF`
-- `PPThinning`
-- `PPSimExample`
+- `CIF` — conditional intensity function primitives, including `simulateCIF`
+- `PPThinning` — point-process thinning simulation
+- `PPSimExample` — complete simulation workflow
 
 These are covered by the corresponding notebooks listed in
 [Examples](Examples.md).
 
+## State-Space GLM (SSGLM) Workflow
+
+The state-space GLM estimation (Section 2.4) is now fully implemented:
+
+- `DecodingAlgorithms.PPSS_EMFB` — full EM algorithm with forward-backward
+  Kalman smoothing. Estimates across-trial coefficient dynamics with
+  confidence intervals.
+- `DecodingAlgorithms.PPSS_EStep` — E-step: forward Kalman filter + backward
+  RTS smoother + cross-covariance computation.
+- `DecodingAlgorithms.PPSS_MStep` — M-step: Newton-Raphson update for
+  observation model parameters.
+- `DecodingAlgorithms.PPSS_EM` — single-neuron EM driver.
+- `nstColl.ssglm` / `nstColl.ssglmFB` — collection-level convenience wrappers
+  that run SSGLM across all neurons in a spike train collection.
+
+This workflow is demonstrated in Example 03 (PSTH and SSGLM dynamics).
+
 ## Decoding Workflow
 
-The adaptive filtering and decoding portions of the paper map to:
+The adaptive filtering and decoding portions of the paper (Sections 2.5-2.6)
+map to:
+
+**Point-process adaptive filters (Section 2.5)**:
+
+- `DecodingAlgorithms.PPDecodeFilterLinear` — linear-CIF point-process
+  adaptive filter for continuous stimulus decoding.
+- `DecodingAlgorithms.PPDecodeFilter` — general CIF version using symbolic
+  gradients/Jacobians.
+- `DecodingAlgorithms.ComputeStimulusCIs` — stimulus confidence intervals.
+- `DecodingAlgorithms.PP_fixedIntervalSmoother` — fixed-interval smoother
+  for off-line smoothing of decode estimates.
+
+**Hybrid filter (Section 2.6)**:
+
+- `DecodingAlgorithms.PPHybridFilterLinear` — joint discrete/continuous state
+  estimation combining point-process observations with a hidden Markov model
+  over discrete states and Kalman filtering over continuous kinematics.
+
+**Kalman and UKF filters**:
+
+- `DecodingAlgorithms.kalman_filter` — standard linear Kalman filter.
+- `DecodingAlgorithms.ukf` — unscented Kalman filter for nonlinear state
+  estimation.
+
+Related notebooks:
+
+- `DecodingExample`, `DecodingExampleWithHist`, `StimulusDecode2D`,
+  `HybridFilterExample`
+
+## Signal Processing Methods
+
+`SignalObj` now includes a full suite of signal processing methods mirroring
+the MATLAB toolbox:
+
+**Spectral analysis**:
+
+- `MTMspectrum` — multi-taper spectral estimation using DPSS tapers.
+- `spectrogram` — time-frequency decomposition.
+- `periodogram` — standard periodogram PSD estimate.
+
+**Correlation and cross-covariance**:
+
+- `xcorr` — cross-correlation (or auto-correlation).
+- `xcov` — cross-covariance with lag support.
+- `autocorrelation`, `crosscorrelation` — normalized correlation functions.
+
+**Time manipulation**:
+
+- `shift` / `shiftMe` — shift signal in time (copy vs in-place).
+- `alignTime` — re-reference time axis to a marker.
+- `power`, `sqrt` — element-wise transforms.
+
+**Peak-finding**:
 
-- `DecodingAlgorithms`
-- `DecodingExample`
-- `DecodingExampleWithHist`
-- `StimulusDecode2D`
-- `HybridFilterExample`
+- `findPeaks`, `findMaxima`, `findMinima` — local extrema via
+  `scipy.signal.find_peaks`.
+- `findGlobalPeak` — global maximum or minimum per channel.
 
 ## Example-to-Paper Section Mapping
 
 The paper's representative workflows align to the following Python surfaces:
 
-- `mEPSCAnalysis` and `PSTHEstimation`: event-process and PSTH analysis
-- `ExplicitStimulusWhiskerData` and `HippocampalPlaceCellExample`:
-  stimulus-response and receptive-field modeling
-- `DecodingExample`, `DecodingExampleWithHist`, and `StimulusDecode2D`:
-  decoding and state estimation
-- `nSTATPaperExamples` and the canonical gallery in [Paper Examples](paper_examples.md):
-  consolidated reproduction workflow for the toolbox paper
+| Paper section | Example | Python surface |
+|---|---|---|
+| 2.3.1 — mEPSC Poisson | Example 01 | `examples/paper/example01_mepsc_poisson.py` |
+| 2.3.2 — Whisker stimulus | Example 02 | `examples/paper/example02_whisker_stimulus_thalamus.py` |
+| 2.3.3 — PSTH | Example 03, Part A | `examples/paper/example03_psth_and_ssglm.py` |
+| 2.4 — SSGLM | Example 03, Part B | `examples/paper/example03_psth_and_ssglm.py` |
+| 2.3.4 — Place cells | Example 04 | `examples/paper/example04_place_cells_continuous_stimulus.py` |
+| 2.5 — PPAF decoding | Example 05, Parts A-B | `examples/paper/example05_decoding_ppaf_pphf.py` |
+| 2.6 — Hybrid filter | Example 05, Part C | `examples/paper/example05_decoding_ppaf_pphf.py` |
+
+See also:
+
+- `nSTATPaperExamples` notebook and the canonical gallery in [Paper Examples](paper_examples.md)
+- All five paper examples are now **self-contained scripts** with full analysis
+  workflows, matching their MATLAB counterparts.
diff --git a/docs/api.rst b/docs/api.rst
index 14736bf4..942bbea0 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -3,23 +3,25 @@ API Reference
 
 Core modules:
 
-- ``nstat.signal``
-- ``nstat.spikes``
-- ``nstat.events``
-- ``nstat.history``
-- ``nstat.trial``
-- ``nstat.cif``
-- ``nstat.analysis``
-- ``nstat.fit``
-- ``nstat.decoding``
-- ``nstat.datasets``
+- ``nstat.core`` — ``SignalObj``, ``Covariate``, ``nspikeTrain``
+- ``nstat.trial`` — ``CovariateCollection`` (CovColl), ``SpikeTrainCollection``
+  (nstColl), ``Trial``, ``TrialConfig``, ``ConfigCollection`` (ConfigColl)
+- ``nstat.events`` — ``Events``
+- ``nstat.history`` — ``History``
+- ``nstat.cif`` — ``CIF``
+- ``nstat.analysis`` — ``Analysis``
+- ``nstat.fit`` — ``FitResult``, ``FitSummary`` (FitResSummary)
+- ``nstat.decoding_algorithms`` — ``DecodingAlgorithms``
+- ``nstat.confidence_interval`` — ``ConfidenceInterval``
+- ``nstat.data_manager`` — dataset download and cache management
 
-Compatibility adapters:
+MATLAB-compatible public imports (``from nstat import ...``):
 
-- ``nstat.SignalObj``
-- ``nstat.nspikeTrain``
-- ``nstat.FitResult``
-- ``nstat.FitResSummary``
-- ``nstat.ConfigColl``
-- ``nstat.CovColl``
-- ``nstat.TrialConfig``
+- ``SignalObj``, ``Covariate``, ``nspikeTrain``
+- ``CovColl``, ``nstColl``
+- ``Trial``, ``TrialConfig``, ``ConfigColl``
+- ``History``, ``Events``, ``CIF``
+- ``Analysis``, ``FitResult``, ``FitResSummary``
+- ``DecodingAlgorithms``, ``ConfidenceInterval``
+- ``getPaperDataDirs``, ``get_paper_data_dirs``
+- ``nSTAT_Install``, ``nstat_install``