Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

chore(release): prepare 1.6.0 (#294)

Matthew Kissingerb1df057d9ac2
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index ca3728f0..c42b6dd7 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "kiln",
"description": "Build and revise 3D assets with your coding agent. Write JavaScript, inspect selected views, edit saved source revisions, and export GLB files locally.",
- "version": "1.5.0",
+ "version": "1.6.0",
"author": {
"name": "Matthew Kissinger"
},
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 1b288588..770e1c43 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "kiln",
- "version": "1.5.0",
+ "version": "1.6.0",
"description": "Create, review, save, and refine procedural 3D assets with portable source and GLB collections.",
"author": {
"name": "Matthew Kissinger"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index abb2083a..0e51a2ad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,9 @@ does not publish a package.
## Unreleased
+
+## 1.6.0 (2026-10-27)
+
- `kiln_export_to` takes `textures: 'manifest'`, so an MCP author can act on the texture
duplication `kiln textures` reports instead of only seeing it. The runtime sidecar gains
`textures[]` naming each embedded image by `sha256` and mime type, which lets a destination
@@ -130,6 +133,23 @@ does not publish a package.
Wording only: no measured value, receipt field or tier status changes
([#291](https://github.com/instruktlabs/kiln/issues/291)).
+- `defineBudget` accepts zero material caps. `images: 0` and `decodedBytes: 0` are now valid:
+ zero is the honest declaration for an untextured asset, and the evaluator already measured it
+ correctly, passing at measured 0 and failing the moment a texture appears. A new `capacity()`
+ validator takes non-negative integers for the material caps, while `count()` still requires a
+ positive integer for `triangles` and `draws`, which describe what an asset must have rather
+ than what it may carry. **This relaxes a deliberate contract**: `{ images: 0 }` was previously
+ rejected, and a test asserted that rejection. Specs that were valid before remain valid
+ ([#286](https://github.com/instruktlabs/kiln/pull/286)).
+- The repair advice shown when a delivery helper fails states the `defineBudget` contract in
+ full. It described the helper as `defineBudget({ triangles, draws? })`, omitting `images`,
+ `decodedBytes` and `materialTier`, which Discovery's helper spec and the `SPEC_SHAPE` string
+ both list — so an author whose call failed for an unrelated reason was told those fields did
+ not exist. A test now asserts the advice names every field the validator accepts, so the text
+ and the validator cannot drift apart again.
+||||||| 24bc8fd
+
+
## 1.5.0 (2026-10-25)
- Generated Codex workspaces forward `KILN_EXPORT_ROOT` to the MCP server, so
diff --git a/dist/agent-run.mjs b/dist/agent-run.mjs
index 7a18177a..245315bf 100644
--- a/dist/agent-run.mjs
+++ b/dist/agent-run.mjs
@@ -42930,7 +42930,7 @@ function createKilnSourceDef(store) {
}
// src/engine-identity.ts
-var ENGINE_VERSION = "1.5.0";
+var ENGINE_VERSION = "1.6.0";
var ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
function engineIdentity() {
return { version: ENGINE_VERSION, installUrl: ENGINE_INSTALL_URL };
diff --git a/dist/build.json b/dist/build.json
index 9018cf73..3f7ca8cf 100644
--- a/dist/build.json
+++ b/dist/build.json
@@ -2,10 +2,10 @@
"schemaVersion": 1,
"entries": {
"worker": {
- "identity": "sha256:d5e4f9f962c7264d80419e27427a261512213dc8782675de23aba660a3356421",
- "engineVersion": "1.5.0",
+ "identity": "sha256:31499dfdba8a076a1921e6687e440cd6f898a06f87580bbe029c3968bdeb228a",
+ "engineVersion": "1.6.0",
"toolchain": "[email protected]",
- "sourceHash": "b660e9c652ad45c534674f82d4d1e4aa58af404d01b3bb64eff2093524fba4fa",
+ "sourceHash": "963c0b92cbd55db6157e3d4b8180d7cc0fb19d3ec0d33f7b9554ae8cb60fad0c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10",
"dependencies": {
@@ -40,10 +40,10 @@
"bundleHash": "sha256:395bac1322db31159ac553f054496245315a1473099fd4c6bd0e1e7b339aed66"
},
"agent-run": {
- "identity": "sha256:d5e4f9f962c7264d80419e27427a261512213dc8782675de23aba660a3356421",
- "engineVersion": "1.5.0",
+ "identity": "sha256:31499dfdba8a076a1921e6687e440cd6f898a06f87580bbe029c3968bdeb228a",
+ "engineVersion": "1.6.0",
"toolchain": "[email protected]",
- "sourceHash": "b660e9c652ad45c534674f82d4d1e4aa58af404d01b3bb64eff2093524fba4fa",
+ "sourceHash": "963c0b92cbd55db6157e3d4b8180d7cc0fb19d3ec0d33f7b9554ae8cb60fad0c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10",
"dependencies": {
@@ -75,13 +75,13 @@
},
"target": "node",
"file": "agent-run.mjs",
- "bundleHash": "sha256:9757bd38ccbb9c8963edaa014fbcac2c950074032234f51f32b7e2f03a4044ca"
+ "bundleHash": "sha256:9a1975f7f41954fbf31499e35d870fd597a0f50b44ea2d2aa551518b41c7d3e7"
},
"agent-providers": {
- "identity": "sha256:d5e4f9f962c7264d80419e27427a261512213dc8782675de23aba660a3356421",
- "engineVersion": "1.5.0",
+ "identity": "sha256:31499dfdba8a076a1921e6687e440cd6f898a06f87580bbe029c3968bdeb228a",
+ "engineVersion": "1.6.0",
"toolchain": "[email protected]",
- "sourceHash": "b660e9c652ad45c534674f82d4d1e4aa58af404d01b3bb64eff2093524fba4fa",
+ "sourceHash": "963c0b92cbd55db6157e3d4b8180d7cc0fb19d3ec0d33f7b9554ae8cb60fad0c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10",
"dependencies": {
@@ -116,10 +116,10 @@
"bundleHash": "sha256:9d6faf03d307321bc2e3bd5ce5bdee0bbbf61e0ebed8bfebfa1fb072287b83fa"
},
"mcp": {
- "identity": "sha256:d5e4f9f962c7264d80419e27427a261512213dc8782675de23aba660a3356421",
- "engineVersion": "1.5.0",
+ "identity": "sha256:31499dfdba8a076a1921e6687e440cd6f898a06f87580bbe029c3968bdeb228a",
+ "engineVersion": "1.6.0",
"toolchain": "[email protected]",
- "sourceHash": "b660e9c652ad45c534674f82d4d1e4aa58af404d01b3bb64eff2093524fba4fa",
+ "sourceHash": "963c0b92cbd55db6157e3d4b8180d7cc0fb19d3ec0d33f7b9554ae8cb60fad0c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10",
"dependencies": {
@@ -151,13 +151,13 @@
},
"target": "node",
"file": "mcp-server.mjs",
- "bundleHash": "sha256:feca46c85c8813b816fb71c1dea9211ede75eed2403d8a093e511fc3e6d8690a"
+ "bundleHash": "sha256:4c8f00a36bcc57be3ff7afb3df03646ffebdc355e7bb42478112aa2ac4c1319f"
},
"cli": {
- "identity": "sha256:d5e4f9f962c7264d80419e27427a261512213dc8782675de23aba660a3356421",
- "engineVersion": "1.5.0",
+ "identity": "sha256:31499dfdba8a076a1921e6687e440cd6f898a06f87580bbe029c3968bdeb228a",
+ "engineVersion": "1.6.0",
"toolchain": "[email protected]",
- "sourceHash": "b660e9c652ad45c534674f82d4d1e4aa58af404d01b3bb64eff2093524fba4fa",
+ "sourceHash": "963c0b92cbd55db6157e3d4b8180d7cc0fb19d3ec0d33f7b9554ae8cb60fad0c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10",
"dependencies": {
@@ -189,13 +189,13 @@
},
"target": "node",
"file": "cli.mjs",
- "bundleHash": "sha256:66ba511f41eb4da4d75f1c716980605b0fc8b1ec97265661228924b607cfa411"
+ "bundleHash": "sha256:8d2766d2ebe4e4fcdb389dd8961e1fab9165926b65bee8749e5e9ffb68e4ce40"
},
"engine": {
- "identity": "sha256:d5e4f9f962c7264d80419e27427a261512213dc8782675de23aba660a3356421",
- "engineVersion": "1.5.0",
+ "identity": "sha256:31499dfdba8a076a1921e6687e440cd6f898a06f87580bbe029c3968bdeb228a",
+ "engineVersion": "1.6.0",
"toolchain": "[email protected]",
- "sourceHash": "b660e9c652ad45c534674f82d4d1e4aa58af404d01b3bb64eff2093524fba4fa",
+ "sourceHash": "963c0b92cbd55db6157e3d4b8180d7cc0fb19d3ec0d33f7b9554ae8cb60fad0c",
"rendererSourceHash": "27927c48b377f7694251a76c0cecd05216fcbbb8a7d03e8bf2bd681dabb5573a",
"dependencyHash": "af916d063d319fe3c11d1acc13211950eea82bb5ebb87ae4eb60008d72fa7f10",
"dependencies": {
@@ -227,7 +227,7 @@
},
"target": "node",
"file": "mcp-engine.mjs",
- "bundleHash": "sha256:3fdffe687e4af2b168843b2a4566f4c4bdbe54fa6125c5ee6d7198859387813a"
+ "bundleHash": "sha256:b456e4fa734133a8439525b999c7c670105312ceb0936dfca6749daf7d55f6c9"
}
}
}
diff --git a/dist/cli.mjs b/dist/cli.mjs
index 98a8650e..ba4c2b7c 100644
--- a/dist/cli.mjs
+++ b/dist/cli.mjs
@@ -46870,7 +46870,7 @@ var init_program_artifacts = __esm(() => {
function engineIdentity() {
return { version: ENGINE_VERSION, installUrl: ENGINE_INSTALL_URL };
}
-var ENGINE_VERSION = "1.5.0", ENGINE_INSTALL_URL;
+var ENGINE_VERSION = "1.6.0", ENGINE_INSTALL_URL;
var init_engine_identity = __esm(() => {
ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
});
diff --git a/dist/mcp-engine.mjs b/dist/mcp-engine.mjs
index a4c8fa0f..1a344833 100644
--- a/dist/mcp-engine.mjs
+++ b/dist/mcp-engine.mjs
@@ -46368,7 +46368,7 @@ import { readFile as readFile9 } from "node:fs/promises";
var KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v6.html";
// src/engine-identity.ts
-var ENGINE_VERSION = "1.5.0";
+var ENGINE_VERSION = "1.6.0";
var ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
function engineIdentity() {
return { version: ENGINE_VERSION, installUrl: ENGINE_INSTALL_URL };
diff --git a/dist/mcp-server.mjs b/dist/mcp-server.mjs
index 9b3ce30f..c6bd7944 100644
--- a/dist/mcp-server.mjs
+++ b/dist/mcp-server.mjs
@@ -2162,7 +2162,7 @@ import { readFile } from "node:fs/promises";
var KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v6.html";
// src/engine-identity.ts
-var ENGINE_VERSION = "1.5.0";
+var ENGINE_VERSION = "1.6.0";
var ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
// src/requirements-json.ts
diff --git a/docs/plans/2026-10-26-vietnam-asset-rebuild.md b/docs/plans/2026-10-26-vietnam-asset-rebuild.md
index 144983ba..c385dc1b 100644
--- a/docs/plans/2026-10-26-vietnam-asset-rebuild.md
+++ b/docs/plans/2026-10-26-vietnam-asset-rebuild.md
@@ -372,14 +372,21 @@ contract, and `images: 0` was rejected although zero is the honest cap for an un
The owner asked for an adversarial pass on my own findings. It substantially revised them: **one
of seven is ready to implement.** Arguing against each:
-1. **Floating-part QA — gap real, my analogy wrong, fix 3-5x bigger than implied.** I claimed
- `CHAR_CONTACT_FLOATING` was the precedent to copy. It is not: it checks a *declared* contact
- role against asset-local ground ("Ground contact {role} is {offset} m above asset-local
- ground"), not part-to-part contact. No domain has part-to-part contact checking. Worse, the
- obvious rule is unstateable: "every part must touch another" would flag P0's corrected sling
- swivels, which hang free on purpose, as defects — a false positive worse than the miss it
- prevents. A real fix needs an author-declared contact mechanism, as characters already have.
- **Design work, not a patch. Do not hand this to an agent as a fix.**
+1. **Floating-part QA — WITHDRAWN, 26 October. The feature already exists.** I claimed nothing in
+ Kiln covers one part of a prop floating off another. That is false. **#220 shipped as
+ COMPLETED on 23 October**, and the changelog records it: parts that rest on an external support
+ can be declared, which turns "the floating-parts warning to an informational line, and its
+ connectivity observation becomes" advisory. `src/qa/geometry-relations.ts` exposes `contact`,
+ `clearance`, `penetration`, `containment`, `coverage`, `alignment`, `concentricity` and
+ `tolerance`. Open **#277** extends the same mechanism to neighbouring modules and states the
+ relationship explicitly.
+
+ **What survives is narrower**, now tracked as **#289**: why the existing warning did not report
+ the M16A1's front sight post 2 mm off its A-frame, with per-material welding hiding the
+ primitive inside a single part as the suspected cause. That needs a reproduction first.
+
+ I ranked this first on two readings without once checking the issue tracker or the changelog.
+
2. **Shadow exclusion in draw diagnostics — weakest Tier 1 item, downgrade.** The docs already
state it and P0 knew it, so the people who read docs are not misled. A receipt qualifier is
cheap but low value.
@@ -397,6 +404,424 @@ of seven is ready to implement.** Arguing against each:
7. **`AGENTS.md` omits `build:sdk` — ready.** Verified by me, one line, no design content, no
behaviour change. **The only item ready to implement as stated.**
+## The one rule: go to the artefact
+
+Seven distinct false signals occurred in this cycle, and they look like seven unrelated lessons
+until you line them up:
+
+| what lied | what it described |
+| --- | --- |
+| a wrapper's exit code | the test run |
+| a `^not ok` grep | the test run, under the other runtime's reporter |
+| a failure-line grep returning zero | a summary that said `1 fail` |
+| a background task's "exit code 0" | a log ending `4 fail` |
+| a silently auto-merged `.mjs` | the bundle its source would produce |
+| GitHub's `mergeable: CONFLICTING` | a head that is a strict descendant of `main` |
+| `wc -m` agreeing with `wc -c` | a byte budget, by ASCII coincidence |
+
+**Every one is a derived or cached summary disagreeing with the artefact it describes.** And the
+remedy was the same every time: **go to the artefact.**
+
+- Read the log, not the exit code.
+- Regenerate the bundle, do not inspect it.
+- Ask git about ancestry (`git merge-base --is-ancestor origin/main HEAD`), not the API about
+ mergeability — a cached value computed mid-push reports garbage for a window afterwards.
+- Run the snapshot test, do not regenerate the snapshot.
+- Read `Ran N tests` from the runner, do not count `test(` in source.
+
+**The seventh variant is the sharpest, because it is currently telling the truth.**
+`AGENTS.md` is gated at `Buffer.byteLength(agents) < 12 * 1024`. On `main` the file is 100% ASCII
+— verified, zero non-ASCII bytes — so `wc -m` and `wc -c` both report **12284**. They agree
+*exactly*, and only because of what the file happens to contain.
+
+A character count is a summary of a byte count. This one is a summary that is correct today,
+**which is worse than one that is wrong**: a wrong summary gets caught, while a correct one
+trains you to trust the method. One em dash and they diverge by 2 while the editor keeps
+reporting the comfortable number, against a budget whose entire headroom is **3 bytes**.
+
+So the rule is not "derived summaries are unreliable". It is that a derived summary is a
+different thing from the artefact *even when the two agree*, and agreement today is not a
+property you can carry.
+
+State it as one rule rather than seven lessons, because the seventh variant has not been seen yet
+and a list of six will not cover it. The question to ask of any green light is: **is this the
+thing, or a summary of the thing?**
+
+## Verifying a test run: eight bad signals in one cycle
+
+Across one day of dogfooding, **eight separate derived signals were wrong**, each by a
+different mechanism. None was caught by the thing that produced it. Recorded because the cost
+was real — one of them alone cost a 13-minute rerun, and one nearly shipped.
+
+| # | Signal | Reality | Mechanism |
+| --- | --- | --- | --- |
+| 1 | wrapper reported `exit 0` | suite had failures | `echo "EXIT=$?"` after a pipe captured `tail`'s status, not the runner's |
+| 2 | `^not ok` grep matched nothing | suite had failures | Node 22 emits TAP, Node 24 emits spec — the grep pattern was for the other format |
+| 3 | failure-line grep returned 0 | summary said `1 fail` | the runner did not print the expected marker for that failure class |
+| 4 | background task "completed (exit code 0)" | log ended `1 fail` / `4 fail` | harness exit code simply wrong; hit independently by two sessions |
+| 5 | command reported `exit 1` | tests were **fine**, 11 pass / 0 fail | a `grep -c` appended to the pipeline exited non-zero on zero matches |
+
+**The rules that survived all five:**
+
+- **Read the summary totals out of the log.** It is the only reading that was right every time.
+- **A test-run exit code carries no information in either direction once anything is piped after
+ it.** A pipeline's status is its *last* command. Four of the five were false greens, which is
+ the expensive direction, but #5 shows a false red costs a cycle chasing nothing.
+- **Never infer success from absent failure lines.** Formats differ by runtime and by failure
+ class.
+- **Do not match incidental lines against a remembered count.** One session reported 18
+ `✗ Tool failed` lines as benign; the next had 9, of two kinds rather than one. Both runs were
+ 0 fail. The count is scope- and concurrency-dependent, so an expected number for it turns a
+ harmless artefact into a false signal — which is the very thing these rules exist to prevent.
+ Read the totals and the `(fail)` count; nothing else.
+- **Do not truncate the log you are going to read.** A `tail -22` preserved the totals and
+ destroyed every `(fail)` line, leaving a correct total naming nothing. Capture whole, read the
+ totals, grep the detail from the file.
+- **Pre-register the expected total, then check it.** State the number *before* the run, derived
+ from the merged tree, and treat a mismatch as a finding rather than a prompt to recount. A
+ post-hoc derivation can be unconsciously fitted to whatever the run produced, which is the
+ failure mode of every check above. Done properly on the third merge: 4,020 predicted, 4,020
+ observed.
+- **Cross-check the arithmetic.** The strongest verification found in this cycle is independent
+ of exit codes, formats and failure lines: *the pass count should equal the known baseline plus
+ the tests you added.* 3,987 + 6 = 3,993 passing proves no silent failure, because a masked
+ failure would read 3,992 pass / 1 fail.
+- **Read `Ran N tests` from the runner; never count source.** `test.each`, a `describe` loop and
+ a conditional `test` each break a source grep the same way. The runner's own count is the only
+ one that reflects what executed.
+- **But count instances, not declarations — a sixth way to be wrong.** Verifying another
+ branch's expected count by grepping added `test(` lines returned 4 where the truth was 6: two
+ of the tests sat inside `for (const exporter of ['legacy','three'])` and therefore ran twice.
+ The grep looked authoritative and was off by two. A parameterised loop makes a wrong
+ expectation look reasonable, which is the worst property an expectation can have. **Also
+ re-derive the baseline when `main` moves** — each merge in this cycle shifted it (3,987 to
+ 3,996 to 4,002), and the check is only as good as the number it is checked against.
+
+- **An eighth, and the cheapest to fall for: a state read while it was still being derived.**
+ `gh issue view 290 --json state` returned `OPEN` moments after #295 merged, so I posted a
+ comment blaming the title-reference auto-close gap that genuinely had caught #293 earlier.
+ The timestamps say otherwise: #295 merged at 12:03:14Z and the issue closed at 12:03:18Z.
+ The read landed four seconds inside a window where GitHub had not finished acting on
+ `Closes #290` in the PR body. Nothing about the value looked provisional — `OPEN` is exactly
+ what a real auto-close failure returns, which is why the wrong conclusion was publishable.
+ The tell is not in the value but in the clock: a derived state read within seconds of the
+ event that derives it is not evidence yet. Read what settles it instead — the keyword in the
+ PR body, or `closed_at` — rather than the state it will eventually produce.
+
+## The worst merge hazard: generated output that does not conflict
+
+Found landing the second of four PRs, and it is more dangerous than the `CHANGELOG.md` one
+because **nothing announces it**.
+
+Merging `main` into a branch, of the five committed `dist/` bundles, only `dist/build.json`
+conflicted. **The four `.mjs` files auto-merged cleanly.** Git interleaved two different
+minified bundles into a file that is textually plausible and semantically meaningless, reported
+no conflict, and said nothing.
+
+> A conflict at least announces itself. A silent auto-merge of generated output does not.
+
+A conflict list is therefore not a hazard list: the files git flags are the ones it could not
+reconcile, which is the opposite of the ones most likely to be wrong. Minified, generated or
+machine-ordered text is exactly what git is most willing to merge and least able to merge
+correctly.
+
+**The handling is to refuse the merge for derived files — and to do it _before_ merging, not
+after.** Restore `dist/` to the merge-base state and **commit that first**. The branch then
+carries zero delta on those files, so git has nothing to interleave and simply takes `main`'s
+bundles; the `build.json` conflict disappears for the same reason. Then merge, and rebuild from
+merged source last.
+
+The post-merge form — merge, then discard the result and regenerate — reaches the same end state
+but passes through a tree that *contains* the interleaved garbage and relies on remembering to
+throw it away. **One makes the failure unreachable; the other makes it recoverable.** Never
+inspect or fix a merged bundle either way: "did git interleave these correctly" has no useful
+answer.
+
+**The idempotence check is what catches it**, which is why it earns its place beyond staleness:
+
+```
+git status --short # clean after the regenerate
+node scripts/build-runtime.mjs all
+git status --short # still clean -> committed bundle matches merged source
+```
+
+A silently interleaved bundle fails that immediately, because regenerating from source produces
+something different from what the merge produced.
+
+## Rehearse the merge first — it is free
+
+`git merge-tree --write-tree` computes a complete merge and writes **no refs, no commit, and
+nothing to the working tree**. `git status` is empty afterwards. So "what will actually conflict"
+is answerable before committing to anything, with no half-merged tree to extract yourself from.
+
+Measured on the third branch of this cycle, against a `main` that already carried the first:
+
+| | conflicts | silently auto-merged |
+| --- | --- | --- |
+| branch as it stood | `CHANGELOG.md`, `dist/build.json` | **`agent-run.mjs`, `cli.mjs`, `mcp-engine.mjs`** |
+| `dist/` restored to merge-base first | `CHANGELOG.md` only | **nothing — not one line** |
+
+That is the interleaving hazard reproduced independently on a second branch, and it turns the
+claim that the pre-merge revert "makes the failure unreachable" from an argument into a
+measurement: **three silent wrong interleavings and one conflict, removed.** With zero delta on
+the branch there is nothing for git to combine, so it takes `main`'s bundles outright.
+
+**Make it step 0 of any rebase in a multi-branch cycle**, with an explicit acceptance criterion
+so the rehearsal has a pass/fail rather than being a look around: *only `CHANGELOG.md` conflicts,
+and no `dist/` path appears at all.* Anything else means stop and understand it first.
+
+One limit worth stating: a dry run only exercises the overlaps that exist at the time. Files the
+other branch has not yet touched come back one-sided and trivial, and become two-sided only once
+it lands — so re-run the rehearsal after each merge rather than trusting an earlier result.
+
+## Generated is not the same as unverifiable
+
+The opposite mistake to the bundles, and it cost nothing only because it was caught before the
+third merge: **do not regenerate a snapshot to resolve a merge.**
+
+Running the snapshot test *without* `--update-snapshots` compares the committed snapshot against
+what the merged source actually generates. **Passing is proof the merge was correct.**
+Regenerating unconditionally overwrites the file so that it trivially matches — converting a
+verifiable state into an unverifiable one, and destroying the only evidence that the merge of the
+*source* was sound.
+
+So: merge, run the snapshot test **without** update, and regenerate only if it fails — treating
+that failure as something to understand rather than paper over.
+
+**The line between this and the bundles is not "generated output".** Both are generated. The
+difference is structure and an oracle:
+
+| | minified bundle | `.snap` |
+| --- | --- | --- |
+| shape | effectively one enormous line, no structure | line-oriented, stable ordering |
+| a bad merge is | textually plausible, semantically dead | a test failure |
+| detectable by reading | no | yes |
+| has a comparator | no — only regenerate-and-compare | yes, the test itself |
+
+Discard-and-rebuild is the only honest route for the first. For the second it is actively
+harmful.
+
+## The conflict nobody guards
+
+When several branches land in one cycle, their conflicts are not equally dangerous, and the
+ranking is the opposite of the intuitive one:
+
+| conflicted file | caught by |
+| --- | --- |
+| `dist/` bundles | `workspace-setup.test.ts`, plus the idempotent-rebuild check below |
+| generated snapshots | regeneration is authoritative; the test fails if stale |
+| **`CHANGELOG.md`** | **nothing** |
+
+Every branch in this cycle inserted at the same `## Unreleased` anchor, so the file conflicts
+every time. It is **neither regenerable nor covered by any test**, so a careless resolution
+silently drops one side's entry and no gate, total, snapshot or CI run will say so. The loss
+surfaces only when someone later asks why a shipped change is undocumented.
+
+So resolve it by keeping both entries, and **state in the report which entries survived**. That
+statement is the only check that exists. Raised by the session landing third, after two merges
+had already passed through the file unremarked — including by the session coordinating them.
+
+## Staleness in a derived artifact
+
+`dist/` is a build output committed in the same tree as its input, so it can silently disagree
+with the source beside it. Only `workspace-setup.test.ts` catches that.
+
+**The rule is stronger than "rebuild last after a rebase."** One session rebuilt the bundle, then
+made a cosmetic edit to a CLI help string, and that alone failed the test. So: **any source edit
+after a build leaves a lie in the tree**, including a typo fix, and rebase hygiene is only one
+instance of it.
+
+**The cheap check is idempotence**, and it needs no test suite:
+
+```
+git status --short # empty
+node scripts/build-runtime.mjs all
+git status --short # still empty -> the committed bundle matches its source
+```
+
+A two-second answer to "is this bundle stale", usable before every push.
+
+## Shepherding order is a cost decision, not a queue
+
+The repository requires a branch to be up to date with its base before it merges.
+`gh pr merge 301` refused outright — *"the head branch is not up to date with the base
+branch"* — on a PR whose fourteen checks were green and whose merge rehearsed clean. So a
+merge-up is **mandatory for every PR regardless of conflicts**, and each merge moves `main`
+forward and invalidates the next one. Shepherding several PRs is therefore strictly serial,
+and the only free variable is the order.
+
+Order by what a re-land costs, not by PR number or readiness:
+
+| PR | files | touches `dist/` | cost to bring current |
+| --- | --- | --- | --- |
+| #301 | 3 | no | a plain `git merge origin/main` |
+| #300 | 8 | no | a plain `git merge origin/main` |
+| #295 | 9 | 4 bundles | restore, merge, rebuild |
+| #302 | 16 | 5 bundles | restore, merge, rebuild |
+
+#301 and #300 live entirely under `packs/` and `site/` — they touch neither `dist/` nor
+`src/`, so `main`'s bundles stay accurate across them and updating costs nothing. #295 and
+#302 each rebuild bundles, and **a rebuild is only valid against the `main` it will actually
+merge onto**, so every bundle-touching merge destroys the other's. Put the two cheap ones
+first and the two rebuilds last, one apiece, and each rebuilds exactly once. The same four in
+the reverse order rebuild five times between them.
+
+This inverts the intuition that the most exposed PR should go first. #295 is furthest behind
+— its base was two commits back before #298 even landed — and that is an argument for
+sending it *last*, because being behind is cheap to fix and rebuilding is not.
+
+Two things not to take on trust while draining a queue like this:
+
+- **Green CI describes a tree that no longer exists.** #300 and #301 were 14/14 against base
+ `f5e9eb5`, which stopped being `main` the moment #298 landed. That run is still evidence —
+ but only about the merge-base, so it has to be paired with a check that the PR shares no
+ file with what landed since. Here neither shared one, so the green survived; it does not
+ always.
+- **Don't hand a session a conflict you haven't rehearsed.** Both pack PRs edit
+ `packs/holodeck/README.md`, so a collision looked certain. Rehearsing it said otherwise:
+ `git merge-tree --write-tree` for `main + #301`, then `git commit-tree` on that tree
+ parented on `main` to get a synthetic commit, then `merge-tree` again for #300 on top of it
+ — clean, tree `ebacb0c`. The hunks never overlapped. A warning about a conflict that does
+ not exist is the same defect as a number handed over to be matched: it manufactures a false
+ signal in someone else's session.
+
+The README is worth a human read anyway, and for a reason the rehearsal cannot cover: prose
+has no test or snapshot behind it, so two non-overlapping hunks can merge clean and still
+leave the file incoherent — a renamed flag still documented, two additions reading as
+duplicates. Same shape as `CHANGELOG.md` under *the conflict nobody guards*.
+
+**That read found a real defect, 27 October.** The prediction was not hypothetical. #300's
+session read the merged `packs/holodeck/README.md` instead of trusting the clean merge, and
+found that #274's own first commit had inserted new subsections after the Regenerate preamble,
+pushing two paragraphs — on content-addressed object keys and `published.json` — down to the
+end of *Recover a lost store*. There they read as describing the recovered store rather than
+every staged download. The fix (`6fba946`) moved 25 lines and added none: prose order only.
+
+Note what that instance actually establishes. The defect did not come from the merge, so no
+merge discipline would have surfaced it; it came from an earlier commit in the same PR and
+only became *visible* in the merged file. A rehearsal proves a merge is clean. Nothing proves
+prose still means what it meant, and the only instrument is a reader. Two PRs' hunks landing
+in one document is simply the moment someone is most likely to look.
+
+## A peer's instruction is not the owner's
+
+Twice I told the clearance session to fold a one-line test fix into its own PR, and twice it
+declined and escalated instead. I recorded that as a session ignoring an instruction, and told
+the owner so. It was not: the owner had told that session directly, in their own words, "its own
+PR, not #302", and a peer message cannot reverse the owner's scoping call. The session was
+holding the right line; I was the one out of order. Verified afterwards against that session's
+transcript rather than its report.
+
+The failure is structural rather than a lapse, which is why it is worth writing down. A
+shepherding session sees every PR, every branch and every rehearsal, so its own view of the
+queue feels complete — and the one thing it cannot see is what the owner said inside another
+session. That is precisely the class of instruction that outranks its own. Completeness in one
+dimension reads as authority in all of them.
+
+The correction is in the framing, not the content. My cost argument was right: folding in costs
+one CI cycle where a separate PR costs two. Sent as information, that is something the session
+can weigh against what it was told. Sent as "fold it in", it is a directive I had no standing to
+give. A shepherd coordinates by supplying measurements; it does not scope other people's work.
+
+The expensive half was reporting the session to the owner as having disregarded an instruction.
+A wrong technical claim gets corrected by the next measurement — this cycle has eight of those,
+all caught. A wrong claim about someone's conduct has no measurement behind it and does not
+correct itself.
+
+## Three contract decisions, and what checking the options cost
+
+Settled by the owner, 27 October: #277 declares neighbours through **project inventory
+placement**; #289 **closes** on its reproduction with the welded-mesh hole split out as #304;
+#287 **exposes `textures`** on the MCP export tools and names both options in Discovery.
+
+The outcomes matter less than the pattern. Each of the three was parked as a judgement call,
+and in each case running one cheap command before presenting the options changed what was
+being decided.
+
+**#277 — the cost was understated, not overstated.**
+`grep -cE 'transform|placement|position' src/projects.ts` returns **0**. The option had been
+described as projects gaining a layout concept; in fact projects have no spatial vocabulary at
+all, so it introduces the first one. That is a larger commitment than "add a field", and it is
+the kind of thing that only shows up as a number. The contract boundary that rules out the
+model-authored alternative was equally checkable: `src/contracts/requirements.ts:1` states
+"Host authority is deliberately external", and line 254 already carries the precedent —
+`requirements.validation`, commented "never model-authored".
+
+**#289 — the decision was that it was two decisions.**
+One issue held a by-design precision floor and a genuine coverage hole, and presenting them
+together would have forced a single wrong answer to both. The floor is three deliberately
+matched constants (`src/render.ts:2927`, `src/render.ts:267`,
+`src/qa/part-connectivity.ts:46`), all 2 cm, and it is correct: a trigger clearing its guard by
+a millimetre is normal geometry. The hole is that two primitives welded into one
+`BufferGeometry` are silent at 200 mm, where unwelded they report from 25 mm — and Kiln welds
+per material by default. Splitting it let the floor close as not-a-defect while the hole became
+#304 with its own acceptance criteria.
+
+The fix's cost was also worth checking rather than assuming. No component machinery exists
+anywhere in `src/` — zero hits for `connectedComponent`, `unionFind`, `disjointSet` or
+`floodFill` — which reads as expensive until you notice `geometryDiagnostics`
+(`src/geometry.ts:146`) already enumerates edges to count `nonManifoldEdges` at line 237. A
+union-find over a walk the code already performs is a different proposition from new topology.
+
+**#287 — the issue's own analysis was wrong in the direction that made the work cheaper.**
+The comment asserted that `kiln_export` hardcodes `profile: 'runtime'`. It does not:
+`src/tools/registry.ts:3029` is `.enum(['runtime', 'editable']).default('runtime')`. So an
+export-shaping enum on the MCP surface is established precedent, and adding `textures` beside
+it is the same move rather than a new one. Only `textures` was actually missing — the sole hit
+in the registry is a `TextureUsage` type import at line 93.
+
+### A check's tolerance is its contract
+
+The durable result is #289's division of labour. Kiln measures gross structure; the destination
+audits millimetre fit. When a check's tolerance is right and an author still gets surprised, the
+defect is in what the check *says about itself*, not in the threshold — so the fix is stated
+coverage plus a regression test that pins the statement, which is what #298 shipped. A
+limitation documented only in a warning that never fires would not have helped anyone, which is
+why the rule landed in the QA integration reference as *run the destination's audits before
+`kiln_save`*, not after.
+
+### Single-digit headroom is a tripwire
+
+Measuring #287's affordability turned up something unrelated and worse than the thing being
+measured:
+
+| gate | current | limit | headroom |
+| --- | --- | --- | --- |
+| `kiln_render` input schema | 4,988 B | 5,000 B | **12 B** |
+| `kiln_inspect` input schema | 4,917 B | 5,000 B | 83 B |
+| all 19 tool definitions | 42,783 chars | 45,000 | 2,217 |
+| `AGENTS.md` | 12,284 B | 12,287 B | **3 B** |
+| `kiln_export` input schema | 663 B | 5,000 B | 4,337 |
+
+Two gates in this repo now sit within a dozen bytes of failing. Neither will be tripped by work
+that intends to change them; both will be tripped by the next unrelated edit that happens to
+touch the file, where the failure arrives as a budget error with no obvious relation to what the
+author was doing. A gate with single-digit headroom has stopped measuring a budget and started
+measuring luck.
+
+### 1.6.0 carries #287, and the order is not free
+
+The owner folded #287's `textures` exposure into 1.6.0 rather than shipping it afterwards: an
+input schema change invalidates the prompt cache for every client, and one invalidation beats
+two.
+
+That makes the release sequence load-bearing, for a reason the build script states itself.
+`scripts/build-runtime.mjs:86` comments that the MCP entry bundles
+`src/generated/mcp-manifest.json` and must "regenerate it from the registry first, before the
+source identity below is taken." The contract test measures that *packaged* manifest rather
+than the live registry — `src/tools/__tests__/registry-contract.test.ts` imports
+`packagedMcpManifest`, and its header says the generated manifest "is what every harness
+receives." So the order is:
+
+1. `textures` on `kiln_export` and `kiln_export_to`, plus the Discovery entries.
+2. `node scripts/build-runtime.mjs all`, which regenerates the manifest from the registry.
+3. Only then the version bumps across the eleven files and
+ `plugins/kiln-engine/package-provenance.json`.
+
+Done in the other order, provenance pins a package whose advertised manifest does not carry
+the option the release notes claim. Nothing fails loudly — the artefact is simply wrong, which
+is the signature of every other hazard in this document.
+
## Open decisions
- **D0 — how far to redesign.** "Better" needs a ceiling or P0 never ends. Proposal: one
diff --git a/package.json b/package.json
index 1b3107da..c579f170 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@instruktlabs/kiln",
- "version": "1.5.0",
+ "version": "1.6.0",
"description": "Create and refine procedural 3D assets with JavaScript, image feedback, and reusable source revisions.",
"license": "MIT",
"author": "Matthew Kissinger",
diff --git a/plugin.json b/plugin.json
index 24d575c5..c38cccaa 100644
--- a/plugin.json
+++ b/plugin.json
@@ -2,7 +2,7 @@
"name": "kiln",
"displayName": "Kiln",
"description": "Build and revise 3D assets with your coding agent. Write JavaScript, inspect selected views, edit saved source revisions, and export GLB files locally.",
- "version": "1.5.0",
+ "version": "1.6.0",
"license": "MIT",
"homepage": "https://github.com/instruktlabs/kiln",
"keywords": [
diff --git a/plugins/kiln-engine.release.json b/plugins/kiln-engine.release.json
index 02573b5f..c710fd03 100644
--- a/plugins/kiln-engine.release.json
+++ b/plugins/kiln-engine.release.json
@@ -1,4 +1,4 @@
{
- "version": "1.5.0",
- "engineVersion": "1.5.0"
+ "version": "1.6.0",
+ "engineVersion": "1.6.0"
}
diff --git a/plugins/kiln-engine/.claude-plugin/plugin.json b/plugins/kiln-engine/.claude-plugin/plugin.json
index 6cd064df..56333a77 100644
--- a/plugins/kiln-engine/.claude-plugin/plugin.json
+++ b/plugins/kiln-engine/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "kiln-engine",
- "version": "1.5.0",
+ "version": "1.6.0",
"description": "Set up a local Kiln workspace to create, inspect and revise editable 3D assets with Claude Code or Codex.",
"author": {
"name": "Instrukt Labs",
diff --git a/plugins/kiln-engine/README.md b/plugins/kiln-engine/README.md
index b8b886d2..3072f2b0 100644
--- a/plugins/kiln-engine/README.md
+++ b/plugins/kiln-engine/README.md
@@ -1,7 +1,7 @@
# Kiln local plugin
-Plugin version 1.5.0, maintained by Instrukt Labs under the MIT license.
-This plugin pins engine 1.5.0. Registry setup requires that exact version
+Plugin version 1.6.0, maintained by Instrukt Labs under the MIT license.
+This plugin pins engine 1.6.0. Registry setup requires that exact version
to be published. Use a published release tag for normal installation or a reviewed
local archive for development qualification. The installation ID remains
`kiln-engine@instruktlabs`.
@@ -31,7 +31,7 @@ codex plugin add kiln-engine@instruktlabs
Restart or reload your coding agent's plugins as its installation message directs.
Then ask it to set up a Kiln workspace. The maintained setup skill runs this
plugin's `bin/kiln-setup-workspace.mjs` with Node, installs
-`@instruktlabs/[email protected]` outside the project and configures your chosen
+`@instruktlabs/[email protected]` outside the project and configures your chosen
workspace. The same initializer supports existing projects and new workspaces.
The plugin registers setup only. The workspace supplies authoring skills and one
diff --git a/plugins/kiln-engine/package-provenance.json b/plugins/kiln-engine/package-provenance.json
index baddb263..b0f7d3ac 100644
--- a/plugins/kiln-engine/package-provenance.json
+++ b/plugins/kiln-engine/package-provenance.json
@@ -1,20 +1,20 @@
{
"schemaVersion": 1,
"kind": "kiln-local-plugin",
- "pluginVersion": "1.5.0",
- "engineVersion": "1.5.0",
+ "pluginVersion": "1.6.0",
+ "engineVersion": "1.6.0",
"executables": [
"bin/kiln-setup-workspace.mjs"
],
"files": {
".claude-plugin/icon.png": "sha256:b4b651c402793b7e27cab780f04b14f80daec6d0cd5b7e4e90313930581a54e9",
- ".claude-plugin/plugin.json": "sha256:12e27b178b75fdfa3136f3f65e27f3efedc9b7f1a8e715d1084a125f19e0c2fa",
+ ".claude-plugin/plugin.json": "sha256:4c51da2f7477000f3bb080702fd365f643186cda8554ad93dd29cf8eb5c2f833",
"bin/kiln-setup-workspace.mjs": "sha256:3d9a30236919a6ca91acb6b26f808cec442e6edc3dd88fe010645b010d76e838",
"LICENSE": "sha256:cdba278ebf1d6de618869936226bf03be4887179c128efc7aaa13d22034826a5",
- "plugin.json": "sha256:eeff4f8368cdeecc9884ec3da3b4107843ecf23fed017e23ea7d477fac4d496b",
+ "plugin.json": "sha256:29ecda1d44bf5b7c63aae98062175ddbfbeb7751650c5b7a17bb848ec88e7d04",
"PRIVACY.md": "sha256:5f58d981667e40441e21c2dec411f269a9a67a6141cec61976d27088fb12573b",
- "README.md": "sha256:ceccb26fe61e147f50da8ef7ce4a2800d60be4fb37c2acd99b619ba72022d2a1",
- "runtime.json": "sha256:1330870e64304f9eea7b373d8f555fa7e306ea53bc0acda5ff73cc74e99c8fc6",
+ "README.md": "sha256:80353c670abc95d7bf9d57187d6532d5a3dc590c099dfa28d7edf3eaf1f32cfe",
+ "runtime.json": "sha256:283c81ace01c2f560929174ccf4a8b6ee483ca3fe0f47c5134302dba0d2194c9",
"SECURITY.md": "sha256:8e238d3985deff828efd71bc3354a5b0275613a4921f369fc971f760ca249606",
"skills/kiln-setup-workspace/references/plugin-install.md": "sha256:c338fb792e7fad0364c3e1a13c94c506afa1395489ec1b6e83b36d04728935fb",
"skills/kiln-setup-workspace/references/renderer-setup.md": "sha256:a716a1e35c3ed69256c9f90ca7e08a3f0e66ccfc391c57a9454cad5d3c6f78dd",
diff --git a/plugins/kiln-engine/plugin.json b/plugins/kiln-engine/plugin.json
index 0561d74b..56fc82ef 100644
--- a/plugins/kiln-engine/plugin.json
+++ b/plugins/kiln-engine/plugin.json
@@ -1,7 +1,7 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "kiln-engine",
- "version": "1.5.0",
+ "version": "1.6.0",
"description": "Set up a local Kiln workspace to create, inspect and revise editable 3D assets with Claude Code or Codex.",
"author": {
"name": "Instrukt Labs",
diff --git a/plugins/kiln-engine/runtime.json b/plugins/kiln-engine/runtime.json
index aa70420a..9fddc545 100644
--- a/plugins/kiln-engine/runtime.json
+++ b/plugins/kiln-engine/runtime.json
@@ -1,6 +1,6 @@
{
"name": "@instruktlabs/kiln",
- "version": "1.5.0",
+ "version": "1.6.0",
"harnesses": [
"claude",
"codex",
diff --git a/plugins/kiln-hosted/plugin.json b/plugins/kiln-hosted/plugin.json
index b264ef8a..08fa00bb 100644
--- a/plugins/kiln-hosted/plugin.json
+++ b/plugins/kiln-hosted/plugin.json
@@ -1,7 +1,7 @@
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "kiln-engine",
- "version": "1.5.0",
+ "version": "1.6.0",
"description": "Create, review and revise editable 3D assets, with private saved revisions and GLB downloads.",
"author": {
"name": "Instrukt Labs",
diff --git a/src/engine-identity.ts b/src/engine-identity.ts
index 6541c2a8..d05a4917 100644
--- a/src/engine-identity.ts
+++ b/src/engine-identity.ts
@@ -27,7 +27,7 @@
* `src/__tests__/package-contents.test.ts` fails if it disagrees with the manifest
* or with any plugin manifest, which is what keeps the literal honest.
*/
-export const ENGINE_VERSION = '1.5.0';
+export const ENGINE_VERSION = '1.6.0';
/**
* Where this engine was loaded from, as a `file://` URL of the package root.