---
name: istari-html-craft
description: >
  How to make a self-contained HTML page the Istari Digital web app can render —
  a System README, status board, viewer, or report. Use only when the deliverable
  is an HTML page on the platform (strict CSP): "make an HTML readme", "dashboard".
  Do not use for uploading CAD or creating a System.
---

# istari-html-craft

Skip this skill unless the deliverable is an **HTML page** on the platform (README, dashboard, report). Uploading CAD or creating a System is `istari-models` / `istari-systems`.

Pair with `istari-links` (ids and URLs) and `istari-structure` (commit order: README last).

## Hard requirements

1. **Self-contained.** Inline CSS and JS. Embed images as `data:` URIs. No CDN scripts, no external fonts, no `fetch`, no ES `importmap`.
2. Include `<meta name="viewport" content="width=device-width, initial-scale=1">`.
3. **Responsive.** One `@media (max-width:820px)` block for grids.
4. **Named file** — `00-README.html`, not a temp name.
5. **Regenerate** generated pages; say so in a provenance line.

## Pick an archetype

| Job                     | Archetype                     | Must include                                               |
| ----------------------- | ----------------------------- | ---------------------------------------------------------- |
| What is this System?    | Front door (`00-README.html`) | A deep-link row per Resource with a one-clause description |
| Is the program OK?      | Status board                  | A bottom-line sentence, then evidence                      |
| What does it look like? | Viewer                        | The geometry or series from **embedded** data              |
| Did it pass?            | Verification report           | Observed vs required, and a link to raw output             |
| How does this work?     | Explainer                     | Thesis once at the top, then numbered sections             |

Do not mix two archetypes on one page.

## Writing

- The first paragraph states the **answer**, not the table of contents.
- Descriptions name the tool, scale, and claim — they do not restate the filename.
- Status is never colour alone (glyph + word).
- Escape anything interpolated into HTML.

## Links in HTML

Use `https://<host>/systems/<system_id>/<branch>/tree/m~<resource_id>?tab=file` (`istari-links`). Do not put a revision in the path. Do not invent `~latest`.

```python
assert "importmap" not in html
assert not re.search(r"<(?:script|link|img)[^>]+(?:src|href)=[\"']https?://", html)
assert not re.search(r"m~[0-9a-f-]{36}~", html)
```

Then confirm each `m~` id is tracked on the branch.