spectro-kernel 0.6.1__tar.gz → 0.7.0__tar.gz

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/.gitignore

@@ -164,6 +164,12 @@ venv.bak/
 # Rope project settings
 .ropeproject
 
+# documentation - generated by tools/docs/generate.py
+docs/algorithms/
+docs/recipes/catalogue/
+docs/ai/
+docs/llms.txt
+
 # mkdocs documentation
 /site
 

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/CHANGELOG.md

@@ -6,6 +6,289 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-09-26
+
+The release that turns presets into **recipes** : a measurement written once,
+with its conventions fixed and everything instrument-dependent declared as a
+variable, so that observers with different spectrographs produce comparable
+numbers. It also lands the bricks those recipes need for pro-am campaigns
+(time-series line-profile analysis, the flux-calibration chain, stellar
+activity and rotation indicators, resolving power, spline continuum) and a
+FITS reader that copes with the amateur "zoo". Numerical changes are carried
+by MAJOR bumps of the bricks concerned and listed below.
+
+### Added — recipes, variables and profiles (presets v2)
+
+- A preset may declare a `variables` block (`type` among `str`, `int`,
+  `float`, `bool`, `path`, `list`; `default`, `required`, `description`,
+  `choices`) and reference them as `"${name}"` in step parameters. The
+  values come from a **profile** (`spectro pipeline <recipe> --profile
+  file.yaml`), from `--set name=value` (converted to the declared type),
+  from `PipelineBuilder().from_preset(name, variables={...})` /
+  `from_config(config, variables)`, or from the `variables` argument of
+  the MCP `run_preset` tool. Defaults fill the gaps ; a missing required
+  variable, an undeclared token or a value of the wrong type is refused
+  before anything runs, with the variable's description in the message.
+  A preset without `variables` is unchanged.
+- `requires: ">=0.7, <1.0"` : the kernel range a recipe was validated for
+  (plain comparison operators) ; a recipe outside the range refuses to build.
+- Standard metadata vocabulary : `kind` (`analysis`, `reduction`,
+  `campaign`, `template`), `status` (`draft`, `reviewed`, `reference`),
+  `references` (mandatory for a campaign recipe), `conventions`.
+- **Discovery** : besides the bundled catalogue, the kernel lists recipes
+  from every directory in `SPECTRO_PRESET_PATH` and from installed
+  packages registering the `spectro_kernel.presets` entry point (a
+  `Path` to a directory of YAML files). `list_presets()` reports each
+  recipe's `source` ; a bundled name wins over an external one.
+- **Validation** : `spectro preset validate <file-or-name>...` (also
+  `--profile` / `--set` to type-check values) reports every problem at
+  once : name not snake_case, missing or malformed version, missing
+  description, unknown `kind` / `status`, campaign recipe without
+  references, unsatisfied `requires`, unknown algorithm, unknown parameter,
+  required parameter neither set nor bound, undeclared token, unused
+  variable, `depends_on` matching no step. `spectro preset show <name>`
+  prints a recipe's variables and steps ; `spectro presets` shows the
+  source and the number of variables. Python : `validate_preset`,
+  `validate_preset_file`, `preset_sources`, `find_preset`.
+- **Provenance** : every named pipeline built from a file or a config
+  closes its run with a `pipeline:<name>` `ProcessingStep` carrying the
+  recipe version, the bound variables, the kernel version and the source,
+  so a result states which recipe produced it. Ad-hoc pipelines assembled
+  in Python without a name are unchanged.
+- The bundled `full_reduction_easyspec` template (2.0.0) replaces its
+  `__REPLACE__` placeholders by ten declared variables (`bias_dir`,
+  `dark_dir`, `flat_dir`, `science_path`, `exposure_seconds`, `airmass`,
+  `gain`, `readnoise`, `target_name`, `combine_method`) ; the six analysis
+  presets gain `kind` and `status` metadata. The preset file format is
+  published as `preset.schema.json`.
+- The curated collection lives in a separate repository,
+  [spectro-kernel-recipes](https://github.com/matthieulel/spectro-kernel-recipes)
+  (`pip install spectro-kernel-recipes`), starting with `be_halpha_ew`,
+  `binary_rv_ccf`, `solar_long_slit` and `stellar_long_slit` (all `draft`).
+
+### Added — time-series line-profile analysis (category `timeseries`, `stacking`)
+
+- **`temporal_variance_spectrum` v1.0.0** (scipy) — Fullerton, Gies & Bolton
+  1996, ApJS 103, 475, §3 : N ≥ 3 continuum-normalised epochs in
+  `ctx.spectra`, resampled on the finest common grid over the overlap ;
+  per-epoch noise σ_ic from `uncertainty` or DER_SNR on a continuum window
+  (`continuum_lo` / `continuum_hi`) ; weights w_i = (σ_0/σ_ic)² with
+  σ_0 = [(1/N) Σ σ_ic⁻²]^(−1/2) ; (TVS)_j = (N−1)⁻¹ Σ_i w_i (S_ij − S̄_j)² ;
+  reported as (TVS)^{1/2} with the χ²_(N−1) significance threshold at
+  `confidence` (0.99). Writes `extras.tvs` and the `tvs_*` metrics, the
+  bounds of the longest significant run as `tvs_variable_lo_aa` /
+  `tvs_variable_hi_aa`. Caveat documented : the pixel-dependent
+  photon-noise term α_ij of the paper is not applied (uniform noise across
+  the profile). Tests : variability confined to |v| < 120 km/s → 71 % of
+  pixels flagged inside, 2.2 % beyond 200 km/s ; no variability → 1.2 %
+  above the 99 % threshold ; threshold exact to 1e-12.
+- **`phase_dispersion_minimization` v1.0.0** (numpy) — Stellingwerf 1978,
+  ApJ 224, 953 : Θ = s²/σ² over M = N_b·N_c overlapping phase samples
+  (`n_bins` 10, `n_covers` 3), uniform frequency grid (`n_periods` 2000),
+  light-curve input exactly as `lomb_scargle`. `ctx.periodograms[key]`
+  carries Θ with `meta.lower_is_better` ; metrics `pdm_best_period_days`,
+  `pdm_theta_min`. No false-alarm probability on purpose
+  (Schwarzenberg-Czerny 1997, ApJ 489, 941). Tests : eclipse and sawtooth
+  signals at 3.7 d over 60 d recovered to 0.11 % ; pure noise → Θ ≈ 1.00.
+- **`box_least_squares` v1.0.0** (astropy) — Kovács, Zucker & Mazeh 2002,
+  A&A 391, 369, wrapping `astropy.timeseries.BoxLeastSquares` ;
+  `duration_hours` list, `objective` likelihood / snr ; periodogram plus
+  `extras.bls_model` and the `bls_*` metrics. Without uncertainties the
+  noise is 1.4826·MAD (Rousseeuw & Croux 1993) instead of astropy's
+  implicit σ = 1 (which gave a 41-σ transit an SNR of 0.09). Tests :
+  P = 2.5 d, depth 1 %, 3 h box on a 30 d series → period to 0.012 %,
+  depth to 1.8 %, SNR 41.
+- **`stack_spectra` 2.0.0 → 2.1.0** (additive) : `method: "weighted"`, the
+  Bevington & Robinson inverse-variance mean with the stack uncertainty
+  (Σ w)^(−1/2) ; weights from the `weights` parameter, else from every
+  spectrum's `uncertainty`, else from DER_SNR² (Tody 1993, IRAF `scombine`).
+  mean / median / sum are bit-identical to v2.0.0. Test : σ = 1 and 2 →
+  weights 4:1, output σ = 1/√1.25.
+
+### Added — flux-calibration chain (categories `correction`, `catalog`, `nebular`)
+
+- **`atmospheric_extinction_correct` v1.0.0** (numpy) — F_0 = F·10^{0.4 k(λ) X}
+  (Hayes & Latham 1975, ApJ 197, 593 ; Hardie 1962). Built-in `curve`
+  `"kpno"`, the IRAF `onedstds$kpnoextinct.dat` mean extinction table
+  (3200–10400 Å, Tody 1986 ; all 82 nodes checked against the IRAF source,
+  the last four being CTIO values), or a user table in `ctx.extras`. Airmass from
+  `airmass`, else from the header / site with Kasten & Young 1989, Appl.
+  Opt. 28, 4735, eq. 3. Uncertainty scaled with the flux. Metrics
+  `airmass`, `k_mag_median`, `n_outside_curve`.
+- **`deredden_interstellar` v1.0.0** (dust_extinction, optional extra
+  `reduction`) — F_0 = F / 10^{−0.4 A(λ)} with CCM89 (Cardelli, Clayton &
+  Mathis 1989, ApJ 345, 245 ; default), F99 (Fitzpatrick 1999, PASP 111,
+  63) or G23 (Gordon et al. 2023, ApJ 950, 86) ; `ebv`, `rv` (3.1) ; fails
+  outside a law's validity range. Test : CCM89, R_V = 3.1, E(B−V) = 0.1 at
+  5500 Å → factor 10^{0.4·0.31} = 1.330, checked against the package.
+- **`standard_star_reference` v1.0.0** (astropy ; network, lazy) — loads a
+  CALSPEC standard (Bohlin, Gordon & Tremblay 2014, PASP 126, 711 ; Bohlin,
+  Hubeny & Rauch 2020, AJ 160, 21) by name or `filename` from the STScI
+  reference-atlas archive through the SSRF-guarded fetch with timeout and
+  size cap, or a Pickles 1998 (PASP 110, 863) template ; vacuum → air with
+  Morton 2000 (`to_air`) ; writes `extras.catalog_spectrum` (rename with
+  `output_key`, e.g. to `reference_spectrum` for `response_from_standard`).
+  Pickles templates are normalised to unity at 5556 Å by construction
+  (Pickles 1998, §3 and §5) and passed through unchanged ; the brick reports
+  `flux_at_5556_aa` so the caller can see it.
+- **`balmer_decrement_extinction` v1.0.0** (scipy) — c(Hβ), E(B−V) and A_V
+  from the observed Hα/Hβ ratio against Case B 2.86 (Osterbrock & Ferland
+  2006, Table 4.4, §7.2) with the CCM89 f(λ) ; negative extinction clamped
+  to 0 with a note ; metrics `balmer_ratio_observed`, `c_hbeta`,
+  `ebv_balmer`, `a_v_balmer`, `flux_halpha`, `flux_hbeta`.
+
+### Changed — uncertainties are now propagated (MAJOR bumps ; flux byte-identical)
+
+Until now every one of these bricks copied the input `uncertainty` array
+unchanged, which is wrong after any of them. Each now documents its rule ;
+a spectrum without uncertainty is processed exactly as before.
+
+- `smooth_gaussian` 1.0.1 → 2.0.0 and `smooth_savgol` 1.0.1 → 2.0.0 :
+  σ_out,i = sqrt(Σ_k w_k² σ²) with the very kernel applied (Gaussian
+  truncated at 4σ ; Savitzky-Golay coefficients incl. the edge polynomials).
+  White noise, sigma = 2 px → σ_out = 0.376 σ in the interior and 0.641 σ
+  at the first and last samples (the 'nearest' edge weights add before
+  squaring) ; window 11 / order 3 → 0.4555 σ. Both checked against the full
+  linear operator to 1e-9 and by Monte-Carlo. Correlated noise is not
+  tracked (documented).
+- `normalize_polynomial` 1.1.1 → 2.0.0, `normalize_to_region` 1.0.1 →
+  2.0.0, `normalize_max` 1.0.2 → 2.0.0, `normalize_percentile` 1.0.2 →
+  2.0.0, `normalize_edges` 1.0.2 → 2.0.0 : σ_out = σ_in / |continuum|,
+  continuum treated as noise-free.
+- `resample_linear` 1.0.1 → 2.0.0 : σ_out = sqrt(interp(σ²)) (linear
+  interpolation of the variance ; v1 interpolated σ itself).
+- `combine_spectra_arithmetic` 1.0.1 → 2.0.0 : add/sub in quadrature ;
+  mul/div with the relative errors in quadrature when the reference
+  carries an uncertainty (Bevington & Robinson §3.2), else σ·|r| or σ/|r|.
+
+### Added — stellar activity, rotation, resolution, continuum (new category `activity`)
+
+- **`activity_index_caii_hk` v1.0.0** (numpy, `activity`) — the Mount
+  Wilson S index, S = α (H + K)/(R + V) with the HKP-2 triangular 1.09 Å
+  H and K bands and the 20 Å R and V bands (Vaughan, Preston & Wilson 1978,
+  PASP 90, 267 ; Duncan et al. 1991, ApJS 76, 383), `alpha` 2.3 (échelle
+  convention, Lovis et al. 2011) with an optional linear calibration to the
+  Mount Wilson scale ; log R'_HK when `b_v` is given (Noyes et al. 1984,
+  ApJ 279, 763 ; Middelkoop 1982, A&A 107, 31). Fails outside 3890–4011 Å.
+- **`activity_index_halpha` v1.0.0** (numpy, `activity`) — Gomes da Silva
+  et al. 2011, A&A 534, A30 (after Boisse et al. 2009, A&A 495, 959) : 1.6 Å
+  core at 6562.808 Å over the 6550.87 ± 5.375 Å and 6580.31 ± 4.375 Å
+  reference bands ; `halpha_index` and its error.
+- **`ccf_bisector` v1.0.0** (numpy, `activity`) — bisector of the CCF
+  written by `cross_correlate_rv` (or of one line of the spectrum) after
+  Toner & Gray 1988, ApJ 334, 1008, and the bisector inverse slope BIS =
+  v_top(10–40 %) − v_bottom(55–90 %) of Queloz et al. 2001, A&A 379, 279 ;
+  `bis_kms`, `bisector_span_kms`, `extras.ccf_bisector`. Symmetric profile
+  → BIS = 0 within 0.01 km/s.
+- **`vsini_fourier` v1.0.0** (scipy, `kinematics`) — v sin i from the first
+  zero of the Fourier transform of a line profile (Carroll 1933, MNRAS 93,
+  478 ; Gray 2005, ch. 18) with q₁(ε) from Dravins, Lindegren & Nordlund
+  1990, A&A 228, 203 (`epsilon` 0.6 → q₁ = 0.660) ; the first zero is
+  accepted only when the side lobe stands above the Fourier noise floor
+  (`metrics.fourier_noise_floor`, `fourier_sidelobe_ratio`), and unresolved,
+  emission or noise-dominated lines fail explicitly. Tests : 30, 80 and
+  150 km/s recovered within 5 % at 0.5 % noise. Reference to the modern
+  recipe : Díaz, González, Levato & Grosso 2011, A&A 531, A143.
+- **`measure_resolving_power` v1.0.0** (scipy, `quality`) — R = λ/FWHM from
+  Gaussian fits of the `n_lines` strongest isolated lamp / sky lines
+  (isolation by `min_separation_aa`), median and scatter of R, instrumental
+  FWHM in Å and km/s (Gray 2005, ch. 12 ; Tody 1986, IRAF `splot`). Test :
+  12 lines of FWHM = λ/5000 → R = 5000 ± 2 %.
+- **`normalize_spline` v1.0.0** (scipy, `continuum`) — the IRAF
+  `continuum` recipe (Tody 1986 ; Tody 1993) : iteratively clipped cubic
+  spline (`n_knots`, `low_reject` 2.0, `high_reject` 3.0, `niterate` 10,
+  `grow` 0), `extras.continuum_spline`, σ/continuum propagated ;
+  cross-references `normalize_polynomial`.
+
+### Changed — FITS reading and writing (`read_fits` 2.0.0 → 3.0.0, `io/fits.py`)
+
+The reader now takes explicit, documented decisions on the FITS "zoo"
+(audit items C6 / C7) ; 37 new tests in `test_io_fits_zoo.py`.
+
+- `CD1_1` wins over `CDELT1` when both exist (Greisen & Calabretta 2002 ;
+  v2 preferred `CDELT1`), `PC1_1` scales `CDELT1` ; `CUNIT1` (or IRAF
+  `WAT1` units) in nm / µm / m converted to Å with the original label in
+  `meta["wavelength_unit_original"]` ; WAVE-LOG (Paper III) and IRAF
+  `DC-FLAG` handling unchanged.
+- No dispersion keywords → 0-based pixel axis, `wavelength_unit="pixel"`,
+  `meta["wcs"]="none"` (v2 labelled the pixel index "Angstrom").
+- A genuine 2-D image is refused unless the new `row` parameter selects a
+  row (v2 silently returned row 0) ; length-1 axes are squeezed ; IRAF
+  multispec / échelle markers redirect to `read_echelle_fits` ; 3-D cubes
+  are refused.
+- Extension selection : a data-bearing PRIMARY wins over tables (v2
+  preferred any table) ; otherwise the first table with recognisable
+  wavelength / flux columns (incl. SDSS `loglam`) ; the new `hdu`
+  parameter (index or EXTNAME) overrides ; when nothing is readable the
+  error lists the HDUs found.
+- `ERROR` / `ERR` / `ERRS` / `SIGMA` / `UNCERT(AINTY)` (1σ) and `IVAR`
+  (1/√ivar) image extensions and error / ivar table columns fill
+  `uncertainty` ; `MASK` extensions and `mask` / `and_mask` columns fill
+  `mask` ; `BUNIT` becomes the flux unit ; descending axes are kept and
+  flagged `meta["wavelength_descending"]`.
+- `write_fits` : the linear layout now appends `ERROR` and `MASK`
+  extensions when the spectrum carries them, read back by `read_fits`
+  (round-trip tested) ; a spectrum without either is still a single HDU.
+
+
+### Documentation
+
+- A new **Recipes** section (the recipe / profile idea, the format
+  reference, how to share a recipe) and a generated recipe catalogue with
+  one page per recipe plus `/ai/presets.json` ; the CLI, MCP, pipelines and
+  reduction-walkthrough pages updated accordingly.
+
+- The long-slit tutorial is now worked on a **solar** spectrum (Fraunhofer
+  wavelength calibration, no lamp) with a **stellar** arc-lamp variant ;
+  the aurora example is gone. Its code samples were also corrected : the
+  2-D reduction runs from Python (`spectro pipeline` loads 1-D spectra) and
+  the lamp hand-off uses the real `lamp_identifications` keys.
+- The BeSS-dashboard cookbook page is removed ; the aurora line-monitor
+  notebook is parked in `docs/.drafts/` (not published) for a later return.
+
+## [0.6.2] — 2026-09-19
+
+A documentation and web release : the docs move to a generated,
+agent-readable site at https://docs.spectrokernel.io/, the landing page is
+rebuilt around the open MCP server, and the server gains CORS so the web
+playground can use it. No algorithm changes.
+
+### MCP server
+
+- CORS for browser clients in HTTP mode : `SPECTRO_MCP_CORS_ORIGINS`
+  (default : the spectrokernel.io sites ; `*` or `none`), with the
+  `Mcp-Session-Id` header exposed, so the web playground on the landing
+  page can talk to the public server. Pre-flights are answered before the
+  API-key check.
+
+### Documentation — new build pipeline and hosting (no package change)
+
+- The site is now built with **Zensical** (the Material for MkDocs team's
+  successor engine, reading the unchanged `mkdocs.yml`) and published at
+  **https://docs.spectrokernel.io/** by Netlify, which builds it from the
+  repository (base directory `tools/docs`, see `tools/docs/netlify.toml`) ;
+  pull requests get a deploy preview and GitHub Actions keeps a strict build
+  check. `mkdocs build` keeps working as a fallback.
+- The algorithm catalogue is generated *before* the build by
+  `tools/docs/generate_catalogue.py` (Zensical runs no MkDocs plugin such as
+  `gen-files`) : one page per algorithm under `/algorithms/<category>/<name>/`
+  (summary, backend, version, context reads/writes, parameter table, Python /
+  CLI / MCP call examples, references, related algorithms), a category index,
+  and a navigation tree consumed by `literate-nav`.
+- Machine-readable layer for agents and tooling : `/ai/algorithms.json`
+  (validated at build time against `/ai/schemas/algorithms.schema.json`,
+  schema version 1, stamped with the package version), a curated `/llms.txt`
+  derived from the navigation, and the Markdown source of every page served
+  next to its HTML (`<page>/index.md`). Netlify headers set the content types
+  and CORS on `/ai/*`.
+- `tools/docs/build.py` reproduces the CI build locally (generators + strict
+  build + post-processing) ; `tools/docs/generate.py && zensical serve` for
+  live preview. Generated files (`docs/algorithms/`, `docs/ai/`,
+  `docs/llms.txt`) are git-ignored. `.readthedocs.yaml` and
+  `docs/gen_catalogue.py` are removed ; the `docs` extra now installs
+  `zensical`, `mkdocstrings[python]`, `mkdocs-material`,
+  `mkdocs-literate-nav`, `jsonschema`.
+
 ## [0.6.1] — 2026-09-19
 
 A correctness and hardening release driven by a full audit of the

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: spectro-kernel
-Version: 0.6.1
+Version: 0.7.0
 Summary: A shared catalogue of astronomical spectroscopy algorithms, composable into reproducible pipelines, usable as a Python library, a CLI, or an MCP server.
 Project-URL: Homepage, https://github.com/matthieulel/spectro-kernel
-Project-URL: Documentation, https://matthieulel.github.io/spectro-kernel/
+Project-URL: Documentation, https://docs.spectrokernel.io/
 Project-URL: Source, https://github.com/matthieulel/spectro-kernel
 Project-URL: Issues, https://github.com/matthieulel/spectro-kernel/issues
 Project-URL: Changelog, https://github.com/matthieulel/spectro-kernel/blob/main/CHANGELOG.md
@@ -54,9 +54,12 @@ Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
 Requires-Dist: ruff>=0.5; extra == 'dev'
 Provides-Extra: docs
-Requires-Dist: mkdocs-gen-files>=0.5; extra == 'docs'
+Requires-Dist: jsonschema>=4.0; extra == 'docs'
+Requires-Dist: mkdocs-literate-nav>=0.6; extra == 'docs'
 Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
+Requires-Dist: pyyaml>=6.0; extra == 'docs'
+Requires-Dist: zensical>=0.0.62; extra == 'docs'
 Provides-Extra: embedding-ml
 Requires-Dist: torch>=2.2; extra == 'embedding-ml'
 Provides-Extra: embedding-remote
@@ -197,6 +200,7 @@ by environment variable (none of these affect stdio mode) :
 | `SPECTRO_MCP_ALLOW_KEY_IN_URL` | unset | `1` also accepts the key as `?api_key=…` in the URL (for claude.ai / Claude Desktop connectors, which cannot set headers); the parameter is scrubbed before access logging. `Authorization: Bearer <key>` is always accepted. |
 | `SPECTRO_MCP_RATE_PER_MINUTE` | `0` (off) | Sliding-window request limit per API key (per client IP when auth is off). |
 | `SPECTRO_MCP_TRUSTED_PROXY` | unset | `1` behind a load balancer: trust `X-Forwarded-For` for the client IP. |
+| `SPECTRO_MCP_CORS_ORIGINS` | spectrokernel.io sites | Comma-separated browser origins allowed to call the server (`*` for any, `none` to disable). The `Mcp-Session-Id` header is exposed to browsers. |
 | `SPECTRO_MCP_MAX_SESSIONS` | `200` | Cap on live in-memory sessions; the least recently used one is evicted. |
 | `SPECTRO_MCP_MAX_PIXELS` | `32000000` | Refuse downloaded FITS files with more data elements than this (256 MB as float64); `0` disables. |
 | `SPECTRO_MCP_DOWNLOAD_BUDGET_S` | `120` | Wall-clock budget for one URL download (on top of the 256 MiB cap). |
@@ -206,6 +210,16 @@ by environment variable (none of these affect stdio mode) :
 | `SPECTRO_MCP_S3_BUCKET`, `SPECTRO_MCP_S3_ENDPOINT`, … | unset | Presigned-URL uploads (`request_upload_url`). |
 | `SENTRY_DSN` | unset | Error reporting. |
 
+## Recipes and profiles
+
+A recipe (preset) is a measurement written once with its conventions fixed;
+what depends on your instrument is a variable, bound by a profile at run
+time: `spectro pipeline be_halpha_ew --input obs.fits --profile my_setup.yaml`.
+Generic recipes ship with the kernel; campaign recipes live in the curated
+[spectro-kernel-recipes](https://github.com/matthieulel/spectro-kernel-recipes)
+collection (`pip install spectro-kernel-recipes`). See the
+[Recipes](https://docs.spectrokernel.io/recipes/) documentation.
+
 ## Architecture
 
 ```
@@ -234,7 +248,7 @@ from the registry. Build it locally with:
 
 ```bash
 uv pip install -e ".[docs,all]"
-mkdocs serve     # live preview at http://127.0.0.1:8000
+python tools/docs/generate.py && zensical serve   # live preview at http://127.0.0.1:8000
 ```
 
 Every algorithm declares its **provenance** — a `backend` (the library it leans on) and

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/README.md

@@ -111,6 +111,7 @@ by environment variable (none of these affect stdio mode) :
 | `SPECTRO_MCP_ALLOW_KEY_IN_URL` | unset | `1` also accepts the key as `?api_key=…` in the URL (for claude.ai / Claude Desktop connectors, which cannot set headers); the parameter is scrubbed before access logging. `Authorization: Bearer <key>` is always accepted. |
 | `SPECTRO_MCP_RATE_PER_MINUTE` | `0` (off) | Sliding-window request limit per API key (per client IP when auth is off). |
 | `SPECTRO_MCP_TRUSTED_PROXY` | unset | `1` behind a load balancer: trust `X-Forwarded-For` for the client IP. |
+| `SPECTRO_MCP_CORS_ORIGINS` | spectrokernel.io sites | Comma-separated browser origins allowed to call the server (`*` for any, `none` to disable). The `Mcp-Session-Id` header is exposed to browsers. |
 | `SPECTRO_MCP_MAX_SESSIONS` | `200` | Cap on live in-memory sessions; the least recently used one is evicted. |
 | `SPECTRO_MCP_MAX_PIXELS` | `32000000` | Refuse downloaded FITS files with more data elements than this (256 MB as float64); `0` disables. |
 | `SPECTRO_MCP_DOWNLOAD_BUDGET_S` | `120` | Wall-clock budget for one URL download (on top of the 256 MiB cap). |
@@ -120,6 +121,16 @@ by environment variable (none of these affect stdio mode) :
 | `SPECTRO_MCP_S3_BUCKET`, `SPECTRO_MCP_S3_ENDPOINT`, … | unset | Presigned-URL uploads (`request_upload_url`). |
 | `SENTRY_DSN` | unset | Error reporting. |
 
+## Recipes and profiles
+
+A recipe (preset) is a measurement written once with its conventions fixed;
+what depends on your instrument is a variable, bound by a profile at run
+time: `spectro pipeline be_halpha_ew --input obs.fits --profile my_setup.yaml`.
+Generic recipes ship with the kernel; campaign recipes live in the curated
+[spectro-kernel-recipes](https://github.com/matthieulel/spectro-kernel-recipes)
+collection (`pip install spectro-kernel-recipes`). See the
+[Recipes](https://docs.spectrokernel.io/recipes/) documentation.
+
 ## Architecture
 
 ```
@@ -148,7 +159,7 @@ from the registry. Build it locally with:
 
 ```bash
 uv pip install -e ".[docs,all]"
-mkdocs serve     # live preview at http://127.0.0.1:8000
+python tools/docs/generate.py && zensical serve   # live preview at http://127.0.0.1:8000
 ```
 
 Every algorithm declares its **provenance** — a `backend` (the library it leans on) and

spectro_kernel-0.7.0/docs/.drafts/README.md

@@ -0,0 +1,7 @@
+# Drafts (not published)
+
+Pages parked here are excluded from the site: both Zensical and MkDocs skip
+dot-directories. Move a page back under `docs/` (and add it to the `nav` in
+`mkdocs.yml`) to publish it again.
+
+- `notebooks/aurora-line-monitor.md` - parked on 2026-09-19, to be reinstated later.

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/concepts/algorithms.md

@@ -103,7 +103,7 @@ principle](../why.md#the-principle-we-do-not-reinvent). Every algorithm declares
 - its **`references`** - the literature for the method, or the wrapped library.
 
 Both are visible in `spectro describe <name>`, in the
-[catalogue](../catalogue.md), and in every MCP tool description. Nothing is a black box:
+[catalogue](../algorithms/index.md), and in every MCP tool description. Nothing is a black box:
 you can always see what an algorithm stands on and where the method comes from.
 
 ## Naming conventions

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/concepts/pipelines.md

@@ -90,7 +90,12 @@ spectro pipeline balmer_quick --input obs.fits    # run one
 ```
 
 Presets are why an analysis can be cited and reproduced: *"this measurement used the
-`balmer_quick` v1.0.0 preset"* is a precise, checkable statement.
+`balmer_quick` v1.0.0 preset"* is a precise, checkable statement. Since v0.7.0 a
+preset can declare **variables** (the instrument- or observer-dependent values)
+that a **profile** supplies at run time, and every run closes with a
+`pipeline:<name>` record in the history naming the recipe, its version and the
+bound values. The [Recipes](../recipes/index.md) section explains the idea and
+the [format](../recipes/format.md) page is the reference.
 
 ## Reproducibility {#reproducibility}
 

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/contributing.md

@@ -57,10 +57,10 @@ CI runs the same checks on every pull request; keep `main` green.
 
 ```bash
 uv pip install -e ".[docs,all]"
-mkdocs serve        # live preview at http://127.0.0.1:8000
-mkdocs build        # static build into site/
+python tools/docs/generate.py && zensical serve   # live preview at http://127.0.0.1:8000
+python tools/docs/build.py                        # what CI runs: generators + strict build into site/
 ```
 
-The [algorithm catalogue](catalogue.md) page is *generated* from the registry at build
+The [algorithm catalogue](algorithms/index.md) page is *generated* from the registry at build
 time - you never edit it by hand. Add a docstring and metadata to your algorithm and the
 catalogue page documents it automatically.

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/getting-started.md

@@ -114,4 +114,4 @@ The agent now sees every algorithm as a tool. See [As an MCP server](usage/mcp.m
   catalogue](tutorials/discover-the-catalogue.md).
 - Understand the moving parts → [Concepts: architecture](concepts/architecture.md).
 - A guided, end-to-end analysis → [Tutorial: analyse a spectrum](tutorials/analyse-a-spectrum.md).
-- Browse everything available → [Algorithm catalogue](catalogue.md).
+- Browse everything available → [Algorithm catalogue](algorithms/index.md).

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/index.md

@@ -49,7 +49,7 @@ through MCP, you can do from a terminal, and vice-versa.
   your first analysis in five minutes.
 - :material-sitemap: **[Concepts](concepts/architecture.md)** - the architecture,
   the data types, the registry, the pipelines.
-- :material-book-open-variant: **[Algorithm catalogue](catalogue.md)** - every
+- :material-book-open-variant: **[Algorithm catalogue](algorithms/index.md)** - every
   algorithm, auto-generated from the code.
 - :material-school: **[Tutorials](tutorials/first-spectrum.md)** - from *"I captured a
   spectrum of a star, now what?"* all the way to writing your own algorithm.

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/notebooks/be-star-variability.md

@@ -63,8 +63,8 @@ natural answer; today the cleanest path is the Python snippet above.)
 
 ## Going further
 
-- Replace the synthetic spectra with real BeSS extractions - see the
-  [BeSS cookbook page](../cookbook/bess-dashboard.md).
+- Replace the synthetic spectra with real BeSS extractions: `read_fits` reads
+  them directly (see [As a Python library](../usage/library.md)).
 - Add `compare_normalisations` (Tier 2+) before stacking when continuum
   variations between nights are suspect.
 - Couple it with `lomb_scargle` on a per-epoch line-strength metric to look for

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/notebooks/claude-mcp-end-to-end.md

@@ -136,7 +136,7 @@ beyond `spectro-mcp --http`.
   workflows (e.g. "always run `compare_normalisations` before measuring a
   line").
 - Wrap the agent in a periodic task (cron + a Claude API call) for nightly
-  monitoring - Be-star variability alerts, aurora amplitude history,
+  monitoring - Be-star variability alerts, solar line monitoring,
   exoplanet RV drift.
 - Pair with the [web playground](../cookbook/web-playground.md) for human-in-the-loop
   debugging when the agent picks the wrong tool.

{spectro_kernel-0.6.1 → spectro_kernel-0.7.0}/docs/notebooks/full-reduction-walkthrough.md

@@ -109,30 +109,40 @@ run_algorithm(
 # → ctx.spectrum.flux is now in erg/s/cm²/Å.
 ```
 
-## The same as a preset
+## The same as a recipe
+
+The whole chain (steps 1-3, the file-driven portion) is the bundled recipe
+`full_reduction_easyspec`. Everything that depends on your night is a
+variable of the recipe; you supply the values with a profile:
+
+```yaml
+# night_2026-06-09.yaml
+bias_dir: /data/biases
+dark_dir: /data/darks
+flat_dir: /data/flats
+science_path: /data/science/alf_cyg_001.fits
+exposure_seconds: 300
+airmass: 1.18
+target_name: alf Cyg
+```
+
+```bash
+spectro preset show full_reduction_easyspec          # the variables and their meaning
+spectro pipeline full_reduction_easyspec --profile night_2026-06-09.yaml
+```
 
-The whole chain (steps 1-3 - the parameter-free, file-driven portion) is
-templated in the bundled preset
-[`full_reduction_easyspec`](https://github.com/matthieulel/spectro-kernel/blob/main/src/spectro_kernel/presets/catalog/reduction/full_reduction_easyspec.yaml).
-It is a *template*: the `__REPLACE__` placeholders are the runtime paths you fill
-in before building the pipeline. A typical usage:
+Or from Python:
 
 ```python
-from spectro_kernel import PipelineBuilder, WorkContext
-from spectro_kernel.presets import load_preset
-
-config = load_preset("full_reduction_easyspec")
-for step in config["steps"]:
-    p = step["params"]
-    for key, value in p.items():
-        if isinstance(value, str) and value.startswith("__REPLACE_WITH_BIAS_DIR__"):
-            p[key] = "/data/biases"
-        elif isinstance(value, str) and value.startswith("__REPLACE_WITH_DARK_DIR__"):
-            p[key] = "/data/darks"
-        # … etc.
-
-pipeline = PipelineBuilder().from_config(config).build()
+import yaml
+
+from spectro_kernel import WorkContext
+from spectro_kernel.pipeline import PipelineBuilder
+
+profile = yaml.safe_load(open("night_2026-06-09.yaml"))
+pipeline = PipelineBuilder().from_preset("full_reduction_easyspec", profile).build()
 result = pipeline.execute(WorkContext())
+print(result.history[-1])   # pipeline:full_reduction_easyspec v2.0.0, the bound variables
 ```
 
 Steps 4-6 (wavelength + extinction + flux) stay separate calls because their