--- name: export-ml-site description: > Package JOURNAL, exploratory data analysis markdown, and design notes into an offline MkDocs site opened via report.html at the workspace root. Embeds existing notebook HTML companions in their associated reports. Never executes Python. Trigger when the user asks for a website, mkdocs, or documentation site. metadata: modelTier: small --- # Export ML Site ## Human-facing prose Details: `setup-workspace` `references/human_facing_prose.md`. Tell the user to open `report.html`. Do not quote `site init` / `site build` as something they should run. The site is a derived index of files other skills already write. Markdown is the report: its figures, TableReport HTML, and existing converted notebooks (`.nb.html`, written only by `export-ml-notebook` with `notebook convert --html`) are embedded inline. HTML viewers have open-separately and fullscreen controls. Each experiment design note has one `## Notebooks` section: evaluation first, then audit. The audit viewer is `audit/.nb.html` from `notebook convert --html`. A missing file is omitted. Do not use ``. Derived HTML and PNG viewers under `scratch/results//` (report, checks, metrics, plus extra Display slugs) may be copied into the staged docs. Core Results headings are Report overview / Checks / Metrics. `### Metrics` is a heading; the scores are the embedded `metrics.html` viewer, not a second markdown table. Extra slugs use `` under `## Results` **or** `## Method` (`pipeline` is the Method DataOp report when `pipeline/index.html` exists, otherwise the graph file `pipeline.html`). Only Markdown and already-generated notebook/HTML viewers are exported. The gitignored serialized Skore `reports/` directory is private runtime state and is never copied into the site. On desktop, site pages are in the top bar (experiments in a scrollable dropdown) and the page contents are in a collapsible left rail beside a 1200px report column. Mobile uses a drawer. Workflow stages publish at completed checkpoints, after their Python execution and final durable Markdown batch and before the next user decision. They call `site build --if-stale`: unchanged inputs skip MkDocs. This is coalescing, not a file-save hook; do not build between related Markdown edits. Only `policy.site` `true` enables these automatic builds. `null` and `false` do not change policy. A direct user request to rebuild uses `site build` without `--if-stale`. ## Lookup Run `status` and read `policy.site`. Take the first row that matches. `site build` writes the site. Do not stop after reading the table. | `policy.site` | Turn | Then | |---|---|---| | `null` | direct request | step 2: persist `true`, install `mkdocs-material`, `site init`, then build | | `false` | direct request | step 3. Do not init or build until it is `true`. | | `true` | direct request, and `site build` reports `mkdocs-material is required` | load `add-python-package` for `mkdocs-material`, then build once more. Do not `site init` again. | | `true` | direct request, first site turn | step 4 `site init`, then step 5 `site build` | | `true` | direct request, later turn (`site init` already ran) | step 5 `site build` only. Do not `site init`. | | `true` | workflow checkpoint, not a direct request to build | `site build --if-stale` (preview section, including its one retry). Unchanged inputs skip MkDocs. | ## Sequence 1. `python -m skore_skills status`. Read `policy.site`. 2. If `policy.site` is `null`: persist `python -m skore_skills policy set site true`. Do not AskUserQuestion. Then load `add-python-package` for `mkdocs-material` (agent) then `python -m skore_skills site init`. Continue to build. 3. If `policy.site` is false: say the documentation site is off; offer to turn it on. Do not init or build until it is true. 4. If this is the first site turn, run `site init` (gitignore only). Later turns only `site build`. 5. `python -m skore_skills site build`. Do not run `notebook convert`. If `site build` errors with `mkdocs-material is required`, load `add-python-package` for `mkdocs-material` (agent) and build once more. Do not `pixi add` / `uv add`. If that skill is missing, or the retry still fails, name the error in one line. Name a build error; the markdown sources remain the record. Tell the user to open `report.html` at the workspace root (double-click; no server). Do not send them to the markdown instead. Stage owners that just ran `site build` must name that launcher (and the stage page: `html/data_analysis.html` or `html/.html`) in the same User-facing close. ## Preview before markdown-review gates Stage owners that just wrote durable markdown and will ask the user to approve or continue must rebuild the site **before** that AskUserQuestion / consent stop — not only at End of turn. 1. If `policy.site` is true and this skill is installed, run `python -m skore_skills site build --if-stale`. Skip in one line otherwise. If `site build` errors with `mkdocs-material is required`, load `add-python-package` for `mkdocs-material` (agent) and build once more. Do not `pixi add` / `uv add`. If that skill is missing, or the retry still fails, name the error in one line. Name a build error; do not fail the gate. 2. In the same message as the gate, **Open these**: the `.md` path, plus `report.html` and the stage page (`html/.html`, `html/data_analysis.html`, or the home page for `JOURNAL.md`) when the build ran. A file link is an addition, never the context. 3. Do **not** `notebook convert`, `git end-turn`, or `git commit` on this preview rebuild. Do not re-run `site init`. 4. Close-time conversion and build remain a freshness safety gate. Current notebooks and site inputs skip execution/build; changed or missing outputs are refreshed. ## Stop conditions - Do not assemble the site by hand. `site build` writes the site. - Do not `git commit` or `git end-turn`. - Do not `pixi add` / `uv add`; load `add-python-package`. - Do not convert or execute `# %%` scripts. - Do not copy or link serialized files from gitignored `reports/`. - Skip in one line if this skill is not installed.