{{NAME}}

13 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• construct_hologram/skill/SKILL.md23 KB576cf3173d65upstream ↗

  ---
  name: {{NAME}}
  description: Build a construct — an animated, audited holographic model — of a real or fictional object, building, machine, creature or product (CD, book, guitar, lamp, lighthouse, jellyfish...) from a request and its evidence. Produces an audited declarative scene, a self-contained animated WebGL page (staged construction, opening, idle life, reduced-motion still) and reviewed captures; on request, a film of the construct assembling across a track of music, or a 3D model of it (glTF or OBJ, with named parts and working joints) for Blender, game engines and the web, a watertight 3D print (STL, 3MF), a model kit to print and glue, or FreeCAD and STEP; or a NetLogo model's recorded run drawn in time. Use when someone wants a construct or a hologram: a holographic model, wireframe light model or animated 3-D presentation of a thing, a quick parts-and-joints 3D model of one, a print or a kit of one, or a NetLogo run visualised; not for photorealistic rendering, rigged characters, or retrieving cover art.
  ---
  
  # {{TITLE}}
  
  You author a **scene** (declarative JSON); the bundled tools validate it, audit it, compile
  it and render it. You never write graphics code. Work the loop below until the construct is
  *genuinely good* — accurate and beautiful, honest about what is known, alive without being
  noisy: something you would put in a launch video — or until the mode's limits are
  reached, whichever comes first. Then deliver the best version so far.
  
  Tools (Python 3.10+, standard library only; a Chromium-family browser for captures;
  ffmpeg optional for video). `TOOLS` below is `{{SKILL_DIR}}/runtime/cli.py`, where
  `{{SKILL_DIR}}` is the folder that contains this SKILL.md:
  
  ```sh
  python3 TOOLS new <object|architecture|machine|organism|cd|book> --output scene.json
  python3 TOOLS check scene.json                     # validate + compile + audit (--json: paths and fix hints)
  python3 TOOLS build scene.json --out out/          # out/construct.html (open in any browser)
  python3 TOOLS review scene.json --out out/         # + out/review/*.png contact sheets
  python3 TOOLS video scene.json --out out/hologram.mp4 --seconds 16
  ```
  
  For a CD, a book, a guitar, a synth, a bottle, a can, a glass or a car there is a **simple path**:
  `python3 TOOLS params --list`, then `params <archetype> --variant <v> --output p.json`, fill
  in the facts (leave sizes at their standard unless the user gave them), and `check`/`review`
  it like a scene; a builder draws it in the house style. Use the full loop below for anything
  else, or when the result needs more than the archetype offers. `prompts/` holds the same
  rules for other models and hosts (`system.md`, `params.md`, `scene.md`, `repair.md`,
  `vision-review.md`); `construct author --mode fast --vision` runs the whole bounded loop
  with any OpenAI-compatible model.
  
  Work in a folder of your own. Never install software or change settings to make this run;
  if no browser is available, say so and deliver the HTML without captures.
  
  ## The loop
  
  0. **Choose the mode, announce it, and decide on research.** Four modes
     ([effort](references/effort.md)); the user can just say one:
     - **fast:** one pass with self-review, no rounds loop: ≤10 minutes and 2 reviews (≤30 and
       4 for a richer subject). Generic subjects, simple objects, quick asks. Cents with a
       DeepSeek-class model (tested: DeepSeek V4.1 Flash).
     - **masterpiece:** judged rounds ([rounds](references/rounds.md)): a defect ledger, at most
       4 items a round, one critic who compares each version with the best so far; it stops
       after 2 rounds without a win, at every criterion 3, at 12 rounds or at 2 hours of active
       work. A named subject whose likeness matters. Frontier-model token cost.
     - **timeboxed:** masterpiece in 2 hours in all: the same rounds and stop rules, but the
       2-hour ceiling counts the critic's time with yours, so a slow critic means fewer rounds,
       not a longer wait. **Only when the user asks for it** (by name, or for masterpiece
       within two hours).
     - **unbounded:** the same rounds with only the stop rules: no round cap, no time ceiling.
       The critic finds a win almost every round, so it can run many rounds and hours at a high
       token cost; the per-round report lets the user stop it at any time. **Only when the user
       asks for it by name.**
  
     The old names still work (quick, standard and showcase are fast). **If the user names no
     mode, choose one and announce it before any work:** the mode, why, the rough time and
     cost, and how to switch ("say fast for a single 10-minute pass"). Fast for a generic
     subject, a simple mechanical object or a quick ask; masterpiece for a specific named
     subject whose likeness matters (a car model, a landmark, a named building); never
     timeboxed or unbounded. If you are a smaller or cheaper model and the subject is a hard named one, say
     so and recommend GPT-6.1 Sol or Claude Opus 5.5 (or a model of that class) for masterpiece, with fast as the option on
     this model. The limits are ceilings, not targets. A
     generic subject ("a desk lamp") needs no research; a concrete, named one (a brand and
     model, a named building or peak, a species) is researched whenever you are unsure of its
     identity-defining shape or specs; "research: on/off" in the request overrides both. See
     [effort](references/effort.md).
  
     **Watch the clock, and draft early.** Research takes at most 40% of the tier's time and
     ends in a first draft: by 40% a complete scene that passes `check` is saved in your
     folder. Never hold the only copy in context, and never plan one big write at the end:
     improve the saved scene in place, `check` it and save it after every round, so a valid
     scene is always on disk. At 80% (in Hermes, the run budget's wrap-up notice) stop adding:
     make the saved scene valid, `build` it and deliver it with `authoring.next`.
  1. **Research, then facts.** For a researched subject, first look up the exact thing — the
     official or maker's pages, manuals, specs, plans, reference photos — then look at the
     references with vision (any model that can see: Claude, GPT, Gemini, DeepSeek) and
     measure silhouette and proportions, within the tier's research counts. Only then author.
     For a named subject, write the **identity checklist** now: the features that make it
     itself (a Countach: low wedge, NACA ducts, periscope roof channel, trapezoid arches,
     scissor doors), in `authoring.identity`, each later listed with the parts that build it.
     Write down what is actually known and where it came from: the user's
     words, supplied measurements, documents they gave you, the sources you read. Every fact gets a certainty:
     `verified` (cites a source), `user_supplied`, `inferred` (your reasoning: typical sizes,
     proportions) or `decorative` (chosen for presentation). Do not invent precision; a
     generic reconstruction says so (`subject.accuracy: "generic"`), and a new design, with
     nothing real to reconstruct, is `"original"`. What the user asked for, or a document says
     the thing must do, is a fact with `"requirement": true` and its source; name its key in the
     `basis` of each part that realises it (the part stays `inferred`). Each value is
     documented (`verified`, citing its source), traced (`traced`, citing the orthographic
     drawing; from a perspective photo `inferred`) or invented (`inferred` with a note, or
     `decorative`). A part whose size and shape are known differently says each:
     `{"size": "verified", "shape": "traced"}`, its verified dimension facts in `basis`. Without a
     cited source nothing is `verified`. See [provenance](references/provenance.md).
  2. **Recognition before geometry.** Name the silhouette, the primary masses and the **two
     or three identity features** that make the thing itself (a lighthouse: tapering banded
     tower, gallery, glazed lantern; a record player: platter with record, S-shaped tonearm).
     Decide proportions from facts. Plan stages bottom-up. See
     [composition](references/composition.md).
  3. **Write the scene.** Start from `new <category>` or an example in
     `{{SKILL_DIR}}/examples/`. Build masses first, then structure, identity, detail. Use
     the right shape for each part (lathe for turned forms, extrude for plans and gables, tube
     for limbs and arms, repeats for colonnades and railings, mirror for symmetry). Give
     every part a role, a certainty and a stage. Text (titles, spines, labels) comes from
     facts through `labels`, images through named artwork slots; never choose colours, the
     renderer owns them. See [vocabulary](references/vocabulary.md). **Draw with craft**
     ([craft](references/craft.md)): a line-weight hierarchy, dark depth-writing fills under
     a faint contour wire (never a main surface with `line: "none"`), a sub-volume per
     feature, density where the identity lives and true detail everywhere (one clear object at
     hero scale, something true in every region up close), and a critic round answered by a
     refine pass; the shipped examples show all five.
     When the thing's identity is a shape you cannot know from text (a guitar body, a car,
     a building's elevation), measure it from a reference image: see
     [tracing](references/tracing.md). Never invent an outline and call it verified. A named
     car or hull: trace side, top and front and loft through them (`loft-from-traces`); a
     named car or landmark: measure the likeness with `compare` before calling it finished.
     Buildings: the architecture kit (`tower`, `roof`, `dormer`, `facade`, `battlements`,
     `buttress`; [composition](references/composition.md)) and a measured site
     (`terrain --into`). A real
     place, peak or route comes from elevation data, and Earth from coastline data
     (`globe`): see [terrain](references/terrain.md).
  4. **Animate with intent.** Choose an assembly style; `articulations` for what opens once
     (a lid, a board, a disc lifted out); part motion only where the object keeps moving (a
     platter spins, a tentacle sways, a beam turns); idle events that suit the subject; and a
     camera tour to the identity feature. See [animation](references/animation.md).
  5. **Check until the audit is clean.** `check` must report `audit: PASS`. Fix every
     error (floating or unsupported parts, overclaimed certainty, accuracy that is not backed);
     read every warning and either fix it or be ready to explain it. Where one part rests on
     another, work out both heights and make them meet: a cylinder's base is at its `at` (on
     its side, its underside is `at.y - radius`), a centred box's underside half its height
     below.
  6. **Review as an art director, and iterate.** Run `review`, then open and actually inspect
     `review/hero.png`, `sheet-views.png`, `sheet-assembly.png`, `sheet-motion.png`,
     `sheet-life.png`, `sheet-provenance.png` and each `view-<id>.png`. Score them against the
     [art-direction rubric](references/review.md): silhouette, proportions against the
     references, identity features, depth and layering, composition and hero framing, the
     assembly's story, motion, detail density, honesty. Improve the weakest point, `check`,
     `review` again. Your own review records `"outcome": "self-reviewed"`; only an
     **independent critic** (a fresh context comparing renders with the references:
     `critique`, see [review](references/review.md)) can record "good"
     or "outstanding". Use it for a richer fast run, in the rounds modes, and whenever the
     subject is named. In masterpiece or unbounded mode run the rounds with `python3 TOOLS
     rounds start scene.json --mode masterpiece` (or `timeboxed`, `unbounded`) ([rounds](references/rounds.md)):
     tag each edit with its ledger id, give each round's packet the request in the user's words
     (`rounds packet --request "..." --reference ...`; without it the critic gets none), one
     critic per round, keep a version only when it beats
     the best, and after every round report in chat the critic's top requests, what changed
     (ledger ids), won or lost, and the minutes.
     **Count the rounds in the scene:** before each review, add one to
     `authoring.review_rounds` and save; `check` warns `tier-rounds` past the tier's cap
     (quick 0, standard 2, showcase 4), and that is the end of reviewing. Stop when every criterion is good and you would show it as it is, or when
     the tier's review rounds or time run out. A host may add a fresh-eyes critic (an
     independent reviewer over the contact sheets). Geometric validity (the audit) and art
     direction (your eyes) are separate gates. If you cannot see images, still fix every
     `detached`, `thin-support`, `tips` and `thin` warning, and record `"outcome": "unreviewed"`.
  7. **Deliver.** Record how it was made in the scene's `authoring` block (`tier`,
     `research`, the `sources` used, `review_rounds`, `outcome`: good, limit or unreviewed,
     and `next`: the most valuable improvements still open). Hand over `scene.json`,
     `out/construct.html` (and `out/geometry.json`, the video if made) with a short note: what
     is evidence, what is inferred or designed, which artwork is authentic and which is
     generated decoration, what you reviewed, and — if a limit stopped you — what the next
     improvement would be. Never call a generic reconstruction exact, and never present
     generated art as a real cover.
  
  ## A construct that assembles across a track (film mode)
  
  Only when the user asks for a film or video of a construct assembling to music, or hands you a
  track for it ("make a construct of X that assembles across this track"). Otherwise ignore this.
  
  1. **Author the construct as usual**, with the loop above. Keep its own assembly short (at most 20 s);
     the film sets the long one.
  2. **Measure the track:** `python3 TOOLS audio track.wav --out audio.json` (add `--voice vocals.wav`
     if there is a vocal stem). Note the track's length in seconds.
  3. **Render the film:** `python3 TOOLS video scene.json --out film.mp4 --assembly <length - 1.25>
     --audio audio.json --sound track.wav --camera steady --size 1920x1080 --fps 24` (1.25 s is the
     ceremony opening; use the full length for another assembly style). `--camera steady` keeps the
     whole construct in view; use `tour` when the scene's own camera flights should play. Leave
     `--reactivity` at its default unless the user asks for a calmer (0.5) or stronger (1.5) film.
     It takes about an hour for four minutes of film; say so before you start.
  4. **Review the film** by sampling frames, for example
     `ffmpeg -i film.mp4 -vf fps=1/10 frame-%02d.png`, and look at them: the build should visibly
     move on with the music and end with the whole construct. Report what you made, its length,
     and the reactivity and camera you used. Details: `docs/FILM.md` in the Construct repository.
  
  ## A NetLogo model as a construct
  
  Only when the user asks to visualise a NetLogo model or run. No scene authoring is needed: the
  bridge computes the construct from a recorded run (details: `docs/NETLOGO.md`). Over MCP, the same
  steps are `construct_netlogo_instrument` and `construct_netlogo_draw`.
  
  1. Record. If the user works in NetLogo 7, the Construct extension is simplest (`extensions
     [construct]`, `construct:start`, `construct:record`, then `construct:draw` in the Command
     Center: `hosts/netlogo/README.md`). Otherwise `python3 TOOLS netlogo-instrument Model.nlogox
     --title "Model" --out run/` with what to record: `--turtles a,b`, `--reporters "count sheep;count
     wolves"`, `--patches pcolor:4`, `--no-turtles`, `--seed N`, `--ticks N`. Setup and go come from
     the model's own buttons when it has no `setup`/`go`; `--setup "setup 4"` when setup takes inputs
     (a refusal names the buttons). Tell the user to run it in NetLogo (setup, go), or headless with
     the command it prints, if NetLogo is installed.
  2. `python3 TOOLS netlogo run/run.jsonl --view <view> --out scene.json`: `space-time` (moving agents),
     `network-time --state var` (spreading on a network), `phase --x R1 --z R2` (two quantities in a
     cycle; `--smooth N`), `field` (spreading over patches). `--time sqrt` when most change comes early.
     The scene carries its legend, how-to-read lines and a replay of the run with its counts.
  3. Build and review it as usual, and credit the model as its Info tab asks.
  4. **Art direction (optional, when the user wants it to look good).** Never edit the data: write a
     layer, `art.json`, and redraw with `--art art.json`. It holds `credit` (your exact model name),
     `title`, `summary`, `looks` (a data part's label, look or note, by id), its own `parts`, `facts`
     and `annotations` (source `art`, or none; `inferred` with a note when computed from the run,
     else `decorative`), `presentation` (views, framing), `animation`, `reading` (`{"how": [...]}`,
     the panel's lines in your words) and `legend` (`false` when your annotations replace it).
     Compute every milestone (half adopted, the last burn, a peak) with a short script over
     `run.jsonl`, never by eye; keep every data part visible; review before and after each change
     and keep only what reads better. The scene's `data_lock` fact makes `check` refuse any change to
     the data. In masterpiece or unbounded mode, judge the layer with the rounds as for any construct
     (`rounds start scene.json`, redrawing with `--art` between rounds): the critic of a run checks
     every label and milestone against the recording and judges how well a student could read it.
  5. **Two runs compared (when the user asks what a parameter changes):** record both, then `python3 TOOLS
     netlogo-compare a.jsonl b.jsonl --labels "vision 3,vision 6" --out scene.json` and build it.
  6. **A 3D model of the run (optional, when asked):** add `--solid --glb run.glb` (each turtle a
     sphere where it rose, a cycle as a tube, a spread as a surface, in the run's own colours; the
     build replays the run in Blender).
  7. **Films (optional, when asked).** A film of the run in Blender, every agent as moving light,
     silent, at 30 ticks a second: `python3 TOOLS netlogo-film run.jsonl --out film.mp4` (or
     `--blend`; it takes minutes at full size, so offer `--seconds 10 --size 960x540` first).
  
  ## A 3D model of a construct (export)
  
  Only when the user asks for a 3D model, a file for Blender, Godot, Unity or Unreal, a glTF, GLB or
  OBJ of the construct. Author and review the construct first, as above; then:
  
  - `python3 TOOLS export scene.json --out model.glb` (glTF 2.0: every part a named object, its
    joints as the `open` animation, periodic motion as `idle`, each vertex's build phase as
    `_PHASE`). For OBJ: `--out model.obj` (an `.mtl` beside it; `--frame z-up` for Z-up tools).
  - For a game engine: `--merge --wire seams` (static parts merged per material, the design lines as
    dark seams); `--wire tubes` keeps all the line art as thin geometry instead;
    `--pose open` rests the model open; `--materials map.json` colours and finishes parts by id or
    pattern (`{"materials": [{"parts": ["body", "door-*"], "color": "#2b4a6f", "finish": "paint"}]}`;
    finishes: paint, brushed, chrome, wood, rubber, plastic, glass, light), when the user wants a
    finished model. Keep the map beside the scene as `<scene>.materials.json`: colours are the
    user's choice, never facts in the scene.
  - For physics: `--pieces glued` makes what stays put one body and each door, lid or tailgate one more on its
    own hinge (`hosts/godot/construct_joints.gd` makes them Godot joints); `--pieces` alone, pieces that break
    apart and settle; `--colliders`, a collision box per part.
  - A `no-surface` audit warning names a main or structural part drawn only as lines: it would be
    missing from the model, so give it a solid shape (a tube, a box) when the export matters.
  - Say what the model is: correctly sized named parts with working joints, built from simple
    shapes, without textures; good for blockouts, props and previews, not a finished hero asset.
    Details: `docs/EXPORT.md` in the Construct repository.
  
  ## A 3D print of a construct
  
  Only when the user asks to 3D print it, or for an STL or 3MF. Author and review the construct
  first; then `python3 TOOLS print scene.json --out model.3mf` (or `.stl`) writes one watertight
  solid, Z up, on the bed, 100 mm on its longest side (`--size MM`, or `--scale 43` for 1:43 of the
  real size). `--printers` says how large it prints on five printer classes and what is lost at that size;
  `--printer desktop --fit` prints at the largest size that fits; `--exact` keeps the construct's own solids
  (finer detail than voxels). Refine the solid first (`check --fit`, references/review.md). Report what it prints: the size and scale, and its notes (overhangs that need supports,
  parts thickened to the wall, parts drawn only in lines and not printed: `--lines` prints them
  raised). Exit status 1 means it is not watertight: say so, never hand it over as printable. The user
  does not need a printer to check it: a slicer (PrusaSlicer, Bambu Studio, Cura) opens and slices it.
  Details: `docs/PRINTING.md` in the Construct repository.
  
  ## A construct in FreeCAD or CAD (STEP)
  
  Only when the user asks for FreeCAD, CAD or STEP, and FreeCAD is installed: `python3 TOOLS freecad
  scene.json --out model.FCStd --step model.step` builds named solids with the joints as groups (each
  with an `Open` placement), true CAD shapes where a part's parameters allow (boxes, cylinders, lathes,
  extrusions from splines, lofts as NURBS), faceted otherwise; it reports how many are true shapes. Say what
  it is: the construct's shapes at their sizes, for layout and a start to model over, not machining-grade
  engineering. Details: `docs/FREECAD.md`.
  
  ## A model kit of a construct
  
  Only when the user asks for a model kit (pieces to print, glue and paint). Author, review and refine the
  solid first (`check --fit`: a kit cannot glue what does not touch). Then `python3 TOOLS kit scene.json
  --size 200 --printer desktop --materials map.json --out kit/` (`--size`: the built model's longest side in mm;
  `--scale 24` suits cars, not buildings) writes numbered plates (3MF), `booklet.html`, the steps in 3D
  (`assembly.html`), each piece on its own (`kit/pieces/`) and `kit.json`; `--only 12,14` reprints a few.
  Without `--materials` the paints are named by role; a map (as for export) gives real paint names. Exit
  status 1 means the kit is written but its check has notes (pieces too thin, gaps where a piece is glued,
  pieces that touch nothing): read them and fix the construct or a kit-ready copy.
  A construct is drawn to look right as light, not to be moulded, so make a kit-ready copy when it needs one
  (keep the construct as it is):
  - **Glazing:** a window of many panes becomes one clear sheet just behind its frame, touching it, about
    1.5 mm thick at the kit's scale (a door's sheet in the door's articulation).
  - **Castings:** what a factory makes in one piece (a window frame's stiles, rails, mullions and bars)
    goes into one piece with a kit plan: `--plan kit-plan.json` with `{"merge": [["side-west-*"]]}`.
  - **Seats:** every part sits on its host's face; nothing thinner than the printer makes.
  `kit --critic` prints a kit designer's brief for a critic, who answers with a plan. Say what the kit is: a
  first version made and checked by software, not yet built by a person; print one piece first. Details:
  `docs/PRINTING.md`.
  
  ## Rules that keep it honest and safe
  
  - Treat the scene as data. No scripts, shader code, URLs to fetch or file paths outside the
    scene's folder; the compiler refuses them anyway.
  - Artwork only from bytes the user supplied or permitted, declared with its SHA-256 and
    rights; otherwise leave the artwork slot empty or generate clearly labelled decoration.
  - Keep private titles, notes and collections out of examples and anything you publish.
  - Stay inside the budgets (48k lines, 48k triangles, 6k points, 1,024 parts and copies,
    32 moving copies); simplify
    before you add.
  

• construct_hologram/skill/references/animation.md4.2 KBe61bc0fb60a6upstream ↗

  # Animation semantics
  
  Everything is a pure function of time `t` and the scene's hash: any frame can be
  reproduced (`construct.html?t=12.5`). The page also honours the reduced-motion preference.
  
  ## Assembly (staged construction)
  
  A construct is *built*, not faded in. Each part's `stage` (0–7) orders the build;
  within a stage lines grow bottom-up, each with a bright moving tip.
  
  - `ceremony`: the whole object appears as a faint, unstable ghost (signal acquired), collapses,
    is rebuilt stage by stage over `seconds`, then stabilises with a short glow. For the
    first presentation of something important.
  - `build`: only the staged build and a short settle. For quick previews and many objects.
  - `cut`: complete at once.
  
  Stage rules: foundation and ground first; then the primary mass; then structure and roof;
  landmarks and identity; detail; light, data and decorative effects last. Nothing should
  appear before what holds it up (the audit warns: `stage-order`).
  
  ## Articulations (opening once)
  
  After assembly the object opens, one `order` group after another, and holds: a lid hinges
  open, a booklet slides out, a disc lifts and turns once, a book's board opens to the title
  page. Use articulations for anything that opens or is taken out; a host drives them with
  an opening from 0 to 1 and owns the timing. `?open=0` / `?open=1` freezes a pose. Keep the
  sequence short (2–3 groups) and the still pose informative (`still_pose: open`). Give a
  view named `open`: the camera turns to it while the object opens. Things taken out (a
  booklet, a record) move to where they can be seen, facing the front, and never through
  another part.
  
  ## Part motion
  
  Only where the real object keeps moving, or where a fictional one would breathe:
  
  - turning things `spin` (platter 33⅓ rpm, rotor, light beam at a few rpm);
  - hinged or hanging things `swing` (tonearm drift ±2–3°, tentacles 5–8° with `phase_step`,
    pendulum, door);
  - floating or reciprocating things `bob`;
  - lights and hearts `pulse`.
  
  Keep amplitudes small and periods long (4–60 s): the presentation is ambient. Moving
  copies are limited to 32. A part has one periodic motion; it can also be articulated (a
  disc that lifts and then spins). Nested periodic motion (a fan head oscillating while its
  blades spin) is not available yet: show the more characteristic one.
  
  ## Idle life (host-optional)
  
  After assembly the construct stays alive with occasional events (`idle.events`), seeded so
  captures repeat. Hosts may play none of them; never make recognition depend on one:
  
  | event | look | suits |
  |---|---|---|
  | `scan` | a bright band climbs the object | anything; buildings, devices |
  | `sweep` | energy crosses along a horizontal axis | long objects, machines |
  | `wave` | a breath rises, pushing outward slightly | organisms, soft forms |
  | `shimmer` | scattered lines twinkle | everything, quietly |
  | `propagate` | a front expands from the identity feature | lights, cores, emitters |
  | `glitch` | a slice loses registration (stepped) | sparingly: machines, sci-fi |
  | `brownout` | half the object dims and recovers | sparingly |
  | `tear` | a height band jitters | sparingly |
  | `burst` | motes thrown out and gathered back | creatures, magic, energy |
  
  `life`: `alive` (events at `cadence`), `calm` (half as often, softer), `off`. Choose 2–4
  events that suit the subject; avoid the unstable ones for calm or documentary subjects.
  
  ## Camera (host-optional)
  
  `drift` (degrees per minute) slowly orbits after assembly; `breathe` varies the distance
  by a few percent. A `tour` flies to named views at given times (`fly` seconds, eased, with a
  small lift) — use it to visit the identity feature and return to the hero. Interaction
  (drag, wheel, keys 1–6) takes over; the presentation resumes after a pause.
  
  ## Still state
  
  `reduced_motion: "still"`: assembly complete, no events, no part motion, no drift. Shown
  for `?motion=reduced`, the M key, or when the system asks for reduced motion. Check
  `review/still-reduced-motion.png`: the still must stand on its own.
  
  ## Video
  
  `video scene.json --out clip.mp4 --seconds 20` renders frame-exact (24 fps) from `t = 0`;
  use `--start` to skip the assembly, `--view` to hold another view. Needs ffmpeg; without
  it, the frames are kept.
  

• construct_hologram/skill/references/composition.md6.1 KBcb9e2730d2d7upstream ↗

  # Recognition and composition
  
  A construct is recognised by its **silhouette**, its **proportions** and **two or three
  identity features**, in that order. Neon on a wrong silhouette is still wrong.
  
  ## Before you write a part
  
  1. **Proportions from facts.** Write the overall size and the ratios that matter (a
     lighthouse ~4× taller than its base is wide; a jewel case 142 × 125 × 10 mm; an LP
     0.30 m on a 0.46 m plinth). Inferred is fine; unstated is not.
  2. **Silhouette.** Which outline would a child draw? Build that first as `mass` parts.
  3. **Primary structure.** What holds it up, how it is divided (floors, bays, segments,
     joints). `structure` parts, few and clean.
  4. **Identity features.** The two or three things that make it *this* thing: tonearm and
     grooves; banded tower and lantern; scalloped bell and trailing tentacles. Give them
     `role: identity`, real geometry and a camera view.
  5. **Detail, deliberately.** Only detail that reads at the hero framing and helps
     recognition. Repeats (railing posts, windows, ribs) read as texture; keep them `detail`.
  6. **Leave out** what does not help: interiors nobody sees, every bolt, decorative
     clutter. Simplify before adding.
  
  ## Choosing shapes
  
  - Turned or round things → `lathe` (profile through the real changes of radius).
  - Footprints, floor plans, gabled fronts, letterforms → `extrude`.
  - Anything that bends: limbs, arms, cables, branches, tentacles → `tube` with a tapering
    `radius` list.
  - Many identical things → `repeat` (radial for rings of things), symmetric creatures and
    vehicles → `mirror`.
  - Bodies whose width and height both change along their length (car bodies, glasshouses,
    hulls, fuselages) → `loft`: one section per real change, back to front.
  - Curved surfaces read through their rings and meridians: 8–16 meridians, rings at real
    profile changes; more lines are not more legible.
  
  ## Recipes by kind (adapt, do not copy)
  
  - **Architecture**: massing from a traced plan (`trace` the footprint, then an `extrude`
    with `axis: y`) and elevations (a traced front as an `extrude` with `axis: z`); then the
    kit: `roof` (gable, hip) on each block, `tower` with its real roof (cone, pyramid, spire,
    onion) for every tower at its real height, `facade` for window rows and arcades (round,
    pointed), `dormer`, `battlements` and `buttress` in rhythm with `repeat`. A landmark is a
    crowd of particular features: count the towers in the references and place each one. A
    ground: a rock plinth, or measured terrain (`terrain --into`). Stage: ground → mass → roofs
    and towers → facades → detail. Start from `examples/castle.json`.
  - **Manufactured object**: the housing as mass; working parts (platter, arm, blade, lid)
    as identity, each a separate part so it can move; small controls as detail. Show it in
    use (record on the platter, lid open) when that is recognisable.
  - **Vehicle**: never a box body, and never a body outlined with thin tubes (they render as
    glowing wire, not a surface: the audit warns `tube-outline`; a main or structural part drawn
    only as lines has no surface for the 3D export: the audit warns `no-surface`). Trace the side silhouette and the plan (top) outline first
    — from references when the car is a named model ([tracing](tracing.md)) — and loft the
    lower body through them: half-widths from the plan, sill and shoulder heights from the
    side, the sides leaning in (`half_width_top` about 0.9 of the bottom). Round the plan at
    the nose and tail with extra sections; the nose of most cars is far narrower than the
    cabin. The glasshouse is a second loft, narrower at the roof, from the windscreen base
    raked back. Wheels stand on the ground in arches on the body's side; lights at nose and
    tail as detail. The `vehicle` archetype (`params vehicle --variant wedge|coupe|sedan`)
    builds exactly this and is the quickest start; for a named car, replace its body with one
    lofted from traced side, top and front views (`loft-from-traces`) and measure it with
    `compare` ([tracing](tracing.md)). The section method, as the best-liked cars were built:
    the traced side outline as a thin `extrude` (`axis: x`) on each flank with a glass fill;
    cross-sections every 10–15 cm as `extrude` slices (`axis: z`) with `look: {"fill": "dark",
    "line": "none"}`, which give the body its volume and hide what is behind; and smooth
    `curve`s across the body at the main stations (bonnet, windscreen base, roof, deck) as the
    identity lines, plus curves along the arch lips and shoulder. A `loft` does the slices and
    sections in one part; add the curves on top.
  - **Machine**: the frame, the moving assembly (with `spin`/`swing` at its real pivot), the
    power or light source as `data`.
  - **Organism**: body volumes as ellipsoids/lathe; limbs as tapered tubes from real joints;
    `mirror` for bilateral animals, radial repeats for radial ones; gentle motion with
    `phase_step` ripples; never a perfectly rigid creature.
  - **Fictional entity**: take the described features as `user_supplied` facts and design
    everything else as `inferred` (designed from the request); use `decorative` only for
    atmosphere. Label it fictional in the title.
  - **CD / book / artwork carrier**: standard generic dimensions (inferred). A jewel case is
    a tray (inlay slot on its back, spine labels on its left face), a hinged lid carrying the
    booklet (`cover-front`), and a disc in the tray (`disc` slot, circle mask with the hole)
    that lifts and turns once. A book is boards, a rounded spine (`extrude`) with a flat
    spine face for its labels, a ribbed page block whose front carries the title-page labels,
    and a front board hinged on the spine. Name `anchors.front` and `anchors.spine`. Text
    comes from facts through labels; images through slots. Start from
    `examples/cd.json` and `examples/book.json`.
  
  ## Framing
  
  The camera fits every part's boxes (decorative point clouds excluded). Choose `framing`
  yaw/pitch that shows the identity features and the depth (≈25–40° yaw, 10–30° pitch);
  add a view that targets the main identity feature and tour to it. A tall thin object wants
  a lower pitch; a flat object (turntable, board game) a higher one.
  

• construct_hologram/skill/references/craft.md7.0 KB7973158a7f6bupstream ↗

  # Drawing craft: what makes a construct read
  
  A clean audit says a construct stands up; it does not say it reads. The strongest constructs
  made with this skill were not the ones with the most code or the most effort. They were drawn
  with a few habits that every model can follow. Measured on the same skill, the same prompts and
  the same time, the strongest runs against the rest:
  
  | | strongest runs | the rest |
  |---|---|---|
  | distinct line weights | 8–19 | 0 (the defaults) |
  | parts with a dark, depth-writing fill | 9–128 | 0–7 |
  | identity parts | 22–125 | 10–29 |
  | independent critic | every round, each answered by a refine pass | some runs never |
  
  Five rules follow, in the words of the scripts that drew them. Read them with the examples that
  ship with this skill (its `examples/` folder): `leica-m3.json`, `open-reel.json`,
  `sea-cliff.json`, `juggernaut-et7.json`, `porsche-911-964.json` and `sagrada-familia.json`.
  
  ## 1. A line-weight hierarchy
  
  Three weights, and the eye reads the object in that order:
  
  | layer | `look.weight` | also |
  |---|---|---|
  | identity: the lines that name it | 1.1–1.5 (a signature line up to 2.6) | `glow` 0.3–0.7 |
  | structure: the form | 0.8–0.9 | |
  | detail: seams, lenses, slats | 0.55–0.65 | `alpha` 0.25–0.6: faded |
  
  ```python
  curve('side-window-frame', window, 'identity', 'x', look={'weight': 1.5})
  curve('door-seam', seam, 'detail', 'x', look={'weight': .8})
  curve('rear-demister-' + str(k), [[-w, y, z], [0, y + .008, z], [w, y, z]], look={'alpha': .25, 'weight': .4})
  curve('rear-lightbar', bar, 'identity', look={'weight': 2.6})
  ```
  
  Without weights every line is the same line, and nothing is first.
  
  ## 2. A dark fill under a faint contour; feature lines on top
  
  Every visible main surface (a body, a roof, a hood, a bumper, a glasshouse, a tower's mass)
  keeps a **faint contour wire** over its dark, depth-writing fill: `look` weight about 0.4–0.5,
  alpha about 0.5–0.6. That fine wire following the surface is what makes it read as sculpted;
  without it the surface is a flat dark shape and the construct looks like a cardboard mockup.
  Then draw the feature lines yourself, heavier: roof rails, lower edges, bumper faces, window
  frames.
  
  ```python
  # The cabin keeps its faint surface wire over a depth-writing shell; its contours are authored on top.
  by['glasshouse']['look'] = {'fill': 'dark', 'weight': .45, 'alpha': .55}
  for sg in [-1, 1]:
      cv('roof-rail-' + str(sg), rail(sg), 'identity', look={'weight': 1.2})
  by['front-bumper']['look'] = {'fill': 'dark', 'weight': .45, 'alpha': .55}
  cv('front-lower-edge', lower_edge, 'identity', look={'weight': 1.1})
  ```
  
  Hide only true construction scaffolding: helper volumes, guides, a section stack that is not a
  surface. `line: "none"` is for occluders and backings (a dark panel behind a grille, a plate
  that hides the far side), never for a visible main surface; `check` warns `bare-surface` when
  one is. A critic that calls a surface's faint contour "construction lines" is wrong: it is the
  surface.
  
  The dark fill also hides what is behind it, so the far side stops showing through.
  
  ```python
  # Main masses recede; foreground architecture and silhouettes dominate.
  for x in parts:
      if x['role'] == 'mass':
          x['look'] = {'fill': 'dark', 'alpha': .42, 'glow': .08, 'weight': .65}
  ```
  
  ## 3. Sub-volumes per feature, each conforming to its neighbours
  
  Not one body: a volume for each feature, shaped to the ones it meets. Wings that rise above the
  bonnet and seat the lamps; a bowl behind each lamp; arches that follow the tyre, with the
  body's sections lowered around them.
  
  ```python
  # Smooth, substantial front wings seat the lenses and sit higher than the bonnet.
  add('front-fender-' + str(sg), 'mass', {'type': 'loft', 'sections': secs, 'round': 1}, [sg * .615, 0, 0], 2,
      look={'fill': 'dark', 'weight': .65, 'alpha': .75})
  # Complete lamp bowls behind the lens.
  add('headlamp-bowl-' + str(sg), 'mass', {'type': 'sphere', 'radii': [.157, .165, .16]}, [sg * .62, .735, 1.83], 2,
      look={'fill': 'dark', 'weight': .5, 'alpha': .7})
  # Conform the lower body's arches to the tyres without deleting structure through the car.
  for s in body_sections:
      if abs(s[0] - zc) < R * 1.10:
          s[2] = max(.205, R + math.sqrt((R * 1.10) ** 2 - (s[0] - zc) ** 2))
  ```
  
  A building works the same way: a foot under each tower, a deck under each lantern, the gables
  standing on the walls.
  
  ## 4. Density where identity lives, and detail everywhere
  
  Two looks, and a construct needs both:
  - **at hero scale, one clear object:** the silhouette and the identity features read first;
  - **up close (4×), every region still has something true to find:** seams, panel lines,
    louvres, fixings, tracery, coursing. A bare face or an empty corner is unfinished work.
  
  Spend parts on what names the subject, three to five times more than on the rest: lamp rims
  and lenses, louvres and slats, window rows, spires, tracery. Keep the masses simple in shape,
  not empty: they carry their faint contour and their true seams. Clutter is detail that is not
  true to the subject or that drowns the silhouette; it is not detail as such.
  
  ```python
  for r in [.132, .146]:          # two concentric rims on each round lamp
      curve('lamp-rim-' + suffix + '-' + str(r), rim(r), 'identity', look={'weight': 1.2})
  for dy in [-.07, 0, .07]:       # and the refractor lines inside, faint
      curve('lens-' + suffix + '-' + str(dy), lens(dy), stage=4, look={'alpha': .35, 'weight': .5})
  for k in range(12):             # twelve slats on the engine-lid grille
      curve('grille-slat-' + str(k), slat(k), 'detail', stage=4, look={'weight': .75})
  ```
  
  ## 5. Checkpoint, critic, then a refine pass that answers the defects in order
  
  Every round: save a checkpoint of the scene, run the independent critic
  (`python3 TOOLS critique scene.json --reference side=photo.jpg ...`), then write a refine
  pass that takes the ranked defects one by one, most severe first, and says which one each change
  answers. Re-measure positions from the photos rather than nudging by eye.
  
  ```python
  """Second geometry pass responding to independent critic's ranked defects."""
  d = json.loads(Path('checkpoints/round-01/scene.json').read_text())
  # Re-seat headlights at measured wing-end height.
  for p in parts:
      if p['id'].startswith('headlamp-'):
          p['at'][1] -= .057; p['at'][2] += .055
  # Spatial 12-point star: three interlocking axes, no flat gear-like rosette.
  ...
  d['authoring']['review_rounds'] = 2
  ```
  
  Keep each round's reasoning in the comments: the next round, and the next reader, can see what
  was answered. A changed scene makes the critic's record stale; critique the version you deliver.
  
  ## What does not help
  
  - More code. The strongest generators were 160–420 lines; the rest were longer.
  - One body with everything on it. Sub-volumes read; one skin reads as a blob.
  - Every line at the default weight, every wire showing.
  - Main surfaces with no contour at all (`line: "none"`): a dark cardboard mockup.
  - Bare faces and empty corners left for "later": up close they are the unfinished work.
  - Calling a construct finished because the audit passes. A clean audit is not a good picture.
  

• construct_hologram/skill/references/effort.md12 KB1dbe6d32d5b9upstream ↗

  # Research and effort
  
  Aim for genuinely good, and always stop within the mode's limits. Both rules hold together.
  
  ## Research: optional, decided by the request
  
  | request | research | record |
  |---|---|---|
  | a generic subject: "a watch", "a desk lamp", "a fictional moss snail" | none: a typical, well-proportioned example from general knowledge; `subject.accuracy: generic`, facts `inferred` or `decorative` | `"research": "not_needed"` |
  | a concrete, named subject: a brand and model, a named place or building, a species, a specific artwork or vehicle | **preferred whenever you are unsure** of its identity-defining shape or specs (below) | `"done"`, with the sources used |
  | the same, and you are confident without looking | skip it; then nothing is `verified` (no cited source): facts `inferred`, accuracy `approximate` at most | `"skipped"` |
  | no web tool in the host | proceed without it; mark accuracy honestly; say in `next` what research would improve | `"unavailable"` |
  | the user says "research: on" or "research: off" | the user wins, either way | `"done"` / `"off"` |
  
  Research, when it applies, comes **before** any part is written:
  
  1. **Look up the exact subject:** the official or maker's pages, manuals, specifications,
     plans and drawings, and reference photos (front, side, three-quarter).
  2. **Look at the references** with vision (any model that can see images: Claude, GPT,
     Gemini, DeepSeek; in Hermes through the vision toolset) and measure the silhouette and the
     proportions. Trace the identity shape when text cannot give it ([tracing](tracing.md)).
  3. **Record what each value is:** documented (`verified`, citing the page), traced
     (`inferred`, citing the reference image) or invented (`inferred` with a note, or
     `decorative`).
  4. **Only then author.**
  
  Record it in the scene: `"authoring": {"tier": "standard", "research": "done", "sources":
  ["maker-specs", "ref-front"]}`, every id also in the scene's `sources`.
  
  ## Modes: fast, masterpiece, timeboxed, unbounded
  
  The user picks a mode by saying its name, or says nothing and you pick one (below).
  
  | mode | what it does | stops at | costs | for |
  |---|---|---|---|---|
  | **fast** | one pass with self-review, no rounds loop (the standard tier; showcase for a richer subject) | the tier's limits: 10 min and 2 reviews, or 30 min and 4 | 10 minutes (30 for a richer subject); cents with a DeepSeek-class model (tested: DeepSeek V4.1 Flash) | generic subjects ("a watch", "a car"), simple mechanical objects, quick asks; DeepSeek-class models do these well |
  | **masterpiece** | the rounds loop: a defect ledger and one independent critic a round, each version judged pairwise against the best so far ([rounds](rounds.md)) | 2 rounds in a row without a pairwise win, every criterion 3, **12 rounds**, or **2 hours of active work** | up to 12 rounds and 2 hours of active work, plus the critic's time; the most tokens of a normal run, so use a frontier model (tested: GPT-6.1 Sol, Claude Opus 5.5) | a specific named subject whose likeness matters: a car model, a landmark, a named building |
  | **timeboxed** | masterpiece in 2 hours in all: the same loop and stop rules, the critic's time counted with yours | the same as masterpiece, with **2 hours of working time, the critic's included** | up to 12 rounds and 2 hours in all, the critic's time included; fewer rounds than masterpiece when the critic is slow, so use a frontier model (tested: GPT-6.1 Sol, Claude Opus 5.5) | a user who wants masterpiece done within two hours; only when asked |
  | **unbounded** | the same loop with **only** its stop rules: no round cap, no time ceiling | 2 rounds in a row without a pairwise win (or every criterion 3), or the user | no cap: many rounds and hours, at a high token cost; stop it at any round | only when the user asks for it by name |
  
  **Unbounded, plainly:** the critic finds a win almost every round, so an unbounded run can go
  on for many rounds and hours, at a high token cost. The per-round report lets the user stop it
  at any time. In the author's own blind comparisons, on two subjects, there was no visible gain
  after about 12 rounds, which is why masterpiece stops there. Offer unbounded only when asked; never choose it yourself.
  
  The old tier names still work: quick, standard and showcase are fast; masterpiece is
  masterpiece. `tier: showcase` or `mode: masterpiece` in a request is honoured.
  
  ### Choosing when the user says nothing
  
  Pick the mode yourself and **announce it before any work**, in two or three lines: the mode,
  why, the rough time and cost, and how to switch. For example:
  
  > Mode: **masterpiece**, because a Porsche 911 is a specific named car whose likeness matters.
  > About 12 rounds and up to 2 hours of active work, at frontier-model token cost. Say "fast"
  > for a single 10-minute pass instead (or "unbounded" to keep going past 12 rounds).
  
  - **fast:** a generic subject, a simple mechanical object, a quick request.
  - **masterpiece:** a specific named subject whose likeness matters (a car model, a landmark, a
    named building).
  - **timeboxed** and **unbounded:** never chosen automatically.
  
  **Say which model fits.** If you are a smaller or cheaper model and the subject is a hard named
  one, say so in the announcement and recommend GPT-6.1 Sol or Claude Opus 5.5 (or a model of that class) for masterpiece (the
  evaluation runs: small models made scale errors and often failed to save a scene);
  offer fast mode as the alternative on the current model.
  
  ## The tiers behind the modes
  
  | mode | tier | use | wall clock | review/improve rounds | check rounds | research, when it applies |
  |---|---|---|---|---|---|---|
  | fast | quick | fast mode: bulk imports and simple archetypes (the parameter path) | 2 min | 0 (audit only) | 3 | none beyond the source data |
  | fast | standard | fast mode: one entry, a generic subject or a simple object | 10 min | 2 | 6 | ≤5 searches, ≤3 sources read, ≤3 reference images |
  | fast | showcase | fast mode for a richer subject: more references, more review rounds | 30 min | 4 | 10 | ≤10 searches, ≤6 sources read, ≤6 reference images |
  | masterpiece | masterpiece | a named subject whose likeness matters: rounds judged pairwise against the best, until two rounds without a win, every criterion 3, 12 rounds or the 2-hour ceiling | 120 min active | 12 (default cap) | 8 per round | ≤20 searches, ≤12 sources read, ≤12 reference images |
  | timeboxed | timeboxed | only on request: masterpiece in 2 hours in all, the critic's time counted with the author's | 120 min in all | 12 (default cap) | 8 per round | ≤20 searches, ≤12 sources read, ≤12 reference images |
  | unbounded | unbounded | only on explicit request: the same rounds with only the stop rules (two rounds without a win, or every criterion 3); no round cap, no time ceiling; many rounds and hours at a high token cost | none | until the stop rules | 8 per round | ≤20 searches, ≤12 sources read, ≤12 reference images |
  
  Effort goes where it is visible: silhouette, then proportions, then the two or three identity
  features, then secondary detail. Model nothing smaller than about 0.5% of the object's largest
  size: that is efficiency guidance, not a reason to stop.
  
  ## Watch the clock: draft early
  
  A run that researches well and then writes one large scene at the end can lose everything to
  the time limit (seen in a live run: ten minutes of excellent research, no scene saved). So:
  
  | share of the tier's time | what is true |
  |---|---|
  | ≤ 40% | research is over (within its counts) and a **complete scene that passes `check` is saved** in your folder |
  | 40–80% | improve the saved scene in place: one change, `check`, save, `review`; a valid scene is always on disk |
  | 80% | stop adding (in Hermes: the run budget's wrap-up notice); make the saved scene valid, `build`, deliver with `next` |
  
  Start the first draft from what you have (the silhouette, the masses, the identity features
  roughly placed) rather than from a perfect plan; size and detail come in the rounds after.
  
  ## Masterpiece and unbounded: the rounds
  
  For a subject that must be recognisable exactly (a named car, a landmark building).
  Masterpiece runs judged rounds ([rounds](rounds.md)) and stops at the first of: two rounds in a
  row that do not beat the best, every criterion at 3, 12 rounds, 2 hours of active time (an
  interruption does not count), or the user. Timeboxed counts the critic's time in the 2 hours too (the two are
  logged apart and added). Unbounded drops the round cap and the time ceiling.
  Every round:
  
  1. Work on at most 4 ledger items, regressions first, and tag each edit with its ledger id.
  2. `check` until clean; `rounds packet` checks the round in and writes the critic's packet.
  3. One fresh critic judges it blind, then against the best so far (A/B, unlabelled), then
     reconciles the ledger; `rounds record` keeps the version if it wins overall (its
     regressions lead the next round) and reverts it only if it loses.
  4. Report the round in chat: the critic's top requests, what changed (ledger ids), won or
     lost, the minutes. Everything else is in `rounds.md` and `checkpoints/round-NN/`.
  
  Start it with the same research, identity checklist and draft-early rule as any tier: a
  complete, valid scene first, then the rounds. A run can be resumed at any time
  (`rounds status`): usage limits are expected.
  
  ## When to stop
  
  At whichever comes first:
  
  - **The review judges it genuinely good**: accurate and beautiful, something you would put in
    a launch video. Only an independent critic can record "good" or "outstanding"; your own
    review records "self-reviewed". Judge it with the art-direction rubric in [review](review.md) on the rendered
    captures, not only the audit. Review, improve the weakest point, review again.
  - **Any limit of the tier is reached** (wall clock, check rounds, review rounds, research
    counts, or a host's token or cost ceiling).
  
  Then deliver the best version so far, and record how it ended:
  
  ```json
  "authoring": {"tier": "standard", "research": "done", "sources": ["maker-specs", "ref-front"],
                "review_rounds": 2, "outcome": "limit",
                "next": ["trace the headstock from a side photo", "finer fret markers"]}
  ```
  
  `outcome` is `outstanding` or `good` (an independent critic's verdict, recorded by
  `construct critique`), `self-reviewed` (your own review), `limit` or `unreviewed` (nobody could
  look at the captures). `next`
  lists, most valuable first, what the next improvement would be, so the construct can be
  regenerated at a higher tier later. Say the same in the hand-over.
  
  ## Count the rounds
  
  Before each review round, add one to `authoring.review_rounds` in the saved scene and save
  it. `check` warns `tier-rounds` once the count is past the tier's cap: stop reviewing then,
  deliver, and put what you would still improve in `next`.
  
  ## Who enforces the limits
  
  - **The agent** (any host) follows the tables above; the mode is the user's choice, or yours
    when they name none (announced first, never unbounded).
  - **`construct author`** enforces them itself: `--mode` (or `--tier`), a wall-clock timeout, check and
    review round counters (no review round starts after 80% of the time), saving every new best
    valid draft to `--out` at once, a cap on web reference images (`--max-images`; the user's own
    photos are source data, not research), and optional `--max-total-tokens` or `--max-cost`
    (with `--price-in`/`--price-out`, USD per million tokens). `--vision` turns on the
    review rounds for a model that can see. Single limits can be raised, never removed.
  - **MCP hosts** ask `construct_limits` for a tier's limits (with overrides, or the `tier:` and
    `research:` words found in a request) and enforce them in their own loop.
  - **Claude Code**: a command hook (`hosts/claude-code/construct_budget.py` in the
    repository, with its settings recipe) refuses review commands past the tier's rounds and,
    past the wall clock, every tool but reading, `check` and `build`.
  - **Hermes**: `hermes chat --run-budget 600 --max-turns 120` (per run; the owner's
    `config.yaml` stays as it is) gives the 80% wrap-up notice and a hard ceiling.
  - **Hosts add hard limits on top**: a Hermes run budget (its turn and time limits), an agent
    harness's timeout and cost ceiling, a provider's spend cap.
    Whichever limit is tightest wins. Only the unbounded mode, on the user's explicit request,
    runs without Construct's own round cap and time ceiling.
  

• construct_hologram/skill/references/method.md2.1 KBcf680d524d86upstream ↗

  # The method, and where it comes from
  
  This toolkit generalises the method its author used to build Measured Light holograms of
  real places (an independent recreation: no code, fonts or assets from that work are included).
  
  **facts → recognisable parts / construction sheet → deterministic construction →
  geometric audit → fixed-view and animation captures → visual critique → correction.**
  
  What made it work, and how the skill keeps it:
  
  | lesson | here |
  |---|---|
  | Truth first: one document holds the numbers, with certainty and reasons | `facts` with certainty, sources and notes; parts cite `basis` |
  | A closed vocabulary composes everything; no object has code of its own | the shape table, repeats, mirrors; unknown keys are errors |
  | Geometry is built once, deterministically | the compiler: same scene, same bytes |
  | An audit that must come back empty | `check` (support, assembly order, overclaims, accuracy) |
  | Fixed renders and critics catch what the audit cannot (over-bright guesses, clutter, weak silhouettes) | `review` contact sheets and the checklist |
  | Certainty is the material | verified crisp, inferred softer, decorative dotted; size and shape answered apart; provenance view |
  | The identity tone carries recognition features | `role: identity` (the renderer gives it its identity light) |
  | Staged assembly, ghost/collapse/build/stabilise | `assembly.style: ceremony` |
  | Alive but calm; events, not constant motion | seeded idle events, `calm` life |
  | Reduced motion is a first-class state | `reduced_motion: still`, checked in review |
  
  Concepts specific to those places (listener seats, loudspeakers, measured positions) are
  deliberately absent: an arbitrary object has its own facts.
  
  ## Time budget
  
  Most time goes to research, facts and visual judgment, not JSON. With the vocabulary in hand
  a first scene takes minutes. Those places were finished when they were genuinely striking,
  not merely accurate; here that aim is bounded by a mode (fast or masterpiece, or timeboxed or unbounded
  when the user asks for one) whose limits are ceilings, never targets: see [effort](effort.md). Write down your facts and
  identity features before the first part.
  

• construct_hologram/skill/references/provenance.md4.7 KB922238216ad6upstream ↗

  # Provenance, certainty and rights
  
  The construct's look tells the truth about what is known; the scene records why.
  
  ## Certainty
  
  | certainty | means | needs | looks |
  |---|---|---|---|
  | `verified` | checked against a cited source | a `source` id, or a verified basis fact | crisp light |
  | `user_supplied` | the user said or gave it | ideally a `user_request`/`user_supplied` source | crisp |
  | `traced` | fitted to an orthographic drawing, plan or elevation that a verified size scales | that reference as `source` (`drawing` or `reference_image`) | as inferred; blue in the provenance view |
  | `inferred` | your reasoning: typical sizes, proportions, designed from a description | a `note` saying why helps | a step back |
  | `decorative` | chosen for presentation, not evidence | nothing | dotted, faint |
  
  - Facts carry certainty; parts carry certainty and cite the facts they rest on (`basis`).
    A part never claims more than its basis (the audit flags overclaims).
  - `subject.accuracy`: `generic` unless you are modelling *this particular* thing from
    evidence; `documented` only when its key parts are evidence-backed (audit-enforced).
  - `subject.synthetic: true` for examples and demonstrations only; a real request is
    `false` with its request source `user_private`.
  - **Dimensions are not shapes: say each.** A spec page verifies a length or a height, not an
    outline, so give a part both answers when they differ:
    `"certainty": {"size": "verified", "shape": "traced"}` with the length in `basis` and the
    blueprint as `source`. Link every part whose own dimension is a verified fact to it in `basis`
    (a body to its length and width, a tower to its height, a tyre to its size code). A count or a
    description does not verify a size, and neither does a measured thing a part only sits on or is
    computed from: a crater on a moon of known radius, a fret placed by the scale length.
  - A shape is `verified` only when a source of kind `drawing`, `measurement` or `dataset` gives its
    coordinates (the audit warns: `shape-overclaim`); `traced` when you fitted it to an orthographic
    reference (a blueprint, a plan, a patent elevation, a square-on overhead); `inferred` when it was
    read off a perspective photograph or designed. Looking for orthographic drawings is the fastest
    way to make a real object's construct more than a guess.
  - **Guesses come in shades.** The provenance view deepens an inferred part from designed (cites
    nothing) through described (a document, a basis fact) and seen (read from a picture of it, cited as
    its `source`) to seen and checked (also resting on a verified fact, or passing a silhouette
    comparison, `construct compare --record`); a traced part deepens once its reference's comparison
    passes. So cite on every part the picture or page you read it from: a part modelled from a photo
    that does not cite it shows as designed.
  - **Designed to a requirement.** A new design (`subject.accuracy: "original"`) or a designed part
    of a real thing still answers to something: what the user asked for ("two seats") or what a
    document says it does ("a 64-slot modulation matrix"). Write that as a fact with
    `"requirement": true` and its source (the request, the manual), and put its key in the `basis`
    of each part that realises it. The part stays `inferred`, shaded designed (a requirement says
    what it must do, not what it looks like); the legend splits DESIGNED into "designed · to a
    requirement" and "designed", and names the requirements' sources.
  - **Unknown stays unknown.** A fact you do not know is not written at all (never `null`, a
    placeholder or a plausible guess), and nothing is labelled with it.
  
  ## Sources
  
  `{"id", "kind", "title", "rights", "ref"}`. Cite what you actually used: the request, a
  measurement the user gave, a document they supplied, a page you read. `ref` is citation
  text; the tools never fetch it. Rights: `synthetic`, `user_private`, `permitted`,
  `public_domain`, `reference_only` (you may describe it, not reproduce it).
  
  ## Artwork
  
  - **Authentic** artwork (the real cover, label, poster) only from bytes the user supplied
    or explicitly permitted: declare `provenance: "authentic"`, its rights and source, and
    its SHA-256. Never download covers on your own initiative, never recreate a real cover
    from memory, never present an approximation as the real thing.
  - **Generated decoration** is allowed and must be declared `generated-decorative`; the
    viewer captions it "GENERATED DECORATION, NOT AUTHENTIC". Say so in your delivery note.
  - No bytes or a hash mismatch: the slot stays empty and labelled. That is a correct result.
  
  ## Privacy
  
  Keep private collections, titles, notes and personal photos out of examples, logs and
  anything published. Use synthetic stand-ins when demonstrating.
  

• construct_hologram/skill/references/review.md10 KB19ea937ed96cupstream ↗

  # Review
  
  Two gates, both required:
  
  1. **Geometric validity** — `check` reports `audit: PASS`. It proves the object stands up
     (every part rests on the ground, on another part or on a declared floating part, its
     surface meeting that part's surface: a box that only overlaps is not enough),
     that nothing claims more certainty than its evidence, and that accuracy claims are
     backed. It cannot judge beauty or likeness.
  2. **Art direction** — your eyes on the captures. Read the images; do not infer them from
     the JSON. The bar is not "recognisable": it is **genuinely good**, accurate and
     beautiful, something you would put in a launch video.
  
  ## The art-direction rubric
  
  Score each criterion 0–3 from the captures, against the references:
  
  - **3 outstanding**: someone who knows the subject names it exactly at a glance; silhouette
    and proportions match the reference within a few percent; finished, polished, exhibition
    quality. Rare.
  - **2 good**: clearly right; deviations show only beside the reference.
  - **1 weak**: the right kind of thing, wrong where an owner notices at once (boxy where it is
    curved, towers missing, a rectangle where the nose tapers).
  - **0** missing or wrong.
  
  | criterion | good means | look at |
  |---|---|---|
  | silhouette | reads instantly as this thing, from the hero and every side | `hero.png`, `sheet-views.png` |
  | proportions | right against the facts and the references: heights, widths, spacing | `sheet-views.png` front and side, beside the reference |
  | identity | the two or three identity features are rendered with care, in proportion, bright | `hero.png`, their own `view-<id>.png` |
  | depth | masses, structure, detail and ornament layer clearly; nothing equally loud | `hero.png` |
  | composition | strong hero framing with margin; nothing cut off; the best side | `hero.png`, each view |
  | assembly | the build order tells the object's story: foundations first, the reveal last | `sheet-assembly.png` |
  | motion | articulations and idle life bring it alive without noise, about real pivots | `sheet-motion.png`, `sheet-life.png` |
  | density | one clear object at hero scale; up close every region has something true (a bare face or empty corner is unfinished); never clutter: no hairlines, nothing hovering or poking through | every sheet, `solid.png` |
  | honesty | labels only from facts; inferred and decorative parts look it; the caption says GENERIC or APPROXIMATE when it is, ORIGINAL DESIGN for a new design | `sheet-provenance.png`, `hero.png` |
  
  It is **good** when every criterion scores 2 or more and you would show it as it is.
  Otherwise **iterate**: improve the weakest criterion first, `check`, `review`, score again.
  Stop when it is good or when the tier's review rounds or time run out ([effort](effort.md)),
  and record the remaining ideas in `authoring.next`.
  
  A model that can see reviews its own captures (`prompts/vision-review.md` asks for exactly
  these scores). That self-review records `"outcome": "self-reviewed"`: an author grading its own
  work is lenient (seen in live runs: unfinished castles graded "good"). Only the independent
  critic can record "good" or "outstanding".
  
  ## The independent critic
  
  Fresh eyes, the method the original places were finished with. The critic is not the author: a
  subagent, a delegated task or a second model call with a fresh context, which sees only the
  packet:
  
  ```bash
  python3 TOOLS critique scene.json --reference side=side.jpg --reference top=top.jpg \
      --reference three-quarter=hero.jpg --request "a Lamborghini Countach LP400"
  ```
  
  That writes `critique/packet.md` (the critic's instructions, the request, your identity
  checklist, the scene's hash) and renders from the views of your references beside them. Then:
  
  - **Claude Code**: start a subagent with only this: "Read critique/packet.md and every image
    it lists; answer with the critique JSON it asks for; save it as critique/critique.json".
    Do not give it your conversation.
  - **Hermes**: delegate the same task (the delegation toolset), or run the critic as a
    second model call: add `--base-url`, `--model` and `--key-env` to the command above.
  - **`construct author --critic`** (or `--tier masterpiece`) runs it for you every round.
  - **Masterpiece rounds** (`rounds packet` / `rounds record`, [rounds](rounds.md)) use one critic
    per round in three parts: this version blind, then against the best so far (A/B), then the
    defect ledger. The pairwise pick decides; scores are recorded, and every score below 3 must
    cite a defect of its criterion.
  
  Record the answer: `python3 TOOLS critique scene.json --record critique/critique.json`. It
  checks the critique, binds it to the scene's hash (a later edit makes it stale), recomputes
  the verdict from the scores (outstanding: every score 3, nothing critical or major, every
  checklist feature present at quality 3; good: every score at least 2, nothing critical), and
  writes `critique/defects.md`: the ranked defects. Fix them most severe first, then critique
  again.
  
  ## The capture set (`review --out out/`)
  
  | file | what to look for |
  |---|---|
  | `review/hero.png` | the main impression with labels: is it instantly *this* object? |
  | `sheet-views.png` | hero, front, side, back, top, three-quarter: silhouette from every side, proportions, nothing missing or poking through |
  | `sheet-assembly.png` | ghost → collapse → staged build → settle: order makes sense, nothing hovers before its support, the tip of construction reads |
  | `sheet-life.png` | idle events at their peak: visible but not chaotic, suited to the subject |
  | `sheet-provenance.png` | certainty colours (verified ice-white, size verified cyan, shape verified violet, traced blue, user-supplied green, inferred amber, decorative magenta): is the honest story visible, and is anything amber that a cited dimension or drawing could vouch for? Pale amber (designed) on a part you read from a reference means it does not cite it. |
  | `still-reduced-motion.png` | the still state alone |
  | `solid.png` | the surfaces as a solid, as a print or a modelling program shows them (S in the page): panels that meet, glass inside its frames, nothing crumpled, faceted or poking through. The light forgives these; a print does not. |
  | `sheet-motion.png` | opening and part motion across seconds |
  | `view-<id>.png` | each of your scene's own views, still: is the target framed with context? |
  
  ## Checklist (what each criterion hides)
  
  - **Recognisable at thumbnail size?** Squint at a single view cell. If not, the silhouette
    or proportions are wrong — fix masses before anything else.
  - **Identity features visible** in hero and in their own view?
  - **Hierarchy**: masses and identity carry the image; detail and ornament recede. If
    everything is equally bright it is clutter (audit warns above 55 % detail). Main surfaces
    keep their faint contour wire: that is form, not clutter.
  - **Framing**: the object fills the frame with margin in every view; nothing cut off.
  - **Proportions** against the facts; no part obviously too thick, thin, high or low.
  - **Contact**: legs on the ground, roofs on walls, arms on pivots, a shade on its arm. The
    audit's `detached` warning compares real surfaces and names the nearest part; fix it, do
    not explain it away. `unsupported` (an error) is a part whose box reaches its support but
    whose surface does not; `thin-support` is a part held up only by a strut or a wire far
    thinner than itself, with the sturdy part it should rest on named. `tips` is a part that
    stands on something with its weight off it, on one edge or a point (a back board standing on
    a rail and leaning back with nothing behind it): give it a second hold on the side it leans to.
    `thin` flags a structural part too fine to render.
  - **Honesty**: inferred and decorative parts look it; generated art is labelled; the caption
    says GENERIC or APPROXIMATE when it is, ORIGINAL DESIGN for a new design.
  - **Motion**: ambient, never frantic; parts move about their real pivots.
  - **Opening**: lids and boards swing about their real hinge and nothing passes through
    anything; the open pose shows what opening is for (the disc, the title page). Choose the
    `open` view's yaw and pitch from `view-open.png` (try a few: the board or lid must not
    hide what it reveals) and keep the hero for the closed object's best side.
  - **Text**: labels sit on their face, read the right way up, and only name facts you have.
  - **Still**: the reduced-motion frame is a complete, good picture.
  
  ## Common defects and fixes
  
  | defect | fix |
  |---|---|
  | reads as a generic box/cylinder | stronger identity parts; real profile changes in lathe/extrude; better hero yaw |
  | mush of lines | fewer meridians/rings/ribs; `fill: none` on thin parts; move clutter to `detail` |
  | part floats or sinks | correct `at`/`anchor`; heights from the support's top; or `floating: true` if real |
  | dotted, broken-looking main body | it is `decorative`: designed parts of a requested object are `inferred` |
  | too dark/faint | role `mass`/`identity` instead of `structure`; `look.glow`; fewer competing parts |
  | wrong rotation axis in motion | axis and pivot are world values for the first copy |
  | labels collide | fewer annotations, `offset` them apart |
  | a part pokes through another in `solid.png` (a fender edge up through a bonnet, a pillar over the roof) | `check --fit` names it and where: trim it to end at the other's face |
  | a part through a pane (`check --fit`: crosses-glass) | stop it at the glass, or split the pane around it |
  | an open shell (`check --fit`: open): a tube end or a lathe's top you can see into | `"caps": true`, or start and end the lathe's profile on its axis |
  | a part buried in another (`check --fit`) | usually the other is far too thick (a fender that swallows the strut tower): thin it; or the buried part is not needed |
  
  Fix, `check`, `review` again, within the tier's review rounds.
  
  ## Refining the solid
  
  The light forgives what a solid, a print or a kit does not. When a construct will be printed, made a kit or
  exported for an engine, refine its solid: open the page and press **S**, run `construct check scene.json --fit`
  (the parts that poke through others where it shows, and the parts buried in others, the most visible first;
  some are meant, a part set through another by design), fix the scene so parts meet at faces, and `review`
  again: `solid.png` shows the result, and the critic sees it too. Proportions are checked as before, against the
  references with `compare`.
  

• construct_hologram/skill/references/rounds.md8.0 KB6a01b44e7ea9upstream ↗

  # Rounds: how a masterpiece (or unbounded) run gets better, and when it stops
  
  A long run improves only if each round is judged fairly and nothing good is thrown away. In live
  runs a construct gained about one rubric point per round, up to about 20 of 27 by 45–50 active
  minutes. What wasted rounds there:
  - comparing every round with the luckiest score so far (single scores wobble by about ±1);
  - reverting a whole round over one local regression;
  - bundling 5–10 edits, so nobody could tell which one hurt;
  - retiring defects as "known limits" while they were still being fixed.
  
  `construct rounds` keeps the run on disk, so it can be read, steered and resumed. It is the
  masterpiece and unbounded modes; fast mode is one pass without it.
  
  ## Start
  
  In the run's own folder, named after nothing (`run-3f9a/`, not the subject's name), with the
  first draft saved and passing `check`:
  
  ```bash
  python3 TOOLS rounds start scene.json --mode masterpiece      # or --mode unbounded, only when asked
  ```
  
  The run's memory is these files. Every command saves them, so an interruption loses at most one
  step:
  
  | file | holds |
  |---|---|
  | `state.json` | `round`, `step`, `active_seconds`, `critic_seconds`, `best_round`, `status` (running / stopped) |
  | `ledger.json` | every defect ever raised: `id`, `title`, `criterion`, `severity`, `first_round`, `status` (open / fixed / regressed / known-limit), `rounds_attempted`, `history` |
  | `rounds.md` | one section per round, appended: what changed, the critic's requests, won or lost |
  | `checkpoints/round-NN/` | that round's scene, its renders, the critic's answer, the A/B key (never shown to the critic) |
  
  ## One round
  
  1. **Work on at most 4 ledger items.** Regressions come first, then the rest from most severe
     down. Never work on a known limit. Tag every edit with its ledger id:
     `python3 TOOLS rounds change D3 "lowered the bonnet 40 mm at the axle"`. In round 1 the tag
     is `draft`. A fifth item is refused: check the round in and let the critic judge first.
     Small batches tell you which edit did what.
  2. **`check` until clean,** then `python3 TOOLS rounds packet --reference side=side.jpg
     --reference top=top.jpg ...`. That checks the scene in to `checkpoints/round-NN/` and
     writes one packet, in a neutral folder, with the references copied in, for **one** fresh
     critic:
     - **part 1:** this version alone, the standard critique;
     - **part 2:** this version and the best so far, from the same views, unlabelled and in a
       random A/B order, beside the references. The pictures are re-encoded and named at random,
       so no file comparison tells them apart;
     - **part 3:** the ledger.
  
     The critic writes part 1 before it opens part 2. Its blind judgement never sees the history.
  
     The packet holds only what the critic judges by: the renders, the reference pictures and the
     user's request (`--request`, in the user's words; without it, none). `--reference` takes
     pictures only (png, jpg, webp, gif) or links: your notes, reasons and rationale never go in,
     and a document is refused. Once written, the packet is sealed: its files are read-only and its
     hash is in `state.json`.
  3. **The critic.** Give a fresh critic the packet folder and nothing else: a subagent, one
     delegated task (in Hermes, one child a round fits its two-child budget), or direct model
     calls: `python3 TOOLS rounds run --base-url URL --model M --key-env VAR` (one conversation,
     part 1 answered before parts 2 and 3 are shown). Save its answer outside the packet folder.
     The critic and the author do not talk until the answer is recorded: no questions, no
     explanations, no second thoughts after a word from the author.
  4. **`python3 TOOLS rounds record answer.json`.** It refuses an answer when the packet changed
     after it was written (or is gone), and a packet is answered once: a recorded blind verdict is
     not rewritten (the checkpoint's `round.json` is read-only, its hash is in the round's history,
     and `rounds report` names a round whose answer was edited afterwards). A new answer needs a
     new packet and a fresh critic. Then it un-blinds the pair and decides:
     - **Won overall: keep it.** Its regressions go to the top of the ledger. Repair, don't
       revert.
     - **Lost overall: revert.** The working scene becomes the best round again. Next round, try
       a different fix.
  
     Absolute scores are recorded but decide nothing.
  5. **Report the round in chat,** every round.
     `record` prints it: the critic's top requests, what changed (with ledger ids), won or lost
     against the best, and the minutes. Copy it as it is. Then go to step 1, unless it says STOP.
  
  Each round's section in `rounds.md` also answers "would a 4-round finish cap stop here?". Finish
  starts at the first round with no critical or major silhouette, proportions or identity item
  open. This is logged only, to compare stop rules; it never stops the run.
  
  ## The medium
  
  The renderer cannot do three things, and `start` seeds them as known limits (L1–L3):
  - hidden lines show faintly through solid parts (the x-ray style);
  - glass cannot be tinted;
  - stills show the closed still pose.
  
  An ask the critic itself files under one of them (its `limits` answer in part 3) never enters the
  ledger. Don't try to change the renderer from a scene.
  
  ## Scores need evidence
  
  Every score below 3 cites a defect of its criterion, or the critique is refused. In the log, a
  score that moves with no defect added or fixed for its criterion is marked as noise. The pairwise
  gate, not the scores, decides which version is the best.
  
  ## The ledger
  
  `record` reconciles every open item (fixed, open, regressed) and adds the genuinely new
  defects. An item becomes a **known limit** in either case:
  - 3 kept rounds attempted it without progress (rounds that were reverted don't count);
  - the critic says the construct's tools cannot draw it (`inexpressible`).
  
  Known limits are not worked on again. The final report lists them as **skill gaps**: what the
  skill could not express.
  
  ## Stop
  
  At the first of:
  - 2 rounds in a row that don't beat the best (any pairwise win resets the count);
  - every criterion at 3;
  - **masterpiece only:** 12 rounds (a default cap: in the author's own blind comparisons, on two
    subjects, no visible gain showed after about 12 rounds);
  - **masterpiece only:** 2 hours of **active time**: the author's time from `start` or `record` to the
    next `packet`, measured from the run folder's own activity (edits, a generator writing the
    scene, builds). Time after the last write counts only if the next command comes within 10
    minutes; a silence of over 45 minutes between writes (a usage limit) is an interruption; and
    `rounds pause` marks one explicitly. The critic's time, from `packet` to `record`, is measured
    the same way, the packet's folder included, and logged separately;
  - **timeboxed only:** the same 2 hours, counting the author's and the critic's time together;
  - the user says so.
  
  **Unbounded** keeps only the first two: no round cap and no time ceiling. The critic finds a
  win almost every round, so it can run for many rounds and hours at a high token cost. Report
  every round, so the user can stop it at any time.
  
  Then `python3 TOOLS rounds report` appends the final report to `rounds.md`: the best round, the
  curve, the minutes, the open defects and the known limits. Deliver the best round: it is the
  working scene, with its round history in `authoring.rounds`. `construct.html` shows the
  timeline, and `review` writes it as `rounds.png`.
  
  ## Resume (usage limits are expected)
  
  Before stepping away, `python3 TOOLS rounds pause`. After any interruption, `python3 TOOLS rounds
  status` says where the run is and what the next step is. Redo only the step it names, never a finished round.
  
  Only the loop's own stop rules end a run: the critic's all-3, two rounds in a row that do not beat the best,
  the round cap, the active-time ceiling, or the user. When your session ends first (a one-shot run's budget,
  a usage limit), `rounds pause` and say the run can be resumed; do not record the outcome as `limit`, which
  means a stop rule ended it. `rounds status` still says `running` until one has.
  

• construct_hologram/skill/references/terrain.md1.5 KBe7e8fc5bad89upstream ↗

  # Places, peaks and routes
  
  Never sculpt a real mountain from memory. If the user has elevation data (an ASCII grid or XYZ
  export, for example swissALTI3D or Copernicus GLO-30) or can get it, build the place with:
  
  ```bash
  python3 TOOLS terrain --dem tile.asc|tiles/ --center LAT,LON --extent METRES --title "Name" \
      --source-title "dataset, attribution" [--gpx route.gpx] [--mark "Summit=LAT,LON"] [--from NE] --output place.json
  ```
  
  It writes a scene with a verified `terrain` part (MEASURED TERRAIN), the route draped on it,
  markers, the facts and a view from the side you name; `check`, `review` and adjust the view.
  Without data, a small hand-made `terrain` heightfield is allowed but stays `inferred` and shows
  as SKETCHED TERRAIN — say so. Attribution for the data goes in `--source-title`; it is shown
  on the construct. `--dem` takes several tiles or a folder of them; only the area is read. Details:
  docs/TERRAIN.md in the repository.
  
  ## The globe
  
  Never draw Earth's continents from memory as if measured. With coastline data (GeoJSON, for
  example Natural Earth's public-domain `ne_110m_coastline.geojson`):
  
  ```bash
  python3 TOOLS globe --coastlines coast.geojson --title "Earth" \
      --source-title "Natural Earth 1:110m coastline (public domain)" --output earth.json
  ```
  
  It writes a sphere, the coastlines (verified: MEASURED COASTLINES), the axis at the cited
  23.44° tilt and a slow spin. Without data, a hand-made globe is a sketch: `inferred`
  coastlines and `accuracy` approximate at most; say so.
  

• construct_hologram/skill/references/tracing.md5.3 KB5d199081ff41upstream ↗

  # Likeness from references: tracing
  
  Spec pages give dimensions; they never give a shape. When a thing's identity is its outline (a
  guitar body, a car's profile, a building's elevation, a bottle), measure the shape from a
  picture instead of inventing it — and never copy the picture.
  
  ## The steps
  
  1. **Find a reference.** Best: the user's own photo (rights-clean for their collection).
     Otherwise an image you can view on the web (the maker's product photo, a straight-on view),
     found during research ([effort](effort.md)) and counted against the tier's reference images.
     You look at it; you never download it into the scene, embed it or reproduce it.
  2. **Trace it** (any model that can see images). Follow `prompts/trace.md`: answer a
     `construct-trace` JSON with the image's pixel size, the silhouette as 40–120 points (pixels,
     y down) and the named features you need (`nut`, `bridge`, `neck-joint`; `roof-ridge`;
     `wheel-front`...). Check it: `check trace.json` reports a self-crossing or too-short outline.
  3. **Fit it to a documented dimension:**
  
     ```bash
     python3 TOOLS trace trace.json --fit nut:bridge=0.648 --out body.json
     ```
  
     `--fit` takes the distance between two traced features (best: a verified spec such as a scale
     length), or `height=` / `width=` of the outline. `--origin bottom-center` (default), `center`
     or `feature:<name>`.
  4. **Use it.** `body.json` holds an `extrude` profile in metres (front elevation, axis `z`), the
     features in metres (place pickups, the bridge, horns from them), a `source` of kind
     `reference_image` to add to the scene's sources, and a `part` stub: certainty `inferred`,
     cited to the image, with a note. The dimension facts stay `verified`. When the image is
     orthographic (a blueprint, a plan, an elevation) and `--fit` used a verified dimension, make the
     part `{"size": "verified", "shape": "traced"}` with that fact in `basis`; from a perspective
     photograph it stays `inferred` (the audit's `shape-overclaim` keeps it honest).
  5. **Look again.** Review the construct against the reference.
  
  ## Bodies from three views (cars, hulls, fuselages)
  
  A car is recognisable by its exact silhouette from the side and from above, and by how its
  cabin narrows towards the roof. Trace all three, then loft through them:
  
  1. Trace the **side** (nose left or right: note which), the **top** (plan; nose up or down)
     and, if you can, the **front**: one `construct-trace` each, the whole outline including
     the cabin.
  2. `python3 TOOLS loft-from-traces --side side.json --top top.json --front front.json
     --length 4.14 --height 1.07 --width 1.89 --nose-side left --nose-top up --out body.json`
     reconciles them into 24 loft stations (crowded at the nose and tail): bottoms and tops
     from the side, half-widths from the plan, and from the front how wide the body still is
     at each station's top, so the cabin narrows and the bonnet stays wide. It reports the
     traced height and width against the documented ones; a mismatch over a few percent means
     a trace is off.
  3. Put it into a scene: `--into car.json --part body --drop glasshouse` (the traced side
     already includes the cabin). Start from `params vehicle` for the wheels, arches and
     lights, then move the wheels to the traced wheelbase.
  4. Add the identity features on top (ducts, the roof channel, door lines) as curves and thin
     parts on the body.
  
  ## Measure the likeness
  
  `python3 TOOLS compare car.json --trace side.json --view side --overlay side.png` projects the
  construct's silhouette from the view (from the geometry, no browser) and measures it against
  the traced outline: IoU (1 = identical) and how far apart the outlines are, as a share of the
  view's width. Vehicles need IoU 0.88 and outlines within 1.2%; landmark buildings 0.82 and 2%.
  A trace may face any way: a plan tries every quarter turn and mirror, and the result says which
  was used and warns when a trace was drawn across the view (draw plans nose-up, sides nose-left).
  Tyres count as solid discs (a torus, lathe or cylinder named wheel, tyre or tire), the well under an arch is
  filled (a curve, tube or paths named arch), and ornament (a shadow ring, motes) is left out of the silhouette.
  The overlay shows the reference amber, the construct violet, both white: fix where the colours
  show. `--record` writes the result into `authoring.compare` (bound to the scene's hash). An
  outstanding vehicle or landmark needs a passing comparison: the critic's "outstanding" is held
  at "good" without one.
  
  ## Enabling vision in hosts
  
  Tracing works with any model that can see images: Claude, GPT, Gemini and DeepSeek among them.
  
  - **Hermes:** with the vision toolset enabled, attach the photo (`/paste`, or an image path)
    or let the agent call `vision_analyze` on the image, with the `trace.md` instructions as its
    question. DeepSeek V4.1 Flash and GPT-6.1 Sol both describe and trace images this way.
  - **Claude Code:** the agent reads image files directly; put the user's photo in the working
    folder.
  - **Any OpenAI-compatible vision model:** `construct trace-image photo.jpg --what "the guitar
    body outline, front view" --features nut,bridge --fit nut:bridge=0.648 --base-url ...
    --model ... --key-env ... --out body.json` (local photos are sent as data; https images by URL,
    viewed and not kept). `construct author --reference photo.jpg ...` attaches references to a
    whole draft.
  

• construct_hologram/skill/references/vocabulary.md16 KB46d9c38b18f4upstream ↗

  # Scene vocabulary (format `construct-scene` version 2)
  
  Metres, **Y up, the front faces +Z** (a viewer's yaw 0 looks at the front). Angles in
  degrees. Rotations apply X, then Y, then Z, about the part's own origin. Unknown keys are
  errors: the closed vocabulary is the safety boundary.
  
  ## Skeleton
  
  ```json
  {
    "format": "construct-scene", "version": 2,
    "id": "lowercase-id", "title": "Human title",
    "subject": {"category": "object", "summary": "one or two sentences", "accuracy": "generic", "synthetic": false},
    "units": "m", "seed": 7,
    "sources": [{"id": "request", "kind": "user_request", "title": "The user's request", "rights": "user_private"}],
    "facts":   [{"key": "height", "value": 0.42, "unit": "m", "certainty": "inferred", "source": "request", "note": "why"}],
    "assets":  [],
    "parts":   [ ... ],
    "articulations": [ ... ], "labels": [ ... ], "anchors": { ... },
    "annotations": [ ... ],
    "presentation": { ... },
    "animation": { ... }
  }
  ```
  
  - `subject.category`: `architecture, object, machine, vehicle, organism, fictional, cd, book, artwork-carrier, other`.
  - `subject.accuracy`: `generic` (a typical example), `approximate` (based on this particular thing, imprecise), `documented` (its key parts cite evidence; the audit enforces it), `original` (a new design: nothing real to reconstruct; the caption says ORIGINAL DESIGN), `recorded` (a run of a model, drawn from its recording: `construct netlogo` sets it; the caption says RECORDED RUN). `check` prints "evidence-backed key parts: n of m": how many key parts (mass and identity) are themselves verified or user-supplied; 0 is normal for a generic reconstruction.
  - `subject.synthetic`: `true` only for examples and demonstrations; a real request is `false`, its `request` source `user_private`.
  - Facts hold known values only. **An unknown fact is absent**: never `null`, never a guess.
  - `"requirement": true` marks a fact as something the thing must have or do: the user's ("two seats",
    citing the request) or its documentation's ("a 64-slot modulation matrix", citing the manual). It
    needs a `source`. A designed part that realises it names it in `basis` and stays `inferred`: the
    provenance view counts it as designed to a requirement, apart from free design, and lists the
    requirements' sources; `check` warns `requirement-unmet` when no part names one.
  - Colour is the renderer's: every construct renders in one house palette. Never write `presentation.style_hint` (it is ignored, with a warning). If the person explicitly asks for a colour, the host applies it: `build --palette amber` (palettes `violet, cyan, amber, green, ice, rose`; `--identity` tints `none, warm-wood, stone, steel, brass, bio, ember, ice, paper`).
  
  ## Parts
  
  ```json
  {"id": "tower", "label": "Tower", "role": "mass", "certainty": "inferred", "stage": 1,
   "basis": ["tower.height"], "source": null,
   "shape": {"type": "lathe", "profile": [[3.6, 0], [2.8, 20]]},
   "at": [0, 0, 0], "rotate": [0, 0, 0], "scale": 1,
   "look": {"fill": "glass"}, "repeat": null, "mirror": null, "motion": null, "floating": false}
  ```
  
  | field | values |
  |---|---|
  | `role` | `mass` silhouette/primary volume · `structure` supporting construction · `detail` small/repeated (fades first) · `identity` the recognisable features (identity tint, glow) · `data` emphasised point/light (accent, strong glow) · `ornament` atmosphere (motes, sparkle) · `ground` survey/base lines · `artwork` a face carrying an image |
  | `certainty` | `verified` (needs `source` or a verified basis fact) · `user_supplied` · `traced` (fitted to an orthographic reference cited as `source`) · `inferred` · `decorative`; or `{"size": .., "shape": ..}` when they differ (a body whose length is verified and whose outline is traced). A feature the user asked for whose size you chose: a `user_supplied` fact ("three blades") as `basis`, the part `inferred` |
  | `stage` | 0–7, assembly order (foundation first) |
  | `basis` | fact keys the part's dimensions come from |
  | `look` | `tone` (`accent, bright, hairline, structure, dust, identity, data, faint`), `line` (`auto, solid, dashed, dotted, none`), `fill` (`auto, none, glass, dark`), `glow` 0–1, `weight` 0.25–3, `alpha` 0.05–1 — use sparingly: role and certainty already set the look. `fill: glass` is only how the light draws a part: real glass (a pane, a window, a crystal) also says glass, glazing or window in its id (`hood-door-glass`), which the solid view, exports, prints and kits go by |
  | `floating` | `true` for things that truly hover (a beam of light, a halo, a creature's bell, motes); everything else must rest on something |
  | `anchor` (box, sphere) | `center` (default) or `base` (sits on `at`) |
  | `artwork` | `{"slot": "cover-front", "asset": "cover", "face": "front", "mask": "rect"}` — see Artwork |
  
  ### Shapes
  
  | type | parameters | use for |
  |---|---|---|
  | `box` | `size [w,h,d]`, `ribs` 0–32 (panel lines), `anchor` | plinths, cases, rooms, boards |
  | `cylinder` | `radius, height`, `segments` 6–96, `ribs` (vertical lines), `rings` (horizontal), `caps` | columns, feet, platters, knobs (base at `at`, along +Y) |
  | `cone` | `radius_bottom, radius_top, height` (+ cylinder options) | lampshades, spires, beams, funnels |
  | `sphere` | `radius` or `radii [x,y,z]`, `lat` 2–24, `lon` 3–48, `anchor` | heads, domes, bodies, ellipsoids |
  | `torus` | `major, minor`, `segments, sides, rings` | rails, rims, tyres, rings |
  | `lathe` | `profile [[radius, y], ...]` revolved about Y, `segments`, `meridians` | towers, bottles, vases, lamps, bells, records (flat profile = grooves) |
  | `tower` | `radius, height`, `sides` (0 round, 3+ polygonal), `roof` cone · pyramid · spire · onion · flat · none, `roof_height`, `taper`, `profile` straight · parabolic (narrowing ever faster: the Sagrada Família's bell towers), `eave`, `windows [rows, per_row]` | castle towers, turrets, minarets, lighthouses, silos |
  | `roof` | `size [w, d], height`, `style` gable · hip, `ridge` x · z, `overhang`, `courses` | pitched roofs on a block (stands on its eaves) |
  | `dormer` | `width, height, depth, roof_height` (faces +Z, back at z = 0) | windows in a roof (with `repeat`) |
  | `facade` | `size [w, h], rows, cols, opening [w, h]`, `arch` round · pointed · flat · none, `kind` windows · arcade, `outline` | a wall's windows or an arcade, facing +Z; `outline: false` on a box face |
  | `battlements` | `radius` or `path [[x, z], ...]`, `height, merlon, gap, thickness` | crenellated wall tops and tower tops |
  | `shell` | `span, height, reach, bulge, ribs, rows`: a sail from a base edge (on y = 0, `span` wide) up to an apex `height` high and `reach` behind, bulging forward, ribbed | the Sydney Opera House's roofs; pair them with `rotate [0, 180, 0]` and a podium |
  | `buttress` | `width, depth, height, steps` (against z = 0, out along +Z) | cathedral and castle walls (with `repeat`) |
  | `loft` | `sections [[z, half_width, y_bottom, y_top(, half_width_top)], ...]` back to front along +Z, `round` 0–1 | car bodies and glasshouses, hulls, fuselages: the plan (half-widths) and side profile (bottoms, tops) together |
  | `extrude` | `profile [[u,v], ...]` (simple polygon), `height`, `axis` `y` (footprint in XZ, rises) · `z` (front elevation in XY, runs back) · `x`, `ribs` | building plans, gabled houses, book spines, brackets |
  | `tube` | `path [[x,y,z], ...]` (Catmull-Rom smoothed), `radius` or one per point (taper), `sides` 3–24, `samples`, `longitudinal`, `ring_every`, `caps` | limbs, tentacles, tonearms, pipes, cables, branches |
  | `curve` | `points`, `smooth`, `closed` | edges, paths, outlines, shine strokes |
  | `paths` | `paths` (up to 4,000 polylines of `[x, y, z]` points, 30,000 points in all), `detail` | many lines in one part: agent tracks, network edges, measured curves (the NetLogo bridge writes them) |
  | `plane` | `size [w,h]` facing +Z, `divisions` | doors, windows, signs, artwork faces |
  | `grid` | `size [w,d]`, `divisions` | ground plans, decks |
  | `points` | `count` ≤ 2000, `region` `{"box":[w,h,d]}` · `{"sphere": r}` · `{"shell": r}`, `sprite` `disc, ring, square, soft`, `size_px` | dust, spores, stars, sparks |
  | `marker` | `sprite`, `size_px` | one emphasised point |
  
  ### Repeat and mirror
  
  - `"repeat": {"count": 2-64, "step": {"at": [dx,dy,dz], "rotate": [rx,ry,rz]}}` — copies
    stepped from the first (rotate is about each copy's own `at`).
  - `"repeat": {"count": n, "radial": {"axis": "y", "center": [x,y,z], "span": 360}}` —
    copies around an axis (railings, petals, spokes, tentacles).
  - `"phase_step": 0.083` — offsets each copy's motion phase (a ripple).
  - `"mirror": "x"` — adds the reflection across the plane x = 0 (bilateral symmetry).
  
  ### Motion (object-relative)
  
  The pivot is a **world point** and the axis a **world direction** for the first copy
  (default pivot: the part's `at`); repeat and mirror copies carry them along.
  
  | type | fields | example |
  |---|---|---|
  | `spin` | `axis, rpm` (±120), `pivot` | platter 33.33, fan, rotating beam |
  | `swing` | `axis, degrees` (≤ 90), `period`, `pivot`, `phase` | hinge, tonearm drift, tentacle sway, pendulum |
  | `bob` | `axis` (direction), `distance`, `period`, `phase` | floating, piston, breathing body |
  | `pulse` | `period, amount` (0–1) | heart, lamp, glowing core |
  
  ## Articulations (one-shot opening)
  
  Lids, boards, doors, drawers, a disc lifted from its tray: things that open once and hold.
  
  ```json
  "articulations": [
    {"id": "lid-open", "type": "hinge", "parts": ["lid", "booklet"], "axis": [0, -1, 0], "pivot": [-0.071, 0.0625, 0.0052], "amount": 108, "order": 0},
    {"id": "booklet-out", "type": "slide", "parts": ["booklet"], "axis": [1, 0, 0], "amount": 0.07, "order": 1},
    {"id": "disc-lift", "type": "lift", "parts": ["disc"], "axis": [0, 0, 1], "amount": 0.03, "order": 1},
    {"id": "disc-turn", "type": "turn", "parts": ["disc"], "axis": [0, 0, 1], "pivot": [0.003, 0.0625, 0.0004], "amount": 360, "order": 2}
  ]
  ```
  
  `hinge` (degrees, ±180, needs `pivot`), `turn` (degrees, ±1080, needs `pivot`), `slide` and
  `lift` (metres along `axis`; lift defaults to up). Axes and pivots are world values in the
  **closed** pose. List every part that moves with it: a booklet inside a lid is in the lid's
  hinge too. Later `order`s ride on earlier ones (the booklet slides out of the opened lid).
  Positive rotation follows the right-hand rule about `axis`: a lid hinged on its left edge
  (front +Z) opens towards the viewer with `axis [0, -1, 0]` and a positive amount.
  `presentation.still_pose`: `open` (default) or `closed` for the still frame.
  `presentation.labels`: `true` opens the page with the labels showing (a reading the construct
  needs, such as a NetLogo run's legend); otherwise they wait for **L**.
  `reading` (optional, top level): `how`, up to 8 short lines on how to read the construct, shown
  in a panel (**H**); for a construct whose height is time, `clock` (`label`, `from`, `to`, `top` in
  metres, `scale` linear or sqrt) and `series` (up to 6, each a `name` and up to 400 `[time, value]`
  pairs) add a replay bar that draws it up to a moment, with the counts at that moment.
  A number with a unit in `how` or an annotation that clearly names a fact (every telling word of its
  key in the same clause) must agree with it: when the scene changes, the audit's `stale-number`
  names a line still giving the old value. Better: say each number once, from the fact.
  
  ## Labels (text the renderer sets from facts)
  
  ```json
  "labels": [
    {"id": "spine-title", "part": "tray", "face": "left", "field": "title", "role": "title",
     "orientation": "vertical-down", "region": [0, 0.04, 1, 0.58]}
  ]
  ```
  
  `field` names a fact (the label shows its value and inherits its certainty); `text` is
  decorative literal text instead. `face` (box: `front back left right top bottom`; plane:
  `front back`; cylinder/lathe: `top bottom`; default front/top), `region [u0, v0, u1, v1]`
  (0..1 across the face, v downwards), `orientation` `horizontal | vertical-down` (spines,
  reading top to bottom) `| vertical-up`, `role` `title | creator | meta | catalog | body |
  decorative`, `align` `left | center | right`. Never put text in geometry; never label a fact
  you do not know (the compiler refuses a label whose fact is missing).
  
  ## Anchors
  
  `"anchors": {"front": {"part": "lid", "face": "front"}, "spine": {"part": "tray", "face": "left"},
  "grip": {"part": "handle"}, "base": {"point": [0, 0, 0], "up": [0, 1, 0]}}` — all optional. They
  tell a host which face to show face-out, which face a rack shows, where it rests and where it
  is held. Unstated ones come from the bounds (front +Z, spine −X, base bottom centre). Give
  `front` and `spine` for every CD, book and other shelved object.
  
  ## Annotations
  
  `{"id": "lantern", "text": "Lantern room", "part": "lantern", "offset": [0, 1, 0]}` — short
  review labels with a leader line. The anchor is the **top centre of the part's first copy's
  box**, plus `offset` (metres); it follows the part when it opens. Shown with `labels=1` or
  the L key. Mark inferred or decorative content in the text ("Beam (decorative)").
  
  ## Presentation
  
  ```json
  "presentation": {
    "framing": {"yaw": 30, "pitch": 18, "fit": 1.0, "target": null},
    "views": [{"id": "detail", "label": "Detail", "yaw": 20, "pitch": 8, "distance": 1.5, "target": "lantern"}],
    "atmosphere": {"haze": 0.7, "scanlines": true, "vignette": true, "grid": true, "projector": false, "motes": 0.4},
    "occlusion": "xray", "certainty_style": "subtle", "background": "deep", "float": 0
  }
  ```
  
  Built-in views: `hero, front, side, back, top, three-quarter`. A view with `target` frames
  that part alone; `distance` multiplies the distance fitted to that target (or to the whole
  object without one), so a small target with `distance: 1` is already a close-up — raise it
  (1.5–3) to keep context. `review` captures each of your views as `view-<id>.png`. A view named
  `open` is the one that best shows the opened pose; give one whenever the object has
  articulations. `projector` draws an emitter with
  light rays and rising motes under small objects; `float` drops the survey ground below a
  hovering subject; `certainty_style: "explicit"` dashes everything inferred.
  
  ## Animation
  
  ```json
  "animation": {
    "assembly": {"style": "ceremony", "seconds": 6, "interference": true},
    "idle": {"life": "alive", "events": ["scan", "sweep", "shimmer"], "cadence": [5, 11], "strength": 0.6},
    "camera": {"drift": 6, "breathe": 0.03, "tour": [{"view": "detail", "at": 14, "fly": 3}, {"view": "hero", "at": 22, "fly": 3.5}]},
    "reduced_motion": "still"
  }
  ```
  
  Details and choices: [animation](animation.md).
  
  ## Artwork
  
  ```json
  "assets": [{"id": "cover", "path": "assets/cover.png", "sha256": "<64 hex>", "media_type": "image/png",
              "rights": "user_private", "provenance": "authentic", "source": "user-photo"}]
  ```
  
  and on a part with a face (box, plane, cylinder, lathe):
  `"artwork": {"slot": "cover-front", "asset": "cover"}`. Slots name the place an image belongs:
  `cover-front, cover-back, inlay, disc, label, booklet-page-1 … 64`, each once. Leave `asset`
  out for an empty slot a host fills later. `face` as for labels; `mask` `rect` or `circle`
  (with `inner_radius` in metres for a disc's hole); `region` a part of the face.
  `provenance`: `authentic` (the real artwork: needs `permitted`/`user_private` rights and a
  cited source), `user_photo`, `synthetic`, `generated-decorative`. Paths are relative to the scene's folder. The build
  embeds only bytes whose hash matches; anything else is an empty slot. Compute the hash
  with `shasum -a 256 file` (or Python's `hashlib`).
  
  ## Budgets
  
  1,024 parts, 1,024 copies, 32 moving copies, 16 articulations, 48 labels, 48,000 lines,
  48,000 triangles, 6,000 points, coordinates within ±500 m. Over budget: lower `segments`, `meridians`, `ribs`, `lat/lon`,
  repeat counts, or drop fills (`"fill": "none"`) on thin parts.
  

• README.mdupstream ↗

  Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/rtmandreyev-construct-construct-hologram-skill.md