arch-motion-pageCAUTION

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: arch-motion-page
description: Compile a product or technology architecture into a one-page animated A4 blueprint (live HTML, poster PNG, HyperFrames MP4) from a small YAML spec. Use for animated architecture explainers, "A4 architecture page with motion", HyperFrames architecture videos, or turning a system analysis into a motion one-pager.
license: MIT
metadata:
  author: Joey (github.com/joeeeeey)
---

# arch-motion-page (amp)

By **Joey** ([@joeeeeey](https://github.com/joeeeeey)) · [live demo](https://joeeeeey.github.io/arch-motion-page/) · [repo](https://github.com/joeeeeey/arch-motion-page) · MIT

[![The example page drawing itself, then a Director card dispatching packets to six specialist cards](https://raw.githubusercontent.com/joeeeeey/arch-motion-page/gh-pages/media/skills-sh-hero.webp)](https://joeeeeey.github.io/arch-motion-page/)

amp turns an architecture analysis into one A4 page. The page has a header, a brand column, a three-tier figure and three columns of academic-style text. It builds itself in about 3 s, then loops a heartbeat story: the root pulses, signal packets travel the edges, each worker card swells as its packet lands, and the hand-off flows into the substrate. Edges march, mascots bob and a neon gradient wordmark breathes. After the build, every frame is a usable poster. The default skin is white paper with black type (`plush-academic`); `blueprint` is the navy alternative. Pages can be English or Chinese (`meta.lang: zh`).

**Division of labour.** The agent writes only `spec.yaml`. Deterministic compilers own every coordinate, colour and keyframe:

```
spec.yaml ─▶ lib/spec.mjs (validate, budgets)
          ─▶ lib/archetypes/tiered.mjs (boxes, edges, packet routes)
          ─▶ templates/paper-a4.mjs + themes/<name> (HTML/CSS)
          ─▶ lib/motion.mjs (JSON op list) ─▶ runtime/amp-runtime.js (ONE paused GSAP timeline)
          ─▶ out/index.html  (also a valid HyperFrames composition)
```

## Hard rules

- Never hand-edit `out/`. Every fix goes into the spec. Fix the compiler, theme or template only when the defect is generic.
- Keep the page deterministic:
  - No wall-clock reads.
  - No unseeded randomness.
  - No network at view time: the build copies GSAP (from npm) and the Latin fonts (`vendor/fonts/`) into `out/`, subsets CJK fonts into `out/fonts/`, and assets live inside the spec folder.
- Run third-party tools in containers. Font subsetting (zh pages and `--single`) runs pyftsubset in Docker with `--network none`; the CJK sources are pinned downloads, verified by sha256 and cached in `~/.cache/arch-motion-page/`.
- Review at the HTML stage with `scripts/review.mjs`.
  - Render video only after the HTML passes review **and** the user approves.
  - Render only inside Docker (`scripts/render.sh`). Never run `npx hyperframes` on the host.
- Images are optional. Generate them with whatever image tool is available (an installed image-generation skill, or any model that outputs PNG with a transparent background), and keep each prompt next to its asset in `assets/source/*.prompt.txt`.
  - Never print API keys or image-tool config.
  - Never commit generated assets that contain anything sensitive.

## Workflow

0. **Setup (once):** run `npm install` in this skill dir. It needs Node ≥ 22 and a local Chrome (override with `CHROME=/path`).
1. **Analyse the system into three tiers**, using `references/design-grammar.md`:
   - **root**: the entry point or orchestrator, exactly one node.
   - **workers**: 3–7 roles or services.
   - **substrate/outcome**: 2–6 shared stores, platforms or results. The last node is usually the outcome.

   Then pick:
   - The **one story** worth looping: which workers, in which order.
   - An optional **feedback edge**: outcome → root.
2. **Write the spec.**
   - Start a work dir outside the skill, e.g. `/tmp/amp-<slug>/`.
   - Copy `examples/self-intro/spec.yaml` there as a template.
   - Fill it using `references/spec-schema.md`. Respect the character budgets, because the build warns on every overrun. Budgets count a CJK character as width 2.
   - Language variants sit next to it as `spec.<lang>.yaml` (e.g. `spec.zh.yaml` with `meta.lang: zh`) and build into `out-<lang>/`.
3. **Assets (optional):**
   - Use node `icon:`s from the built-in set; no images needed.
   - Or generate a plush cast and a brand image:
     ```bash
     # any image tool: one 2048x1024 PNG character sheet, transparent background
     <image-tool> --prompt-file cast.prompt.txt --size 2048x1024 --background transparent \
       --output /tmp/amp-assets/cast.png
     uv run --with pillow --with numpy python scripts/slice_cast.py /tmp/amp-assets/cast.png \
       <workdir>/assets/mascots --grid 4x2 --names a,b,c,d,e,f,g,h --height 240
     ```
   - The prompt recipe is in `examples/self-intro/assets/source/`.
4. **Build:** `node scripts/build.mjs <workdir>/spec.yaml`. This writes `<workdir>/out/`. Pass `--theme <name>` to try another skin. The first zh build creates the `amp-fonttools` image and downloads the Noto SC fonts once; later builds take seconds.
5. **Review:** `node scripts/review.mjs <workdir>/out`. Then:
   - Read `review/contact.png` and the console fit report.
   - Zoom into the figure with `--zoom 288,148,752,520`, or into the hero with `--zoom 40,148,1000,520`.
   - Score against `references/review-rubric.md`, edit the spec, rebuild, and repeat.
   - The page is done when the fit report says OK, columns fill 88–99%, the review prints `loop seam ... OK`, and the rubric passes.
6. **Present or publish as HTML:**
   - `out/index.html` autoplays when opened: the build plays once, then the live story loops from `loopFrom` (about 3.4 s) to the end. Both ends of that window are the same frame, so the page never jumps back to blank. `?once` plays everything once and holds the last frame. It sits centred on a desk at 1:1 when the window is wide enough and scales down to the window width otherwise.
   - Keys: Space play/pause (at the end it r

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

declared (5 observation(s))

Network

declared (5 observation(s))

Shell

declared (2 observation(s))

Dependencies

not all pinned

Secrets in source

none-found

Findings (9)

const list = await (await fetch(`http://127.0.0.1:${port}/json/list`)).json();

const base = `http://127.0.0.1:${server.address().port}`;

await c.send('Page.navigate', { url: `http://127.0.0.1:${sheetServer.address().port}/contact.html` });

yaml

docs/demo-zh.webp

docs/demo.webp

docs/poster-blueprint.png

docs/poster-en.png

docs/poster-zh.png

Gates applied: no_behavioural_pass.