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.

docs: the install guide was directing readers away from the release (#106)

Matthew Kissinger09eb5964a55b
diff --git a/AGENTS.md b/AGENTS.md
index 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. **Both
registry** -- never hand-write a tool definition in a skin, or the transports drift apart and the
repo'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: the
latter's coexistence with a full tool set is provider-dependent, while a submit tool is unambiguous
everywhere. The MCP surface has no submit tool, because there the host agent writes the file itself.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5f461b70..0b7d4fdd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,38 @@
Changes to `@kiln/engine`. Source and installable packages are distributed through
GitHub. 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 Windows
diff --git a/docs/install.md b/docs/install.md
index 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 package
diff --git a/docs/migration.md b/docs/migration.md
index 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 additions
below 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 once
Save the `programRef` returned by a render or source import. Pass that reference to
diff --git a/docs/plans/repo-size-and-r2-migration-2026-09-10.md b/docs/plans/repo-size-and-r2-migration-2026-09-10.md
index 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 r
and the reflex was to treat the frequency as the diagnosis. The distinguishing evidence
cost nothing to read. This sits alongside 15.3 and 15.7: there an assertion was true and
measured 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.mjs
index 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');