Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
docs: rewrite the README around the fifty, and say how to install the plugin
Matt Kissinger81de3f7e6c56
diff --git a/AGENTS.md b/AGENTS.mdindex cb236ccd..fc59a555 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -15,7 +15,7 @@ Read [README.md](./README.md) before changing exports or package contents. Runti`src/tools/registry.ts` owns tool names, descriptions, and schemas. Two skins consume it: thein-process Strands tools (`src/agent/tools.ts`) and the stdio MCP server. **Both must iterate the-registry** — never hand-write a tool definition in a skin, or the transports drift apart and the+registry** -- never hand-write a tool definition in a skin, or the transports drift apart and therepo's central claim stops being true. There is a test that asserts name parity; keep it passing.Prefer an explicit terminal submit tool over `structuredOutputSchema` in the in-process loop: the@@ -32,7 +32,7 @@ deterministic engine paths.The port is injected twice, for different jobs, and their deadlines must stay separate. A host callsit once after the loop for the artifact sheet, where nothing is blocked and a long deadline iscorrect. `KilnToolContext.viewRenderPort` injects it into `kiln_render` for the IN-LOOP grid, where a-slow render blocks the agent mid-thought — that deadline is its own per-call argument and belongs far+slow render blocks the agent mid-thought -- that deadline is its own per-call argument and belongs farlower. Never collapse the two onto one value.Routing is conditional on `sceneNeedsPbrShading(root)`: bound texture or `metalness > 0`, never@@ -40,7 +40,7 @@ material type, because `gameMaterial` and `pbrMaterial` both construct a `MeshStare indistinguishable after construction. Host telemetry rides `onViewsRendered`, while every unified`kiln_render` result also carries model-visible `ViewFidelityV1`; a geometry-flat CPU image must neverbe treated as material evidence. Keep the input schema stable unless the active change explicitly-versions it — the tool definition is cached, and changing it invalidates that cache.+versions it -- the tool definition is cached, and changing it invalidates that cache.**The GPU is a view producer only, never gate evidence.** `QaContext` is deliberately image-free so aQA rule structurally cannot read a render buffer. Do not add pixels to it.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8406622b..220f0351 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,40 +6,475 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.## [Unreleased]### Added+- **A specimen gallery in `site/`, built by running the programs rather than by+ committing meshes.** The README's stills are a weak claim about geometry -- a lit+ render hides topology, and a reader has no way to tell a dense mesh from a clean one.+ The gallery loads all fifty as real GLBs with orbit controls, a wireframe toggle and+ the triangle count, draw calls, material count and bounds off the engine's own+ integration manifest. Nothing in it is checked in: `site/scripts/build-assets.mjs`+ runs each `examples/*.kiln.js` through the same evaluator the test suite uses and+ keeps what comes back, so a program and the mesh on the page cannot drift, and a+ program that stops building fails the deploy. Attribution on each card comes from the+ program's own header through `scripts/authorship.ts` -- extracted from the authorship+ test so that the README and the gallery read the headers with one parser instead of+ two that will eventually disagree. React and three live in `site/` and nowhere else;+ the engine still has no browser dependency. `.github/workflows/pages.yml` deploys it.+- **A fifth skill, `kiln-batch-dispatch`, for the person pointing agents at the problem+ rather than the agent building the asset.** The other four are read by whoever is+ holding the geometry; this one covers wiring a harness up, proving the tools are+ actually reachable before trusting a single result, and running the clean-room+ dispatcher across models and subjects until you have a library. It exists because+ the two halves fail as one: a batch launched on unproven wiring produces a pile of+ empty sandboxes, and no way to tell whether the models were weak or the tools were+ never there. It also writes down the two limits that cost the most time here -- a+ harness's default output cap silently truncating a model mid-file, and a run cut off+ at its deadline still being a success if a usable program is on disk.+- **`--category` on the dispatcher, with six experimental values and one honest+ default.** Every asset ever dispatched from this repository came back+ `category: 'prop'`, because the brief said so in a string literal. The problem was+ never that they were props -- most of them are, correctly, and almost anything can be+ built as one -- but that the field carried no information, so a library could not be+ sorted by it and the engine's per-category guidance was unreachable. The flag takes+ any of the seven contract values and rejects anything else in the first second rather+ than filing an asset under nothing. `prop` stays the default and its brief is+ deliberately empty, which makes it the least constrained thing the dispatcher can+ send. The other six append a short note on what tends to go wrong for that kind of+ subject, and they are a bet rather than a taxonomy: worth reaching for when the+ subject really is a building or a plant, worth dropping first when a run comes back+ worse than the same brief as a prop. `src/__tests__/dispatch-categories.test.ts` fails+ if the list the script carries ever drifts from `ASSET_CATEGORIES`.+- **Hermes as a fifth harness, which is the first real evidence that any of this is+ portable.** The other four are JavaScript CLIs that broadly agree on what a plugin+ is; Hermes is a Python agent with its own YAML config, its own skill store and its+ own provider routing, sharing no code and no convention with them. It takes the+ same `dist/mcp-server.mjs` and the same `skills/` directory unchanged: `hermes mcp+ add` connects on the spot and enumerates all seven tools, and+ `hermes config set skills.external_dirs` registers every shipped skill as `local`. It+ does not read `.claude/skills` out of the working directory the way the others do,+ and that config key is the whole difference. Smoke-tested green at 97s on a free+ model. `-z` is the headless mode the dispatcher drives, and since it has no+ working-directory flag the sandbox is simply the CWD it is spawned in -- which is+ also where it reads `AGENTS.md`, so the clean room holds without extra work.+- **`bun run smoke:harness`, which proves a harness can reach the tools.** Every+ wiring failure in this project has been silent: `agy plugin validate` reports the+ MCP server as processed while `agy mcp list` shows none, and a harness that can+ see the tools but will not grant them answers exactly like one that never had+ them -- which is also what a model too weak for the job looks like. Three+ indistinguishable failures with one symptom is a thing worth being able to test,+ so this sends a short brief into a throwaway directory -- call+ `kiln_list_primitives`, write a four-line program, validate it -- and then builds+ what came back with the engine, because the child's own report of success is the+ only evidence that proves nothing. Measured on one machine: Claude Code 13s,+ OpenCode 37s, Antigravity 105s, each green. Codex reached the model and stopped+ at its account's own usage limit, which is the diagnosis the script exists to+ make -- the wiring is fine and the provider is out. Codex has since been smoked+ green as well, at 37s, once the flag below let it call a tool at all.+- **A fourth vendor in the gallery, and a wider spread of subject.** This step took+ the heroes to twenty-seven, and the additions were chosen for the range they prove+ rather than for how they look: a supercarrier, a phased-array air-defence radar,+ a fighter with a lofted aerofoil and a geostationary comms satellite, which are+ the subjects where a program has to compute its shape rather than place it, and a+ Dutch tower windmill written by DeepSeek V4 Flash -- the first asset here from a+ fourth vendor's model, dispatched clean-room through OpenCode like the Muse Spark+ ones. The anglerfish was rebuilt: the first was a smooth dark cone with a jaw+ drawn on it, and organic form is the case this tool is worst at, so it is the one+ worth showing honestly. Eleven of those twenty-seven were not written by Claude.+- **Tangents for non-indexed geometry.** `computeTangentBasis` required an index+ buffer and warned, per mesh, when there was not one -- so a normal map on any+ flat-shaded part, anything merged from several geometries, and anything through+ `.toNonIndexed()` shipped with no TANGENT attribute and a note saying each runtime+ would guess its own. That is most of what a hand-built asset is made of. A+ triangle soup is an index buffer that reads 0, 1, 2, ..., so the same accumulation+ is exactly right for it and every vertex comes out holding its own face's tangent;+ a test unwelds a box and checks the soup and the indexed copy agree per vertex.+ `examples/anglerfish.kiln.js` had twelve of those warnings and now has none.+- **A measured ceiling on the always-on context cost.** `src/__tests__/mcp-payload.test.ts`+ now derives the JSON Schema for all seven tools and sums the front matter of every+ shipped skill, holds each under a budget, and requires the README to quote the real+ figures. The README argued the surface was small with numbers nothing was checking.+- **`kiln_edit`, the refine verb, and the `kiln-refine-asset` skill that drives it.**+ Every MCP tool took a whole program and rendered it, so changing one line of a+ finished asset meant re-emitting the entire file and trusting that the other two+ hundred lines came back unchanged. `kiln_edit` takes exact-string replacements+ instead: they apply in order, a match that is not unique is refused rather than+ guessed at, and if any edit fails **nothing** is applied -- so a bad edit costs a+ retry rather than a program in a state the model never asked for. It returns the+ patched source, a unified diff, and the six-view sheet together, because the loop+ is edit-then-look. It is deliberately stateless: the in-process agent keeps a+ working buffer across turns, but over MCP the host holds the program text, and a+ second copy inside the server would have been a desync the model cannot see. The+ buffer itself moved to `src/edit-buffer.ts` so both transports share one+ implementation -- importing it from `agent/tools.ts` would have pulled+ `@strands-agents/sdk` into `kiln/tools` and into the MCP bundle, which is the one+ edge that subpath is documented not to have. Like the unified `kiln_render`, the+ def sits outside `createKilnToolRegistry`, whose four tools are a frozen bench+ baseline.+- **The scanned texture library doubled, from eight CC0 families to sixteen.** The+ first eight were all rough exterior surfaces, which left three material recipes --+ `skin`, `leaf`, and `rubber` -- with nothing photographic to bind at all, and made+ rust the only metal in the package. Added: brown leather, forest leaf litter,+ rubber tiles, riveted steel plate, clay roof tiles, cobblestone paving, finished+ oak veneer, and polished marble. 48 maps, 747,977 embedded bytes, still inside the+ 1 MiB package budget the test enforces.+- **OpenCode support, and clean-room dispatch.** `scripts/dispatch-asset.mjs` gained an+ `opencode` harness, reaching a dozen vendors' models behind `provider/model` ids.+ More importantly, every dispatch now runs in its own directory containing only the+ brief and the Kiln skills. Dispatches previously ran with the harness pointed+ at this repository, where a child agent could read thirteen finished example+ programs -- which quietly invalidated the claim those runs were evidence for. The+ write grant is scoped to the sandbox, and the authoring model is stamped into the+ program it wrote. `examples/gramophone.kiln.js` is the first asset in the gallery+ actually built that way -- authored through OpenCode by+ `muse-spark-1.3-contributor`, a third vendor's model, in a directory holding+ nothing but the brief and the skills. Every other example predates the sandbox and+ is attributed without the clean-room claim.+- **Animated GIFs of the animated examples, via `scripts/anim-gifs.ts`.** The+ render port fits its camera to the bounding box it is handed, which is right for+ a still and wrong for a sequence -- a robot arm's posed extent varies 63% across+ its cycle, so the asset would appear to breathe as the camera refit itself each+ frame. Because the projection is orthographic and the port's fit is exact, each+ frame is put back onto one shared camera afterwards by a scale and a translation+ that are both computable, so the result is a fixed camera rather than an+ approximation of one.+- **`scripts/check-vision.mjs`, a preflight that refuses to dispatch a blind model.**+ Kiln's loop is the model looking at its own render, so image input is the one+ capability that is not optional -- and a text-only model does not fail, it just+ builds worse assets from the documentation alone. A nine-model batch here was+ found to contain four text-only models, picked by name on the assumption that a+ current flagship accepts images. Vision also varies between a vendor's own+ variants: `glm-5.3-flash` sees images and `glm-5.3` does not. The check reads+ OpenCode's cached model metadata, costs about two seconds for any number of+ models, and exits non-zero naming the offenders.- **Browser-safe GLB integration manifest.** Every `renderGLB` / `renderSceneToGLB`result now carries `kiln.integration-manifest.v1`: artifact SHA-256, metre/+Y-upcoordinate semantics, world bounds, ground offset, role, render metrics, andstructural-validator counts. `inspectGlbIntegration(bytes)` derives the samecontract from finished bytes without executing model-authored source.+- **Four assets from a sixth model, through a sixth harness.** GPT-6 Astra wrote an+ orbital station, a rigid airship at its mooring mast, a blast furnace and a Gothic+ clock tower, dispatched through Codex into the usual clean room. They are the first+ batch in this repository where every program cleared the zero-structural-warning bar+ the shipped examples are held to on the first pass, with no hand repair and no+ promotion-time fix, at 10,212 / 11,764 / 11,964 / 11,664 triangles. The gallery is+ now fifty programs, thirty-five of them written by something other than Claude.### Fixed+- **The Codex harness could not call a single tool, and said so only in the child's+ transcript.** `codex exec` pins its approval policy to `never`, and a `never` policy+ does not queue an MCP call for later approval, it refuses it outright -- so four+ dispatches came back inside a minute each having written nothing but a note that+ `kiln_list_primitives` was blocked. The dispatcher passed `--sandbox+ workspace-write`, which grants the filesystem and says nothing about tools;+ `--approve-for-me` is the flag that does both, selecting the same sandbox and moving+ approval to automatic review, and the two are mutually exclusive on the command line+ for exactly that reason. Worth noting alongside it: `codex plugin add` installs this+ repository's manifest happily and registers neither its MCP servers nor its skills,+ so the TOML server block is still required -- the same trap `agy` sets, failing the+ same silent way. Both are now documented per-harness in `docs/install.md`.+- **`cylinderUnwrap` now unwraps cylindrically, which it has always claimed to do.**+ It and `boxUnwrap` were the same function: both preserved existing UVs and both fell+ back to the same flat projection, so on the one case the file's own header describes+ -- a curved surface carrying a directional texture -- brick came out as horizontal+ smears. Built-in `cylinderGeo` never hit it because Three.js ships UVs with it;+ anything swept or extruded did, and a texture-backed material on unwrapped geometry+ is a QA blocker rather than a silent miss. It now runs u around the Y axis and v up+ the height, normalized across the geometry's own angular span so a 22 degree curb+ stone gets the whole texture rather than six percent of its width, with caps+ projected flat so they do not sample a single row of texels.+- **The well, which was a ring of boxes pretending to be masonry.** A box has parallel+ sides, so on a circle its neighbours meet it at an angle and the joint opens into a V+ that widens toward the outside face -- 40 mm of it at the outer radius, sixteen times+ around, which read as a cog wheel with a dark slot at every tooth. The curb is now cut+ the way a mason would cut it: wedge stones whose side faces lie on radial planes,+ inner and outer faces following the curve, in two courses offset by half a step so no+ joint runs the full height. The shaft is lined with an extruded ring rather than a+ solid cylinder, since the hole is the point of a well, and there is water at the+ bottom of it. The roof posts are bedded rather than balanced: a square post stopped on+ a round wall always reads as overhanging it, because from any angle where the wall+ curves away it does, so each post now runs past both courses to the plinth and the+ three stones on its line are cut around it with `boolDiff`. Only those stones lose+ their instancing -- an angular overlap test picks them out, one per post in the+ un-skewed course and two in the skewed one where the post straddles a joint.+- **The pinball machine's backbox, which stood on nothing.** It was built entirely+ behind the cabinet's rear face, cantilevered off a 30 mm wall. Sliding it forward onto+ the cabinet only traded one fault for another: the playfield runs the cabinet's full+ length, so everything the head gained in support it took out of the glass, and at+ 380 mm deep it buried the bumpers. The fix was the one a real machine already uses --+ the cabinet grew the rear bay the head bolts to. It is 1.34 m long instead of 1.14, its+ rear face and back legs moved with it, the backbox is 200 mm deep rather than 380, and+ the head now sits on that bay entirely behind the glass. The file's header records the+ repair, because the gallery makes a claim about who wrote each program and a claim+ quietly edited afterwards is worse than no claim.+- **The vending machine's sold-out column, which read as a hole in the model.** One+ unlit column was meant to be the asymmetry that stops a 4 x 3 grid looking like a+ texture. It is, but everything in that column -- the dimmed panel, the bezel shelves,+ the rails -- is near-black, so instead of an empty rack behind a switched-off light it+ came out as a solid black rectangle with no shape in it, next to three lit columns. All+ four columns are stocked now, with an amber PET added as the fourth product, and the+ asymmetry that survives is the one that was always doing the work: cans in one column,+ bottles in the other three.+- **The vending machine's bin label, which was a flat plate on a round drum.** A 240 mm+ slab across a 390 mm bin touches it along one line: the middle sinks in and both ends+ stand 40 mm proud, which from the front reads as a white wing growing out of the side.+ It is now an annular sector swept up through the label's height -- the same wedge the+ well's curb stones are cut from -- sitting 6 mm proud all the way round.+- **`createPart` now rejects a wrong call instead of dying in the exporter.** The+ harness smoke run found this the way it was always going to be found: a free model+ on Hermes wrote `createPart(root, { name, geo, material })` -- the shape most other+ scene APIs take -- and the run failed 185 seconds later with `undefined is not an+ object (evaluating 'Object.keys(morphAttributes)')`. Nothing in that sentence names+ anything the model wrote, so it had no way back and spent its remaining turns+ guessing. `new THREE.Mesh()` accepts any two arguments at all, which is what let a+ function reference and a plain object travel that far. The three positional+ arguments are now checked at the door, and each message says which argument, what+ arrived, and what the call looks like when it is right: a parent passed first is+ told the parent belongs in the options object, `boxGeo` without parentheses is told+ geometry helpers have to be called, an un-awaited `roundedBoxGeo` is told the helper+ is async and `build()` has to be too, and a hex number where a material belongs is+ told to wrap it. The same program now fails in under a second with a sentence a+ model can act on.+- **Three hero assets whose geometry was wrong in ways a contact sheet hides.** The+ ferris wheel braced its two A-frames together at mid-height, and the upper tie sat+ 1.93 m from the hub inside a 3.60 m rim -- a girder straight through the spokes and+ the cars. It is now a clearance rule rather than a pair of chosen heights: candidate+ bracing levels are filtered against the wheel's swept envelope, rim radius plus how+ far a car hangs below its pin, and only the low portal survives, which is exactly+ where a real double-A-frame wheel is braced. The vending machine's cans were albedo+ `0x4a2f0c` at metalness 0.78; a metal has no diffuse term, so its whole appearance+ is a specular reflection tinted by its albedo, and a near-black albedo under a+ neutral studio dome returns almost nothing -- the cans rendered as black rectangles+ and their column read as empty stock. A printed can is a coating over the metal, so+ it is dielectric like the bottles, and only the bare lid is aluminium. And the+ lighthouse's keeper's cottage stood a plain rectangular slab on each end wall as a+ gable, leaving 0.91 m of stone above the slate at both eaves; the gables are now+ pentagons derived from the roof pitch through `extrudeProfile`, tucked 20 mm under+ the roof underside so the two cannot fight for the same pixel.+- **An external 32,000-token ceiling was ending dispatched runs mid-thought.**+ OpenCode caps one assistant step at 32,000 output tokens by default, whatever the+ model publishes. It is not a number this project set, and it took reading its+ session store to see: across every step ever recorded there, nothing had exceeded+ 32,000 -- not once, not by a token -- while the models involved declare between+ 80,000 and 943,718. Runs stopped there mid-sentence, with no file and no error,+ looking exactly like a model that was not up to the work. Dispatch now sets+ `OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX` per run from the model's own declared+ limit, read out of OpenCode's model catalog, so the ceiling is the provider's and+ never one invented here. `docs/install.md` says how to do the same by hand.+- **Removed every default cap on how much work an agent may do.** The generation+ budget defaulted to 40 model calls, `--max-steps` to 24, and whole-program+ rewrites after a first successful render to 2. All three were cost guards from a+ hosted product where the operator paid for the calls. Out here the person running+ the tool is the person paying for it, and a ceiling they did not choose stops an+ asset halfway for reasons that have nothing to do with the asset. All three now+ default to no limit -- zero was already this codebase's "unlimited" value,+ honoured by the call budget, the step hook and the grade-refine headroom check,+ so this is a default change rather than new machinery. `--max-steps` also accepts+ `0` now instead of rejecting the value its own help text recommends, and the+ rewrite bound became a per-host option so a caller who wants it can still ask.+ The sandbox byte limits, the procedural texture bounds and the render deadlines+ stay: those are safety and correctness, not cost.+- **Nothing told a model to write the file before it had solved the asset.** The+ skill's loop said "write the program" at step two and "write the *final* program+ to a file" at step six, which invites a model to keep the whole thing in its head+ until it is finished. Some do, and never arrive: measured through OpenCode's+ session store, four separate runs spent their entire output allowance -- to the+ token -- on one unbroken reasoning block, hand-solving pin positions and cylinder+ attachment points in prose until they were cut off mid-number, having written+ nothing at all. Three different vendors' models failed this way. The loop now+ says to save a rough version early, says plainly not to solve the geometry+ analytically first, and names the failure so a model can recognise it. The+ dispatch brief says the same.+- **Attribution rested on the request rather than on what ran.** The dispatcher+ stamped the model it had *asked* for, which is the one claim the gallery exists+ to make and the one thing it was not checking. It now reads the model back out+ of the harness's own output and records that, reporting the difference if the+ two ever disagree. No harness has been caught substituting a model -- every one+ of the six OpenCode runs already promoted agrees with its log -- so this closes+ a gap rather than a leak, and makes "nothing in the gallery is misattributed" a+ statement backed by a check instead of an assumption.+- **Codex could never have authored an asset.** Three faults in its entry in the+ dispatch table, each of which fired before the model saw the brief, which is why+ nothing in the gallery came from it and why nothing said so. `--full-auto` is+ deprecated in favour of an explicit `--sandbox`. A clean room is a bare temp+ directory, and Codex refuses to start in one as "not inside a trusted directory"+ unless the git check is waived. And the sandbox was never passed at all: with no+ `--cd` the child ran in this repository, with every finished example in reach --+ the exact contamination the sandbox exists to prevent, in the one harness whose+ results would have been quietly worthless rather than merely absent. Its default+ model is now unset rather than `gpt-5.1-codex`, which that account is not entitled+ to and which no repository can guess; dispatch demands `--model` instead of+ stamping an author it cannot name.+- **The dispatcher's usage line omitted OpenCode**, which had written six of the+ twenty-seven programs in the gallery at the time. It is generated from the harness+ table now, so it cannot drift from the list it describes again.+- **A busy GPU renderer was read as an absent one.** `--render auto` probed+ `/health` with a 1.5 second budget and treated anything that was not a clean+ answer as "no service here". The render service is single-threaded, so while it+ is drawing somebody else's frame it accepts the socket and answers late, and a+ batch of agents pointed at one GPU had runs silently drop to the CPU rasterizer+ and judge their materials off a sheet where every textured surface is flat white.+ Nothing logged a fault, because from the caller's side nothing had failed. The+ probe now distinguishes the two: a refused connection still falls through at once,+ which is the point of the short budget on machines with no renderer at all, but a+ timeout is retried against an 8 second one. `src/__tests__/cli-render-mode.test.ts`+ holds a stand-in service to both cases and to the closed port.+- **Material constructors accepted an options object as their colour.**+ `gameMaterial(color, options?)` takes the colour first, and a program that wrote+ `gameMaterial({ color, roughness, metalness })` got a white material at default+ roughness rather than an error: `THREE.Color.set` ignores an object it does not+ recognise, so the mistake survives all the way to the render, where it looks like+ a lighting problem. It cost a real asset an afternoon. All four constructors now+ refuse a non-colour first argument and say where the settings go.+- **A dispatched program that outlived its own run lost its author.**+ `scripts/dispatch-asset.mjs` recorded the authoring model only on a clean exit,+ so a run that wrote a finished program and then hit a wall was scored as having+ produced nothing: the file was still promoted, and stamped `Authored by: null`.+ Which is worse than an honest partial claim, because it is not a claim at all.+ Three assets in this gallery were written that way. The check is now "is there a+ program on disk", asked before the failure is classified rather than inside one+ branch of it, so it covers every way a run can be cut short instead of the one+ that was noticed first -- a provider limit, and the dispatcher's own 25 minute+ deadline, both of which fire long after the program is written. The+ interruption is carried into the manifest and stated plainly in the file header,+ because a run that was cut off cannot claim it looked at its own render and+ revised. Separately, the rate-limit matcher knew `RESOURCE_EXHAUSTED`, `429` and+ `quota` but not "session limit", which is Claude Code's wording, so a batch that+ hit one reported three flat failures and gave up instead of falling back or+ waiting the window out.+- **`examples/aircraft-carrier.kiln.js` wore a comb of teeth around its counter.**+ The hull, the flight deck and the deck-edge netting were runs of axis-aligned+ slabs, each held at the half-beam or the deck width of its own centre. Wherever+ the ship is not parallel to its own keel -- the fine entry, the whole counter, the+ stern round-in where the starboard edge sweeps 21 m outboard in 23 -- every join+ left an end cap facing aft, and an end cap is lit as a different surface from the+ plating either side of it. Halving the station spacing only doubled the number of+ teeth, because the discontinuity was in the normals and not in the size of the+ step. All three are now lofted along their own planform curves, which share their+ vertices: no cap to catch the light, no step to refine, and 7,000 fewer triangles+ than the slabs cost.+- **Dispatched Claude runs stopped for permission with nobody to ask.**+ `--permission-mode acceptEdits` grants writes and nothing else, so a child that+ reached for `kiln_render` blocked on a prompt no terminal was attached to. Three of+ four runs in one batch returned after a minute having written no program, no error+ and exit 0 -- just a courteous note about which permissions they would need, which+ is the worst shape a failure can take on an unattended path. The sandbox now ships+ a `.claude/settings.json` allowing the Kiln MCP tools under either install name+ plus the file tools, scoped to the one throwaway directory rather than reaching for+ `--dangerously-skip-permissions`.+- **A dispatch deadline that could not actually end a run.** `--timeout` fired on+ schedule, wrote "timed out; killed" into the log, and then called `child.kill()`,+ which signals the direct child and nothing beneath it. On the path that matters+ that child is a shell: an npm-installed CLI on Windows is a `.cmd` shim, so the+ agent itself is a grandchild and survived. It went on holding the stdout pipe+ open, `close` never fired, and the job hung after having already been declared+ dead -- three jobs in one batch sat between 14 and 38 minutes past a 24-minute+ deadline, with a concurrency slot held by each. The deadline now kills the+ process tree (`taskkill /T` on Windows; elsewhere the child is spawned as its own+ process-group leader so the group takes the signal), and the promise settles on a+ 15-second grace timer whether or not `close` ever arrives, so a descendant that+ refuses to die costs one job rather than the batch.+- **Orthographic views now fit what they are looking at.** The GPU render service+ framed every view with `max(sizeX, sizeY, sizeZ) * 0.72` -- the longest axis+ whichever way the camera was pointed, padded by a constant -- so anything that was+ not a cube rendered small in a large frame, and a long object viewed down its own+ axis was framed for a length nobody could see. Views are now fitted per direction+ by projecting the bounding box's eight corners onto the camera basis, which is+ exact for an orthographic projection. This also makes `--render cpu` and+ `--render gpu` frame identically: the CPU rasterizer has always fitted this way,+ and the two disagreeing meant the documented side-by-side of the two modes was not+ comparing the same crop. `render-service/src/framing.mjs` is the whole of it, and+ it is GPU-free so it is covered by unit tests.+- **Unit-length normals out of `lathe()` and `revolveGeo()`.** `THREE.LatheGeometry`+ copies its running meridian normal into the previous-normal slot *before*+ normalising it, so the final ring of a revolve carried normals scaled by the length+ of the last profile segment -- enough to fail `GLTF_ACCESSOR_VECTOR3_NON_UNIT` on+ export. Both entry points now normalise before returning.+- **`kiln_list_primitives` no longer sends its catalog twice.** The result carried+ all 92 entries as a structured array *and* as the text rendered from that array,+ and the default MCP serialization pretty-printed both: 90,497 bytes for one call.+ Harnesses disagree about results that size. OpenCode truncates them, spills the+ full copy to a file, and hands the model a cut-off catalog -- a dispatched+ `glm-5.3` run spent twenty-two minutes grepping that spill file at increasing+ offsets and never wrote a program. `KilnToolDef` gained an optional `text()`+ extractor (the text analogue of the existing `media()`), so a def whose output+ already contains a rendered form of itself can send that instead of a JSON dump.+ In-process callers still get `primitives` from `run()`. Measured after: 36,647+ bytes, received in full, with the same model correctly enumerating all 92+ primitives. `src/__tests__/mcp-payload.test.ts` holds the ceiling.+- **Unit-length normals out of `subdivide()`.** `three-subdivide` builds each new+ vertex normal by summing the normals of the faces meeting there and never divides+ through, so a normal comes back at the length of however many faces touched it --+ 2/3 after one iteration on a box, 0.35 after two. No raster shows it, because a+ shader normalises before it lights, but the glTF validator rejects every one of+ them. Found by a dispatched agent whose printing-press bed was+ `subdivide(boxGeo(1.5, 0.6, 0.8), 2)`: 1,104 bad normals out of 1,152, and the+ build stopped at final-glb. Same repair as `lathe()`.+ `src/__tests__/subdivide-normals.test.ts` also asserts the raw upstream call is+ still broken, so the workaround can be removed the day that changes.- **Explicit default scenes on exported GLBs.** Generated and composed artifacts nowset the glTF default scene, and optimize/palette rewrites repair legacy files whosefirst scene existed without being selected. Consumers no longer have to guess whichscene to mount.+- **`kiln_screenshot_animation` no longer rejects every textured asset.** The tool+ poses the scene and exports it again to render one camera cell, and that export+ was being submitted to asset QA as though it were a new asset. It is not: those+ bytes came out of this engine and had already passed. But a texture that has been+ through a GLB round trip returns as a decoded image without the payload+ provenance `MAT_TEXTURE_DECODE_FAILED` looks for, so QA blocked the preview --+ meaning no textured asset could look at its own animation, including+ `examples/robot-arm.kiln.js`, which is the repository's designated animation+ example. `renderSceneToGLB` gained a `derivative` option that makes QA observe+ rather than block for exactly this re-serialization; reports still record their+ real disposition, and the option is far narrower than the process-wide+ `KILN_QA_MODE` escape hatch.+- **Dispatched agents no longer hang after finishing their work.** `scripts/dispatch-asset.mjs`+ spawned children with stdin as an open pipe. OpenCode keeps its process alive while stdin is open,+ so a run would author the asset, write the file, and then sit there until the dispatch timeout+ killed it and reported a failure. Children are now spawned with stdin closed; the same command+ that ran to a 75-second kill exits in six.+- **The dispatch sandbox is a real one.** It was created under `.dogfood/`, inside this repository,+ so a child agent's CLI resolved the project root by walking up to `.git` and found the whole repo,+ `examples/` included. It now lives in the OS temp directory.+- **The MCP server no longer needs Bun on the consumer's PATH.** Every published+ config said `"command": "bun"`, which asks the harness to resolve a name against+ its own environment. Bun's Windows installer appends to the *User* PATH, and a+ process only ever sees the environment it was born with, so any harness started+ before that install died with `exec: "bun": executable file not found in %PATH%`.+ There is no Bun-specific API on the server's runtime path, so it now ships as+ `dist/mcp-server.mjs`, a committed Node bundle -- committed because a plugin install+ is a git clone with no build step. Bun remains the development toolchain and is no+ longer something a user of the plugin needs.-## [0.6.0] — 2026-07-12+## [0.6.0] -- 2026-07-12### Added- **`measureGlbBounds(bytes)` (H-41).** World-space AABB straight from stored GLBbytes (WebIO + `getBounds`, EXT_mesh_gpu_instancing registered) so consumers that- only hold the artifact never need `executeKilnCode` to recover a footprint —+ only hold the artifact never need `executeKilnCode` to recover a footprint --Kiln Studio's compose catalog drops its execute-model-code bbox fallback on this.- **Six-grid rear-quarter variant (H-33 arm).** `SIX_VIEWS_REAR_QUARTER` swaps the3/4 cell to the opposite-rear azimuth (`[-0.7, 0.5, -0.7]`, labeled `3/4 Rear`);`resolveGridViews(variant)` + the `KILN_GRID_VARIANT=rear-quarter` env select it- as the `renderViewGrid` default per-process — no wire or tool-schema change.+ as the `renderViewGrid` default per-process -- no wire or tool-schema change.Explicit `opts.views` always wins; unknown env values fall back to `SIX_VIEWS`.- **Gemini thinking + budget knob (H-43/B1).** The `google` provider now forwards`KilnModelDescriptor.maxTokens` → `generationConfig.maxOutputTokens` and effortkeywords → `thinkingConfig.thinkingLevel` ('xhigh'/'max' collapse to 'high';numbers ignored; the KILN_THINKING env stays Anthropic-only). A bare descriptor- still sends nothing — Gemini API defaults (65,536 output, dynamic thinking) are+ still sends nothing -- Gemini API defaults (65,536 output, dynamic thinking) arepreserved unless a consumer opts in. NOTE for consumers: registry rows that- carried a decorative Google `maxTokens` now BIND — set them to the intended+ carried a decorative Google `maxTokens` now BIND -- set them to the intendedceiling before upgrading.### Changed+- **The texture library's signal floor is now two floors instead of one.** The+ package-weight test asserted every map's peak channel deviation cleared 2, which+ worked while all eight families were rough: it was really asking "is this real+ photography rather than a proof swatch". Extending the library to smooth materials+ broke it for the right reason -- a polished marble normal map and an oak veneer+ normal map are *supposed* to be near-flat, and one high floor would have quietly+ restricted the library to rough surfaces forever. Per map the assertion is now+ only that the image is not constant; the photography claim is enforced per family,+ where it belongs.- **OpenRouter reasoning clamp (A7).** `resolveOpenRouterReasoning(thinking,maxTokens?)` now bounds reasoning by the completion budget: numeric budgets capat 50% of `maxTokens` (dropped entirely when even the 1024 floor exceeds that@@ -49,7 +484,7 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.configurations are untouched.- **QA-blocked render errors are actionable (H-40(3)).** `AssetQaBlockedError`'smessage now spells out each blocker's human message + authored `repairText`- (first 6, then a count) instead of bare rule codes — this string is exactly what+ (first 6, then a count) instead of bare rule codes -- this string is exactly whatthe agent reads when a mid-loop `kiln_render` is QA-blocked, and what thesalvage path records for QA-blocked step-cap programs.@@ -57,56 +492,56 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.- **Per-render QA cost (H-40(4), `scripts/qa-cost-bench.ts`):** registry rules add1–10 ms p95 per render across all five category fixtures; Khronos validation(unconditional, both modes) adds 1–4 ms p95. Two orders of magnitude under the- 1.5 s follow-up threshold — mid-loop QA stays on unconditionally.+ 1.5 s follow-up threshold -- mid-loop QA stays on unconditionally.-## [0.4.0] — 2026-07-02+## [0.4.0] -- 2026-07-02### Added- **M1c GPU-instancing pass (plan/05 §3.3).** `renderSceneToGLB`/`renderGLB` gain an`instance: 'off' | 'auto' | 'on'` option (default `auto` = only `role: 'fill'` assets)- and `optimizeGlbBytes` gains `{ instance, role }` — the web-tier re-bake seam, so the+ and `optimizeGlbBytes` gains `{ instance, role }` -- the web-tier re-bake seam, so thepass reaches prod with no wire change. Repeated geometry (>= 5 nodes sharing one meshafter dedup) is rewritten to `EXT_mesh_gpu_instancing` batches in the upstream-canonical`dedup → instance → palette` order, cutting draw calls + bytes for fence runs /- colonnades / container stacks. **Perf/filesize only — the A–F grade keys on material+ colonnades / container stacks. **Perf/filesize only -- the A–F grade keys on materialcount and does not move** (tests assert grade + triangle parity). Skipped foranimated/skinned docs and any asset carrying `Joint*` pivot names (Kiln City targetsthose by name). Results are recorded as `InstancingSummary` (`meta.instancing`,- `RenderSceneResult.instancing`, `OptimizeGlbResult.instancing` — and+ `RenderSceneResult.instancing`, `OptimizeGlbResult.instancing` -- and`OptimizeGlbResult.summary` is now optional: an instancing-only pass has noconsolidation summary). All engine glTF IO now registers `EXTMeshGPUInstancing`(new dep `@gltf-transform/extensions`) so re-reads (grade-from-bytes,optimize-from-bytes, palette snap, scene export merge) preserve the batches, and`collectGlbMetrics` is instance-aware (an instanced node counts one draw but N× its- triangles — exactly what a supporting GPU renders).+ triangles -- exactly what a supporting GPU renders).- **M3 composer role/tier awareness (plan/05 §4.1).** `CatalogEntry` gains optional- `role` (`CatalogAssetRole` — the M1d asset taxonomy) + `tier` (A–F); `catalogList()`+ `role` (`CatalogAssetRole` -- the M1d asset taxonomy) + `tier` (A–F); `catalogList()`(and therefore `scene_list_assets`) surfaces them. Placement roles now DEFAULT fromthe catalog asset's role via `placementRoleForAsset` (wonder/poi → hero, fill → fill,- else support) in `place`/`placeExact`/`cluster`/`ring`/`layout` — an explicit agent+ else support) in `place`/`placeExact`/`cluster`/`ring`/`layout` -- an explicit agentrole still wins. The composer system prompt teaches the mapping, wonder scale-up, andD/F-tier density budgeting.-## [0.3.0] — 2026-07-02+## [0.3.0] -- 2026-07-02### Added- **Generation-loop transcript compaction (default on).** Before every model call,`runKilnAgent` now strips the image out of each SUPERSEDED render tool result(kiln_render / kiln_screenshot / kiln_view_interior / animation strips), swapping it for- a short text placeholder — only the newest render image rides each request. The prune is+ a short text placeholder -- only the newest render image rides each request. The prune issurgical, unlike the composer's whole-transcript collapse: no messages are added orremoved, toolUseIds are untouched (tool-use/tool-result pairing stays valid on everyprovider), and the JSON metrics half of each result survives. This was the biggest- input-token/cost lever in a multi-render run — previously every render image rode ALL+ input-token/cost lever in a multi-render run -- previously every render image rode ALLlater model calls. Opt out per run with `imageCompaction: 'off'`. New helpers exportedfrom `agent`: `pruneStaleRenderImages`, `installRenderImageCompaction`,`STALE_RENDER_PLACEHOLDER`.- **M1b grade-aware refine loop (plan/05 §3.2, default on).** After the model finalizes,the run bakes + grades the program exactly as the shipped artifact will be graded(grade-aware `auto` consolidation, matching `generateKilnAsset` and the Studio web-tier- re-bake). If it still grades below B for a consolidation-fixable reason — material+ re-bake). If it still grades below B for a consolidation-fixable reason -- materialsprawl (>3 distinct) or texture sprawl (>4), never a transparency-only demotion (glass- caps at C by design) — and the step budget leaves headroom, ONE bounded feedback turn+ caps at C by design) -- and the step budget leaves headroom, ONE bounded feedback turn(grade, material count, offending material list, consolidation directive) is fed back;the refined program is kept only if its grade actually improves. Opt out with`gradeRefine: 'off'`. Emits a `grade_refine` progress event; token usage now accumulates@@ -120,10 +555,10 @@ for the consuming app's lockfile + tarball provenance, not public npm releases.`RunKilnAgentResult.capped: true` flag (mirrors the composer's `capped` semantics); acap with nothing renderable is still an `error`.-## [0.2.0] — 2026-07-02+## [0.2.0] -- 2026-07-02The release cut the 0.1.1 composer note promised: formally versions the scene composer-surface (`@kiln/engine/composer`, `/composer/agent` — shipped in 0.1.x without a bump)+surface (`@kiln/engine/composer`, `/composer/agent` -- shipped in 0.1.x without a bump)plus the fixes below.### Fixed@@ -150,7 +585,7 @@ plus the fixes below.`agent/run.ts`, `palette.ts`) to the `@kiln/engine` reality and removed danglingreferences to files that do not exist in this repo.-## [0.1.1] — 2026-06-30+## [0.1.1] -- 2026-06-30### Documentation- Clarified that `@kiln/engine` remains private execution infrastructure. External developer access@@ -162,7 +597,7 @@ plus the fixes below.`KILN_THINKING` budgets are ignored for this model so the agent harness does not sendmanual extended-thinking params that Sonnet 5 rejects.-### Added — scene composer (`@kiln/engine/composer`, `/composer/agent`)+### Added -- scene composer (`@kiln/engine/composer`, `/composer/agent`)A THREE-free scene-composition surface: a `PlacementModel` single-source-of-truth with asmall scene DSL (`scene()`/`asset()`), terrain-agnostic hierarchy-aware layout, an overlapvalidator (MTV resolution), a ground sampler, and a `SceneRenderPort`; plus the Strands@@ -174,7 +609,7 @@ past a threshold (the externalized model IS the state), with a soft step-cap bac> The surface landed without a version bump (Studio consumed it via the committed> `@kiln/engine` 0.1.0 tarball); formally versioned by the 0.2.0 release above.-## [0.1.0] — 2026-06-23+## [0.1.0] -- 2026-06-23Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kiln`(source `d396c10`), file history preserved via `git subtree split`.@@ -187,7 +622,7 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kil### Removed vs pixel-forge core/kiln (what makes it lean)- TIJ pipeline modules `imposter/`, `fbx-ingest/`, `sprite-atlas/`, `retex/`,- `photogrammetry/`, `lod/` — the only modules pulling in Playwright + the heavier+ `photogrammetry/`, `lod/` -- the only modules pulling in Playwright + the heavierimage path.- Legacy single-shot `generate.ts` (Studio uses the agent path) and the entangled root`index.ts` barrel (Studio consumes subpaths, not the barrel).@@ -196,8 +631,8 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kil`@pixel-forge/shared`.### Retained runtime deps (lazy-loaded)-- `sharp` — texture decode in `loadTexture` (`await import('sharp')`).-- `xatlasjs` — UV atlas in `autoUnwrap` (`await import('xatlasjs/dist/node/...')`).+- `sharp` -- texture decode in `loadTexture` (`await import('sharp')`).+- `xatlasjs` -- UV atlas in `autoUnwrap` (`await import('xatlasjs/dist/node/...')`).### Tests- 36 source test files ported (382 pass / 2 skip / 0 fail offline). Live agent tests@@ -206,7 +641,7 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kil`generate()` wrapper), and `companions`/`refactor-validation` (tested the legacy`generate.ts` companion aliases `kiln.editCode`/`kiln.refactor`, also pruned).- Provider SDKs (`@anthropic-ai/sdk`, `@google/genai`, `openai`, `ai`,- `@aws-sdk/client-bedrock-runtime`) are **devDependencies only** — needed to exercise+ `@aws-sdk/client-bedrock-runtime`) are **devDependencies only** -- needed to exercisethe multi-provider `makeKilnModel` factory in `providers.test.ts`; they never enterruntime `dependencies`. The kiln-glb skill-drift gate is `skipIf`-guarded (the skilllives outside the engine repo).@@ -218,7 +653,7 @@ Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/killeft visible for a hardening pass; `noNonNullAssertion`/`useLiteralKeys` are off and`useIterableCallbackReturn` is warn (all idiomatic in the extracted code).-### Follow-ups (deliberately deferred from WS0 — see ../plan/03-standards-harness.md)+### Follow-ups (deliberately deferred from WS0 -- see ../plan/03-standards-harness.md)- Burn down the 19 Biome warnings + re-promote `useIterableCallbackReturn` to error.- Tighten `tsconfig` (`exactOptionalPropertyTypes`); currently mirrors pixel-forge corefor a zero-drift green typecheck.diff --git a/README.md b/README.mdindex c9a42f74..763640a8 100644--- a/README.md+++ b/README.md@@ -1,89 +1,275 @@# Kiln-**A vision-in-the-loop code-generation agent that builds 3D assets as source code.**+[](https://github.com/matthew-kissinger/kiln/actions/workflows/ci.yml)+[](LICENSE)-Kiln turns a sentence into a game-ready GLB by having a model *write a program*, look at what it-rendered, and fix it — not by sampling a mesh. The output is a small program with named parts, not-an opaque blob: editable, diffable, parametric, and readable by the next agent that touches it.+**Game-ready 3D models, built by an agent that writes them as code, renders them, and looks at what+came out.**-Ten hero assets, each one a checked-in program in [`examples/`](examples/). Click any image for-the full-size render. No mesh was sampled, no geometry was hand-authored, and none of it was-touched in a DCC tool. A model wrote each program, rendered it, looked at the result, and revised-— which is also why each file's header comment reads like a post-mortem.+Kiln does not sample a mesh. A model writes a small JavaScript program that constructs the geometry;+Kiln runs it, exports a glTF binary, rasterizes six orthographic views, and hands the images back so+the model can fix what it sees. What you keep at the end is the GLB *and* the program that made it:+named parts, real metres, a diff you can read, and a file the next agent can edit instead of+regenerating from scratch.++Fifty assets below, each one a checked-in program in [`examples/`](examples/). Click any image+for the full-size render. No mesh was sampled, no geometry was hand-authored, and nothing was+touched in a DCC tool. A model wrote each program, looked at the render, and revised, which is why+every file's header comment reads like a post-mortem.<table><tr><td width="33%" valign="top"><a href="examples/renders/field-gun.png"><img src="examples/renders/field-gun.png" alt="a Napoleonic field gun on a wooden carriage, generated by Kiln"></a><br><b><a href="examples/field-gun.kiln.js">field-gun</a></b><br>15,544 tris · Claude Opus 5<br><sub>booleans and arrays</sub></td>- <td width="33%" valign="top"><a href="examples/renders/street-lamp.png"><img src="examples/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris · Claude Opus 5<br><sub>revolved profiles, emissive + glass</sub></td>- <td width="33%" valign="top"><a href="examples/renders/diving-helmet.png"><img src="examples/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris · Claude Opus 5<br><sub>material contrast</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/cathedral.png"><img src="examples/renders/cathedral.png" alt="a Gothic cathedral with flying buttresses and lit stained glass, generated by Kiln"></a><br><b><a href="examples/cathedral.kiln.js">cathedral</a></b><br>19,842 tris · Claude Opus 5<br><sub>repetition, and windows cut rather than placed</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/mech.png"><img src="examples/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="examples/mech.kiln.js">mech</a></b><br>18,398 tris · Claude Opus 5<br><sub>armour oriented along a bone</sub></td></tr><tr>+ <td width="33%" valign="top"><a href="examples/renders/diving-helmet.png"><img src="examples/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,416 tris · Claude Opus 5<br><sub>material contrast</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/cafe-racer.png"><img src="examples/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,962 tris · Claude Opus 5<br><sub>a tapered sweep along a curve</sub></td><td width="33%" valign="top"><a href="examples/renders/penny-farthing.png"><img src="examples/renders/penny-farthing.png" alt="a penny-farthing bicycle, generated by Kiln"></a><br><b><a href="examples/penny-farthing.kiln.js">penny-farthing</a></b><br>12,450 tris · Claude Opus 5<br><sub>curves and radial arrays</sub></td>- <td width="33%" valign="top"><a href="examples/renders/mech.png"><img src="examples/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="examples/mech.kiln.js">mech</a></b><br>18,398 tris · Claude Opus 5<br><sub>armour oriented along a bone</sub></td>- <td width="33%" valign="top"><a href="examples/renders/arcade-cabinet.png"><img src="examples/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris · <b>Gemini 3.8 Flash</b><br><sub>silhouette from a swept profile</sub></td></tr><tr><td width="33%" valign="top"><a href="examples/renders/sushi-store.png"><img src="examples/renders/sushi-store.png" alt="a two-storey Japanese sushi shopfront with a tiled roof, generated by Kiln"></a><br><b><a href="examples/sushi-store.kiln.js">sushi-store</a></b><br>24,082 tris · Claude Opus 5<br><sub>a facade as layered depth</sub></td>- <td width="33%" valign="top"><a href="examples/renders/cafe-racer.png"><img src="examples/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,410 tris · Claude Opus 5<br><sub>a tapered sweep along a curve</sub></td>- <td width="33%" valign="top"><a href="examples/renders/beam-engine.png"><img src="examples/renders/beam-engine.png" alt="a rotative beam engine, generated by Kiln"></a><br><b><a href="examples/beam-engine.kiln.js">beam-engine</a></b><br>15,396 tris · Claude Opus 5<br><sub>an animated four-bar linkage</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/street-lamp.png"><img src="examples/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris · Claude Opus 5<br><sub>revolved profiles, emissive + glass</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/arcade-cabinet.png"><img src="examples/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris · Gemini 3.8 Flash<br><sub>silhouette from a swept profile</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/robot-arm.png"><img src="examples/renders/robot-arm.png" alt="a six-axis industrial robot arm with a parallel gripper, generated by Kiln"></a><br><b><a href="examples/robot-arm.kiln.js">robot-arm</a></b><br>15,324 tris · Claude Opus 5<br><sub>a kinematic chain that animates</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/carousel.png"><img src="examples/renders/carousel.png" alt="a fairground carousel with a striped canopy and horses, generated by Kiln"></a><br><b><a href="examples/carousel.kiln.js">carousel</a></b><br>16,356 tris · Gemini 3.8 Flash<br><sub>a radial array that turns</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/ferris-wheel.png"><img src="examples/renders/ferris-wheel.png" alt="a ferris wheel with lit gondolas on a braced frame, generated by Kiln"></a><br><b><a href="examples/ferris-wheel.kiln.js">ferris-wheel</a></b><br>10,452 tris · Gemini 3.8 Flash<br><sub>a lattice that still reads at distance</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/orrery.png"><img src="examples/renders/orrery.png" alt="a brass orrery with an emissive sun and planets on arms, generated by Kiln"></a><br><b><a href="examples/orrery.kiln.js">orrery</a></b><br>15,720 tris · Gemini 3.8 Flash<br><sub>arrayed gear teeth on one drive</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/longcase-clock.png"><img src="examples/renders/longcase-clock.png" alt="a mahogany longcase clock with a painted dial, generated by Kiln"></a><br><b><a href="examples/longcase-clock.kiln.js">longcase-clock</a></b><br>12,600 tris · Gemini 3.8 Flash<br><sub>case joinery at furniture scale</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/radio-telescope.png"><img src="examples/renders/radio-telescope.png" alt="a steerable parabolic radio telescope on a pedestal, generated by Kiln"></a><br><b><a href="examples/radio-telescope.kiln.js">radio-telescope</a></b><br>16,532 tris · Gemini 3.8 Flash<br><sub>a dish that tracks</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/anglerfish.png"><img src="examples/renders/anglerfish.png" alt="a deep-sea anglerfish with warty skin, a gaping jaw of needle teeth and a glowing lure on an arched illicium, generated by Kiln"></a><br><b><a href="examples/anglerfish.kiln.js">anglerfish</a></b><br>19,108 tris · Claude Opus 5<br><sub>organic form, and an emissive lure</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/hot-air-balloon.png"><img src="examples/renders/hot-air-balloon.png" alt="a hot-air balloon with a striped envelope and a wicker basket, generated by Kiln"></a><br><b><a href="examples/hot-air-balloon.kiln.js">hot-air-balloon</a></b><br>9,816 tris · Gemini 3.8 Flash<br><sub>a lathed envelope in twenty-four gores</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/vending-machine.png"><img src="examples/renders/vending-machine.png" alt="a lit drinks vending machine behind glass, generated by Kiln"></a><br><b><a href="examples/vending-machine.kiln.js">vending-machine</a></b><br>12,468 tris · Claude Opus 5<br><sub>emissive area as the enemy of shape</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/gramophone.png"><img src="examples/renders/gramophone.png" alt="an acoustic gramophone with a faceted brass horn on a hinged mahogany case, generated by Kiln"></a><br><b><a href="examples/gramophone.kiln.js">gramophone</a></b><br>10,724 tris · Gemini 3.8 Flash<br><sub>brass against mahogany, and a horn that folds out of a lid</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/typewriter.png"><img src="examples/renders/typewriter.png" alt="a cast-iron typewriter with a fan of type bars, brass trim and a sheet in the platen, generated by Kiln"></a><br><b><a href="examples/typewriter.kiln.js">typewriter</a></b><br>14,128 tris · Muse Spark 1.3<br><sub>a mechanism arrayed on an arc</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/lighthouse.png"><img src="examples/renders/lighthouse.png" alt="a stone lighthouse with a copper-domed lantern, a gallery rail and a keeper's cottage on a rocky islet, generated by Kiln"></a><br><b><a href="examples/lighthouse.kiln.js">lighthouse</a></b><br>16,492 tris · Muse Spark 1.3<br><sub>a whole small site, not just the tower</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/steam-locomotive.png"><img src="examples/renders/steam-locomotive.png" alt="a green 4-4-0 steam locomotive with a cowcatcher, brass domes and side rods, generated by Kiln"></a><br><b><a href="examples/steam-locomotive.kiln.js">steam-locomotive</a></b><br>19,256 tris · Muse Spark 1.3<br><sub>coupled wheels, and rods that have to reach them</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/windmill.png"><img src="examples/renders/windmill.png" alt="a Dutch tower windmill in brick with a shingled cap, a stage gallery and four lattice sails, generated by Kiln"></a><br><b><a href="examples/windmill.kiln.js">windmill</a></b><br>9,872 tris · DeepSeek V4 Flash<br><sub>coursing that is a texture, not a stack of rings</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/aircraft-carrier.png"><img src="examples/renders/aircraft-carrier.png" alt="an aircraft carrier with an angled flight deck, deck markings and an island superstructure, generated by Kiln"></a><br><b><a href="examples/aircraft-carrier.kiln.js">aircraft-carrier</a></b><br>17,904 tris · Claude Opus 5<br><sub>a third of a kilometre, laid out by arithmetic</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/air-defense-radar.png"><img src="examples/renders/air-defense-radar.png" alt="a truck-mounted air-defence phased-array radar with the panel raised, generated by Kiln"></a><br><b><a href="examples/air-defense-radar.kiln.js">air-defense-radar</a></b><br>16,094 tris · Claude Opus 5<br><sub>an array face that is a grid, not a texture</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/fighter-jet.png"><img src="examples/renders/fighter-jet.png" alt="a single-seat multirole fighter on its landing gear with canted tails and open nozzles, generated by Kiln"></a><br><b><a href="examples/fighter-jet.kiln.js">fighter-jet</a></b><br>18,172 tris · Claude Opus 5<br><sub>an aerofoil lofted station by station</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/comms-satellite.png"><img src="examples/renders/comms-satellite.png" alt="a geostationary communications satellite with gold thermal blankets, two solar wings and three dish antennas, generated by Kiln"></a><br><b><a href="examples/comms-satellite.kiln.js">comms-satellite</a></b><br>18,824 tris · Claude Opus 5<br><sub>a 21 m span that still has a 2.6 m bus in it</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/victorian-greenhouse.png"><img src="examples/renders/victorian-greenhouse.png" alt="a Victorian glasshouse with a curved barrel roof, cast-iron ribs and a brick stylobate, generated by Kiln"></a><br><b><a href="examples/victorian-greenhouse.kiln.js">victorian-greenhouse</a></b><br>10,462 tris · Gemini 3.8 Flash<br><sub>glazing bars as structure, not as a texture</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/gothic-gatehouse.png"><img src="examples/renders/gothic-gatehouse.png" alt="a Gothic castle gatehouse with two drum towers, machicolations and a lowered drawbridge, generated by Kiln"></a><br><b><a href="examples/gothic-gatehouse.kiln.js">gothic-gatehouse</a></b><br>10,428 tris · Gemini 3.8 Flash<br><sub>two drums, one arch, and a bridge that lands</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/cable-stayed-bridge.png"><img src="examples/renders/cable-stayed-bridge.png" alt="a cable-stayed road bridge with a portal pylon and fanned stay cables, generated by Kiln"></a><br><b><a href="examples/cable-stayed-bridge.kiln.js">cable-stayed-bridge</a></b><br>7,580 tris · Omen Alpha<br><sub>a stay pattern that has to reach the deck</sub></td></tr><tr>- <td width="33%" valign="top"><a href="examples/renders/lunar-lander.png"><img src="examples/renders/lunar-lander.png" alt="a lunar module on four legs, generated by Kiln"></a><br><b><a href="examples/lunar-lander.kiln.js">lunar-lander</a></b><br>13,208 tris · Claude Opus 5<br><sub>crumpled foil, and asymmetry on purpose</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/fire-lookout-tower.png"><img src="examples/renders/fire-lookout-tower.png" alt="a fire lookout tower with a glazed cab on a braced lattice and a switchback stair, generated by Kiln"></a><br><b><a href="examples/fire-lookout-tower.kiln.js">fire-lookout-tower</a></b><br>4,408 tris · LongCat 2.0<br><sub>a whole tower at four thousand triangles</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/tram.png"><img src="examples/renders/tram.png" alt="a 1920s city tram on rails with a trolley pole reaching up to the overhead wire, generated by Kiln"></a><br><b><a href="examples/tram.kiln.js">tram</a></b><br>12,540 tris · Gemini 3.8 Flash<br><sub>a body that is mostly window</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/tugboat.png"><img src="examples/renders/tugboat.png" alt="a harbour tugboat with a rope fender belt, an orange funnel and a raised wheelhouse, generated by Kiln"></a><br><b><a href="examples/tugboat.kiln.js">tugboat</a></b><br>9,856 tris · Gemini 3.8 Flash<br><sub>a hull lofted station by station</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/deep-sea-diver.png"><img src="examples/renders/deep-sea-diver.png" alt="an atmospheric diving suit with a copper helmet, jointed limbs and weighted boots, generated by Kiln"></a><br><b><a href="examples/deep-sea-diver.kiln.js">deep-sea-diver</a></b><br>10,876 tris · Gemini 3.8 Flash<br><sub>a figure built out of hardware, not anatomy</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/pumpjack.png"><img src="examples/renders/pumpjack.png" alt="an oilfield pumpjack with a walking beam, horsehead and counterweights on a skid, generated by Kiln"></a><br><b><a href="examples/pumpjack.kiln.js">pumpjack</a></b><br>10,236 tris · Gemini 3.8 Flash<br><sub>a linkage that would actually swing</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/drilling-rig.png"><img src="examples/renders/drilling-rig.png" alt="a land drilling rig with a derrick over its substructure, mud tanks and a pipe rack, generated by Kiln"></a><br><b><a href="examples/drilling-rig.kiln.js">drilling-rig</a></b><br>11,048 tris · Gemini 3.8 Flash<br><sub>a site rather than a silhouette</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/harbour-crane.png"><img src="examples/renders/harbour-crane.png" alt="a rail-mounted harbour crane with a luffing jib and a spreader on the hoist, generated by Kiln"></a><br><b><a href="examples/harbour-crane.kiln.js">harbour-crane</a></b><br>10,568 tris · Gemini 3.8 Flash<br><sub>steelwork that still reads as steelwork</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/crawler-crane.png"><img src="examples/renders/crawler-crane.png" alt="a lattice-boom crawler crane on tracks with the hook block hanging, generated by Kiln"></a><br><b><a href="examples/crawler-crane.kiln.js">crawler-crane</a></b><br>12,660 tris · MiniMax M3<br><sub>a boom that is one bay, repeated</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/excavator.png"><img src="examples/renders/excavator.png" alt="a tracked hydraulic excavator with the boom, stick and bucket curled in, generated by Kiln"></a><br><b><a href="examples/excavator.kiln.js">excavator</a></b><br>12,400 tris · Omen Alpha<br><sub>rams that line up with the joints they drive</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/printing-press.png"><img src="examples/renders/printing-press.png" alt="a wooden hand printing press with a screw platen, type cases and ink balls, generated by Kiln"></a><br><b><a href="examples/printing-press.kiln.js">printing-press</a></b><br>10,188 tris · Gemini 3.8 Flash<br><sub>a mechanism you could explain from the render</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/pipe-organ.png"><img src="examples/renders/pipe-organ.png" alt="a church pipe organ with ranks of display pipes above a console and pedalboard, generated by Kiln"></a><br><b><a href="examples/pipe-organ.kiln.js">pipe-organ</a></b><br>10,340 tris · Gemini 3.8 Flash<br><sub>ranks arrayed without becoming a comb</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/planetarium-projector.png"><img src="examples/renders/planetarium-projector.png" alt="a dumbbell planetarium projector with two star globes on a trunnion mount, generated by Kiln"></a><br><b><a href="examples/planetarium-projector.kiln.js">planetarium-projector</a></b><br>10,932 tris · Gemini 3.8 Flash<br><sub>black on black, and still legible</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/astronomical-clock.png"><img src="examples/renders/astronomical-clock.png" alt="an astronomical clock with a gilt astrolabe dial in a carved stone case, generated by Kiln"></a><br><b><a href="examples/astronomical-clock.kiln.js">astronomical-clock</a></b><br>9,324 tris · Gemini 3.8 Flash<br><sub>a dial carrying the whole asset</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/espresso-machine.png"><img src="examples/renders/espresso-machine.png" alt="a three-group commercial espresso machine with portafilters, steam wands and cups warming on top, generated by Kiln"></a><br><b><a href="examples/espresso-machine.kiln.js">espresso-machine</a></b><br>19,080 tris · GLM 5.3 Flash<br><sub>chrome, which is the hardest thing to shade</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/pinball-machine.png"><img src="examples/renders/pinball-machine.png" alt="a pinball machine with a lit backbox, a glassed playfield and a rear cabinet bay, generated by Kiln"></a><br><b><a href="examples/pinball-machine.kiln.js">pinball-machine</a></b><br>8,700 tris · GLM 5.3 Flash<br><sub>a head that has to stand on something</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/trebuchet.png"><img src="examples/renders/trebuchet.png" alt="a counterweight trebuchet with a slung beam, a ballast box and the sling laid out on the ground, generated by Kiln"></a><br><b><a href="examples/trebuchet.kiln.js">trebuchet</a></b><br>2,652 tris · Gemini 3.8 Flash<br><sub>a siege engine in 2,652 triangles</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/rigid-airship.png"><img src="examples/renders/rigid-airship.png" alt="a 1930s rigid passenger airship moored at its mast, with a promenade window row, engine cars and a cruciform tail, generated by Kiln"></a><br><b><a href="examples/rigid-airship.kiln.js">rigid-airship</a></b><br>11,764 tris · GPT-6 Astra<br><sub>one lofted envelope, with everything hung off it</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/orbital-station.png"><img src="examples/renders/orbital-station.png" alt="a rotating-torus orbital station with lit window bands, four spokes, a docking hub and solar wings, generated by Kiln"></a><br><b><a href="examples/orbital-station.kiln.js">orbital-station</a></b><br>10,212 tris · GPT-6 Astra<br><sub>a ring that has to close on itself</sub></td>+</tr>+<tr>+ <td width="33%" valign="top"><a href="examples/renders/blast-furnace.png"><img src="examples/renders/blast-furnace.png" alt="a blast furnace with three hot-blast stoves, downcomer piping, galleries and a cast house, generated by Kiln"></a><br><b><a href="examples/blast-furnace.kiln.js">blast-furnace</a></b><br>11,964 tris · GPT-6 Astra<br><sub>a plant rather than an object</sub></td>+ <td width="33%" valign="top"><a href="examples/renders/clock-tower.png"><img src="examples/renders/clock-tower.png" alt="a Gothic clock tower with gilt dials, a louvred belfry, crocketed pinnacles and a leaded spire, generated by Kiln"></a><br><b><a href="examples/clock-tower.kiln.js">clock-tower</a></b><br>11,664 tris · GPT-6 Astra<br><sub>four faces that have to agree</sub></td></tr></table>-Every shot above is regenerated by `bun scripts/hero-shots.ts`, straight from the checked-in-programs through the same PBR render port the agent loop uses. Nothing in this README was-retouched.+Every shot is regenerated by `bun scripts/hero-shots.ts` straight from those programs, through the+same PBR render port the agent loop uses. Nothing in this README was retouched.++A still is a weak claim about a mesh, so all fifty are also up at+**[the specimen gallery](https://matthew-kissinger.github.io/kiln/)**, where you can orbit them,+flip them to wireframe to see the topology under the shading, and pull the GLB down to open in+whatever you use. That page holds no assets either: its build runs the same programs through the+same evaluator, so what you orbit there is what the file beside it produces today rather than an+export somebody remembered to refresh. It lives in [`site/`](site).++A gallery is thin evidence when it is all one model's work, so it is worth saying who wrote what.+35 of the 50 programs above were not written by Claude. Gemini 3.8 Flash wrote 21 of them through+the Antigravity CLI and GPT-6 Astra wrote 4 through Codex; Muse Spark 1.3 wrote 3, GLM 5.3 Flash+and Omen Alpha 2 each, and there is 1 apiece from DeepSeek V4 Flash, MiniMax M3 and LongCat 2.0.+The rest came through OpenCode, bar the fire lookout tower, which came out of Hermes -- a Python+agent with its own config, its own skill store and its own provider routing, and the one harness+here that is nothing like Claude Code.++Every one of those runs was dispatched into a directory holding nothing but the brief and the Kiln+skills: no engine source, and no finished example to copy an interface from. Nothing in the tools+or the skills changed for any of them, which is the claim the gallery is really making. The loop+belongs to neither the model nor the harness it was built in, and it does not need the model to+have read this repository first.++## And they move++`animate()` is part of the same program. It returns named clips built from rotation and position+tracks against the parts the program already created, so a joint that moves is the joint that was+modelled -- there is no separate rig to keep in sync, and a diff of the motion is a diff of the same+file. The model reviews a clip the way it reviews a still: `kiln_screenshot_animation` poses the+scene across the clip and hands back the frames, which is how a walk that slides, a knee that bends+backwards, or an arm that swings through its own base gets caught before the GLB is written.++<table>+<tr>+ <td width="50%" valign="top"><img src="examples/renders/robot-arm.gif" alt="an industrial robot arm running a pick-and-place cycle"><br><b><a href="examples/robot-arm.kiln.js">robot-arm</a></b><br><sub>a six-axis pick-and-place cycle</sub></td>+ <td width="50%" valign="top"><img src="examples/renders/carousel.gif" alt="a fairground carousel turning, with horses rising and falling"><br><b><a href="examples/carousel.kiln.js">carousel</a></b><br><sub>a turn, with the horses on their own phase</sub></td>+</tr>+<tr>+ <td width="50%" valign="top"><img src="examples/renders/orrery.gif" alt="an orrery with planets orbiting a lit sun"><br><b><a href="examples/orrery.kiln.js">orrery</a></b><br><sub>planets on nested arms off one drive</sub></td>+ <td width="50%" valign="top"><img src="examples/renders/radio-telescope.gif" alt="a radio telescope dish slewing in azimuth and elevation"><br><b><a href="examples/radio-telescope.kiln.js">radio-telescope</a></b><br><sub>a slew in azimuth and elevation</sub></td>+</tr>+</table>-The arcade cabinet is the one that matters most here. It was authored end to end by a **different-vendor's model in a different harness** — Gemini 3.8 Flash driving the same plugin through the-Antigravity CLI — with no changes to the tools or the skills. The loop is not Claude-specific.+These are rendered by `bun scripts/anim-gifs.ts` from the checked-in programs, through the same PBR+port as the stills. One detail in that script is worth borrowing if you build something similar: the+port fits its camera to whatever bounding box it is handed, so a sequence whose posed extent changes+-- the arm above varies by 63% between folded and reaching -- will appear to breathe as the camera+refits every frame. Because the projection is orthographic and the fit is exact, each frame can be+put back onto one shared camera by a scale and a translation that are both computable, which is a+correction rather than an approximation.-*The contact sheet the model looks at — `examples/field-gun.kiln.js`, 15,544 triangles: a revolved+*The contact sheet the model looks at. `examples/field-gun.kiln.js`, 15,544 triangles: a revolvedbronze barrel bored with a boolean, a stepped oak carriage carrying strapwork and bolt heads, and-twelve-spoke wheels with iron tyres:*-`bun run kiln render examples/field-gun.kiln.js --views sheet.png`--## What this is--A working reference implementation of an agent loop that can **see its own work**:+twelve-spoke wheels with iron tyres.*-```-list primitives -> write program -> validate (AST) -> render -> look at six views -> fix -> finalize+```bash+bun run kiln render examples/field-gun.kiln.js --views sheet.png```-The interesting parts are architectural, and they generalize past 3D:--- **One tool definition, two transports.** [`src/tools/registry.ts`](src/tools/registry.ts) is the- single source of truth. The in-process Strands skin and the MCP server both iterate it, so tool- names and schemas cannot drift apart.-- **Deterministic gates, kept separate from model judgment.** Self-intersection, part connectivity,- and AST validation all fail closed with no model call. `QaContext` is deliberately image-free so a- QA rule *structurally cannot* read a render buffer.-- **A render port with a fail-closed degrade.** `captureViewsViaPort` owns the deadline, PNG- validation, grid composition, and a never-throw fallback. Renderers are swappable; correctness- does not depend on which one ran.-- **Budgets and compaction** as first-class concerns, because agent loops that render images run- out of context and money.--## What this is not--- **Not photoreal reconstruction.** Output is stylized to mid-fidelity procedural geometry. If you- want a scanned-looking mesh, use a diffusion model — Trellis, Hunyuan3D and friends are better at- that, and it isn't close.-- **Not a mesh generator.** No diffusion, no photogrammetry, no point cloud. A model writes code;- the code builds geometry.-- **Not novel in category.** [img2threejs](https://github.com/img2threejs/img2threejs) is an- architectural peer running the same essential loop. Kiln differs in being TypeScript/Strands, in- running its vision loop with no browser required, and in its deterministic gate layer.-- A single reference view cannot reveal hidden sides. Assets are inferred, not measured.+## What this does that asking your agent directly does not++Any coding agent will cheerfully write you a Three.js scene of a motorcycle. It writes it in one+pass, never sees the result, and reports success. The failure mode is not bad code, it is confident+code about geometry nobody looked at: a front mudguard sunk inside the tyre it is meant to arch over,+an exhaust routed into the engine instead of out the back, a robot arm whose pick pose reaches+upward. All three of those are in this repository's example headers, because they happened and the+loop caught them.++Kiln closes that loop, and then declines to trust it on its own.++The model gets eyes. `kiln_render` builds the program, exports the GLB, and returns the metrics and+the six-view contact sheet in one tool result, so looking costs a single call rather than a detour+through a file the agent cannot open. Every render also reports `viewFidelity`, which tells the agent+in band whether it may judge material from what it is looking at or only geometry. An agent that+cannot see a texture must not conclude the texture is wrong.++What vision is bad at gets checked by machine instead. Self-intersection, part connectivity, floating+geometry, degenerate and non-unit normals, triangle budget, and glTF validity all fail closed with no+model call, and the QA context is deliberately image-free so a rule *structurally cannot* read a+render buffer. No render will ever show you a normal of length 0.9994. The validator rejects it on+sight, and that matters because the exporters downstream will too.++The model reads the catalog before it writes anything. `kiln_list_primitives` returns the real+signatures, so the program is written against the API that exists rather than the one the model+half-remembers from some other engine. That one step is the difference between a run that compiles+and a run that burns four turns failing on names.++And what comes out is contracted, not merely valid. Metres, +Y up, sitting on the ground plane at+y=0, materials drawn from a palette chosen for instancing, a triangle count that lands where the+gallery lands, and a versioned `integrationManifest` sidecar carrying the artifact hash, bounds,+grounding offset, semantic role, and structural QA. Drop the file into a scene and it is the right+size, the right way up, and standing on the floor.++## Where it works and where it does not++Kiln is good at things that were manufactured. A form that comes from a profile turned on a lathe, a+plate bent to a radius, a frame welded out of tube, or one bay repeated the length of a nave is a+form you can describe as a program, and a program is what Kiln writes. That covers more of an art+list than it sounds like: vehicles, aircraft and ships; ordnance and defence hardware; machinery,+instruments and tooling; furniture, fittings and shop dressing; architecture and the modular kit+pieces buildings are assembled out of; and the long tail of props that fill a level and never get a+close-up. The gallery is deliberately all of that.++It is at its best when you want many of them. A program with numbers in it is already a family, so+the second crate is a parameter rather than another generation, and a street's worth of lamps is one+casting with different arm lengths. That is also where the loop pays for itself: authoring is minutes+of unattended wall clock, and the marginal variant is a rerun. Dispatching a batch of them without+supervision is a documented path further down this page, not an aspiration.++It is bad at things that grew. Faces, hands, cloth, foliage, anything with muscle under the skin all+want a sculpt, and the honest recommendation there is a diffusion model. Trellis, Hunyuan3D and their+successors will beat this outright, and it is not close.++It is also not reconstruction. Given one reference image, Kiln infers the sides it cannot see rather+than measuring them. If you need *that* object rather than something like it, reach for+photogrammetry or a scanner.++The economics differ too, and it is worth being plain about it. A mesh sampler answers in seconds.+Kiln spends minutes, because looking is the expensive part and looking is the entire point. What+those minutes buy is that the cost does not come back. Edit the wheel radius, rerun, and you get the+same motorcycle with bigger wheels; regenerate a sampled mesh and you get a different motorcycle.+The second version of a Kiln asset is a diff, and the hundredth variant of it is a loop.++Code-as-geometry with a model in the loop is not a category Kiln invented, and there are other+projects in it. What is unusual here is the shape of the loop rather than the idea of it: the vision+pass has no browser anywhere in it, so it runs in a container and in CI; and the model's judgment+sits on top of a deterministic gate layer that never sees pixels, so a confident wrong answer cannot+promote a broken asset.++## Where the tokens go++Most of what an agent spends on 3D is not spent on the object. It guesses at an API and reads the+errors back, renders into a file it has no way to open, narrates the geometry to itself in prose+because narration is all it has, and re-derives on every asset the same things it worked out on the+last one. Those turns are expensive and most of them carry an image, and none of them is the model+thinking about the shape.++Kiln pays that discovery once, up front, and keeps it out of the loop. The primitive catalog is a+single call that returns real signatures, so the program is written against the API that exists+rather than the one the model half-remembers from some other engine. Looking is a single call too:+`kiln_render` builds the program, exports the GLB, rasterizes six views, and returns the contact+sheet and the metrics in one tool result, so a revision costs one look instead of a render, a file+write, a read that fails, and a paragraph of speculation. The deterministic gates cost no model+tokens at all, because self-intersection, floating parts, non-unit normals, triangle budget and glTF+validity are all decided in process and their context is image-free by construction. And a fix is a+patch rather than a rewrite: `kiln_edit` replaces exact strings and re-renders, so the tenth revision+does not re-emit the first nine.++What sits in context permanently is small, and it is measured rather than asserted. The seven tool+schemas derive to 15,839 characters of JSON Schema, call it four thousand tokens. The five skills+advertise themselves in 1,698 characters of front matter, four hundred more; their bodies come to+about eight thousand tokens between them and load only when one of them actually fires. Everything+else a model would otherwise have to be told about building an asset lives in the engine, where it+is executed rather than read.++The wall clock is honest about the trade. An unattended dispatch of a mid-sized asset lands between+two and six minutes on one machine, and thirteen for the carrier at the end of the gallery, which is+a third of a kilometre long and has the part count to match. Several of the assets above were+authored exactly that way, in a batch nobody watched.## Quickstart-**No API key required.** Render an existing Kiln program and look at the result:+No API key required. Render one of the checked-in programs and look at the result:```bashgit clone https://github.com/matthew-kissinger/kiln && cd kiln@@ -92,8 +278,8 @@ bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png```That exercises the geometry build, the QA gates, and the rasterizer with no model and no key. The-default `--render auto` briefly looks for a local GPU render service and falls back to the CPU-rasterizer when there is none, so this works unchanged on a machine with no GPU.+default `--render auto` glances for a local GPU render service and falls back to the CPU rasterizer+when there is none, so it works unchanged on a machine with no GPU.To generate from a prompt, set one provider key and:@@ -101,10 +287,211 @@ To generate from a prompt, set one provider key and:bun run kiln generate "a weathered wooden crate" --out crate.glb```-## Rendering: three modes+## Install it in your agent++Kiln ships as an [Agent Plugin](https://agentplugins.codes/): an MCP server exposing the tool+surface, alongside five skills that teach an agent to use it well, covering authoring an asset,+refining one that already exists, composing finished assets into a scene, proving one works inside a+real project, and wiring another harness up to generate a library at scale. Pick your harness below; [`docs/install.md`](docs/install.md) has the long+form, including the sharp edges.++Every route starts with a clone and its dependencies, because the engine ships TypeScript source+rather than a published package:++```bash+git clone https://github.com/matthew-kissinger/kiln && cd kiln && bun install+bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png+```++If that writes a GLB and a contact sheet, the engine is fine and anything that goes wrong afterwards+is transport configuration.++**The server your harness launches runs on Node, not Bun.** `dist/mcp-server.mjs` is a committed+bundle, because a plugin install is a git clone with no build step, and it is what every config+below points at. Bun is the development toolchain here; it is not something a user of the plugin+needs on their `PATH`. That distinction is not cosmetic -- it is the fix for a real bug, and+[`src/__tests__/mcp-bundle.test.ts`](src/__tests__/mcp-bundle.test.ts) rebuilds the bundle, compares+it byte for byte, and then speaks MCP to it under `node` so it cannot rot.++<details>+<summary><b>Claude Code</b></summary>++```bash+claude plugin marketplace add matthew-kissinger/kiln+claude plugin install kiln@kiln+```++Verify with `claude mcp list`, where you want `plugin:kiln:kiln … ✔ Connected`.+</details>++<details>+<summary><b>Antigravity CLI (<code>agy</code>)</b></summary>++Two commands, because they do different jobs:++```bash+agy plugin install .+agy mcp add --env KILN_RENDER=auto kiln node /absolute/path/to/kiln/dist/mcp-server.mjs+```++The first brings in the skills. The second is not redundant: as of `agy` 1.1.25, installing a+plugin does **not** register the MCP servers it declares. `agy plugin validate .` will happily+report `mcpServers: 1 processed` while `agy mcp list` reports `No MCP servers configured`, and the+agent sees no tools. `agy mcp add` is the supported registration and writes the entry itself, so+there is no JSON to hand-edit. Confirm with `agy mcp list`.++For headless (`agy -p`) runs you also need permission grants in+`~/.gemini/antigravity-cli/settings.json`. Scoped `mcp()` and `write_file()` rules work; `command()`+targets are soft-denied in print mode whatever the syntax, so only `command(*)` passes. See+[`docs/install.md`](docs/install.md#headless-permissions) for the evidence and the upstream issue.+</details>++<details>+<summary><b>OpenCode</b></summary>++OpenCode has no plugin manifest to install -- its plugins are JavaScript modules, which is a+different thing entirely -- so Kiln arrives as an MCP server plus skills, and both are one-time+edits. Put this in `~/.config/opencode/opencode.json`, or in an `opencode.json` at your project+root:++```json+{+ "$schema": "https://opencode.ai/config.json",+ "mcp": {+ "kiln": {+ "type": "local",+ "command": ["node", "/absolute/path/to/kiln/dist/mcp-server.mjs"],+ "enabled": true,+ "environment": { "KILN_RENDER": "auto" },+ "timeout": 30000+ }+ }+}+```++Three details differ from every other client on this page and each one fails silently if you carry+a config over unchanged: the key is `mcp` rather than `mcpServers`, the type is `local` rather than+`stdio`, and the command and its arguments are a single array rather than a `command` plus `args`.+The schema rejects unknown keys, so a stray `env` is not ignored, it is an error.++`timeout` bounds the connection handshake, not the tool calls that follow, which is the opposite of+what the name suggests. Set to 200 ms the server never connects and `opencode mcp list` reports+`kiln failed`; set to 1500 ms it connects, and a `kiln_render` that takes nine seconds still comes+back with its picture. The handshake itself measures around 1.2 seconds against a default of five,+so the default works and an explicit value only buys headroom for a cold start.++Verify with `opencode mcp list`, where you want `kiln connected`.++The skills are the second half, and OpenCode reads Anthropic's `SKILL.md` layout directly. Copy them+to `~/.config/opencode/skills/` for every project, or to `.claude/skills/` inside one -- OpenCode+looks in both, along with `.agents/skills/`:++```bash+cp -r skills/* ~/.config/opencode/skills/+```++One cosmetic surprise: OpenCode namespaces tools by server, so `kiln_render` is presented to the+model as `kiln_kiln_render`. Nothing needs changing, and models find the tools anyway, but it is+what you will see in the transcript.+</details>++<details>+<summary><b>Hermes</b></summary>++Hermes is a Python agent with its own YAML config, its own skill store and its own provider routing,+which makes it the honest test of whether any of this is portable rather than Claude-Code-shaped.+Two commands attach both halves:++```bash+hermes mcp add kiln --command node --args /absolute/path/to/kiln/dist/mcp-server.mjs --env KILN_RENDER=auto+hermes config set skills.external_dirs /absolute/path/to/kiln/skills+```++The first connects immediately, prints the seven tools it found and asks whether to enable them. The+second is how Hermes finds skills at all: it reads a list of absolute directories out of its config+rather than `.claude/skills` out of the working directory, so pointing it at this repository is the+whole step. `hermes mcp list` and `hermes skills list` confirm both halves landed.++Hermes ships with no model provider, so a fresh install fails on `No inference provider configured`+before the brief is ever read -- which reads exactly like a broken plugin and is not one.+[`docs/install.md`](docs/install.md) has the login and the follow-up that catches everybody out.+</details>++<details>+<summary><b>Codex CLI</b></summary>++Codex keeps its MCP servers in TOML at `~/.codex/config.toml`, and the path has to be absolute:++```toml+[mcp_servers.kiln]+command = "node"+args = ["/absolute/path/to/kiln/dist/mcp-server.mjs"]+env = { KILN_RENDER = "auto" }+```++That is the whole of it for interactive `codex`, which asks before each tool call. `codex exec` is+the one that needs a flag: it pins the approval policy to `never`, and a `never` policy refuses an+MCP call rather than queueing it, so a scripted run comes back in under a minute reporting that+`kiln_list_primitives` was blocked and having written nothing. Add `--approve-for-me`, which routes+approvals through automatic review and picks the workspace-write sandbox itself -- which is also why+it is rejected alongside `--sandbox`.+</details>++<details>+<summary><b>Cursor, Zed, or any MCP client</b></summary>++Point the client at the bundle with an **absolute** path. The server resolves its own paths from+`import.meta.url` and never reads `process.cwd()`, so the launch directory does not matter:++```json+{+ "mcpServers": {+ "kiln": {+ "type": "stdio",+ "command": "node",+ "args": ["/absolute/path/to/kiln/dist/mcp-server.mjs"],+ "env": { "KILN_RENDER": "auto" }+ }+ }+}+```+</details>++<details>+<summary><b>In-process TypeScript, no MCP</b></summary>-Kiln renders the views the model looks at, and there are three ways to do it. All three are in this-repository; none requires a cloud account.+```ts+import { createKilnToolRegistry } from 'kiln/tools';+```++`kiln/tools` imports no agent SDK, so porting to a harness that is not Strands does not drag Strands+along. [`examples/strands-harness.ts`](examples/strands-harness.ts) is the whole integration in about+sixty lines.+</details>++Whichever route you took, check it before you judge anything by the assets it produces:++```bash+bun run smoke:harness+```++That sends a short brief into a throwaway directory for every CLI it finds -- call one tool, write a+four-line program, validate it -- and then builds what came back with the engine rather than+believing the agent's own account of how it went. It matters because every wiring failure here is+silent. A harness that cannot see the server does not say so, one that can see it but will not grant+it behaves the same way, and so does a model that simply was not up to the job. Three different+problems, one symptom, and no way to tell them apart by looking at a bad asset.++The MCP server exposes the **raw tools**, which means *your* agent is the author. It writes the+program, looks at the render, and iterates using its own model, with no separate provider key and no+nested agent loop. The trade is that your harness then supplies both the author and the vision judge:+the deterministic gates still run independently, but the eyes/judge separation the production system+maintained is collapsed. That is deliberate, and it is what buys the portability.++## Seeing the work: CPU and GPU++There are two renderers in this repository, and the mode picks between them. Neither wants a cloud+account.```bash--render auto # default: local GPU service if one is up, else CPU@@ -115,29 +502,25 @@ repository; none requires a cloud account.### What the difference actually looks like-The same program — the field gun above — rendered both ways:+The same program, the field gun above, rendered both ways:| CPU rasterizer | GPU PBR ||---|---||  |  |Geometry is equally legible in both. On the CPU sheet you can still count the twelve spokes, see the-bolt heads on the cheek straps, and read the stepped carriage — silhouette, proportion, orientation-and part contact all survive intact.+bolt heads on the cheek straps, and read the stepped carriage; silhouette, proportion, orientation and+part contact all survive intact.What does not survive is every material cue in the asset. The oak carriage, the iron tyres, and the-bronze barrel render as **the same white plastic**. Not dimmer — *absent*. The procedural albedo and+bronze barrel render as **the same white plastic**. Not dimmer, *absent*. The procedural albedo andthe derived normal maps that separate weathered wood from gun-metal simply do not exist in a-flat-shaded render, so an agent looking at the left-hand sheet has no way to tell that this asset has-three materials at all.--**If your assets have textures or metal, use the GPU.** That is most real assets, and it is why-`auto` reaches for a GPU first. The CPU rasterizer is the floor that guarantees the loop runs-anywhere — CI, a container, a laptop with no GPU — not the target.+flat-shaded render, so an agent looking at the left-hand sheet has no way to tell this asset has three+materials at all.-This is also why every render reports `viewFidelity`. When `materialFaithful` is false the agent is-told, in band, that it may judge geometry and **not** material. An agent that cannot see a texture-must not conclude the texture is wrong.+**If your assets have textures or metal, use the GPU.** That is most real assets, and it is why `auto`+reaches for a GPU first. The CPU rasterizer is the floor that guarantees the loop runs anywhere, in+CI, in a container, on a laptop with no GPU. It is not the target.| | CPU raster | GPU PBR ||---|---|---|@@ -157,7 +540,7 @@ cd render-service && npm install && npm start```That is **gpu (local)**. It listens on `:8000`, which is where `--render auto` looks, so nothing else-needs configuring — the next `kiln render` picks it up and says so:+needs configuring. The next `kiln render` picks it up and says so:```sheet.png (GPU dawn-d3d12:nvidia-geforce-rtx-3070:D3D12 driver version 32.0.16.1074)@@ -174,128 +557,225 @@ will not start rather than one that silently renders on CPU and lies about it.With nothing reachable, `auto` falls back to the CPU rasterizer, which is why a machine with no GPUneeds no configuration at all. `captureViewsViaPort` owns the deadline, PNG validation, grid-composition, and a never-throw fallback: a slow or broken renderer costs fidelity, never correctness.+composition, and a never-throw fallback, so a slow or broken renderer costs fidelity and never+correctness.-**The GPU is a view producer only — it is never gate evidence.** QA rules never see pixels.+**The GPU is a view producer only. It is never gate evidence,** and QA rules never see pixels.-## Install it in your agent+## Materials, and where the pixels come from-Kiln ships as an [Agent Plugin](https://agentplugins.codes/): an MCP server exposing the tool-surface, plus three skills that teach an agent how to use it well. Pick your harness below;-[`docs/install.md`](docs/install.md) has the long form, including the sharp edges.+Nothing in this pipeline samples an image model, textures included. There are two ways a surface gets+its detail, and a model authoring an asset reaches for both in the same program.++The first is **procedural**: a declarative stack of layers the model writes out as data, which the+engine rasterizes into a texture.-Everything needs [Bun](https://bun.sh) on `PATH` and a clone, because the package ships TypeScript-source rather than a build artifact:+```js+const brick = proceduralTexture({+ schemaVersion: 2,+ size: 256,+ usage: 'albedo',+ layers: [+ { op: 'bricks', brick: 0x8c4a32, mortar: 0xbfb6a8, rows: 12, cols: 6, mortarWidth: 0.08 },+ { op: 'noise', colorA: 0x000000, colorB: 0x604030, scale: 24, octaves: 4, seed: 7,+ blend: 'multiply', opacity: 0.35 },+ ],+});++const wall = pbrMaterial({ albedo: brick, normal: normalMapFromHeight(brick), roughness: 0.9 });+```++Six operations compose the whole space: `solid`, `checker`, `stripes`, `gradient`, `bricks`, and+tileable `noise`. Each layer carries a blend mode and an opacity, up to eight layers deep, and+`normalMapFromHeight` derives relief from any of it, which is where most of the surface read actually+comes from. That is a small vocabulary on purpose, and it is deliberately *not* the obvious API. The+obvious API hands the model a per-pixel callback, and a callback is arbitrary code with arbitrary cost+and no reviewable record of what it drew. A layer stack is bounded before a single pixel is written,+recorded verbatim in the asset's provenance, and reproducible from the manifest alone. Noise hashes+the lattice coordinate with a seed rather than calling `Math.random`, and wraps at the cell period, so+the same program produces the same bytes on every machine and a wall does not show a seam where the+pattern restarts.++The second is the **scanned library**: sixteen [Poly Haven](https://polyhaven.com) CC0 families, each+shipping an albedo map, an OpenGL normal map, and a packed ambient-occlusion / roughness / metalness+map. Bark, planks, finished oak veneer, concrete, brick, cobblestone, clay roof tiles, marble, rock+face, dry soil, denim, leather, forest leaf litter, rubber, steel plate, and rust. They are embedded+in the package at 128px, which keeps the whole library under a megabyte, and the model binds one by+its `kiln.texture.*` ID rather than by a path or a URL. That identifier is checked against a closed+registry, so an invented ID is a validation error rather than a silent miss, and a generated asset+never reaches for the network at runtime.++Which one to use is not a toss-up. Procedural wins for anything regular and man-made where the model+knows the actual dimensions: brickwork, panelling, tiling, painted stripes, plate seams. The library+wins for organic irregularity, where a layer stack produces something that reads as generated and a+photograph does not: bark, soil, leaf litter, worn leather. Most convincing surfaces use both, with+the photograph as the base and procedural layers over it for wear specific to *this* object.++**Neither path is a diffusion model, and that is a boundary rather than a gap.** A texture computed+from numbers has no third-party provenance to track and no licence to propagate; a scanned family has+one licence, recorded once, in a file you can read. Both are byte-reproducible, which is what lets the+repository pin texture fixtures at all. Sampling a texture at authoring time would trade all three of+those away for surfaces the two existing paths already cover, and it would put a network call and a+provider key inside a loop whose entire claim is that it needs neither. Expanding the scanned library+is a networked, opt-in curation script that runs offline and checks its output in; that is the seam+where new pixels enter, and it is deliberately not the seam where assets are made.++## Dispatching a headless agent++Once Kiln is attached to a CLI harness, that harness can be driven headlessly, which means an agent+you are already talking to can spawn a second agent whose entire job is to build one asset and hand+back a GLB. This is the useful shape for batch work: ten assets, ten child agents, a cheaper model+doing the grunt work while your main session stays on the thing you care about.++The recipe is one line, and it is the same line for every harness:```bash-git clone https://github.com/matthew-kissinger/kiln && cd kiln && bun install-bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png+# Antigravity CLI, verified end to end with Gemini 3.8 Flash and 3.1 Pro+agy --model gemini-3.8-flash-high --print-timeout 25m --add-dir /abs/path/to/sandbox \+ --print="Read /abs/path/to/brief.txt and carry out the instructions in it exactly."++# Claude Code+claude -p "Read /abs/path/to/brief.txt and carry out the instructions in it exactly." \+ --model sonnet --permission-mode acceptEdits --add-dir /abs/path/to/sandbox++# Codex CLI, where --approve-for-me is what lets it call the tools at all+codex exec --approve-for-me --skip-git-repo-check --cd /abs/path/to/sandbox "Read /abs/path/to/brief.txt and carry out the instructions in it exactly."++# OpenCode, which reaches a dozen vendors' models behind provider/model ids+opencode run --auto --dir /abs/path/to/sandbox -m opencode-go/glm-5.3-flash "Read /abs/path/to/brief.txt and carry out the instructions in it exactly."```-If that writes a GLB and a contact sheet, the engine is fine and anything that goes wrong later is-transport configuration.+That Codex flag is the one non-obvious item in the block. `codex exec` pins its approval policy to+`never`, and under that policy an MCP call is refused rather than queued, so a run reports that+`kiln_list_primitives` was blocked and writes nothing at all. `--approve-for-me` moves approval to+automatic review and selects the workspace-write sandbox itself, which is why it cannot be combined+with `--sandbox`.-<details>-<summary><b>Claude Code</b></summary>+[`scripts/dispatch-asset.mjs`](scripts/dispatch-asset.mjs) wraps that, composes the brief, and then+**verifies the result with the engine rather than with the child's own report**:```bash-claude plugin marketplace add matthew-kissinger/kiln-claude plugin install kiln@kiln+node scripts/dispatch-asset.mjs --name water-tower \+ "an American small-town steel water tower on a riveted lattice frame"++node scripts/dispatch-asset.mjs --harness claude --model sonnet --name anglerfish \+ "a deep-sea anglerfish with a glowing lure"```-Verify with `claude mcp list` — you want `plugin:kiln:kiln … ✔ Connected`.-</details>+It writes `<name>.kiln.js`, `<name>.glb`, the six-view sheet, the exact brief it sent, and the child's+transcript into `.dogfood/`, then exits non-zero if `kiln render` refuses the result.-<details>-<summary><b>Antigravity CLI (<code>agy</code>)</b></summary>+### Pick a model that can see++Kiln's loop is the model looking at its own render, so the one capability that is not optional is+image input. A text-only model still produces a file -- it writes blind, from the API documentation+alone -- and it produces a noticeably worse one for a reason that is easy to misread as the model+being weak.-The portable `plugin.json` is accepted unchanged:+This is worth a preflight rather than a guess. A nine-model batch here turned out to have four+text-only models in it, chosen by name from a provider list on the assumption that a current+flagship accepts images; nothing in the run said otherwise, and the resulting assets were quietly+not evidence of anything. Note also that vision can differ between a vendor's variants, which is the+sort of thing you find by checking rather than by reasoning: `glm-5.3-flash` sees images and plain+`glm-5.3` does not.```bash-agy plugin install .+node scripts/check-vision.mjs opencode-go/kimi-k3 opencode-go/glm-5.3+# opencode-go/kimi-k3 sees images+# opencode-go/glm-5.3 TEXT ONLY```-Then register the server in `~/.gemini/config/mcp_config.json` with an **absolute** path, because-Antigravity has no plugin-root variable:+It exits non-zero and names the offenders, so a batch script can refuse to start.-```json-{- "mcpServers": {- "kiln": {- "command": "bun",- "args": ["/absolute/path/to/kiln/src/mcp-server.ts"],- "env": { "KILN_RENDER": "auto" }- }- }-}-```+### The child gets a clean room-For headless (`agy -p`) runs you also need permission grants in-`~/.gemini/antigravity-cli/settings.json`. Scoped `mcp()` and `write_file()` rules work; `command()`-targets are soft-denied in print mode whatever the syntax, so only `command(*)` passes — see-[`docs/install.md`](docs/install.md#headless-permissions) for the evidence and the upstream issue.-</details>+Each dispatch runs in a directory of its own containing exactly two things: the brief, and the five+Kiln skills. Not the engine source, not `AGENTS.md`, and above all not `examples/`.-<details>-<summary><b>Cursor, Codex CLI, Zed, or any MCP client</b></summary>+That last one is the point. These runs are the evidence behind the claim that the tools teach the+API, and for a while they were not evidence of much, because the harness was pointed at this+repository and a child agent could open every finished program in `examples/` and copy an interface+it never had to learn. An asset built that way demonstrates that the model can read. Scoping the write grant+to the sandbox and starting the child inside it is what makes the result mean what it claims to.-Point the client at `src/mcp-server.ts` with an **absolute** path. The server resolves its own paths-from `import.meta.url` and never reads `process.cwd()`, so the launch directory does not matter:+The directory sits in the OS temp area rather than under `.dogfood/`, which matters more than it+looks like it should. Every CLI here finds the project it is working in by walking up from the+working directory to the nearest `.git`, so a sandbox nested inside the repository resolves straight+back to the repository and isolates nothing at all.-```json-{- "mcpServers": {- "kiln": {- "type": "stdio",- "command": "bun",- "args": ["run", "/absolute/path/to/kiln/src/mcp-server.ts"],- "env": { "KILN_RENDER": "auto" }- }- }-}-```-</details>+What this does not isolate is worth stating plainly: skills and MCP servers installed at *user*+scope are still in reach, because no harness here exposes a per-run flag that would suppress them.+What goes away is this repository.-<details>-<summary><b>In-process TypeScript, no MCP</b></summary>+### What the brief has to say-```ts-import { createKilnToolRegistry } from 'kiln/tools';-```+Four things, and each one is in there because leaving it out produced a bad run.-`kiln/tools` imports no agent SDK, so porting to a harness that is not Strands does not drag Strands-along. [`examples/strands-harness.ts`](examples/strands-harness.ts) is the whole integration in about-sixty lines.-</details>+Absolute paths, everywhere. Every CLI resolves relative paths against something and it is rarely your+working tree; `agy` resolves them against the installed plugin copy under+`~/.gemini/config/plugins/kiln`. A brief that says `examples/foo.js` writes a file you will not find.-The MCP server exposes the **raw tools**, which means *your* agent is the author — it writes the-program, looks at the render, and iterates using its own model. No separate provider key, no nested-agent loop.+`kiln_list_primitives` before anything else. Without it the model writes the API it remembers from+some other engine, and every call fails on a name that does not exist.-Note that in this mode your harness supplies both the author and the vision judge. The-deterministic gates still run independently, but the eyes/judge separation the production system-maintained is collapsed. That is a deliberate trade for portability.+An instruction to look at the render and fix what it sees. A model that is not told to look will+write one pass, declare success, and stop. The loop is the entire argument for this tool, and codegen+without it is not worth a round trip.++A triangle budget. Unbounded, models either build twelve boxes or forty thousand triangles of+greebling, and neither one is a game asset.++### Pass the brief in a file, not on the command line++`agy` mangles a multi-line `--print=` argument through a shell, npm-installed CLIs on Windows are+`.cmd` shims that *require* a shell, and a shell cannot carry a multi-line argument. Writing the brief+to a file and passing a one-line pointer sidesteps all of it, works identically on every harness and+OS, and leaves the exact brief on disk next to the result.++### What dispatching is actually for++It is how you make a lot of assets. One dispatch is one asset, so a batch is a loop over briefs, and+because the child verifies its own work against the same gates CI runs, the batch does not need+watching: what comes back is either a program that passed or a log that says why it did not. Several+of the assets in the gallery arrived that way while this README was being written.++It is also the cheapest way to find out whether the documentation on this page is true. The first batch run+against Gemini turned up a real engine bug inside one asset: `THREE.LatheGeometry` emits one ring of+non-unit normals, which no raster ever shows you because a shader normalises before it lights, and+which the glTF validator rejects outright. Every lathed cup and saucer in that model blocked the build+at `final-glb`. Fixed in `src/ops.ts`, with+[`src/__tests__/lathe-normals.test.ts`](src/__tests__/lathe-normals.test.ts) pinning it. Nothing+in the hand-written examples had ever hit it, because none of them happened to lathe a profile+whose last segment was short.## Tool surface| Tool | What it does ||---|---|| `kiln_list_primitives` | the primitive/helper catalog with signatures |-| `kiln_validate` | AST validation — syntax, structure, infinite loops, recursion |+| `kiln_validate` | AST validation: syntax, structure, infinite loops, recursion || `kiln_render` | build the scene, return metrics **and** the six-view sheet, in one call |+| `kiln_edit` | patch an existing program with exact-string edits, and render the result || `kiln_screenshot_animation` | frames of an `animate()` program, so motion is visible too || `kiln_view_interior` | interior camera, for anything enterable || `kiln_inspect` | close-up orbit camera on a named part |-Every one of these comes from a factory in [`src/tools/registry.ts`](src/tools/registry.ts); no-transport hand-writes a definition, and `src/mcp-parity.test.ts` is what keeps that true.--`kiln_render` here is the *unified* definition — the one that returns metrics and pixels together,+`kiln_render` here is the *unified* definition, the one that returns metrics and pixels together,accepts a custom camera capture, routes to the GPU when the scene needs PBR shading, and reports-`viewFidelity` so the agent knows whether it may judge material from what it is looking at. The-engine also carries a frozen four-tool bench baseline whose `kiln_screenshot` is CPU-only by-construction; the in-process loop still runs that baseline plus a terminal `kiln_submit`. Shipping-the baseline over MCP would have meant shipping a surface the render port can never reach.+`viewFidelity` so the agent knows whether it may judge material from what it is looking at. The engine+also carries a frozen four-tool bench baseline whose `kiln_screenshot` is CPU-only by construction;+the in-process loop still runs that baseline plus a terminal `kiln_submit`. Shipping the baseline over+MCP would have meant shipping a surface the render port can never reach.++`kiln_edit` is the refine verb, and it exists because authoring an asset and changing one are not the+same job. Without it, "make the roof taller" meant re-emitting the whole program through+`kiln_render` and hoping the other two hundred lines came back the way they went in. It takes exact+string replacements instead, applies them in order, refuses to guess when one matches twice, and+applies nothing at all if any of them fails -- so a bad edit costs a retry rather than a program the+model has to diff against its own intent. It returns the patched source, a unified diff, and the new+contact sheet together, because the loop is edit-then-look. It holds no state between calls: the+in-process agent keeps a working buffer across turns, but over MCP the host owns the program text,+and putting a second copy inside the server would have created a desync the model cannot see.## Subpath exports@@ -303,7 +783,7 @@ The engine ships TypeScript source; consume by subpath:| Import | What ||---|---|-| `kiln/tools` | the tool registry — the single source of truth, and free of any agent SDK |+| `kiln/tools` | the tool registry, the single source of truth, free of any agent SDK || `kiln/agent` | the Strands agent loop, model factory, tool surface, edit buffer, unified diff || `kiln/render` | GLB build + serialize, grade/optimize/snap, `composeScene` || `kiln/views` | the pure-CPU six-view rasterizer + `node:zlib` PNG encoder |@@ -314,21 +794,39 @@ The engine ships TypeScript source; consume by subpath:| `kiln/palette` | canonical `OPTIMIZED_PALETTE` + directive (pure data, browser-safe) || `kiln/metrics`, `kiln/inspect` | instanceability grade + scene-structure analysis || `kiln/contracts` | asset and integration contracts, `IntegrationManifestV1`, semantic roles |-| `kiln/composer` | THREE-free scene composition — layout, overlap resolution, scene DSL |+| `kiln/composer` | THREE-free scene composition: layout, overlap resolution, scene DSL |-Finished renders include `integrationManifest`, a versioned sidecar carrying the artifact hash,-metres/+Y-up axes, bounds, grounding offset, default scene, role, render metrics, and structural QA.-Consumers holding only GLB bytes can derive the same sidecar with `inspectGlbIntegration(bytes)`;-that path parses the artifact and never executes model-authored source.+Consumers holding only GLB bytes can derive the same integration sidecar with+`inspectGlbIntegration(bytes)`; that path parses the artifact and never executes model-authored+source. Visual quality stays explicitly `not_assessed` until something actually looks at the asset in+its real scene, because structural validation is not a visual pass.-Visual quality stays explicitly `not_assessed` until something actually looks at the asset in its-real scene. Structural validation is not a visual pass.+## How it is put together++The architecture is the part most likely to be useful outside 3D.++[`src/tools/registry.ts`](src/tools/registry.ts) is the single definition of every tool. The+in-process Strands skin and the MCP server both iterate that registry rather than hand-writing their+own schemas, so the two transports cannot drift apart, and `src/mcp-parity.test.ts` fails the build if+they start to.++Model judgment and deterministic judgment sit in separate layers on purpose. The gates run with no+model call and no pixels; the model's vision is advisory on top of them. That ordering is what stops a+confident wrong answer from promoting a broken asset, and it is why the gates keep working when the+render degrades.++`captureViewsViaPort` owns the render deadline, PNG validation, grid composition, and a fallback that+never throws. Renderers are swappable behind it and correctness does not depend on which one ran.++Budgets and compaction are first-class, because an agent loop that renders images runs out of context+and money faster than one that does not, and both of those failures look like the model getting stupid+rather than the loop running out of room.## Determinism-Render and rasterizer compute paths use no `Date.now()` or `Math.random()`, so CPU six-view output-is byte-reproducible — the basis for golden-image tests. Inject seeds and timestamps at the-boundary.+Render and rasterizer compute paths use no `Date.now()` or `Math.random()`, so CPU six-view output is+byte-reproducible, which is what makes golden-image tests possible at all. Inject seeds and timestamps+at the boundary.## Tests@@ -338,45 +836,81 @@ bun run test # offline; live agent tests gated behind KILN_SPIKE_LIVE=bun run test:coverage # LCOV plus the checked coverage ratchet```-Baseline is **95.38% functions / 91.80% lines** across 130 test files. CI enforces non-regression-ratchets of 92% and 91% and uploads `coverage/lcov.info`.-Threshold decreases require an explicit measured rationale.-Tests pin `KILN_RENDER=cpu` so coverage cannot vary by runner GPU.+1,549 tests across 144 files, at a measured **95.96% functions / 92.54% lines**. CI enforces+non-regression ratchets of 92% and 91% and uploads `coverage/lcov.info`; threshold decreases require+an explicit measured rationale. Tests pin `KILN_RENDER=cpu` so coverage cannot vary by runner GPU, and+the example suite executes every checked-in program on every run, then checks this README's triangle+counts against what actually came out.## DependenciesRuntime: `three`, `@gltf-transform/*`, `manifold-3d` (CSG, WASM), `three-subdivide`,-`acorn`/`acorn-walk`, `zod`, plus lazy-loaded `sharp` (texture decode) and `xatlasjs` (UV atlas).-The agent stack — `@strands-agents/sdk` + `@ai-sdk/provider` — is an **optional peer**: install it-only if you use `kiln/agent`.+`acorn`/`acorn-walk`, `zod`, plus lazy-loaded `sharp` (texture decode) and `xatlasjs` (UV atlas). The+agent stack, `@strands-agents/sdk` + `@ai-sdk/provider`, is an **optional peer**: install it only if+you use `kiln/agent`.-Textures are eight [Poly Haven](https://polyhaven.com) CC0 families, embedded with source provenance-retained. Runtime output is self-contained and never calls Poly Haven.+Textures are sixteen [Poly Haven](https://polyhaven.com) CC0 families, embedded with source+provenance retained. Runtime output is self-contained and never calls Poly Haven.### `@ai-sdk/provider` is pinned to v3 by Strands, not by usDo not bump `@ai-sdk/provider` to v4 or `@openrouter/ai-sdk-provider` to v3. Every-`@strands-agents/sdk` version through 1.11.1 peers `@ai-sdk/provider@^3.0.0`, and its `VercelModel`-is typed against `LanguageModelV3`. A cast does not help, because Strands emits V3 shapes at-*runtime*: `vercel.js` sends `{type: 'file', data: <bare bytes>}` where V4 expects-`{type: 'data', data}`, plus `{type: 'file-data', ...}`, which does not exist in V4 at all.+`@strands-agents/sdk` version through 1.11.1 peers `@ai-sdk/provider@^3.0.0`, and its `VercelModel` is+typed against `LanguageModelV3`. A cast does not help, because Strands emits V3 shapes at *runtime*:+`vercel.js` sends `{type: 'file', data: <bare bytes>}` where V4 expects `{type: 'data', data}`, plus+`{type: 'file-data', ...}`, which does not exist in V4 at all.-v4 is purely additive and the only real change here would be one string in three files — which is+v4 is purely additive and the only real change here would be one string in three files, which isexactly why it looks deceptively easy. Stay on `@openrouter/[email protected]` until Strandsships v4 support.+## Contributing++The most useful thing you can send is an asset that came out wrong.++Every fix in `src/` worth having started as a render that looked stupid. `THREE.LatheGeometry`+emitting one ring of non-unit normals, which no raster will show you and which the glTF validator+rejects outright. Orthographic views framing at 45% fill because the camera fit was a guess against+the bounding box rather than a projection of its corners. A quarter turn about Y sending an extruded+profile's u to world -z, which sprang every flying buttress in the cathedral off the pier on the+opposite side. None of those were found by reading the code.++So point `node scripts/dispatch-asset.mjs` at a subject none of the examples covers. Whatever breaks+is a bug report with a reproduction already attached, and if nothing breaks, the asset itself is worth+a pull request.++Places where another pair of hands would obviously help:++- The GPU renderer speaks WebGPU through Dawn and nothing else. A Vulkan or Metal path widens+ where it runs.+- Claude Code, the Antigravity CLI, OpenCode, Hermes and Codex are verified end to end. Cursor and+ Zed are documented from the MCP contract but unproven, and confirming either one is a contained,+ high-value contribution.+- Organic form is the weak axis, as the section above admits. A profile and sweep vocabulary that+ handles soft shapes without a sculpt would move that boundary.+- `kiln/arena` implements Bradley-Terry pairwise ranking for model bake-offs and has only ever been+ pointed at a handful of providers. Anyone holding a key for a model not represented here can+ produce a result nobody has.+- More skills. The five that ship cover authoring, refining, composition, in-project QA, and batch+ dispatch. Rigging, LODs, and material authoring are all unwritten.++Before opening a pull request, `bun run lint`, `bun run typecheck` and `bun run test` must pass. CI+pins `KILN_RENDER=cpu` so a runner that happens to have a GPU cannot change what the golden-image+tests compare against. [`AGENTS.md`](AGENTS.md) is the operating manual if you want to point an agent+at this repository, which is a reasonable thing to do here.+## History-Kiln was a commercial text-to-3D product. It is shut down; this is the engine, which is the half-that stays true regardless of how the product did.+Kiln was a commercial text-to-3D product. It is shut down; this is the engine, which is the half that+stays true regardless of how the product did.-Some of the design here reflects constraints that no longer apply — most visibly the CPU rasterizer,-which exists because the production agent runtime container had no GPU. Where an original decision-made sense only for a hosted multi-tenant product, this repo does the thing that makes sense for an+Some of the design reflects constraints that no longer apply, most visibly the CPU rasterizer, which+exists because the production agent runtime container had no GPU. Where an original decision made+sense only for a hosted multi-tenant product, this repository does the thing that makes sense for anopen one, and `docs/history/` records what the production system did and why.-Initially extracted from the `pixel-forge` monorepo with file history preserved via-`git subtree split`. See `CHANGELOG.md`.+Initially extracted from the `pixel-forge` monorepo with file history preserved via `git subtree+split`. See `CHANGELOG.md`.## Licensediff --git a/docs/history/production-architecture.md b/docs/history/production-architecture.mdindex 90c0fbda..a7f49348 100644--- a/docs/history/production-architecture.md+++ b/docs/history/production-architecture.md@@ -2,7 +2,7 @@Kiln was a commercial text-to-3D product. It is shut down. This document records what the hostedsystem looked like, because several decisions still visible in this repo only make sense against-that background — and because the reasoning is the interesting part.+that background -- and because the reasoning is the interesting part.Nothing here is required to use the engine. It is history.@@ -30,7 +30,7 @@ These are still in the code and still correct.### The render port owns its own degrade-`captureViewsViaPort` — in the engine, not the host — owns the deadline, PNG decode and count+`captureViewsViaPort` -- in the engine, not the host -- owns the deadline, PNG decode and countvalidation, grid composition, and a never-throw fallback to the CPU rasterizer. The host adapterdeliberately just builds a request, POSTs it, and maps the response; its thrown errors are*intentional*, because the shell catches them.@@ -50,9 +50,9 @@ non-deterministic eye out of the judge path is what makes the gates trustworthy.### Two injection seams, two deadlines-The port is injected twice. Once after the loop, for the artifact sheet — nothing waits on it, so a+The port is injected twice. Once after the loop, for the artifact sheet -- nothing waits on it, so along deadline (120s in production) is correct. Once inside `kiln_render`, for the grid the model-actually looks at — that one blocks the agent mid-thought, so it got 6s.+actually looks at -- that one blocks the agent mid-thought, so it got 6s.Collapsing those onto one value breaks one of the two jobs. In production, using the post-loopdeadline in-loop would have stalled every first render of a session, because serverless GPU cold@@ -64,7 +64,7 @@ Originally the GPU ran only *after* the loop. That meant the model authored matesee: it wrote `pbrMaterial(...)`, then checked its work against a flat-shaded image that cannot showwhether the result reads as wet stone or as plastic.-Routing GPU renders into the loop fixed that, conditionally — `sceneNeedsPbrShading` checks bound+Routing GPU renders into the loop fixed that, conditionally -- `sceneNeedsPbrShading` checks boundtextures and `metalness > 0`, and nothing else. Material *type* is deliberately not consulted,because `gameMaterial` and `pbrMaterial` both construct a `MeshStandardMaterial` and areindistinguishable after construction. Roughness is not a signal either, since `gameMaterial` sets it@@ -95,7 +95,7 @@ browser: it shipped with `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1`, Playwright is unson Windows, and `headless-gl` is WebGL1 while three >= r163 requires WebGL2. So: a dependency-freescanline z-buffer rasterizer, flat lambert, base color only.-It turned out to be worth keeping for reasons that had nothing to do with the original constraint —+It turned out to be worth keeping for reasons that had nothing to do with the original constraint --it is deterministic, it needs no install, and it is sufficient for silhouette, proportion,orientation, and contact. But it was never chosen as the better renderer, and this repo does notpretend otherwise.diff --git a/docs/install.md b/docs/install.mdindex 18dc3e7c..ca86a67a 100644--- a/docs/install.md+++ b/docs/install.md@@ -2,8 +2,9 @@Kiln exposes one tool surface over two transports. Pick the one your harness speaks.-Everything below needs [Bun](https://bun.sh) on `PATH` — the package ships TypeScript source rather-than a build artifact, which is also why the entry point is a `.ts` file.+Everything below starts with a clone and its dependencies, because the engine ships TypeScript+source rather than a published package. [Bun](https://bun.sh) is the development toolchain and+installs them.```bashgit clone https://github.com/matthew-kissinger/kiln && cd kiln@@ -20,29 +21,64 @@ That runs the full geometry build, the QA gates, and the rasterizer with no modeGPU, and no key. If it produces a GLB and a contact sheet, the engine is fine and any later problemis transport configuration.+## The server runs on Node++Every config on this page launches `dist/mcp-server.mjs` with `node`. That is a committed bundle,+and both halves of that sentence were forced by real failures.++It is **Node** because `"command": "bun"` asks the harness to resolve a name against its own PATH,+and on Windows that is a coin flip: Bun's installer appends to the *User* PATH, and a process only+ever sees the environment it was born with, so anything started before the install dies with+`exec: "bun": executable file not found in %PATH%`. There is not one Bun-specific API on the+server's runtime path, so bundling for Node takes Bun out of a user's requirements entirely.++It is **committed** because a plugin install is a git clone with no build step, so an artifact that+is built on demand is an artifact that is not there when the harness looks for it.++Rebuild it with `bun run build:mcp` after changing anything under `src/`.+[`src/__tests__/mcp-bundle.test.ts`](../src/__tests__/mcp-bundle.test.ts) rebuilds it, compares byte+for byte against the committed copy, and then speaks real MCP to it under `node`, so a stale or+broken bundle fails the suite rather than somebody's install.+## As an MCP server-Point your client at `src/mcp-server.ts` with an **absolute** path. The server resolves every+Point your client at `dist/mcp-server.mjs` with an **absolute** path. The server resolves everyinternal path from `import.meta.url` and never reads `process.cwd()`, so the working directory the-client launches it in does not matter — only that the script path is right.+client launches it in does not matter -- only that the script path is right.```json{"mcpServers": {"kiln": {"type": "stdio",- "command": "bun",- "args": ["run", "/absolute/path/to/kiln/src/mcp-server.ts"],+ "command": "node",+ "args": ["/absolute/path/to/kiln/dist/mcp-server.mjs"],"env": { "KILN_RENDER": "auto" }}}}```+Codex CLI keeps the same server in TOML at `~/.codex/config.toml`:++```toml+[mcp_servers.kiln]+command = "node"+args = ["/absolute/path/to/kiln/dist/mcp-server.mjs"]+env = { KILN_RENDER = "auto" }+```++Interactive `codex` asks before each MCP call and the server works as soon as the block above is in+place. `codex exec` does not ask: it pins the approval policy to `never`, and under that policy an+MCP call is refused rather than queued, so a scripted run reports that `kiln_list_primitives` was+blocked and writes nothing. Pass `--approve-for-me`, which selects the workspace-write sandbox and+routes approvals through automatic review. It cannot be combined with `--sandbox`, because it sets+that itself.+Set `KILN_RENDER` to `cpu` to pin the deterministic rasterizer, or `gpu` to fail loudly rather thandegrade. `KILN_RENDER_PORT_URL` (plus `KILN_RENDER_TOKEN`) routes views to a GPU render service.-**For textured or metallic assets, run the GPU renderer** — it ships in this repository:+**For textured or metallic assets, run the GPU renderer** -- it ships in this repository:```bashcd render-service && npm install && npm start@@ -52,7 +88,7 @@ It listens on `:8000`, which is where `auto` looks, so the MCP server picks it uconfiguration. See [`render-service/README.md`](../render-service/README.md) and the render-modessection of the [README](../README.md).-Your agent gets six tools and is the author: it writes the program, looks at the render, and+Your agent gets seven tools and is the author: it writes the program, looks at the render, anditerates with its own model. There is no nested agent loop and no second provider key.## As an Agent Plugin@@ -60,23 +96,35 @@ iterates with its own model. There is no nested agent loop and no second provideThe repository is also a plugin package. Two manifest conventions exist as of late 2026 and Kilnships both, because they disagree on filenames and on the path variable:-| | Portable spec | Claude Code | Antigravity |+| | Claude Code | Antigravity | OpenCode ||---|---|---|---|-| Manifest | `plugin.json` | `.claude-plugin/plugin.json` | `plugin.json` (reuses the portable one) |-| MCP config | `mcp.json` | inline `mcpServers` in the manifest | `mcp_config.json` |-| Plugin-root variable | `${PLUGIN_ROOT}` | `${CLAUDE_PLUGIN_ROOT}` | none — absolute paths |-| Skills | `skills/<name>/SKILL.md` | same | same |+| Manifest | `.claude-plugin/plugin.json` | `plugin.json` (the portable spec, reused) | none -- no plugin manifest exists |+| MCP config | inline `mcpServers` in the manifest | `mcp_config.json` | user's `opencode.json`, under `mcp` |+| Plugin-root variable | `${CLAUDE_PLUGIN_ROOT}` | none -- absolute paths | none -- absolute paths |+| Consumed today? | yes | no -- see below | yes, via config rather than install |+| Skills | `skills/<name>/SKILL.md` | same | same files, copied into a skills directory |++A third filename, a bare `mcp.json` at the repository root, is specified by the portable Agent+Plugin spec and is read by none of the three. It used to ship here and was removed once that was+measured rather than assumed.The skills are the same files in both cases. Installing the plugin gives you the MCP tools *and*-the three skills that teach an agent to use them well:+the five skills that teach an agent to use them well:| Skill | When it fires ||---|---|-| `kiln-author-asset` | create, model, build, or refine an asset |+| `kiln-author-asset` | create, model, or build an asset that does not exist yet |+| `kiln-refine-asset` | change an asset that already has a program, by patching it || `kiln-qa-asset` | wire a finished GLB into a real project and prove it works || `kiln-compose-scene` | lay out several finished GLBs into one scene |+| `kiln-batch-dispatch` | wire another harness up, or generate a whole library at once |++Together their front matter is 1,698 characters, about four hundred tokens of always-on context;+the bodies load only when a skill fires.-Together they cost about 215 tokens of always-on context; the bodies load only when a skill fires.+`kiln-batch-dispatch` is the odd one out: the other four are read by the agent building the asset,+and that one is read by whoever is pointing agents at the problem. It covers the rest of this page+as a procedure, the smoke test below, and the clean-room dispatcher the gallery was built with.### Claude Code@@ -85,7 +133,7 @@ claude plugin marketplace add matthew-kissinger/kilnclaude plugin install kiln@kiln```-Verify with `claude mcp list` — you want `plugin:kiln:kiln … ✔ Connected`.+Verify with `claude mcp list` -- you want `plugin:kiln:kiln … ✔ Connected`.Claude Code's MCP config is declared **inline in `.claude-plugin/plugin.json`** rather than in aroot `.mcp.json`. That is deliberate: `.mcp.json` at a repository root is also Claude Code's@@ -93,9 +141,33 @@ root `.mcp.json`. That is deliberate: `.mcp.json` at a repository root is also Cevery contributor who opens this repo a broken server entry and a warning. Declaring it in themanifest works identically for installed users and leaves the repo clean for contributors.+#### Headless permissions++`claude -p` cannot prompt either, and `--permission-mode acceptEdits` is not enough on its own: it+grants writes and says nothing about MCP tools, so a run that reaches for `kiln_render` blocks on a+confirmation with no terminal attached. What comes back is a clean exit, no file, and a polite note+explaining which permissions the model would have needed.++Grant the server in a settings file the run will read -- the working directory's+`.claude/settings.json` is enough, and keeps the grant scoped to that directory:++```jsonc+// <working directory>/.claude/settings.json+{+ "permissions": {+ "allow": ["mcp__kiln", "mcp__plugin_kiln_kiln", "Read", "Write", "Edit", "Glob", "Grep"]+ }+}+```++Naming the server twice is not redundant: the tool prefix depends on how Kiln was installed, and it+is `plugin_kiln_kiln` for a plugin install and `kiln` for a plain `claude mcp add`. Allowing the+server allows its tools. `scripts/dispatch-asset.mjs` writes exactly this file into each sandbox,+which is why an unattended batch does not need `--dangerously-skip-permissions`.+### Antigravity (`agy`)-Antigravity accepts the portable `plugin.json` unchanged — no Google-specific manifest is needed,+Antigravity accepts the portable `plugin.json` unchanged -- no Google-specific manifest is needed,which is the whole point of shipping to a spec:```bash@@ -103,28 +175,38 @@ agy plugin validate . # ok - 3 skills, 1 mcpServeragy plugin install .```-That installs the skills. **Getting the tools attached takes one more step**, for two reasons worth-knowing before you start:+That installs the skills, and only the skills. **Getting the tools attached takes one more command**,+and the reason is worth knowing because the failure is silent and the diagnostics contradict each+other. Measured on `agy` 1.1.25: the CLI finds a plugin's `mcp_config.json` and reports it,-1. Antigravity documents no plugin-root path variable, so a `${PLUGIN_ROOT}` in a plugin's- `mcp_config.json` does not expand.-2. As of `agy` 1.1.15 a plugin's `mcp_config.json` is staged but not merged into the session's- server list.+```+agy plugin validate .+ [ok] .+ skills : 3 processed+ mcpServers : 1 processed+```-So register the server in Antigravity's central config, `~/.gemini/config/mcp_config.json`, with an-absolute path — this is the file the CLI, the IDE, and Antigravity 2.0 all share:+and then never merges it into the session:-```json-{- "mcpServers": {- "kiln": {- "command": "bun",- "args": ["/absolute/path/to/kiln/src/mcp-server.ts"],- "env": { "KILN_RENDER": "auto" }- }- }-}```+agy mcp list+ No MCP servers configured.+```++The agent sees no tools, while `plugin validate` insists the server was processed. Uninstalling and+reinstalling the plugin does not change it, and neither does the path variable, which is why this+page no longer suggests hand-editing a config file at all. Register the server with the CLI's own+command:++```bash+agy mcp add --env KILN_RENDER=auto kiln node /absolute/path/to/kiln/dist/mcp-server.mjs+agy mcp list # kiln stdio enabled node /absolute/path/to/kiln/dist/mcp-server.mjs+```++That writes the entry into `~/.gemini/config/mcp_config.json` itself -- the file the CLI, the IDE+and Antigravity 2.0 share -- so there is no JSON to get wrong. Kiln still ships a correct+`mcp_config.json` in the plugin root, pointed at the same bundle, so that the day `agy` starts+merging it the plugin works with one command instead of two.Remote servers use `serverUrl` rather than `url` or `httpUrl`, which are not supported.@@ -155,8 +237,8 @@ A second file, `~/.gemini/config/config.json`, contributes *shared* grants under`--log-file` and those two lines tell you what the CLI actually parsed.**`command` is the one rule kind that does not accept a target in headless mode.** The documented-syntax — each whitespace-separated token as an anchored regex, e.g. `command(git)` or-`command(npm run (build|lint|test))` — parses correctly and still gets denied:+syntax -- each whitespace-separated token as an anchored regex, e.g. `command(git)` or+`command(npm run (build|lint|test))` -- parses correctly and still gets denied:```tool_confirmation_manager.go:188] Print mode: soft-denying tool confirmation "RunCommand" at step 2@@ -164,7 +246,7 @@ tool_confirmation_manager.go:188] Print mode: soft-denying tool confirmation "RuOnly `command(*)` passes. This is upstream[antigravity-cli#548](https://github.com/google-antigravity/antigravity-cli/issues/548). Scope the-blast radius with `trustedWorkspaces`, a path-scoped `write_file`, and a `deny` list instead —+blast radius with `trustedWorkspaces`, a path-scoped `write_file`, and a `deny` list instead --those are honoured. `mcp(kiln/*)` and `write_file(<abs path>)` were both verified working inheadless mode with the shared wildcard removed, so scope everything you can and treat `command(*)`as the known exception rather than the default.@@ -180,7 +262,214 @@ Three more sharp edges:`README.md` reads the wrong file.Verified end to end with Gemini 3.8 Flash, which authored-[`examples/arcade-cabinet.kiln.js`](../examples/arcade-cabinet.kiln.js) through this path.+[`examples/radio-telescope.kiln.js`](../examples/radio-telescope.kiln.js) through this path -- and+six more of the gallery besides. Every program it wrote says so on its first line.++### OpenCode++OpenCode is the odd one out in a useful way: it has a skills system that reads Anthropic's+`SKILL.md` layout unchanged, and a plugin system that has nothing to do with either. OpenCode+plugins are JavaScript modules that hook into events; there is no manifest, no marketplace and no+install command that would consume this repository's `plugin.json`. So the MCP server is wired up+through config, and the skills are copied.++The MCP half goes in `~/.config/opencode/opencode.json` (global) or an `opencode.json` at a project+root. Both accept JSONC, and `OPENCODE_CONFIG` overrides the path:++```json+{+ "$schema": "https://opencode.ai/config.json",+ "mcp": {+ "kiln": {+ "type": "local",+ "command": ["node", "/absolute/path/to/kiln/dist/mcp-server.mjs"],+ "enabled": true,+ "environment": { "KILN_RENDER": "auto" },+ "timeout": 30000+ }+ }+}+```++Four differences from the shape every other client on this page uses, all of them silent failures if+you paste someone else's config:++- the top-level key is `mcp`, not `mcpServers`+- `type` is `"local"`, not `"stdio"`+- the interpreter and its arguments are one `command` array, not `command` plus `args`+- environment variables live under `environment`, not `env`++The schema sets `additionalProperties: false`, so a leftover `args` or `env` key is rejected rather+than ignored. That is a kindness; it fails loudly at load instead of quietly at use.++`timeout` bounds the connection handshake rather than the tool calls that follow. The name invites+the other reading, so it is worth stating what was measured: at 200 ms the server does not connect+and `opencode mcp list` reports `kiln failed`, while at 1500 ms it connects and a `kiln_render` call+taking nine seconds still returns its picture. The handshake measured about 1.2 seconds against a+5000 ms default, so the default is already sufficient and an explicit value only covers a slow cold+start.++Verify:++```bash+opencode mcp list+```++You want `kiln connected` and the command line echoed back.++Then the skills. OpenCode searches `~/.config/opencode/skills/`, `~/.claude/skills/` and+`~/.agents/skills/` globally, and `.opencode/skills/`, `.claude/skills/` and `.agents/skills/` per+project. The files here need no modification:++```bash+cp -r skills/* ~/.config/opencode/skills/+```++**Raise the output cap before you judge a model by its assets.** OpenCode limits a single assistant+step to 32,000 output tokens by default, whatever the model's own ceiling is. Measured across every+step in its session store, nothing had ever exceeded that number -- not once, not by a single token+-- while the models involved publish limits between 80,000 and 943,718. A model that plans at length+before it writes hits the cap mid-sentence, and the run ends with no file and no error: four separate+runs, from three vendors, died exactly there. Lift it to the model's own published limit:++```bash+OPENCODE_EXPERIMENTAL_OUTPUT_TOKEN_MAX=128000 opencode run --auto -m opencode-go/<model> "..."+```++[`scripts/dispatch-asset.mjs`](../scripts/dispatch-asset.mjs) sets this per run, reading each model's+declared limit out of OpenCode's own model catalog so the ceiling is the provider's rather than one+picked here.++Two things to expect in a transcript. Tools are namespaced by server, so `kiln_render` is presented+as `kiln_kiln_render` -- harmless, and models locate the tools regardless, but it makes the skill+prose and the tool list look inconsistent. And OpenCode reaches many vendors' models behind+`provider/model` ids, so `opencode models` is worth reading before choosing one; asset quality+tracks the model far more than it tracks the harness.++### Codex CLI++Codex has a marketplace-shaped plugin system that reads this repository's manifest unchanged, so the+install itself is two familiar commands:++```bash+codex plugin marketplace add matthew-kissinger/kiln # or a local path+codex plugin add kiln@kiln+```++`codex plugin list` will then show `kiln@kiln installed, enabled`, and the whole tree is copied into+`~/.codex/plugins/cache/kiln/kiln/<version>`.++**That install does not give the agent the tools.** As of Codex 0.153.3, an installed and enabled+plugin's MCP servers are not registered: with the plugin enabled and no server entry in config, a run+asked to name its `kiln_*` tools answers `NONE`. Its skills do not arrive either. Register the server+yourself, exactly as in the MCP section above:++```toml+[mcp_servers.kiln]+command = "node"+args = ["/absolute/path/to/kiln/dist/mcp-server.mjs"]+env = { KILN_RENDER = "auto" }+```++`codex mcp list` should then show `kiln … enabled`. This is the same trap `agy` sets, and it fails+the same silent way: everything reports success and the agent simply has no tools.++Interactive `codex` asks before each tool call and works from there. `codex exec` does not ask -- it+pins the approval policy to `never`, and a `never` policy **refuses** an MCP call rather than+queueing it, so a scripted run comes back in well under a minute saying `kiln_list_primitives` was+blocked and having written nothing at all. Pass `--approve-for-me`, which routes approvals through+automatic review and selects the workspace-write sandbox itself. It is rejected alongside+`--sandbox`, because it sets that:++```bash+codex exec --approve-for-me --skip-git-repo-check --cd /abs/path/to/sandbox "..."+```++Because plugin skills do not load, a dispatched run reaches them as files: the sandbox carries a copy+of `skills/` and the brief names the skill it wants. That is enough -- the child finds and reads it --+but it is worth knowing that the skill is being read rather than installed.++Codex also rejects a model id newer than the CLI (`The 'gpt-6-astra' model requires a newer version of+Codex`), which reads like an entitlement problem and is not one. Update the CLI first.++### Hermes++Hermes is the harness that makes the portability claim worth stating. The other four are JavaScript+CLIs with broadly similar ideas about plugins; Hermes is a Python agent with its own YAML config, its+own skill store and its own provider routing, sharing no code and no convention with any of them. It+takes the same server and the same skills unchanged.++Two commands, both writing to `~/.hermes/config.yaml` (`%LOCALAPPDATA%\hermes\config.yaml` on+Windows):++```bash+hermes mcp add kiln --command node --args /absolute/path/to/kiln/dist/mcp-server.mjs --env KILN_RENDER=auto+hermes config set skills.external_dirs /absolute/path/to/kiln/skills+```++The first connects on the spot, prints the seven tools it found, and asks whether to enable them --+a prompt that wants a terminal, so pipe a `y` into it from a script. The second is the entire skills+story: Hermes does not read `.claude/skills` out of the working directory the way the other four do,+it reads a list of absolute directories out of its config, and pointing that list at this+repository's `skills/` is enough. Verify both:++```bash+hermes mcp list # kiln node …/dist/mcp-server.mjs all enabled+hermes skills list # five kiln-* rows, source `local`+```++`-z` is the headless mode the dispatcher uses: one prompt in, the final response text out, no banner,+and tool approvals resolved without asking. There is no working-directory flag, so the sandbox is+simply the directory the process is spawned in -- which is also where Hermes reads `AGENTS.md` from,+so the clean room holds.++Hermes is a client rather than a model vendor, and it ships with no provider at all. Until it has+one, every run fails with `No inference provider configured` before the model sees a single token of+the brief, which looks exactly like the silent wiring failures this page keeps warning about.+`hermes status` lists the key slots it knows. Its own first-party login is Nous Portal:++```bash+hermes auth add nous --type oauth+hermes config set model.provider nous+hermes config set model.base_url https://inference-api.nousresearch.com/v1+hermes config set model.default <model id>+```++The last three lines are not optional after the login, and skipping them produces the most confusing+state on this page: the credential is stored and `hermes status` reports `Nous Portal logged in`,+while `model.base_url` still points wherever it pointed before and every run dies on `No LLM provider+configured`. The catalog is public and OpenAI-shaped, so+`curl https://inference-api.nousresearch.com/v1/models` will tell you the ids, their pricing and+which ones accept tools without needing a key.++## Checking that it worked++Every wiring failure on this page is silent. A harness that cannot see the server does not say so,+and neither does one that can see it but will not grant it -- the agent simply answers as though the+tools were never mentioned, which is indistinguishable from a model that was not up to the job. So+do not infer from a bad asset that your model is weak. Check the wiring first:++```bash+bun run smoke:harness+```++It runs every CLI it finds on your PATH, and for each one sends a short brief into a throwaway+directory: call `kiln_list_primitives`, write a four-line program, validate it. Then it builds what+came back with the engine itself, because the child's own report of success is the one piece of+evidence that proves nothing.++```+agy ok 105s gemini-3.8-flash-high built 12 tris+claude ok 13s sonnet built 12 tris+codex ok 37s (configured default) built 12 tris+hermes ok 97s (configured default) built 12 tris+opencode ok 52s opencode-go/glm-5.3-flash built 12 tris+```++A harness you have not installed is skipped rather than failed. `--harness <name>` checks one,+`--model <id>` overrides the model, and a failure prints the last of the agent's output and the path+to the sandbox, which is left on disk so you can read the brief it was given and whatever it wrote.+## In-process, without MCP@@ -194,5 +483,5 @@ import { createKilnToolRegistry } from 'kiln/tools';`kiln/tools` is the framework-agnostic core and imports no agent SDK, so porting to a harness thatis not Strands does not drag Strands along. Each def carries `name`, `description`, a zod-`inputSchema`, and `run`. Mapping those four fields is the entire adapter — `src/mcp-server.ts` is+`inputSchema`, and `run`. Mapping those four fields is the entire adapter -- `src/mcp-server.ts` isone such adapter and `src/agent/tools.ts` is another.