folio-anatomySAFE

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: folio
description: Build a museum-style exhibition plate that explains a technical idea - an invented scientific instrument drawn as a live, engraved isometric figure in three views (SVG, WebGL light, and a 3D bench you can turn), with numbered specimen pins, a catalogue key, a working model behind every number, and wall texts that walk through the formula term by term. Use for explanatory figures, interactive explainers, "how does X work" visuals, or technical illustrations for docs, courses, posts and landing pages, even when the request never mentions museums, plates or isometric drawing.
---

# Folio

A Folio plate explains an idea the way a natural history museum explains a specimen. There is one object on a mount, a numbered key beside it, and wall texts that tell you how to look at it. The object here is an instrument you invent, such as a bench, a balance, a loom or a still, whose working parts perform the idea. Readers can poke it, and every reading on it is computed.

## Three commitments

1. **Mechanism, not metaphor.** The instrument has to *perform* the idea, not stand beside it as an illustration. Before drawing, write one line: "When the reader does X, part Y moves, and that movement is Z in the idea."
2. **A single source of numbers.** A small pure model computes everything: needle angles, fluid levels, the readout, the key, the tables. The page only displays what the model returns, so no two places can disagree.
3. **A guided reading.** A good drawing still needs a guide. Each plate ships with a key, a term-by-term reading, the full working, and an honest account of what was simplified.

## Getting started

- Two reference plates ship with the repo. **Plate I** (`examples/attention/`, attention as an assay bench) is the model for ideas made of discrete steps and a formula. **Plate II** (`examples/heart/`, the human heart as a double pump) is the model for anything that runs in time: a simulation integrated every frame, continuous flow, phases, and charts redrawn after each cycle. Open the closer one first.
- The fastest start is to copy a reference plate: `node scripts/new-plate.mjs <name>` makes `examples/<name>/` from Plate I. Then replace its model, scene and texts. Building from a working plate is quicker and safer than starting blank.
- Shared exhibition styles live in `kit/folio-page.css`; a plate's `page.html` puts `/*CSS*/` inside its `<style>` and adds only its own rules.
- `node scripts/build-site.mjs` builds every plate plus the cover page (`site/index.html`) into `docs/`, a website ready for GitHub Pages. To add a plate, add its name to `PLATES` there and a card to the cover.
- Build any plate into one standalone file with `node scripts/build.mjs examples/<name> dist/<name>.html`.
- If only this file is installed (no repo), the appendix at the end holds the drawing library; save it as `folio-kit.js`.

A plate is five files:

| File | Role |
|---|---|
| `folio-kit.js` | the drawing library (shared, never edited per plate) |
| `folio-live.js` | the three views: stage, light layer, orbit, view switch (shared) |
| `model.js` | the pure model; puts one object on `window` |
| `plate.js` | the instrument: static geometry, live slots, input |
| `page.js` | key, controls, wall texts, ledger; listens to the plate |
| `page.html` | the mount and styles, with `/*KIT*/ /*MODEL*/ /*PLATE*/ /*PAGE*/` placeholders |

## Phase A: the brief (no drawing yet)

**A1. Scope.** Tell the user which of these they are getting and roughly how long it will take, before starting:

| Scope | Contents | Typical time |
|---|---|---|
| Sketch | instrument + key + readout, no wall texts | under an hour |
| Plate | the full exhibition page (the default for "explain X") | one and a half to three hours |
| Series | several plates on one shared bench, scale and palette | agree the list first, then one plate at a time |

**A2. The model.** Write `model.js` before anything visual. Gather the real formula, units and magnitudes. Return plain objects: inputs in, every quantity the page will show out. Run it in Node and print a few cases. Look for edge cases now (an empty set, a masked row, a value at the limit). If anything is invented, such as toy weights or sample data, note it for the "About this specimen" wall text.

**A2b. Models that run in time.** When the idea is a process (a heartbeat, a queue draining, a learning curve), write it as state plus a `step(s, dt)` function and a `read(s)` that returns everything shown. Tune parameters against known values in Node before drawing, as Plate II does for a resting adult (about 115/80 mmHg, 70 mL per beat, 5 L/min). Keep the simulation running while the drawing is off screen, and skip only the painting; otherwise changing a control further down the page freezes the numbers.

**A3. The instrument and its correspondence table.** Look for an instrument from the world of laboratories, workshops, observatories or print shops. Then write the table that ties each term to a part:

| Term in the idea | Part of the instrument | What the reader can see |
|---|---|---|
| query | a carriage on an overhead rail | it parks above the word that is asking |
| scaled score | a dial per word | needle position |
| softmax | one sealed reservoir | the columns can only divide what it holds |
| mask | stopcocks with caps | later words are shut off |
| weighted sum | a tray of layered deposit | each layer's length is a weight |

Every row needs a part, and every major part needs a row. Some reliable mappings: a fixed total becomes a reservoir, a purse or a bag of weights. Comparison becomes a dial, a balance or calipers. Selection becomes a valve, a switch or a points lever. Accumulation becomes layers, a stack or a tally. Ordering becomes a rail, a rack or a chute.

## Phase B: the bench

**B1. Inventory.** List the parts before placing them. Aim for 30 to 60. Group them by purpose: *term parts* (from the table, repeated per item), *support parts* (plinth, feet, pos

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.