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

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

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

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

@@ -6,6 +6,49 @@ Until `1.0.0` the public API may change between minor versions.
 
 ## [Unreleased]
 
+## [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.6.2}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: spectro-kernel
-Version: 0.6.1
+Version: 0.6.2
 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). |
@@ -234,7 +238,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.6.2}/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). |
@@ -148,7 +149,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.6.2}/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.6.2}/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.6.2}/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.6.2}/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.6.2}/docs/reference.md

@@ -2,7 +2,7 @@
 
 This page is generated from the source docstrings by
 [mkdocstrings](https://mkdocstrings.github.io/). It documents the public Python API; for
-the *algorithms* themselves see the [catalogue](catalogue.md).
+the *algorithms* themselves see the [catalogue](algorithms/index.md).
 
 ## Data types
 

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/docs/tutorials/discover-the-catalogue.md

@@ -106,7 +106,7 @@ Over [MCP](../usage/mcp.md), the discovery tools are `list_algorithms` and
 
 ## The full reference
 
-The [Algorithm catalogue](../catalogue.md) page lists **every** algorithm with its
+The [Algorithm catalogue](../algorithms/index.md) page lists **every** algorithm with its
 parameters, provenance and references, grouped by category. It is generated directly
 from the registry, so it is always in sync with the version you have installed.
 

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/docs/tutorials/first-spectrum.md

@@ -149,4 +149,4 @@ checked, continuum normalised, lines identified. That is a genuine scientific re
   operation available, and how to inspect each one.
 - **A fuller, guided analysis** → [Analyse a spectrum](analyse-a-spectrum.md).
 - **Periodic targets** (Be stars, eclipsing binaries) → the `lomb_scargle` and
-  `phase_fold` algorithms in the [catalogue](../catalogue.md).
+  `phase_fold` algorithms in the [catalogue](../algorithms/index.md).

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/docs/tutorials/long-slit-reduction.md

@@ -167,5 +167,5 @@ Every algorithm above follows the same kernel contract:
   `ctx.image.meta` (for 2-D) or `ctx.spectrum.meta` (for 1-D), and the
   per-step `metrics` are JSON-serialisable for later auditing.
 
-See [Algorithm catalogue](../catalogue.md) for the full parameter and
+See [Algorithm catalogue](../algorithms/index.md) for the full parameter and
 reference list of each brick.

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/docs/usage/mcp.md

@@ -136,6 +136,7 @@ bricks are now fetched through the same guard as `load_spectrum`.
 | `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 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`. |
+| `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` | Live in-memory sessions before LRU eviction. |
 | `SPECTRO_MCP_MAX_PIXELS` | `32000000` | Largest downloaded FITS accepted (data elements); `0` disables. |
 | `SPECTRO_MCP_DOWNLOAD_BUDGET_S` | `120` | Wall-clock budget per URL download. |

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/docs/why.md

@@ -89,7 +89,7 @@ Every algorithm makes this visible through its `backend` field:
 | `plotly` | Renders figures with Plotly. |
 
 …and through its `references` field, which cites the literature. You can see both in
-`spectro describe <name>`, in the [catalogue](catalogue.md), and in every MCP tool
+`spectro describe <name>`, in the [catalogue](algorithms/index.md), and in every MCP tool
 description.
 
 ### Examples

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/pyproject.toml

@@ -64,9 +64,12 @@ dev = [
   "ruff>=0.5",
 ]
 docs = [
-  "mkdocs-material>=9.5",
-  "mkdocstrings[python]>=0.26",
-  "mkdocs-gen-files>=0.5",
+  "zensical>=0.0.62",              # the site engine (Material for MkDocs successor)
+  "mkdocstrings[python]>=0.26",   # Python API reference (Griffe), used natively by Zensical
+  "mkdocs-material>=9.5",         # fallback engine for the same mkdocs.yml
+  "mkdocs-literate-nav>=0.6",     # fallback engine's nav plugin (Zensical has it built in)
+  "jsonschema>=4.0",              # validates docs/ai/algorithms.json at build time
+  "pyyaml>=6.0",
 ]
 all = [
   "spectro-kernel[catalogs,viz,storage,reduction,mcp,monitoring,embedding-wavelets,embedding-remote]",
@@ -81,7 +84,7 @@ spectro-mcp = "spectro_mcp.__main__:main"
 
 [project.urls]
 Homepage = "https://github.com/matthieulel/spectro-kernel"
-Documentation = "https://matthieulel.github.io/spectro-kernel/"
+Documentation = "https://docs.spectrokernel.io/"
 Source = "https://github.com/matthieulel/spectro-kernel"
 Issues = "https://github.com/matthieulel/spectro-kernel/issues"
 Changelog = "https://github.com/matthieulel/spectro-kernel/blob/main/CHANGELOG.md"

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/src/spectro_kernel/version.py

@@ -1,3 +1,3 @@
 """Single source of truth for the package version."""
 
-__version__ = "0.6.1"
+__version__ = "0.6.2"

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/src/spectro_mcp/__main__.py

@@ -80,8 +80,10 @@ def _http_api_key() -> str | None:
         return api_key
     if _truthy("SPECTRO_MCP_ALLOW_ANONYMOUS"):
         print(
-            "spectro-mcp: WARNING — SPECTRO_MCP_ALLOW_ANONYMOUS=1: the HTTP server "
-            "accepts every request without an API key. Do not expose it publicly.",
+            "spectro-mcp: open mode (SPECTRO_MCP_ALLOW_ANONYMOUS=1): no API key "
+            "required. Local paths are refused, URLs go through the SSRF guard, "
+            "sessions / downloads / memory are capped and requests are rate-limited "
+            "per client IP. Set SPECTRO_MCP_API_KEY to close the server.",
             file=sys.stderr,
         )
         return None
@@ -96,6 +98,28 @@ def _http_api_key() -> str | None:
     raise SystemExit(2)
 
 
+DEFAULT_CORS_ORIGINS = (
+    "https://spectrokernel.io",
+    "https://www.spectrokernel.io",
+    "https://docs.spectrokernel.io",
+)
+
+
+def _cors_origins() -> list[str]:
+    """Origins allowed to call the HTTP server from a browser.
+
+    ``SPECTRO_MCP_CORS_ORIGINS`` is a comma-separated list (``*`` for any
+    origin, ``none`` to disable) ; unset means the spectrokernel.io sites.
+    """
+    raw = os.environ.get("SPECTRO_MCP_CORS_ORIGINS")
+    if raw is None:
+        return list(DEFAULT_CORS_ORIGINS)
+    items = [o.strip() for o in raw.split(",") if o.strip()]
+    if not items or items == ["none"]:
+        return []
+    return items
+
+
 def _run_http(server, args, api_key: str | None) -> int:
     """Serve over HTTP, wiring API-key auth + optional rate-limit middleware.
 
@@ -124,6 +148,23 @@ def _run_http(server, args, api_key: str | None) -> int:
             carriers += ", ?api_key= query parameter (scrubbed from access logs)"
         print(f"spectro-mcp: API-key auth enabled ({carriers}).", file=sys.stderr)
 
+    # Browser clients (the playground on spectrokernel.io) need CORS ; added
+    # last so it is the outermost layer and OPTIONS pre-flights are answered
+    # before the API-key check (browsers send no custom header on a pre-flight).
+    origins = _cors_origins()
+    if origins:
+        from starlette.middleware.cors import CORSMiddleware
+
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=origins,
+            allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+            allow_headers=["*"],
+            expose_headers=["Mcp-Session-Id"],
+            max_age=600,
+        )
+        print(f"spectro-mcp: CORS enabled for {', '.join(origins)}.", file=sys.stderr)
+
     uvicorn_kwargs: dict = {"log_config": None}
     if _truthy("SPECTRO_MCP_TRUSTED_PROXY"):
         # Behind a load balancer (DigitalOcean App Platform, nginx, …) the

{spectro_kernel-0.6.1 → spectro_kernel-0.6.2}/tests/unit/test_mcp_http_entry.py

@@ -97,9 +97,12 @@ def test_http_with_key_puts_auth_outermost(fake_boot, clean_env):
     clean_env.setenv("SPECTRO_MCP_API_KEY", "secret")
     clean_env.setenv("SPECTRO_MCP_RATE_PER_MINUTE", "30")
     assert entry.main(["--http"]) == 0
+    from starlette.middleware.cors import CORSMiddleware
+
     classes = [m.cls for m in fake_boot["app"].user_middleware]
-    # Starlette: index 0 is the outermost layer.
-    assert classes == [ApiKeyMiddleware, RateLimitMiddleware]
+    # Starlette: index 0 is the outermost layer. CORS sits outside auth so
+    # browser pre-flights are answered; auth stays outside the rate limiter.
+    assert classes == [CORSMiddleware, ApiKeyMiddleware, RateLimitMiddleware]
     assert fake_boot["uvicorn_kwargs"].get("proxy_headers") is None
     assert fake_boot["build_kwargs"]["mask_error_details"] is True
 
@@ -137,3 +140,65 @@ def test_stdio_mode_needs_no_key(clean_env, monkeypatch):
     assert record["ran"] is True
     assert "mask_error_details" not in record["build_kwargs"]
     assert os.environ.get("SPECTRO_MCP_DENY_LOCAL_PATHS") is None
+
+
+# --- CORS ------------------------------------------------------------------ #
+def test_cors_origins_default_and_overrides(monkeypatch):
+    from spectro_mcp.__main__ import DEFAULT_CORS_ORIGINS, _cors_origins
+
+    monkeypatch.delenv("SPECTRO_MCP_CORS_ORIGINS", raising=False)
+    assert _cors_origins() == list(DEFAULT_CORS_ORIGINS)
+    monkeypatch.setenv("SPECTRO_MCP_CORS_ORIGINS", "https://a.example, https://b.example")
+    assert _cors_origins() == ["https://a.example", "https://b.example"]
+    monkeypatch.setenv("SPECTRO_MCP_CORS_ORIGINS", "*")
+    assert _cors_origins() == ["*"]
+    monkeypatch.setenv("SPECTRO_MCP_CORS_ORIGINS", "none")
+    assert _cors_origins() == []
+
+
+def test_cors_preflight_is_answered_before_auth():
+    """A browser pre-flight carries no X-API-Key: CORS must sit outside auth."""
+    from starlette.applications import Starlette
+    from starlette.middleware.cors import CORSMiddleware
+    from starlette.responses import PlainTextResponse
+    from starlette.routing import Route
+    from starlette.testclient import TestClient
+
+    async def ok(_request):
+        return PlainTextResponse("ok")
+
+    app = Starlette(routes=[Route("/mcp", ok, methods=["POST"])])
+    # Same registration order as _run_http: auth first, CORS last (outermost).
+    app.add_middleware(ApiKeyMiddleware, expected="secret")
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["https://spectrokernel.io"],
+        allow_methods=["GET", "POST", "DELETE", "OPTIONS"],
+        allow_headers=["*"],
+        expose_headers=["Mcp-Session-Id"],
+    )
+    client = TestClient(app)
+    pre = client.options(
+        "/mcp",
+        headers={
+            "Origin": "https://spectrokernel.io",
+            "Access-Control-Request-Method": "POST",
+            "Access-Control-Request-Headers": "content-type,mcp-session-id",
+        },
+    )
+    assert pre.status_code == 200
+    assert pre.headers["access-control-allow-origin"] == "https://spectrokernel.io"
+    assert "mcp-session-id" in pre.headers["access-control-allow-headers"].lower()
+    # Real request from an allowed origin: auth still applies, headers exposed.
+    ok_headers = {"Origin": "https://spectrokernel.io", "X-API-Key": "secret"}
+    resp = client.post("/mcp", headers=ok_headers)
+    assert resp.status_code == 200
+    assert resp.headers["access-control-allow-origin"] == "https://spectrokernel.io"
+    assert "Mcp-Session-Id" in resp.headers["access-control-expose-headers"]
+    assert client.post("/mcp", headers={"Origin": "https://spectrokernel.io"}).status_code == 401
+    # Disallowed origin gets no CORS grant.
+    other = client.options(
+        "/mcp",
+        headers={"Origin": "https://evil.example", "Access-Control-Request-Method": "POST"},
+    )
+    assert "access-control-allow-origin" not in other.headers

spectro_kernel-0.6.2/tools/docs/__init__.py

@@ -0,0 +1,6 @@
+"""Documentation tooling: generators that turn the live registry into pages and JSON.
+
+Run ``python tools/docs/build.py`` for a full build, or ``python tools/docs/generate.py``
+before ``zensical serve``. Everything written under ``docs/algorithms/``, ``docs/ai/``
+and ``docs/llms.txt`` is generated and git-ignored.
+"""

spectro_kernel-0.6.2/tools/docs/build.py

@@ -0,0 +1,82 @@
+"""Build the documentation site the way CI does.
+
+    python tools/docs/build.py            # generate + zensical build --strict + post-process
+    python tools/docs/build.py --no-strict
+
+Steps :
+
+1. run the generators (``generate.py``) so every generated page exists before the
+   engine looks for it - Zensical does not run MkDocs plugins such as gen-files ;
+2. ``zensical build --strict`` (warnings are errors, exactly like CI) ;
+3. post-process ``site/`` for the hosting platform : publish the Markdown source of
+   every page next to its HTML (``<page>/index.md``) so agents can fetch it, and write
+   the Netlify ``_headers`` file (content types, CORS on the JSON artefacts).
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+DOCS = ROOT / "docs"
+SITE = ROOT / "site"
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from generate import generate_all  # noqa: E402
+
+HEADERS = """\
+# Generated by tools/docs/build.py - Netlify header rules for docs.spectrokernel.io
+/*
+  X-Content-Type-Options: nosniff
+  Referrer-Policy: strict-origin-when-cross-origin
+/*.md
+  Content-Type: text/markdown; charset=utf-8
+/llms.txt
+  Content-Type: text/plain; charset=utf-8
+/ai/*
+  Access-Control-Allow-Origin: *
+  Cache-Control: public, max-age=300
+"""
+
+
+def _zensical() -> str:
+    candidate = Path(sys.executable).with_name("zensical")
+    return str(candidate) if candidate.exists() else (shutil.which("zensical") or "zensical")
+
+
+def publish_markdown_sources() -> int:
+    """Copy each ``docs/**/*.md`` page to ``site/<url>/index.md``."""
+    count = 0
+    for src in DOCS.rglob("*.md"):
+        rel = src.relative_to(DOCS)
+        if rel.name.startswith("."):
+            continue
+        if rel.name == "index.md":
+            target = SITE / rel.parent / "index.md"
+        else:
+            target = SITE / rel.with_suffix("") / "index.md"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(src, target)
+        count += 1
+    return count
+
+
+def main(argv: list[str]) -> int:
+    strict = "--no-strict" not in argv
+    generate_all()
+    cmd = [_zensical(), "build"] + (["--strict"] if strict else [])
+    print("build:", " ".join(cmd))
+    result = subprocess.run(cmd, cwd=ROOT)
+    if result.returncode != 0:
+        return result.returncode
+    n = publish_markdown_sources()
+    (SITE / "_headers").write_text(HEADERS, encoding="utf-8")
+    print(f"build: {n} Markdown sources published next to their pages, _headers written")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

spectro_kernel-0.6.2/tools/docs/generate.py

@@ -0,0 +1,25 @@
+"""Run every documentation generator (catalogue pages + JSON, llms.txt).
+
+    python tools/docs/generate.py && zensical serve
+
+The build script (``tools/docs/build.py``) calls this before building.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+import generate_catalogue  # noqa: E402
+import generate_llms  # noqa: E402
+
+
+def generate_all() -> None:
+    generate_catalogue.generate()
+    generate_llms.generate()
+
+
+if __name__ == "__main__":
+    generate_all()