Construct

Construct turns a description of a real or fictional thing — an object, a building, a machine, a creature — into an animated holographic construct (WebGL). You write a short declarative scene (facts with their certainty, and parts built from a closed set of shapes) or fill an archetype's few parameters; the bundled tools validate it, audit it, compile it deterministically and render it in one holographic style. You never write graphics code and never choose colours.

Inspired by the truth-first construction method of anatomy (true numbers first, a parts list before geometry, an audit run to zero, every rendered image read). Construct shares that method, not code, and adds 3-D animation, certainty as material and a repair loop.

When to Use

• The user asks for a construct or a hologram — a holographic or wireframe light model, or an animated 3-D presentation of a thing: "make a construct of my CD", "a hologram of this lighthouse", "show this guitar as a construct", "a fictional creature for my game".
• A collection entry needs a consistent animated figure: CDs and their cases, books, guitars, synths, bottles, cans, glasses and cars have ready archetypes.
• The user wants a video of a construct assembling across a piece of music ("make a construct of X that assembles across this track"): film mode, step 7 below.
• The user wants a 3D model of the thing for Blender, a game engine or the web (glTF, GLB, OBJ): author the construct, then export it, step 8 below.
• The user wants to 3D print it (STL, 3MF): author the construct, then print it, step 8 below.
• The user wants a model kit to print, glue and paint, or a FreeCAD or STEP file: author the construct, refine its solid, then step 8 below.

Do not use it for photoreal renders, rigged characters, machining-grade engineering, charts, or for finding or recreating real cover art (artwork is shown only from images the user supplies).

Prerequisites

• Python 3.10+ (standard library only). Nothing is installed or downloaded.
• Optional: the web and vision toolsets, for researching a named subject and looking at references and captures. Any model that can see images works (tested: DeepSeek V4.1 Flash, GPT-6.1 Sol). Without them, the construct is built from general knowledge and labelled so.
• For review stills and video: a Chromium-family browser already on the machine (Chrome, Chromium, Edge, Brave, or HOLOGRAM_CHROME=/path) and ffmpeg. Without them you can still check and build; say that captures were not made.

How to Run

All commands use terminal and run the bundled CLI by its absolute path:

python3 ${HERMES_SKILL_DIR}/scripts/cli.py params --list
python3 ${HERMES_SKILL_DIR}/scripts/cli.py params book --variant paperback --output book.json
python3 ${HERMES_SKILL_DIR}/scripts/cli.py check book.json --json
python3 ${HERMES_SKILL_DIR}/scripts/cli.py build book.json --out out
python3 ${HERMES_SKILL_DIR}/scripts/cli.py review book.json --out out
python3 ${HERMES_SKILL_DIR}/scripts/cli.py video book.json --out out/book.mp4 --seconds 12

Work in a folder of your own. out/construct.html opens in any browser.

Quick Reference

Procedure

1. Mode and research. Four modes (references/effort.md); the user can just say one:

   • fast: one pass with self-review, no rounds loop: at most 10 minutes, 2 review rounds, 5 searches, 3 sources, 3 reference images (30 minutes and 4 reviews for a richer subject). Generic subjects, simple objects, quick asks; DeepSeek V4.1 Flash is fine here.
   • masterpiece: judged rounds (below), stopping 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 and no time ceiling: many rounds and hours at a high token cost, stoppable after any round. Only when the user asks for it by name.

   Quick, standard and showcase still work and mean 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. Fast for generic subjects, simple mechanical objects and quick asks; masterpiece for a specific named subject whose likeness matters (a car model, a landmark, a named building); never unbounded. On a smaller or cheaper model with a hard named subject, 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 here. A generic subject ("a desk lamp") needs no research. For a concrete, named one (a brand and model, a named building or peak, a species) research first whenever you are unsure of its shape or specs: the maker's or official pages, specs and reference photos, looked at with vision_analyze and measured. "research: on/off" in the request overrides this. Draft early. Research takes at most 40% of the time; by then a complete scene that passes check is saved in your folder. Improve that file in place, checking and saving after every round. At the run budget's wrap-up notice (80%), stop adding: make the saved scene valid, build it and deliver.

2. Facts. Write down what the user said or gave you and what your sources say. Each fact gets a certainty: verified (cites a source), user_supplied, inferred (your estimate or a traced measurement, with a short note) or decorative. Without a cited source nothing is verified. Leave unknown facts out entirely — never null, "unknown" or a guess. A generic reconstruction is subject.accuracy: "generic"; 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). Read references/provenance.md if artwork or sources are involved.
3. Pick the path. If an archetype fits (params --list), fill its parameter document: copy the facts, leave params empty unless the user gave sizes. Otherwise start from new <category> or an example and read references/composition.md and references/vocabulary.md: name the silhouette and the two or three identity features, build masses first, then structure, identity and a little detail. Draw with 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 example scenes beside assets/examples/castle.json show all five. When the identity is a shape text cannot give (a guitar body, a car, an elevation) and you can see images, trace it from a reference (references/tracing.md: the user's photo or a web image viewed with vision_analyze), then scripts/cli.py trace fits it to a verified dimension. Traced shapes are inferred, cited to the image. A real place or peak comes from elevation data the user supplies: scripts/cli.py terrain, and Earth from coastline data (GeoJSON): scripts/cli.py globe (references/terrain.md).
4. Check until clean. Run check --json. While needs_repair is true, fix every diagnostic at its JSON path using its hint, and check again. Fix every detached, thin-support, tips and thin warning: they are what a viewer notices first.
5. Review as an art director. Run review, then open out/review/hero.png, sheet-views.png, sheet-assembly.png and (if it opens) view-open.png with vision_analyze. Score them with the rubric in references/review.md (silhouette, proportions, identity, depth, composition, assembly, motion, density, honesty). The aim is genuinely good — something you would put in a launch video — not merely recognisable: improve the weakest point, check, review again. Your own review records self-reviewed; for a named subject run the independent critic: scripts/cli.py critique scene.json --reference side=photo.jpg, then delegate critique/packet.md to a fresh subagent (or add --base-url --model --key-env for a second model call) and record its answer with --record (references/review.md). Before each review add one to authoring.review_rounds and save; check warns tier-rounds past the cap. Stop when every criterion is good, or when the tier's review rounds or time run out, whichever comes first. Masterpiece and unbounded run judged rounds (references/rounds.md): scripts/cli.py rounds start scene.json --mode masterpiece (or unbounded). Each round, work on at most 4 ledger items and tag each edit (rounds change D3 "..."). Then rounds packet --request "the user's words" --reference ... (without --request the critic gets no request), with ONE delegated critic a round (or rounds run --base-url ...), and rounds record answer.json. A version is kept only when it beats the best so far, and its regressions lead the next round. After every round, report its summary in chat. Stop when record says STOP: two rounds without a win, every criterion at 3, or, in masterpiece, 12 rounds or 2 hours of active work. After an interruption run rounds status and redo only the step it names.
6. Deliver. Record authoring in the scene (tier, research, sources used, outcome, next improvements). Give the user out/construct.html (and the video if asked), and say plainly what is evidence, what is inferred or designed, which artwork is the user's own and which is generated decoration, and — if a limit stopped you — what the next improvement would be. Never call a generic reconstruction exact.
7. Film mode (only when asked). For a construct that assembles across a piece of music, author the construct as above (keep its own assembly at most 20 s), then: scripts/cli.py audio track.wav --out audio.json (add --voice vocals.wav for a vocal stem) and scripts/cli.py video scene.json --out film.mp4 --assembly <track seconds - 1.25> --audio audio.json --sound track.wav --camera steady --size 1920x1080 --fps 24 (the 1.25 s is the ceremony opening; use the full length for another assembly style). --camera steady keeps the whole construct in view; tour plays the scene's own camera flights. Leave --reactivity at its default unless the user asks for a calmer (0.5) or stronger (1.5) film. It renders about a frame or two a second, so say how long it will take before starting. Review it by sampling frames (ffmpeg -i film.mp4 -vf fps=1/10 frame-%02d.png) and look at them with vision_analyze: the build should visibly move with the music and end whole.
8. A 3D model (only when asked). scripts/cli.py export scene.json --out model.glb writes 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. --out model.obj writes OBJ and its .mtl. --merge --wire seams makes a game-ready prop (static parts merged, design lines as dark seams), --wire tubes keeps all the line art as geometry, --pose open rests it open, and --materials map.json colours and finishes parts by id (paint, brushed, chrome, wood, rubber, plastic, glass, light) when the user wants a finished model; keep it beside the scene, never in it. A no-surface audit warning names a part that would be missing: give it a solid shape. Say what it is: correctly sized named parts with working joints, without textures; a blockout or prop, not a hero asset. A 3D print (only when asked): scripts/cli.py print scene.json --out model.3mf (or .stl) writes one watertight solid on the bed, 100 mm long (--size, or --scale 43 for 1:43); report its size, scale and notes (supports, thickened parts, line-only parts left out: --lines raises them). Exit status 1 means not watertight: never hand that over as printable. --printers says how large it prints on five printer classes; --printer desktop --fit prints at the largest that fits; --exact keeps the construct's own solids. For an engine's physics: --pieces glued makes what stays put one body and each door or lid one more on its hinge (--colliders: a box per part; --pieces alone: pieces that break apart). FreeCAD: true CAD shapes where a part allows (boxes, lathes, splines, NURBS lofts), faceted otherwise; it reports how many. A model kit (only when asked). Refine the solid first: check scene.json --fit names parts that poke through or hide (a kit cannot glue what does not touch). Then scripts/cli.py kit scene.json --size 200 --printer desktop --materials map.json --out kit/ (--size is the built model's longest side in mm; --scale 24 suits cars, not buildings): numbered plates (3MF), booklet.html, the steps in 3D (assembly.html), each piece on its own (kit/pieces/; --only 12,14 reprints a few). Without --materials the paints are named by role; a map gives real paint names. Exit status 1 means the kit is written but its check has notes (pieces too thin, gaps, pieces that touch nothing): read them and fix the construct, or a kit-ready copy of it: a window of many panes as one clear sheet behind its frame; what a factory casts in one piece merged by a plan (--plan kit-plan.json, {"merge": [["side-west-*"]]}). Say what the kit is: made and checked by software, not yet built by a person; print one piece first.
9. A NetLogo model (only when asked). scripts/cli.py netlogo-instrument Model.nlogox --title "Model" --out run/ (with --turtles, --reporters "a;b", --patches pcolor:4, --seed, --ticks) makes the model record itself; after the user runs it, scripts/cli.py netlogo run/run.jsonl --view space-time|network-time|phase|field --out scene.json computes the construct from the run, no authoring needed. Credit the model as its Info tab asks. For art direction (only when asked), never edit the data: write an art.json layer (credit with your exact model name, title, summary, looks by data part id, its own parts, facts and annotations with source art, presentation) and redraw with --art art.json; compute milestones from run.jsonl with a script. The scene's data_lock fact makes check refuse any data change.

Pitfalls

• Inventing facts. A year, an author, a label or a size the user did not give must not appear. The checker refuses placeholders such as "unknown" or "n/a".
• Choosing colours or materials. There are no colour fields; the renderer owns the look. Words like "glowing" become facts or roles (a light is role data).
• Parts that only seem to touch. A shade at the end of a diagonal arm, a handle above a lantern: the detached check names the nearest part; move the part onto it. A pole that stops short of the motor it carries is unsupported (an error) when only the boxes meet, thin-support when a strut bridges the gap. 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.
• Parts that would fall over. A board standing on one rail along its bottom edge and leaning back with nothing behind it is tips: give it a second hold on the side it leans to.
• Hairline structure. A thin arm or leg barely renders: thin gives the minimum radius.
• Real artwork. Show a cover only from bytes the user supplied, declared with its SHA-256 and rights. Never download covers or recreate one from memory.
• Running unbounded, or writing at the end. The tier's limits are ceilings; Hermes's own run budget applies on top. A scene held only in context is lost when the budget ends: save a valid draft by 40% and keep it valid. When a limit is reached, deliver the saved version with its next notes.
• A masterpiece critic that stops after two rounds. In a one-shot run (hermes chat -q), Hermes lets a session start only two helper agents by default (delegation.oneshot_max_children), and the critic is a fresh helper each round. Tell the user to raise it in config.yaml (14 covers a masterpiece run; 0 means no limit), to run interactively, or use a second model as the critic (rounds run --base-url ... --model ... --key-env ...).
• Ending the rounds before the loop does. A one-shot session can run out before the masterpiece loop's stop rules (the critic's all-3, two rounds in a row without a win, 12 rounds, 2 active hours). Then rounds pause and tell the user the run can be resumed (rounds status); do not record the outcome as limit, which means a stop rule ended it.
• Messages that are too large. A message larger than about 8 MB stops the run. Do not attach several full-size review stills at once: ask for smaller ones (review --size 1280x800) and only the sheets you need (--sheets assembly,views). The saved scene survives the stop.
• Captures without a browser. If no Chromium-family browser exists, deliver the HTML and say the review stills were not made; do not install one.

Verification

• check reports audit: PASS and needs_repair is false.
• out/construct.html exists; out/review/hero.png shows the requested thing, recognisably.
• Facts in the scene match the user's words and the cited sources; nothing unknown is filled in.
• authoring records the tier, whether research was done, the outcome and what comes next.
• For a quick self-test: python3 ${HERMES_SKILL_DIR}/scripts/cli.py check ${HERMES_SKILL_DIR}/assets/examples/cd.json must report audit: PASS (0 errors, 0 warnings).