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: the install guide was directing readers away from the release (#106)
Matthew Kissinger09eb5964a55b
diff --git a/AGENTS.md b/AGENTS.mdindex 89ffe2c5..08be89a4 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -30,6 +30,21 @@ in-process Strands tools (`src/agent/tools.ts`) and the stdio MCP server. **Bothregistry** -- 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.+One file, but **two surfaces, deliberately different sizes.** `kilnToolRegistry` is the+in-process agent loop's four tools; `createKilnProgramToolRegistry` is the host-agent MCP+surface of thirteen, which is what `docs/tools.md` documents and what a published release+advertises. "Both iterate the registry" means the definitions live in one file, not that the+two lists match.++The one name that differs is **`kiln_screenshot`, and it is merged rather than missing.** On+the in-process surface `kiln_render` returns metrics only and `kiln_screenshot` carries the+six-view grid -- two tools, so a cheap structural check need not pay for an image. On MCP+`kiln_render` is unified: it holds `media: screenshotMedia` and returns metrics, part paths+and images together, with six views when `capture` is omitted. A separate `kiln_screenshot`+there would be a second way to ask for the same grid. `src/mcp-parity.test.ts` asserts the+MCP surface does not carry it, so the merge stays deliberate; no capability is absent from+the MCP workflow.+Prefer an explicit terminal submit tool over `structuredOutputSchema` in the in-process loop: thelatter's coexistence with a full tool set is provider-dependent, while a submit tool is unambiguouseverywhere. The MCP surface has no submit tool, because there the host agent writes the file itself.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 5f461b70..0b7d4fdd 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -3,6 +3,38 @@Changes to `@kiln/engine`. Source and installable packages are distributed throughGitHub. The package is not published on the npm registry.+## Post-release polish: the install guide had gone stale — 2026-09-12++- `docs/install.md` told readers to use a checkout **"until an updated package is+ released"**, naming `kiln-engine-0.6.0.tgz`, an eight-tool surface, and five tools the+ package lacked. All three were true when written and none survived `v0.7.0`. Verified by+ driving the published tarball's MCP server over stdio: it advertises **13 tools**,+ including all five that section said were missing.+- Rewritten to link the latest release and the generated tool reference instead of+ restating either. The section was fragile because it duplicated facts that live in gated+ files — `docs/tools.md` is already checked against the registry, so it does not need+ repeating in prose that nothing checks.+- A test now enforces the rule that follows: install guidance may not hard-code a release+ tarball version, and must point at `releases/latest` and `tools.md`. Scoped to the docs+ that tell a reader how to *obtain* the package; `CONTRIBUTING.md` keeps its+ `kiln-engine-0.6.0.tgz` because there the filename is the evidence for why the version+ policy exists. Both failure modes verified — a pinned version, and a link that stops+ pointing at the latest release.+- `docs/migration.md` said "keeps the package version at `0.6.0` until release review",+ which stopped being true at the tag.+- **AGENTS.md now explains the two tool surfaces**, which was a real comprehension trap:+ `registry.ts` holds the in-process loop's four tools and the MCP surface's thirteen, and+ "both skins consume it" read as one shared list. The one differing name,+ `kiln_screenshot`, is **merged rather than missing** — in-process, `kiln_render` returns+ metrics only and `kiln_screenshot` carries the six-view grid, so a cheap structural check+ need not pay for an image; on MCP, `kiln_render` is unified and returns metrics, part+ paths and images together, so a separate screenshot tool would be a second way to ask for+ the same grid.+- Also measured while checking the new-developer path, in a fresh clone: **~31 seconds from+ nothing to a rendered GLB** (4s clone, 26s install, 1s render), and the documented+ render-service step works verbatim — `npm --prefix render-service ci --ignore-scripts` in+ 2s, then 37 tests pass.+## The Windows failure was a real bug in the alias lock — 2026-09-12- `rejects lost updates from eight independent processes` went red once on a Windowsdiff --git a/docs/install.md b/docs/install.mdindex b95fd9de..a34d9360 100644--- a/docs/install.md+++ b/docs/install.md@@ -30,15 +30,21 @@ For agent-assisted installation, give your agent the repository URL and ask:## Release compatibility-The downloadable `oss-2026-09-05` package (`kiln-engine-0.6.0.tgz`) exposes eight-MCP tools: discovery, validation, rendering, animation/interior views, inspection,-editing and source access. A fresh September 8 install verified discovery and a-CPU-rendered PNG. That package predates `kiln_save`, `kiln_assets`, `kiln_export`,-`kiln_present` and `kiln_import`; saved-asset examples require the newer checkout.--Use the checkout installation below for that tool set until an updated package is-released. A successful local build or unreleased fix does not update the GitHub-release. Do not substitute an unverified npm registry package.+Install the [latest release](https://github.com/matthew-kissinger/kiln/releases/latest).+It carries the full tool set, including `kiln_save`, `kiln_assets`, `kiln_export`,+`kiln_present` and `kiln_import` -- the five that the earlier `oss-2026-09-05` package+predated, which is why that one needed a checkout instead. The+[generated tool reference](tools.md) is the list the release actually advertises; a test+fails if the two drift apart, so it does not need repeating here.++Every release attaches a per-platform package receipt (Linux, Windows, macOS arm64,+macOS x64) and `SHA256SUMS.txt`. Each receipt records the sha256 of the tarball beside+it and is checked against that exact file before publication, so you can verify what you+downloaded rather than trusting the filename.++A successful local build or an unreleased fix does not update the GitHub release: a+checkout can be ahead of it. Do not substitute an unverified npm registry package -- this+package is distributed through GitHub and is deliberately not published to npm.## Start on a Mac with a local packagediff --git a/docs/migration.md b/docs/migration.mdindex 62b82f42..ac940766 100644--- a/docs/migration.md+++ b/docs/migration.md@@ -1,9 +1,12 @@# Updating an existing Kiln integration-This candidate keeps the package version at `0.6.0` until release review. Existing-inline-code calls and the legacy capture format remain supported. The additions+Existing inline-code calls and the legacy capture format remain supported. The additionsbelow are opt-in, except for corrections to export, camera and setup behavior.+The package version moves with every change that ships, so the version you are moving to+is whatever the [latest release](https://github.com/matthew-kissinger/kiln/releases/latest)+says; see [CHANGELOG.md](../CHANGELOG.md) for what changed between any two.+## Retain the source onceSave the `programRef` returned by a render or source import. Pass that reference todiff --git a/docs/plans/repo-size-and-r2-migration-2026-09-10.md b/docs/plans/repo-size-and-r2-migration-2026-09-10.mdindex ceaf431d..83c33ca5 100644--- a/docs/plans/repo-size-and-r2-migration-2026-09-10.md+++ b/docs/plans/repo-size-and-r2-migration-2026-09-10.md@@ -2092,6 +2092,7 @@ re-measured since the day it was written.| 15.7 | `--receipt` resolved against `root`, not the working directory | **Done 2026-09-12.** Found by assembling the release. See below || 15.8 | `v0.7.0` released | **Done 2026-09-12.** Tag `v0.7.0` at `44b4bc8`; four receipts and `SHA256SUMS.txt` from one CI run, each verified against the published tarball || 15.9 | The Windows failure was a real bug in the alias lock, not a flake | **Found and fixed 2026-09-12.** `mkdir` contention on Windows reports `EPERM`/`EACCES`, which was rethrown. See below |+| 15.10 | Post-release polish: is the repository actually pickup-ready? | **Done 2026-09-12.** Measured rather than asserted; two stale docs and one comprehension trap found. See below |### 15.1 -- the tag is the whole rewrite, on the clone side too@@ -2443,3 +2444,55 @@ rerun, ten green runs behind it" is a description that fits both a flake and a rand the reflex was to treat the frequency as the diagnosis. The distinguishing evidencecost nothing to read. This sits alongside 15.3 and 15.7: there an assertion was true andmeasured nothing; here an explanation was plausible and measured nothing.+++### 15.10 -- measuring "easy to pick up" instead of claiming it++The new-developer path was run rather than reviewed, in a fresh `--filter=blob:none` clone:++| Step, exactly as the README gives it | Time |+| --- | --- |+| `git clone --filter=blob:none ...` | 4 s |+| `bun install --frozen-lockfile` | 26 s |+| `bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png` | 1 s |++About half a minute from nothing to a 324-triangle GLB and a rendered sheet. The+contributor path was run in that same clone, including the step 15.3 had documented but+never tested from scratch: `npm --prefix render-service ci --ignore-scripts` in 2 s, then+`bun run test:render-service` at 37 pass. `check:toolchain`, `check:skills`, `typecheck`+and `lint` all clean on first run.++Three things were wrong, and all three were doc rot rather than code:++**`docs/install.md` was directing readers away from the release.** Its "Release+compatibility" section named `kiln-engine-0.6.0.tgz`, an eight-tool surface, and five+tools the package lacked, closing with "use the checkout installation below **until an+updated package is released**" -- the exact condition 15.8 had just changed. Checked by+driving the published tarball's own MCP server over stdio rather than reasoning from the+registry: 13 tools, including all five named as absent.++The section was fragile because it restated facts that live in gated files. `docs/tools.md`+is already generated from the registry and drift-checked (14.8), so prose repeating it is a+second copy that nothing verifies. It now links the latest release and the tool reference,+and a test enforces that: install guidance may not hard-code a tarball version and must+point at `releases/latest` and `tools.md`. Scoped to the docs that tell a reader how to+*obtain* the package -- `CONTRIBUTING.md` keeps its `kiln-engine-0.6.0.tgz`, where the+filename is the evidence for why the version policy exists. Explaining a past artifact is+not directing a download, and the first draft of the gate did not make that distinction and+failed on it.++**`docs/migration.md`** still said the package version was held at `0.6.0` "until release+review".++**The two tool registries were a comprehension trap**, and this one came from a question+rather than a grep. `AGENTS.md` said two skins consume `registry.ts`, which reads as one+shared list; in fact `kilnToolRegistry` is the in-process loop's four tools and+`createKilnProgramToolRegistry` is the MCP surface's thirteen. The honest answer about the+one differing name is that **`kiln_screenshot` is merged, not missing**: in-process,+`kiln_render` returns metrics only and `kiln_screenshot` carries the six-view grid, so a+cheap structural check need not pay for an image; on MCP, `kiln_render` holds+`media: screenshotMedia` and returns metrics, part paths and images together, defaulting to+six views when `capture` is omitted. A separate screenshot tool there would be a second way+to ask for the same grid. The parity test pins the absence, and the first version of this+note cited that test as if it were the reason -- a test records a decision, it does not+explain it.diff --git a/scripts/reliability.test.mjs b/scripts/reliability.test.mjsindex c6428ad3..7105f051 100644--- a/scripts/reliability.test.mjs+++ b/scripts/reliability.test.mjs@@ -277,6 +277,33 @@ describe('repository reliability contracts', () => {}});+ // `docs/install.md` spent a release cycle telling readers to use a checkout "until an+ // updated package is released", naming `kiln-engine-0.6.0.tgz` and an eight-tool surface.+ // All three facts were true when written and none survived the next release: the+ // published package advertises thirteen tools and carries the five that section says it+ // lacks. The doc was fragile because it restated facts that live in gated files.+ //+ // So the rule is about duplication, not about the number: a guide may link to the tool+ // reference and the releases page, and may not hard-code a tarball version that has to+ // be remembered. CHANGELOG.md is exempt -- naming exact versions is what it is for.+ test('install guidance does not hard-code a release tarball version', async () => {+ // Scoped to the docs that tell a reader how to OBTAIN the package. `CONTRIBUTING.md`+ // names `kiln-engine-0.6.0.tgz` on purpose and keeps it: there, the filename is the+ // evidence for why the version policy exists -- two people held that exact name and+ // had different software. Explaining a past artifact is not directing a download.+ const guides = ['README.md', 'docs/install.md', 'docs/migration.md'];+ for (const guide of guides) {+ const text = await readText(guide);+ const pinned = [...text.matchAll(/kiln-engine-(\d+\.\d+\.\d+)\.tgz/gu)].map(([, v]) => v);+ // A guide that names one is asserting something it cannot keep true.+ expect({ guide, pinned }).toEqual({ guide, pinned: [] });+ }+ // And the replacement has to actually point somewhere that is kept current.+ const install = await readText('docs/install.md');+ expect(install).toContain('releases/latest');+ expect(install).toContain('tools.md');+ });+test('standalone agent context stays concise and names the safety-critical paths', async () => {const agents = await readText('AGENTS.md');