Skip to content

Playbook and Three.js code kit for detailed dioramas: classic pixel art, stroked toon or pixel + stroke; two intake gates for look and model sourcing; free orbit, palette snap and ink; animated toy-scale cast; per-entity frame QA.

README: put Install it above the educational section

sloemodzn7f3e688cee4e
diff --git a/README.md b/README.md
index 324b1f4..30515f4 100644
--- a/README.md
+++ b/README.md
@@ -61,6 +61,62 @@ the pipeline, the recipes, the QA harness and the pitfalls. It stays the source
truth. `references/` holds the same material split into on-demand topic files for
long sessions, and everything else here is copy-in code that supports it.
+## Install it
+
+Paste this into an agent that can run shell commands. It asks where to put the
+folder, downloads the whole repository (playbook, templates, QA harness and every
+worked example), reads them, and reports what it learned before it builds
+anything. `SKILL.md` carries skill frontmatter (`name`, `description`, `version`),
+so an agent with a skills directory can load it by name later.
+
+```text
+Install the Diorama playbook here, then use it to build scenes.
+
+Repo: https://github.com/sloemo01/diorama
+
+1. Ask me where the folder should go before downloading anything,
+ and wait for my answer. Propose ~/skills/diorama as the default.
+ Do not pick a path silently.
+2. Download the whole repository, not just SKILL.md:
+ git clone https://github.com/sloemo01/diorama.git "<target>"
+ Without git:
+ curl -L -o diorama.tar.gz \
+ https://github.com/sloemo01/diorama/archive/main.tar.gz
+ tar xzf diorama.tar.gz && mv diorama-main "<target>"
+3. Prove the install before describing it: SKILL.md, README.md,
+ references/, templates/, verify/ and LICENSE at the root, and print the
+ commit hash (git -C "<target>" rev-parse --short HEAD) or the
+ archive date. If you have no shell or no network, say so and
+ stop. If the download failed or a file is missing, say so and
+ stop. Never describe this playbook from memory.
+4. If you have a skills directory or plugin folder, install it
+ there so you can load it by name in later sessions; otherwise
+ treat "<target>" as the folder.
+5. Read before you build: all of SKILL.md, references/INDEX.md, then
+ templates/DESIGN.md, templates/SOURCES.md, templates/CREDITS.md,
+ templates/qa/README.md, the header comment of every file in
+ templates/, and the worked examples under verify/. SKILL.md is
+ the source of truth; the README is only a summary.
+6. Report back in this order: install path and commit, the Look
+ Contract in one paragraph, the Pipeline as ordered steps, the
+ QA scripts and what each one checks, and three rules from
+ SKILL.md with the section each came from.
+7. Then ask me what the first diorama should be. Do not ask me to
+ fill the design sheet. When I give you a subject, research it
+ first (frames, assets, motion), fill DESIGN.md from the
+ defaults, copy the modules you need into my project instead of
+ editing the installed copy, build through the Pipeline, and run
+ the QA scripts before you show me anything. Give me the paths
+ of the frames you kept and what each one proves.
+
+If two parts of SKILL.md contradict each other, list them before
+you build. A successful clone is not an install: 5 and 6 are it.
+```
+
+Needs `git`, or `curl` and `tar` for the fallback. The QA scripts need Node with
+`three`, `esbuild` and `playwright-core`. The `media/` previews are about 20 MB
+and can be deleted after the clone.
+
## Educational scenes and inspection (5.7)
Educational mode is a first-class exception to narrative cast/ritual/system quotas:
@@ -127,62 +183,6 @@ climbs the bank steps and the windows go red behind them, the sedan pulls away,
cruisers arrive and officers fan out across the street, then the street empties
again.
-## Install it
-
-Paste this into an agent that can run shell commands. It asks where to put the
-folder, downloads the whole repository (playbook, templates, QA harness and every
-worked example), reads them, and reports what it learned before it builds
-anything. `SKILL.md` carries skill frontmatter (`name`, `description`, `version`),
-so an agent with a skills directory can load it by name later.
-
-```text
-Install the Diorama playbook here, then use it to build scenes.
-
-Repo: https://github.com/sloemo01/diorama
-
-1. Ask me where the folder should go before downloading anything,
- and wait for my answer. Propose ~/skills/diorama as the default.
- Do not pick a path silently.
-2. Download the whole repository, not just SKILL.md:
- git clone https://github.com/sloemo01/diorama.git "<target>"
- Without git:
- curl -L -o diorama.tar.gz \
- https://github.com/sloemo01/diorama/archive/main.tar.gz
- tar xzf diorama.tar.gz && mv diorama-main "<target>"
-3. Prove the install before describing it: SKILL.md, README.md,
- references/, templates/, verify/ and LICENSE at the root, and print the
- commit hash (git -C "<target>" rev-parse --short HEAD) or the
- archive date. If you have no shell or no network, say so and
- stop. If the download failed or a file is missing, say so and
- stop. Never describe this playbook from memory.
-4. If you have a skills directory or plugin folder, install it
- there so you can load it by name in later sessions; otherwise
- treat "<target>" as the folder.
-5. Read before you build: all of SKILL.md, references/INDEX.md, then
- templates/DESIGN.md, templates/SOURCES.md, templates/CREDITS.md,
- templates/qa/README.md, the header comment of every file in
- templates/, and the worked examples under verify/. SKILL.md is
- the source of truth; the README is only a summary.
-6. Report back in this order: install path and commit, the Look
- Contract in one paragraph, the Pipeline as ordered steps, the
- QA scripts and what each one checks, and three rules from
- SKILL.md with the section each came from.
-7. Then ask me what the first diorama should be. Do not ask me to
- fill the design sheet. When I give you a subject, research it
- first (frames, assets, motion), fill DESIGN.md from the
- defaults, copy the modules you need into my project instead of
- editing the installed copy, build through the Pipeline, and run
- the QA scripts before you show me anything. Give me the paths
- of the frames you kept and what each one proves.
-
-If two parts of SKILL.md contradict each other, list them before
-you build. A successful clone is not an install: 5 and 6 are it.
-```
-
-Needs `git`, or `curl` and `tar` for the fallback. The QA scripts need Node with
-`three`, `esbuild` and `playwright-core`. The `media/` previews are about 20 MB
-and can be deleted after the clone.
-
## What is in here
| Path | What it is |