@instruktlabs/kiln 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,2579 @@
+# Changelog
+
+Changes to `@instruktlabs/kiln` (previously the private `@kiln/engine` package).
+Source releases and installable package publication are separate milestones.
+Published versions and tags are recorded by the npm registry; changing this file
+does not publish a package.
+
+## 1.0.0
+
+Changes since the 0.10.0 tagged package release, qualified first through the public
+`1.0.0-rc.1` prerelease. Promotion of the stable archive to npm `latest` requires
+the separate release gates in [the runbook](docs/releasing.md).
+Hosted deployment and vendor directory acceptance remain separate milestones.
+
+- **Breaking:** the npm identity is now `@instruktlabs/kiln`, with compiled ESM and
+  TypeScript declarations for its public subpaths. The root is a library entrypoint;
+  use the `kiln` executable for the CLI. `kiln-mcp` starts the stdio MCP server.
+- Consumer archives contain the maintained installation/API/workflow documentation;
+  historical plans, reviews and model traces remain in the repository. Current
+  repository links and package publisher metadata point to Instrukt Labs.
+- Installed isolated evaluation resolves compiled workers and readiness probes
+  without a TypeScript loader. Host isolation still requires its own readiness proof.
+- The stdio executable cancels pending engine warmup when its client disconnects;
+  a tool-list-only session no longer starts unused engine work after closing stdin.
+- Isolated evaluation explicitly requires a user namespace before disabling nested
+  namespaces, satisfying Bubblewrap's launch precondition. Unsupported hosts still
+  fail closed before source execution.
+- Windows asset saves retry transient directory-rename denials within a bounded
+  delay, preserving atomic publication and existing immutable revisions.
+- Source restoration, MCP source resources, reviewed saves and CLI rebuild
+  observations preserve an authored UTF-8 BOM instead of silently changing the
+  source and its program reference. Invalid source UTF-8 is rejected on those reads.
+- Custom asset-library hosts can reuse the canonical saved-material resolver
+  through `@instruktlabs/kiln/assets/node`.
+- The `kiln-engine` local plugin uses the Instrukt Labs marketplace and installs a
+  pinned engine outside its disposable cache. It registers setup only; managed
+  workspaces own the authoring skills and one MCP server. Upgrades preserve stores
+  and refuse conflicts. The npm archive includes the small bundle and both catalogs.
+  Replacing an older `kiln@kiln` installation requires the explicit plugin migration;
+  public directory submission and hosted access remain separate release work.
+
+- Blind-run receipts recognize OpenCode's recorded code-mode MCP calls and AGY's
+  generic MCP dispatcher without inferring execution from source or output text.
+  Setup and authoring guidance now covers waiting for independent authors, checking
+  sloping panel fit, retaining repeated parts during edits and saving child revisions
+  before exporting. The eight-asset campaign records its incomplete handoffs and
+  visual defects separately from valid exports.
+
+- **Breaking (v1 candidate):** `optimize: 'full'` replaces flatten/join with rigid-group
+  merging. Its rigid-merge pass preserves node names, hierarchy and transforms, including animated targets,
+  named joint pivots, semantic nodes, composition placements and LOD levels. Ordinary
+  named mesh nodes can become empty or hold merged geometry. When geometry must remain
+  on every named part, use `optimize: 'off'` or `'palette'` with `instance: 'off'`;
+  the separate GPU-instancing pass can remove named instance nodes. Shared-buffer expansion is limited
+  to 4 KiB per saved draw, and merged buckets split at 65,534 vertices. Results expose
+  boundary, lock and rejection diagnostics. New builds record `rigid-v1`; exact
+  rebuilds of older unversioned full-mode revisions require their original engine
+  or an explicit new authoring revision. Original saved GLBs remain exportable.
+- ORM packing isolates shared images per metallic-roughness/occlusion pair. Materials
+  with different AO maps and consumers in other texture slots retain their original
+  pixels, UVs and samplers; identical packing pairs reuse the packed image.
+- Scene browser tools share portable executable discovery and clean up temporary
+  profiles on launch failure and close. The normal portable scene gate includes
+  script tests, and the static server identifies WebP images correctly.
+- Cloudflare Pages deployment has a portable Node preflight that verifies the exact
+  launch-mode artifact inventory, sizes and hashes against a clean checkout before
+  upload. The PowerShell entry delegates to the same implementation.
+- Inspection and export summaries add bounded per-anchor draw counts, a qualified
+  rigid-merge estimate, and sampled mirrored-tangent/coplanar-part observations.
+  Compact render output and tool input schemas stay unchanged; estimates and flags
+  are advisory, not GPU timings or QA acceptance.
+- Compatible dependency updates include glTF Transform 4.5.1, manifold 3.5.4,
+  MCP client/server 2.3.0, Strands 1.19.0 with the compatible AI SDK 6/provider 3
+  family, image libraries and tooling. Site/scenes use Vite 8.3.2. Maintainer pins
+  move to Node 22.23.3/npm 12.2.0, retaining Bun 1.4.2 and consumer Node compatibility.
+- The exact-input scene release gate verifies public pack hashes and cannot pass
+  through missing-fixture skips. Shadow caches observe morph weights, Farm's economy
+  tier retains its trailer casters, and Golden Gate reflections exclude dynamic
+  traffic/player/fog while preserving vegetation; diagnostic fog hiding persists.
+
+- The scenes' dependency pin check resolves the engine, site and render service
+  from the integrated checkout instead of hard-coded Windows worktrees. It now
+  runs on the Linux hub and relocated checkouts; a filesystem regression test
+  verifies collection and detection of an engine pin mismatch. Contributor and
+  Troy resume instructions name the current validation and workspace setup commands.
+- The kit pass (`applyKitContract`, `packKitGlb`) no longer folds an occlusion map into the
+  metallic-roughness image when the two are read through different UV sets or
+  `KHR_texture_transform` values. It used to point the occlusion slot at the
+  metallic-roughness UV set as well, so a baked AO map on `TEXCOORD_1` was sampled through
+  `TEXCOORD_0`. Such a material keeps its separate occlusion image and UV set, and the
+  summary's new `ormSkipped` names the material and the reason; a matching pair packs as
+  before, and packing no longer rewrites the occlusion slot's UV set.
+- `src/render.ts` and `src/__tests__/optimize.test.ts` no longer cite
+  `docs/kiln-material-consolidation-cycle.md`, which exists on no branch; the `OptimizeMode`
+  comment states the rule in place.
+- `docs/runtime.md` documents `KILN_BAKE_OPTIMIZE` and `KILN_BAKE_INSTANCE`: their values,
+  that they only set the default for a render that omits `optimize` or `instance`, that the
+  MCP and CLI tools pin `optimize: 'off'` (so only `KILN_BAKE_INSTANCE` reaches their GLBs),
+  which library renders take the variables, and that a saved revision rebuilds with the
+  options its manifest recorded. No behaviour changes.
+
+## 0.10.0
+
+**Protocol revision 2026-07-28, and a server that answers before it loads.** The v1
+readiness cycle ([plan](docs/plans/2026-10-01-v1-readiness-cycle.md)) measures Kiln under
+Claude Code, Codex, OpenCode and Antigravity and fixes what the sessions show. Entries
+marked **Breaking** change what a client or an embedder observes.
+
+### MCP transport
+
+- **The stdio server serves protocol revision 2026-07-28 beside the 2025 handshake
+  revisions.** `@modelcontextprotocol/server` and `client` move to 2.2.0 and `ext-apps` to
+  2.0.3. A 2026-07-28 client sends `server/discover` or any request carrying the per-request
+  `_meta` envelope and needs no handshake; a 2025-11-25 or 2025-06-18 client sends
+  `initialize` as before. Every 2026-07-28 result carries `resultType` and the server
+  identity; `server/discover`, `tools/list`, `resources/list`, `resources/templates/list` and
+  the viewer page read are `public` with a one-day `ttlMs`, while asset and project reads
+  stay `private` with `ttlMs: 0`.
+- **Breaking:** a request that carries neither a protocol version nor a preceding
+  `initialize` is answered `-32602` with both ways in, instead of being served as a 2025
+  session. `listChanged` is no longer advertised for tools or resources (the lists are
+  fixed for a build) and `subscriptions/listen` acknowledges no list-changed
+  notifications. Advertised schemas no longer carry `$schema`.
+- **The entry is thin.** `dist/mcp-server.mjs` bundles the protocol library and a generated
+  manifest of the definitions (`src/generated/mcp-manifest.json`, regenerated by the build
+  and by `bun run mcp:manifest`), answers `initialize`, `server/discover` and `tools/list`
+  from it (229 ms after process start in the startup test on the maintainer's PC, against
+  1.1 to 1.7 s before), and loads `dist/mcp-engine.mjs` on the first call that needs the
+  engine, warming it once the harness holds the tool list. **Breaking** for hand-wired
+  installs that copied the one file: both bundles must stay together.
+- **Breaking:** a configuration problem no longer kills the server at startup. A stale
+  workspace, an invalid `KILN_RENDER` or a missing engine bundle come back as the first tool
+  result, naming the next step and no local path; the next call tries again, so a workspace
+  repaired while the harness is open needs no restart. A wrong command-line option and an
+  unreadable or legacy `--requirements` file still exit 1 before the protocol starts.
+- **Breaking** for embedders: `createKilnMcpServer`, `kilnMcpToolDefs` and `runTool` moved
+  from `src/mcp-server.ts` to `src/mcp-engine.ts`, and `createKilnMcpServer` returns the
+  low-level `Server`; `MCP_SERVER_NAME`, `MCP_SERVER_VERSION` and `MCP_SERVER_INSTRUCTIONS`
+  live in `src/mcp-core.ts`. `src/requirements-json.ts` reads a host binding file without
+  zod; `readHostRequirementsFile` validates on top of it as before.
+
+### Tool surface
+
+One versioned batch: tool definitions are prompt-cached, so every schema and description
+change lands together. Measured on the packaged manifest: the seventeen advertised
+definitions 39,603 characters as JSON (74,649 before), every input schema within 5,000
+bytes (four were over, the largest 18,788), input schemas 26,475 bytes in all (61,598),
+`src/generated/mcp-manifest.json` 72,659 characters (205,917).
+
+- **Breaking:** `kiln_project`, `kiln_material` and `kiln_review` are one flat object each
+  with an `action` enum instead of a root `oneOf` (Claude Code dropped all three). Every
+  other field is optional in the schema; the server checks what each action needs and names
+  the missing fields. The nested `draft`, `patch` and `payload` records are opaque in the
+  schema and validated when the action runs; `kiln_discover({ ids: ['shape:project-draft'] })`
+  (and `shape:project-patch`, `shape:material-draft`, `shape:material-import`) returns the
+  full JSON Schema through the new Discovery kind `shape`. `kiln_project` offers `export`
+  only when the host can read project bundles. The field names and defaults are unchanged.
+- **Breaking:** `kiln_edit capture`, `kiln_view_interior capture`, `kiln_inspect shot` and
+  `kiln_screenshot_animation shot` are advertised as opaque records; `kiln_render` states the
+  capture shape in full, `shape:capture` and `shape:camera-shot` describe it, and each tool
+  validates the record as before when it runs. The capture schemas live in
+  `src/tools/capture-input.ts`.
+- `kiln_validate`, `kiln_render`, `kiln_edit`, `kiln_inspect`, `kiln_view_interior` and
+  `kiln_screenshot_animation` accept `file`, a program file inside the workspace named
+  relative to its root, beside `code` and `programRef`; absolute paths and `..` are refused
+  with the rule. A code-mode harness can hand Kiln a path instead of quoting a program.
+- The configured project is visible: `kiln_discover` capabilities carry
+  `project.configured`, the overview says to read it first, and a project-bound render,
+  edit, inspection or save result carries `project: { projectId, revisionId }`.
+- **Breaking:** the server instructions are 692 characters (2,297 before), name no absolute
+  path and point at `skills/` beside the server; the list of skills and the offer to copy
+  them into `.claude/skills/` or `.agents/skills/` moved out. Workspace selection and
+  camera field text is shorter, and every description opens with its purpose.
+- `docs/tools.md` is the packaged manifest pretty-printed (seventeen tools, the advertised
+  bytes), no longer the embedding registry's fourteen.
+- `kiln_material` accepts `resourceId`, the name a project's palette and
+  `materialDependencies` give a material, as an alias of `materialId` (a Codex session
+  passed it twice and was refused both times); the advertised schema and the docs keep
+  `materialId`, and a call naming both with different values is refused with the fix.
+- **Breaking** for a call that pins another revision of a project's material: a project
+  revision implies its material pins, and a pin the call names replaces the project's or
+  the inherited one for the same `resourceId` instead of being refused as a conflict (a
+  Codex session repeated the project's five pins on every render, edit, inspect and
+  animation call, 1,300 to 3,400 characters of arguments each, because the field said
+  project locks could not be replaced). The `materialDependencies` description of the
+  six workspace-bound tools says so in the same number of bytes.
+
+### Program handles
+
+- A `programRef` the store does not know comes back as a tool result that names the next
+  call (`kiln_validate` or `kiln_render` with `code`) and no local path. `kiln_validate`,
+  `kiln_render`, `kiln_edit`, `kiln_inspect`, `kiln_view_interior` and
+  `kiln_screenshot_animation` state the retention of the handle they return: the packaged
+  file store keeps it across sessions and processes without eviction. `ProgramStore` gains
+  an optional `retention` sentence for injected stores, and `docs/tools.md` states the
+  packaged store's.
+
+### Results
+
+The baseline sessions measured a `detail: 'full'` render of 79,078 characters (cut near
+40,000 before Codex's model saw it; 24% of it line breaks and indentation), 41 copies of
+one finding with the same 300-character repair text, and Agy writing every result over
+about 4,000 characters to a file the model then read back. A default result is now at
+most 20,000 characters and no result is over 40,000; on a 97-part fixture whose every
+part floats, the compact render result is 9,103 characters, `full` 16,734 and `lean`
+2,018. `src/__tests__/result-contract.test.ts` and `mcp-errors.test.ts` hold the rules.
+
+- **Breaking:** every tool result is JSON on one line. A render, edit, inspection,
+  interior or animation result leads with `ok`, `acceptance`, `disposition`, up to eight
+  `blockers` (grouped by code with the repair text once), the `findings` counts and
+  `next`, the sentence naming the next call; the `programRef` follows, then the metrics.
+- **Breaking:** the compact report groups the findings of each dimension by code, most
+  severe first: one record per code with `count`, the first affected entity and up to two
+  `alsoAffected`, `findingsTotal`, and `findingsOmitted`/`omittedByCode` beyond twelve
+  groups. The rule records collapse to `ruleSummary` (`evaluated`, `notEvaluated`;
+  `notRequested` rules are not listed). `viewEvidence` carries `current` and the hash-only
+  `lastFaithful`, not the faithful history. The part
+  preview is 24 paths with `partsNextOffset` and the `kiln_inspect listParts` hint.
+  Build warnings are at most twelve of 1,000 characters each with `warningsOmitted`.
+- `detail` on `kiln_render`, `kiln_edit`, `kiln_inspect`, `kiln_view_interior` and
+  `kiln_screenshot_animation` takes `lean`, `compact` (default) or `full`. `lean` is the
+  verdict, blockers, counts, next step, metrics, a short fidelity receipt and three
+  warnings. `full` is every finding, rule and part that fits 40,000 characters, with
+  `retainedReport: { operationId, path }` naming `.kiln/review/<operation>/evaluation.json`
+  (now pretty-printed) when Live Review records the operation; when the complete report
+  does not fit, the warnings are bounded first, then repeated findings group by code
+  with every rule kept, then the part list shrinks and the groups halve, and
+  `qaReport.detail` reads `full-bounded`. The packaged host reads `KILN_RESULT_DETAIL`
+  (`lean` or `compact`) as its default.
+- **Breaking:** a `kiln_edit` result is `ok`, `applied`, `changed` (status, part and
+  animation summaries, the first five changes), `next`, the `diff` (2,000 characters in
+  `lean`, with `diffOmitted`), `preservation` (not in `lean`) and the compacted `render`.
+  The compact `preservation.comparison` is the counts, the artifact before and after and
+  up to twelve changes as path, name, status and changed fields; the bounds of each
+  change and the scope sentences stay in `full` (a live compact edit of a 49-part asset
+  measured 20,069 characters with them, 7,191 of it the comparison). When a compact edit
+  would still pass 20,000 characters, its `diff` is shortened first, never below 2,000,
+  with `diffOmitted`.
+- **Breaking:** a `kiln_inspect compare` page in `compact` or `lean` is the same shape:
+  the counts, the artifact before and after, `offset`, `nextOffset` and each change of
+  the page as path, name, status and changed fields. A live compact page of 50 changes
+  measured 38,952 characters with their bounds and the scope sentences; `detail: 'full'`
+  keeps them.
+- **Breaking:** in `compact` and `lean` detail a per-view receipt (`derivativeReceipts`,
+  and `viewFidelity.receipts` of shot and animation results) is its `derivativeLabel`,
+  `cameraFidelity`, `captureCache` and only the fidelity fields that differ from the
+  result's `viewFidelity`; the camera is in `cameraShots` under the same name. A live
+  six-shot compact edit measured 22,417 characters with 4,672 of receipts repeating the
+  summary and the cameras; `full` keeps whole receipts.
+- **Breaking:** a compact or lean result rounds every number to six decimals (a micrometre
+  on a metre-scale asset); `full` and the retained report keep every digit. The 17-digit
+  doubles of bounds, cameras and origins were 4,346 of a live 24,223-character compact
+  animation result and 1,514 of a 20,556-character compact six-shot edit.
+- **Breaking:** in `compact` and `lean` detail, frames of an animation that resolve to one
+  shot are stated once in `cameraShots` with `frames` counting them and each frame's
+  bounds in `poseBounds` (nine frames repeated a 631-character camera and subject, 5,666
+  characters); `viewFidelity` states once what every receipt shares (the renderer id, a
+  degrade reason); and `viewEvidence.lastFaithful` is omitted when it is the current view.
+  When nine phases and many measured parts would still pass 20,000 characters, the leading
+  frames of `poseBounds` stay whole and `poseBoundsOmitted` counts the rest, with
+  `poseBoundsHint` naming the way to them; `full` keeps every frame that fits 40,000.
+- **Breaking:** a `detail: 'full'` edit is bounded as a whole. A live full edit measured
+  40,533 characters: its render bounded at 40,000 on its own, the 8,177-character diff and
+  the 10,973-character comparison on top. The diff shrinks first (to 2,000, with
+  `diffOmitted`), then the bounds of each change leave the comparison (the retained report
+  keeps them), then the render is bounded again with what is left.
+- **Breaking:** `kiln_edit` no longer echoes the patched source when the program was sent as
+  `code`: a live edit of a 13,173-character program came back at 28,539 characters, the
+  source beside the render. The retained `programRef` serves it through `kiln_source`;
+  `includeCode: true` asks for it, bounded with the rest of the result (`codeOmitted`,
+  `codeHint`).
+- An invalid-input error no longer ends an issue sentence twice (`...or file.. Check`), and
+  one that names a key the tool does not take lists the keys it does (`kiln_material takes
+  action, materialId, ...`): a live session passed a project palette's `resourceId` to
+  `kiln_material get` twice and was told only to check the schema. The `materialId`
+  description names the palette's `resourceId`. A nested record the image tools enforce
+  when they run (`shot`, `capture`) that fails to parse is the same kind of sentence naming
+  the record's Discovery shape, as a tool error: a live session put the camera fields at the
+  root of a `shot` and received `ok: false` with zod's issue dump under "Fix the error in
+  the source".
+- `kiln_assets get` and `restore` without `revisionId` read the asset's newest revision (the
+  one no later revision names as its parent), and `kiln_material get` without `revisionId`
+  reads the material's only revision, naming the revisions when there are several; both
+  match `kiln_project get`. Three live sessions called `get` with the id alone and were
+  refused.
+- **Breaking:** `kiln_inspect listParts` returns names and paths; `placement: true` adds
+  the world transform, mirroring and bounds in pages of 50. The floating-parts warning
+  names the first six parts with their fix and the next 24 by name, and a render result
+  carries the export-time structural warnings once (a second pass over the re-imported
+  scene repeated every floating part under its primitive name).
+- **Breaking:** `kiln_review list` pages (`offset`, `limit` up to 100, default 20) and
+  returns short records (`operationId`, `revision`, `tool`, `status`, timestamps,
+  `programRef`, `pinned`, the artifact hash, capture count and fidelity) with `total` and
+  `nextOffset`; `get` and `pin` return an operation bounded to 20,000 characters, naming
+  the retained file for what was left out. `kiln_discover` detail pages stop at 15,000
+  characters and name the ids not returned in `omittedIds`.
+- **Breaking:** a result with `ok: false` is an MCP error (`isError: true`). Every error
+  names the next call and no absolute local path: an invalid input is a sentence naming
+  the fields and the `shape:` id to read instead of a zod issue dump; an unknown project,
+  material, asset or review id names the `list` action; a renderer that is required but
+  unavailable names `KILN_RENDER`, `KILN_RENDER_PORT_URL` and `kiln_renderer reprobe`;
+  `kiln_review save` names the revision or status to fix; a project import refusing its
+  own id says to pass a different `--id`; a shot whose subject names no node, or more
+  than one, is answered with the shot's fix (one exact part path from the list in the
+  error), not the source's.
+- The CLI `render --json` and `animation --json` receipts carry the compact result by
+  default (one receipt measured 51,312 characters at `full`); `--detail lean|compact|full`
+  selects the detail. The CLI `material list` prints the summaries `kiln_material list`
+  returns, not every manifest (34,116 characters for five pinned materials before).
+- `scripts/tier2-dogfood.mjs` counts the tool steps of an Agy stream (`step_update` with
+  `tool_name`, one per step index), so a blind Agy run's receipt no longer says `unknown`.
+- A saved manifest read as a resource (`kiln://assets/.../manifest.json`) is one line, as
+  every tool result is; the file on disk stays pretty-printed. CLI `kiln asset <id>`
+  without a revision reads the asset's newest revision, as `kiln_assets get` does (it
+  refused with "requires asset ID and revision ID"), while `export` still names one exact
+  revision; `kiln save --help` prints the save usage alone (a blind OpenCode run read
+  2,275 characters of the assets-and-viewer block for it, and the whole block had been
+  16,077 before the records trim).
+
+### Generated code
+
+The follow-ups the owner decided on 2 October 2026 after reading the cycle's report
+(decisions 23 to 28 in the plan) land here, on the same branch, before it merges.
+
+- **Breaking:** generated code runs in strict mode. The evaluator prepends `'use strict'`
+  to every program and `kiln_validate` parses with the same directive, so a construct only
+  strict mode refuses (`with`, a legacy octal literal, a duplicate parameter name) is a
+  `SYNTAX_ERROR` with its line before any evaluation; an assignment to an undeclared name
+  throws (answered as an unbound variable) instead of creating a host global; and a
+  function declared inside a block stays in that block. The source policy allows `this`
+  inside object-literal methods, getters, setters and function properties, class methods,
+  constructors, accessors, field initializers and static blocks, and in arrows nested
+  inside those, where it is the receiver the program built (w29's mesh batcher was an
+  object literal whose `add` method read `this`); `this` at the top level or in a plain
+  function stays `UNSAFE_GLOBAL_ACCESS`, as does `module`.
+- The generic rejection carries the engine's own advice. A program that throws without
+  a closed cause is still answered `Generated asset execution was rejected.` with no
+  message, stack or identifier from it; that sentence now continues with a fixed
+  engine-owned paragraph saying so and naming the way to read values (`kiln_inspect` on
+  a rendered program, not a thrown `Error`) and the way to find the line
+  (`kiln_validate`). The scene session that threw an `Error` to print bounding boxes got
+  the bare sentence (H30). A rejection with a cause keeps that cause's advice alone; the
+  wire message and the adversarial isolation test's exact first sentence are unchanged.
+
+### Knowledge and setup
+
+Standing knowledge is read whole at the start of every session and again after each
+compaction, so it is a budget: the generated guide is at most 5,000 characters and a
+`SKILL.md` at most 16,000 characters and 500 lines, enforced by the workspace tests and
+`check:skills`.
+
+- **Breaking** for generated workspaces: `AGENTS.md` carries a 4,461-character guide
+  (10,716 before) and `CLAUDE.md` is the one-line import `@AGENTS.md`. Claude Code 2.1.287
+  loads `AGENTS.md` by default only where no `CLAUDE.md` exists, so the import keeps one
+  copy of the guide in context whichever file it reads. A workspace carries one skill
+  registry, the directory its harness reads: `.claude/skills/` for Claude Code (whose binary
+  also names `.agents/skills`, so the two copies registered every skill twice),
+  `.agents/skills/` for codex, hermes, agy, copilot and cursor-agent, and none for OpenCode,
+  whose `opencode.json` names `skills/` in `skills.paths`. Existing workspaces are not
+  rewritten: `kiln-init --check` reports the second registry a 0.9 workspace carried as
+  `retired`, `--upgrade` removes it when unchanged and stops on an edited copy.
+- `kiln-author-asset/SKILL.md` is 15,969 characters (19,030 before). Its delivery paragraph
+  offers `node kiln.mjs view` to a person who is present instead of telling the agent to
+  launch it: a headless Codex session saved its asset and then sat behind the viewer until
+  the 30-minute cap. The author, QA and camera guidance make the compact result the way
+  to review and name `detail: "full"` only as a qualified second look: the first wave
+  pair asked `full` on every render and edit in both the compact and the lean arm because
+  the skills said to pass it "for every finding". `check:skills` now refuses a skill
+  sentence that names full detail without "only". `engine-handoff.md` lives once in `kiln-qa-asset` and
+  `export-profiles.md` once in `kiln-author-asset`, each named by skill and path from the
+  other (a skill's markdown links stay inside the skill, so a workspace that installs one
+  skill alone resolves every link); `check:skills` refuses two files under `skills/` with the
+  same bytes.
+- Codex: the generated `.codex/config.toml` is read once `$CODEX_HOME/config.toml` marks
+  the project trusted (measured on 0.160.0; the generator and `START.md` said Codex read no
+  project-local config), `node codex.mjs` applies the same values per run so no trust entry
+  is needed, and its `env_vars` forward `KILN_PROJECT`, so a configured project reaches the
+  server under Codex as it does elsewhere. `kiln-init --help` lists all seven harnesses.
+- Antigravity: the generated `.agents/mcp_config.json` sets `KILN_RESULT_DETAIL=lean` on
+  the server entry. Antigravity writes a result over about 4,000 characters to a file the
+  model then reads back, and the wave's paired sessions showed lean winning both measures
+  only there (24% fewer result characters, 8% fewer output tokens); the other harnesses'
+  entries set nothing and keep the compact default, and a call's own `detail` still wins.
+  An existing Antigravity workspace shows the entry as changed managed configuration to
+  `kiln-init --check`; `--upgrade` refreshes it when the file is unedited.
+- Records: the plugin manifests say 0.10.0 and `kiln` (the Codex plugin manifest said
+  `kiln-oss`), the root `plugin.json` no longer names a schema URL that returns 404,
+  `docs/dogfooding.md` and `docs/clean-room.md` name OpenCode's `--standalone` (there is no
+  `--pure` in 2.0.14), `docs/harnesses.md` records the measured skill directories and the
+  Codex trust rule, and the Tier 2 driver reads the packaged manifest for the tool names it
+  counts as workspace MCP use (its hand-kept list lacked `kiln_discover`, `kiln_renderer`,
+  `kiln_project`, `kiln_material` and `kiln_review`).
+
+## 0.9.0
+
+**Source and site preview for dogfooding.** The v0.9 work is integrated for the
+Cloudflare site rollout. Package publication remains deferred to v1.0 after feedback.
+Individual asset review status is recorded on its page; deployment does not change it.
+
+Kiln 0.9.0 adds optional projects, a material library and Live Review to standalone
+authoring, makes the calibrated `review-neutral-v1` rig the default for review views,
+exports declared levels of detail as `MSFT_lod` chains, and fixes the defects authors
+reported while using 0.8. Standalone assets need no project. The [migration notes](docs/migration.md#changes-in-090) list every change an
+existing author will notice; the [foundation checkpoint](docs/plans/2026-09-26-project-foundation.md)
+records how projects, materials and Live Review were qualified.
+
+### Projects, materials and Live Review
+
+- **Optional projects.** `kiln_project` and `node kiln.mjs project` create, read and
+  update immutable, versioned project records: brief, inventory, design profile,
+  references, delivery intent and an exact material dependency lock. Updates name the
+  expected revision and report conflicts. Work stays standalone unless an operation
+  selects a project (`--project`, MCP `projectId`) or the host configures
+  `KILN_PROJECT`; `--no-project` and `projectId: null` override that default. The
+  collection named `project` remains only a save destination.
+- **Material library.** `kiln_material` and `node kiln.mjs material` keep immutable
+  material revisions with creator, license, recipe, seed and source provenance. Five
+  offline procedural presets (`warm-brick`, `wood-grain`, `brushed-metal`,
+  `woven-fabric`, `coarse-soil`) each produce base colour, normal and packed
+  metallic/roughness maps. Custom procedural drafts, normal-from-height derivation and
+  complete payload import and export are supported. Source compiles a returned
+  `portableSpec` with `compilePortableMaterialSpecV2`; the exact pins travel as
+  `materialDependencies` or `--materials`.
+- **Live Review.** `node kiln.mjs view` opens the local dashboard: Library, Materials,
+  Projects and Live Review. Live Review shows the exact retained artifacts, captures
+  and fidelity of CLI and MCP operations, with iterations, errors, pinning, comparison
+  and reconnection. `kiln_review` lists, gets and pins observed operations and saves an
+  exact reviewed operation. `KILN_WORK_ITEM` optionally groups one authoring item across
+  sessions. The Measure control records a bounded browser load and frame sample.
+- **Delivery.** `project export --profile editable|runtime` packages a project's linked
+  saved revisions; editable packages rebuild offline from source, settings and
+  complete material resources, and `asset ... --rebuild` reports artifact hash equality.
+  The Library aggregates configured collections with collection-qualified IDs.
+- **Seventeen MCP tools.** The packaged stdio server lists the fourteen program tools
+  plus `kiln_project`, `kiln_material` and `kiln_review`. Embeddings advertise those
+  three only when their host services are supplied.
+
+### Review lighting and provenance
+
+- **`review-neutral-v1` is the default review rig**: a calibrated white rig with
+  Review Neutral, a Khronos PBR Neutral variant. A key-facing matte `#C0362C` panel
+  reads `(193,51,40)` instead of `(255,177,147)`; mean CIEDE2000 over the ColorChecker
+  chart falls from 28.09 to 0.51. `neutral-studio-v1` and `gallery-studio-v1` stay
+  selectable by explicit lighting ID, captures without one re-render after the upgrade,
+  and composer's unsupported `neutral-studio-v2` default becomes `review-neutral-v1`.
+  Do not darken albedo for review lighting.
+- The CLI honours `KILN_RENDER` on every renderer-selecting path: an explicit
+  `--render` wins, then `KILN_RENDER`, then auto.
+- Saved builds record the installed engine under every build-cache policy, and an
+  absent optional peer is fingerprinted as peer-absent instead of erasing the runtime
+  identity.
+
+### Levels of detail
+
+- **One tier unless the brief asks.** The authoring skills say so. Tiers are sibling
+  groups named with one stem and a level token (`Body_LOD0`, `Body_LOD1`), LOD0 the
+  full-detail tier, and each set is declared once with
+  `defineLod(levels, { screenCoverage })`: one screen fraction per level, 0 to 1,
+  strictly decreasing, where a last value of 0 never culls. `createPart` is unchanged.
+  Two or more sibling tiers without a declaration, a gap, a missing LOD0 or a set
+  declared inside another tier fail the build with the closed diagnostic `LOD_SET`.
+- **Exported as `MSFT_lod`.** Every GLB Kiln writes from source (the saved `asset.glb`,
+  `kiln_export`, `kiln export`, `render --out`, both export profiles, both converters)
+  carries each set as one chain: LOD0 stays in the scene with `extensions.MSFT_lod.ids`
+  and `extras.MSFT_screencoverage`, the lower levels leave the scene with their subtrees
+  and transforms, and materials are untouched. A loader without the extension draws
+  LOD0.
+- **LOD0 is the headline.** Triangles and bounds count LOD0 and the parts outside every
+  set; `levelsOfDetail` in render results, the integration manifest and CLI receipts
+  lists each level's path and triangles.
+- **Review views.** Default sheets in `kiln_render`, `kiln_inspect` and the `kiln_save`
+  preview draw LOD0. A shot whose subject is a lower level's `path` draws that level in
+  LOD0's place (`visibility: "isolate"` shows it alone), the CPU and GPU views agree,
+  and each chain's `drawn` says which level every view drew. No tool input changed.
+- **Viewer.** Library and Live Review show a Level control (LOD0 to the last level,
+  LOD0 by default) and every level's triangles for a GLB with chains, imported or
+  authored. Expand **Per-part levels** to choose each independent chain, such as a
+  medium tractor body with detailed wheels. Mixed selections report the triangles
+  actually displayed. Current and pinned Live Review artifacts have their own part
+  controls; the current artifact's global selector still sets both views. Selecting
+  another observation of identical bytes retains geometry statistics and updates
+  the observation identity.
+- **Revision comparison** reads chains: each lower level is compared at the path it
+  takes beside LOD0. Switch thresholds are not compared.
+
+### Authoring and review contracts
+
+- Part listings include world position, quaternion, scale, mirrored orientation and
+  world bounds, including compact results.
+- Node and material `userData` round-trips through glTF extras: plain JSON, at most
+  4 KiB per object and 64 KiB per asset. `kiln*` keys remain engine-owned. Validation
+  reports literal problems; builds report omitted dynamic values. Optimization keeps
+  metadata-bearing nodes and materials instead of merging away their identities.
+- `visible = false` survives export as `KHR_node_visibility`. Headline metrics and
+  category QA exclude hidden subtrees; `hiddenNodes` reports their triangle counts.
+  Instancing and flattening preserve the flag and its ancestor scope.
+- `markOpenShell(part, reason)` acknowledges an intentionally unmeasurable open shell
+  without suppressing measured overlap or other failures. Overlapping closed components
+  use union volume; unsupported inward shells and component budgets remain unmeasured.
+- `CUBICSPLINE`, `EASE_IN`, `EASE_OUT` and `EASE_IN_OUT` tracks export standard cubic
+  samplers with computed tangents and play consistently in review. Quaternion loop
+  closure treats `q` and `-q` as the same rotation.
+- Source exports index unindexed primitives by welding exact complete vertices.
+  `indexPolicy: 'asBuilt'` (local host: `KILN_INDEX_POLICY=asBuilt`) retains helper
+  buffers and requires optimization off. Render results and CLI receipts report the
+  index pass's accessor payload bytes before/after, separately from GLB file size.
+- Sweep and loft helpers observe tight curvature and intersecting consecutive rings
+  with station evidence. The bounded local check replaces unconditional unchecked
+  warnings; budget-limited checks remain explicitly partial. Distant segments are
+  outside this check.
+- `kiln.capture.v2` adds shot-level `hide` with exact paths or unique names. Version 1
+  and legacy captures remain valid. CPU and GPU derivatives apply the same hide list;
+  post-loop CPU captures resolve subjects from the exported hierarchy.
+- Instanced capture derivatives and canonical bounds retain every instance transform.
+  Overlap QA excludes alternate levels only within the same LOD chain, and category
+  diagnostic sheets show the default LOD0 scene. Render-service startup tolerates a
+  concurrent winner's bounded warmup; completed captures verify the service instance.
+
+### Fixes from author reports
+
+- **Smaller results.** MCP `kiln_render` and `kiln_screenshot_animation` are compact by
+  default; `detail: "full"` returns every finding and rule. On the carousel example a
+  render result falls from 34,904 to 7,706 characters. `kiln_view_interior`,
+  `kiln_inspect` and `kiln_edit` are compact too; the CLI, retained artifacts and Live
+  Review keep complete reports.
+- **Sizes and files.** Animation composites take a frame `size` of 128 to 1024 px
+  (default 256). Versioned capture shots go up to 2048 px. `--capture` with
+  `output: "separate"` writes `<stem>.shot-01.png` and onward.
+- **Animation.** `createClip(name, duration, tracks, { loop })` records loop intent,
+  exported as the animation extra `kilnLoopIntent` and checked by review
+  (`LOOP_NOT_CLOSED`). GLBs no longer duplicate every clip as the `kilnReviewClipsV1`
+  scene extra.
+- **Views.** Saved previews drawn from the persisted GLB record `exactArtifact: true`.
+  Isolated capture shots send the GPU only the subject. CPU views draw translucent
+  surfaces after opaque ones, farthest first, so glass shows what is behind it. An
+  explicit perspective camera without `near` sets it from the nearest geometry.
+- **Geometry and export.** `extrudeProfile` adds no side rings unless `divisions` asks
+  (16 by default when twisted). `sweepProfile` keeps hard corners (`creaseAngle` 60)
+  and can cap one end. Emissive intensity survives export, above 1 through
+  `KHR_materials_emissive_strength`. An imported GLB's `MSFT_lod` chains survive
+  import, save, optimisation and export.
+- **Diagnostics.** A build that throws names a closed cause with advice and a
+  `Source check:`; `kiln_validate` reports `TEMPORAL_DEAD_ZONE`,
+  `MATERIAL_RECIPE_OVERRIDE` and `MATERIAL_RECIPE_ID`. Overlap QA skips LOD
+  alternates, tests the likeliest pairs first and groups unmeasurable parts;
+  connectivity leaves out LOD1+ parts. Repeated helper notes appear once with a mesh
+  count. The instanceability grade says it is informational, the blend-area budget
+  names its largest materials, and `kiln_inspect` evaluates without optimisation.
+- **Errors that name candidates.** Ambiguous and missing subjects, unknown camera keys
+  (`fovDeg` for `fov`) and missing or shared `surfacePairs` names list what would have
+  matched. `surfacePairs` take exact paths or unambiguous node names, as `measure` does.
+  Animation `measureParts` entries carry each node's world origin.
+- **Setup and CLI.** A workspace's `kiln.mjs` re-executes under the Node recorded at
+  setup, so CLI exports equal `kiln_save` bytes. `.kiln/workspace.json` names the
+  bundle `buildIdentity`, apart from the installed `runtimeIdentity`. The viewer
+  accepts `localhost` and `[::1]`; Git Bash collection roots are refused on Windows.
+  `kiln edit` and `kiln source` accept `--json`, `kiln service start` joins or starts
+  the shared renderer, and a render URL naming the shared local socket takes the local
+  route.
+
+### Fixes from the 0.9 dogfood runs
+
+Three blind setup-and-author runs on the packaged build, two in OpenCode and one in Agy,
+found these before release.
+
+- **`kiln_edit` results** lead with `programRef` and `parentRef` and carry a compact
+  render; `kiln_render({ programRef, detail: "full" })` returns the complete report.
+- **Discovery.** `ids` take a recipe's bare slug (`material-wood-v1`) as well as
+  `recipe:material-wood-v1`, and a material recipe's summary names its
+  `materialRecipe("kiln.material.wood.v1")` call. Reviewed aliases let `bench`, `table`
+  and `cast iron` find the joined-frame recipe, `arrayLinear` and the painted-metal
+  material.
+- **One `--json` rule.** `render`, `source`, `export`, `discover`, `inspect`, `animation`
+  and `service status`/`reprobe` print a receipt; commands that print JSON already accept
+  the flag; `generate`, `view`, `collections add` and `service start`/`stop` refuse it
+  and name the commands that take it. `export --json` names each file with its `bytes`
+  and `sha256`.
+- **Exports never replace a file.** `export` and `source --out` fail and name the existing
+  file; `render --out` still replaces its own working output.
+- **Setup.** `kiln discover --capabilities` reports the collections and source storage the
+  MCP server has, and `kiln-init` creates the `.kiln/programs` store it configures.
+- **Guidance.** The OpenCode configuration check, npm 11's `install-scripts` warning for
+  `webgpu`, the part rotation convention and which way an object faces, searching with
+  `kiln_discover` rather than a harness's own search, observe findings on intended joins,
+  suffixed names for repeated sub-assemblies, a user-level `kiln` server beside
+  `kiln_workspace`, and where agy's `--print` prompt goes.
+
+### Output that changes on upgrade
+
+Review colours under the new rig (assets darkened for the old rig look too dark);
+untwisted `extrudeProfile` triangle counts; `sweepProfile` shading of triangular, square and
+pentagonal profiles (pass `creaseAngle: 180` for the old smooth look); GLB bytes
+of emissive and animated assets; images from explicit perspective cameras without
+`near`; CPU images through glass; GPU isolated shots; MCP result size and shape
+(`detail: "full"` restores the complete report), including `kiln_edit`, which leads with
+its refs; the wording of refused exports; Discovery ranking for `bench`, `table` and
+`cast iron`. A program with two or more sibling `LOD<n>` tiers fails with `LOD_SET`
+until it declares them with `defineLod` or keeps one tier; once declared, its GLB bytes,
+headline triangles and bounds, and default sheets (LOD0 only) change.
+
+## 0.8.0 (source update)
+
+The 0.8.0 source update exposes Original GLB and Runtime GLB downloads in the local
+viewer and public gallery, with companion runtime metadata and unchanged canonical
+files. The public viewer adds native animation selection and pause/play controls.
+Gallery build scripts use the current evaluator API. Site setup text and
+historical-example labels match the upgraded CLI/MCP workflow.
+
+External CLI/MCP authoring skills and native Strands workflow instructions are
+separate. Optional native references expose only explicitly selected technical
+files, with no workspace setup, CLI command or delivery instructions.
+
+- **One asset workflow across CLI and MCP.** Kiln Discovery replaces
+  `kiln_list_primitives`; search ordinary modeling language, browse operations,
+  assemblies and optional recipes, then fetch exact contracts. No search model,
+  GPU, API key or category selection is required. Matching now normalizes Unicode
+  identifiers, retains term/field evidence, labels related and partial results,
+  and limits typo expansion to missing vocabulary.
+- **Explicit migration instead of hidden legacy fallbacks.** Retired Discovery
+  selectors, ambiguous helper aliases, category-driven execution and the old
+  evaluator/native interfaces fail with migration advice. See
+  [the migration guide](docs/migration.md) before updating an integration.
+- **Geometry and assembly contracts are sharper.** The unification pass repairs
+  scale-sensitive geometry diagnostics, sweeps, CSG precision/attributes, UV
+  ownership and assembly reuse. Requirements and QA report unsupported obligations
+  as incomplete; successful generation does not certify an asset's physical fit.
+- **Better evidence during review.** Animation review reports endpoint continuity
+  separately from loop intent and velocity smoothness. Rendered edits automatically
+  compare exported static data and animation channels; source-only edits explicitly
+  leave preservation unassessed. Focused inspection provides paged differences,
+  subtree summaries and surface measurements.
+- **A shared renderer with explicit fidelity.** Compatible clients share a managed
+  service with an idle lifetime; the starting session's exit does not kill other
+  clients' work. Incompatible listeners are reported without replacement. The
+  optional renderer ships inside Kiln; local startup, remote routes, cancellation,
+  admission limits and in-session reprobe share the documented contracts. Material
+  fidelity is reported for each view and CPU views remain geometry-only evidence.
+- **Strands is optional.** Its native workflow uses the shared program-reference
+  tools, unified rendering and an explicit `kiln_finish` terminal. Native context
+  stays outside the shared CLI/MCP skills; SDK/provider dependencies are optional.
+- **Consumer requirements are separate from maintainer pins.** CLI/MCP accept Node
+  20.15.0+ on the 20.x line or 22.2.0+; native Strands requires 22.2.0+. Installed
+  commands do not require Bun. Read-only workspace checks respect an existing
+  installed interpreter; setup canonicalizes parent directory aliases so macOS temporary
+  workspaces remain current after Node resolves their paths. Repair/upgrade remains explicit. OpenCode setup guidance
+  reflects its current CLI, and Cline's affected image path has a documented workaround.
+
+This source update does not publish a new installable package. Qualification and
+remaining limits are recorded in the [progress checkpoint](docs/plans/2026-09-22-progress-checkpoint.md).
+The development entries below retain earlier changes and may describe intermediate
+interfaces superseded by this version; use the current tool and migration guides.
+
+### Test suite holds under a loaded runner
+
+- The test scripts and CI set a 20 s per-test budget instead of Bun's 5 s default. Tests that take
+  under a second locally (a cold CLI spawn, the first `sharp` decode in a file) had timed out at 5 s
+  on the Windows runner and passed on re-run; a real hang still fails, twenty seconds later.
+- The tier-2 driver's process-group test no longer races node start-up. It stopped the run 50 ms
+  after spawn, so on a loaded runner the child died before it had spawned its descendant and the
+  orphan spawned afterwards survived. The test now waits for the child to announce its descendant
+  before interrupting the group, and a separate test proves the deadline reports itself. Temp
+  directories that a just-killed process tree still holds are removed with retries instead of
+  failing the run with `EBUSY`.
+
+### Neutral view backdrop, and a named backdrop per capture
+
+- **Every contact sheet is now painted on the neutral studio grey `#aab1bc` instead of near-black
+  `#1a1a1a`.** The old value was pinned in PR #13 for CPU/GPU parity and never revisited; a dark
+  asset on it lost the silhouette, tail and ground contact the render tool asks the model to check.
+  The new default was chosen by measuring silhouette-edge contrast over the 86 examples plus a
+  near-black test asset on the CPU rasterizer: near-black left 39.7% of edge pixels under a 1.5:1
+  contrast ratio, the studio grey 12.8%. It is also the GPU studio preset's background, so a CPU
+  fallback sheet and a GPU sheet of the same request now share one colour on every path,
+  including exact-camera captures, which used to come back grey from the GPU and near-black from
+  the CPU fallback.
+- **`capture.backdrop` accepts `neutral`, `dark` or `light`** on `kiln_render`, `kiln_edit` and
+  `kiln_view_interior`. Free colours are deliberately not accepted: comparability across runs
+  assumes two sheets of one GLB differ only because the asset does. The chosen id is part of both
+  capture-cache keys and is echoed as `capture.backdrop` in every render result. The render
+  service accepts the same `backdrop` field in both modes from a mirrored table that the engine
+  suite asserts against. The CLI takes it inside a `--capture` recipe or as `--backdrop <id>`,
+  which merges into the same capture object and overrides the recipe's own value, so one shared
+  recipe can be re-run on another backdrop without editing it.
+- **The GPU backdrop is pixel-exact.** The service clears the scene background into its HDR
+  framebuffer and tone-maps it with the asset, so the neutral `#aab1bc` used to read back as
+  `(203, 207, 213)` while the CPU rasterizer painted `(170, 177, 188)`. The service now sets the
+  backdrop as the linear colour that comes out of the output pass as exactly the table's bytes,
+  through an analytic inverse of three's ACES filmic curve and sRGB transfer in
+  `render-service/src/display-transform.mjs`, verified against pixels read back from a dawn-d3d12
+  device. A GPU sheet and a CPU sheet of the same request now agree on the backdrop pixel for
+  pixel. Compositing after the pass was rejected because multisampled edges would have kept a
+  one-pixel fringe.
+- **The render service's free-hex `background` field is gone**, in both modes, along with the
+  presets' own background colour: the named backdrop table is the only source, so nothing can
+  paint a colour the engine would not. `background` in a request is a 400 naming `backdrop`.
+- **`kiln render --render gpu` no longer hangs after starting the renderer itself.** The host
+  kills a service it started from an `exit` hook, which suits the long-lived MCP server, but a
+  one-shot command never reached `exit`: the child's piped stderr kept the loop alive, so the
+  CLI finished its render and then sat forever with a GPU process orphaned behind it. The CLI
+  now stops a service it started when the command settles and leaves one it merely found alone.
+  For a batch of CLI renders, start the service once by hand so each command joins it.
+- Occupancy `coverage` takes the backdrop it should measure against. Sheets cached from earlier
+  versions are keyed by the old request shape and are simply re-rendered once.
+- `kiln_view_interior` echoes `capture` too, so every image result now says which backdrop its
+  silhouettes sat on. The guidance in the schema and skills states one rule for every asset
+  colour: switch only after a sheet shows a part merging with the grey, to `light` when that part
+  is darker than the grey and to `dark` when it is lighter.
+- **`kiln_save` takes the same `backdrop` for the preview it stores**, as does the CLI's
+  `kiln save --backdrop <id>`, and the manifest records the one used as `preview.backdrop`. A
+  preview used to be painted on the default whatever sheet had been accepted, so a grey asset
+  reviewed on `dark` was stored merging with the grey it had just been moved off.
+
+### Experimental community exporter and engine handoff
+
+- The established GLB exporter remains the default. Builds containing this integration also
+  provide an experimental Three.js exporter for explicit comparison; no separate repository
+  is needed. See the [Blender/Unity handoff guide](docs/engine-handoff.md) for scoped CLI/MCP
+  activation, restoration of the default, tested import routes and known limitations.
+- Authoring and QA skills include the handoff guide so agents can discover the option when
+  destination requirements call for it. Blender/Unity does not automatically select it.
+- Expanded export, GPU, deformation and clean-package checks are documented in the
+  [qualification report](docs/evaluation/community-exporter.md). The candidate is not yet
+  qualified to replace the default for all supported workflows.
+
+### Saved-asset export profiles
+
+- Keep byte-preserving `editable` exports as the default. Opt-in `runtime` exports
+  move Kiln's duplicated scene review clips to a versioned, hash-linked sidecar,
+  preserving standalone native glTF playback and the canonical saved revision.
+  Available through the CLI, MCP and `@kiln/engine/asset-export` library entry.
+  [Usage, provenance contract and limits](docs/export-profiles.md).
+
+## 0.7.1: Preserve CLI outputs on failed writes
+
+- GLB, preview PNG, and generated source replacements are written to unique sibling
+  temporary files and renamed only after the write closes successfully. A failed
+  write or rename leaves the previous output intact. Source and asset exports
+  continue to refuse overwrites. Concurrent replacements can fail with a sharing
+  violation on Windows; the CLI reports the error without deleting the destination.
+
+## The setup defects, and a bind that was never ours to choose — 2026-09-13
+
+- **The render service binds loopback now, and widening it costs a token.** `HOST` unset used to
+  bind every interface, and the documented manual start -- `npm start`, "nothing else to
+  configure" -- did exactly that with `RENDER_SERVICE_TOKEN` unset and only a warning. What sat
+  behind it is a `POST /render` that accepts a 48 MB GLB, parses it with three.js and hands the
+  buffers to Dawn and a native Vulkan driver, on a queue that renders one frame at a time -- so a
+  single caller can hold the GPU indefinitely, and an untrusted binary-asset parser sits in front
+  of a kernel driver. That is the shape of CVE-2026-7482, where a crafted model file drove a heap
+  overread in a local inference server that operators had put on the public internet by the
+  hundred thousand. Their default was loopback; ours was not.
+
+  The fix is a rule rather than a flag: **the bind address decides whether auth is required.**
+  Loopback is free, because the operating system is the boundary. Anything wider requires a token
+  and otherwise refuses to boot -- the same choice this file already makes for a software adapter,
+  where a driver regression yields a service that will not start rather than one that silently
+  does the wrong thing. `RENDER_SERVICE_ALLOW_UNAUTHENTICATED=1` is the explicit waiver, spelled
+  so an operator has to type the word. The container image sets `HOST=0.0.0.0` itself, because a
+  container binding loopback is unreachable through `-p`. Verified on hardware: a LAN address is
+  refused by default, an exposed bind with no token exits 1 before the GPU is even acquired, and
+  an exposed bind with one serves while returning 401 without the header.
+
+- **Two generated workspaces could not work, and both for the same reason.** A codex workspace
+  wrote `.codex/config.toml` that codex never reads -- every source it consults is
+  `$CODEX_HOME`-rooted -- so a harness the README lists reached no Kiln tools at all. A hermes
+  workspace redirected `HERMES_HOME` to get its MCP servers and skills read, and that one
+  variable resolves the config path *and* the credential path, so the run died before its first
+  model call. Both now configure **per invocation** through generated launchers: codex via `-c`
+  overrides, hermes via `--in` plus the program store riding the environment into the MCP child.
+  Neither writes outside the workspace and neither touches authentication. The rule they
+  establish: *a workspace may add configuration to an invocation, but it must not replace the home
+  that holds credentials.*
+
+  The hermes diagnosis was wrong before it was right. There is no provider key to inherit --
+  `~/.hermes/.env` holds tool toggles and every API key reads "not set", because the provider is a
+  subscription OAuth. What the redirect actually lost was `model.default` and `model.provider`.
+  Two more things fell out of measuring rather than assuming: `--skills` takes skill *names*, not
+  a path, and the documented `--ignore-rules` was suppressing the workspace's own AGENTS.md.
+
+- **A launcher test, because that is why nobody saw either one.** `harness-smoke.mjs` invokes each
+  CLI directly and never touches the generated launcher, so both defects passed every check. The
+  new test asserts the launcher's shape -- that it registers per invocation, parses under the
+  interpreter that will run it, and never names the home that holds credentials.
+
+- **`arrayLinear` was making copies that were not copies.** It read only `source.position`, so
+  every instance stood up straight however the source was laid down -- while `arrayRadial` next
+  door set a rotation on every copy. Two dispatched models hit this independently. Copies now
+  carry the source's rotation and scale. Separately, `arrayRadial` could only ever orbit the
+  parent's origin, which is what its docstring says and not something a caller could work around;
+  it takes an optional `center` now. These helpers had no unit tests at all, which is how a
+  disagreement between two neighbours survived. **This changes exported geometry** for a program
+  that arrays a rotated or scaled source.
+
+- **The helper overview stopped making models guess.** A bare `kiln_list_primitives` returned
+  names grouped by category and nothing else, and models reliably guessed the JS-conventional
+  `createPart(parent, {...})`. The overview now carries the exact signatures of the two helpers
+  every program calls, read from the catalog so it cannot drift from what a detail request
+  returns.
+
+- **`--render gpu` starts the renderer it needs.** It used to throw when nothing was listening
+  even though the installation ships a service that could start, because only the MCP server ever
+  asked for that. `gpu` means "I asked for a guarantee and would rather know than be quietly
+  downgraded"; answering it with a technicality was the defect. `auto` deliberately still does not
+  spawn -- a one-shot sheet should not pay a GPU boot. Fixing it also removed a dead `throw` and a
+  real crash: the spawn branch read `options.serviceDir` on a path that can now be reached with no
+  options at all.
+
+- **Which Kiln answered is now a question a tool can settle.** A server named `kiln` may be a
+  different installation, and two live examples on one development machine proved it -- an
+  extracted 0.6.0 package registered in `~/.cursor/mcp.json` beside a 0.7.0 checkout, and a stale
+  cached tool namespace. Both were local leftovers rather than repo defects, but the workspace
+  guide has always said "do not substitute it silently" with nothing behind it.
+  `kiln_list_primitives {capabilities:true}` now reports `engine.version` and
+  `engine.installUrl`, and the guide says to compare them against the workspace manifest.
+
+- `zod` 4.6.4 and `webgpu` 0.6.1. The latter was gated on a GPU smoke that has now passed twice:
+  `dawn-vulkan` on a GTX 1660 Ti boots and renders through the engine on 0.6.1.
+
+## Seven harnesses, one version, and the defects only a plain prompt could find — 2026-09-13
+
+- **Two new harness adapters: `copilot` and `cursor-agent`**, bringing the dispatch table to
+  seven. Both were verified end to end rather than written from documentation, and both needed
+  a flag that is not obvious: Copilot's `--allow-all-tools` is *required* for non-interactive
+  mode by its own help, and Cursor needs three separate grants -- `--force` for tool calls,
+  `--approve-mcps` for the server, `--trust` for the workspace -- because an unapproved MCP
+  server is gated independently of tool permission.
+- **`create-workspace.mjs` learned both harnesses.** Copilot reads a workspace `.mcp.json`,
+  the same filename Claude Code reads, and not the same contents: its own `copilot mcp add`
+  writes `type: "local"` plus a tool filter where Claude writes `type: "stdio"` and none. The
+  generated config is the spelling Copilot produced for itself. Cursor gets `.cursor/mcp.json`.
+- **Tool names are not portable, and a prompt that names one is a harness dependency.**
+  Copilot namespaces every MCP tool as `<server>-<tool>`, so an agent asked for
+  `kiln_list_primitives` found nothing by that literal name and correctly reported the tools
+  missing -- while `copilot -p` listing its own tools showed all thirteen as
+  `kiln_workspace-kiln_*`. `harness-smoke.mjs` now says the prefix may exist.
+- **The smoke brief was measuring the wrong thing.** It told the agent to call
+  `kiln_list_primitives` and then "nothing else". A bare call returns a compact overview where
+  `createPart` is one name among eighteen, and the overview's own first line says to ask again
+  with `{names:[...]}` for signatures. Two of five harnesses guessed the JS-conventional
+  `createPart(parent, {name, geo, material})` and were rejected at build time; three wrote the
+  real positional form. Asking for the signatures made both failures pass with the same models.
+  The engine's opaque rejection is not at fault: nothing from a sandboxed exception may cross
+  that boundary, by design.
+- **One version, everywhere a client can read it.** `package.json` moved to 0.7.0 and four
+  other declarations did not: `plugin.json`, `.claude-plugin/plugin.json`,
+  `.codex-plugin/plugin.json` and `MCP_SERVER_VERSION`. Every MCP client reported
+  `kiln v0.6.0` against a 0.7.0 engine, which is worth nothing to a bug reporter citing a
+  version. A test now asserts all five agree, so the next bump cannot miss them.
+- **Gemini CLI is excluded, not missing.** Google switched it off for individual tiers on
+  18 June 2026 in favour of Antigravity CLI; it now fails at startup with
+  `IneligibleTierError`. `agy` is the replacement and already had an adapter.
+- **`agy` print mode does not run unattended by itself.** Its log says what happens instead:
+  `Print mode: soft-denying tool confirmation "CallMcpTool" at step 10`, then exit 0 with no
+  program. It needs `--dangerously-skip-permissions`.
+- **Claude Code's allow-list needed the third server spelling.** `mcp__kiln_workspace` is what
+  a generated workspace and a user-level registration both use; with only `mcp__kiln` and
+  `mcp__plugin_kiln_kiln` listed, a run stopped and asked for `kiln_list_primitives` by name.
+- New: [docs/harnesses.md](docs/harnesses.md), the per-harness install, upgrade, headless-flag
+  and MCP-config reference. [docs/dogfooding.md](docs/dogfooding.md) now opens with the method
+  -- three tiers, and why a scripted brief is a wiring probe rather than a dogfood.
+- [ROADMAP.md](ROADMAP.md) carries a stabilisation queue for the first time. The two items at
+  the top are setup defects rather than engine defects, and both sit on a path the README
+  documents: a generated codex workspace cannot see Kiln at all (codex has no project-local
+  config mechanism -- every source is `$CODEX_HOME`-rooted), and a generated hermes workspace
+  cannot reach a model (its launcher redirects `HERMES_HOME`, and the provider lives in the
+  real home). The codex fix is verified but not applied. The rule it establishes: a workspace
+  may add configuration to an invocation, and must not replace the home holding credentials.
+
+## Five tools were unusable in VS Code, and had been since 0.7.0's camera work — 2026-09-12
+
+- `kiln_render`, `kiln_edit`, `kiln_inspect`, `kiln_view_interior` and
+  `kiln_screenshot_animation` all carried a `z.tuple` camera vector. Zod renders that as
+  JSON Schema 2020-12: `prefixItems` plus **`items: false`**, meaning "nothing beyond the
+  listed positions". VS Code's tool validator tests `items` for truthiness, so `false`
+  reads to it as an array with no items and it refuses to register the tool:
+  *"Failed to validate tool mcp_kiln_kiln_edit: tool parameters array type must have
+  items."* That is the whole authoring loop — no render, no edit.
+- **Not a regression, and not broken anywhere else.** The tuple arrived with the camera
+  capture work in `b2eff76` (2026-09-05) and never changed. Claude Code, opencode 1.18.30
+  and the Copilot **CLI** 1.0.83 all register 13 of 13; only VS Code Copilot Chat rejects
+  any. The two Copilot surfaces disagree with each other.
+- **Kiln was the conformant party.** SEP-1613 is Final: 2020-12 is the default dialect and
+  *"Clients MUST support at least JSON Schema 2020-12"*. The fix is still worth taking,
+  because tuples are the one construct the two dialects spell irreconcilably — draft-07
+  uses `items: [...]`, 2020-12 uses `prefixItems` + `items: false` — while a bounded
+  uniform array (`items: {type: number}` with `minItems`/`maxItems`) is valid and
+  identical in both. Choosing it removes a class of client incompatibility rather than
+  patching one client.
+- It also made the surface smaller: the `tools/list` frame went **33,937 B to 32,081 B**,
+  about 464 tokens saved once per session for every harness, and `docs/tools.md` lost 288
+  lines of tuple boilerplate.
+- The tuple TypeScript type is preserved by a static assertion, so nothing downstream
+  needed a cast. It is deliberately not a zod `.transform`: that reads as equivalent and
+  **breaks every non-MCP harness**, because the Strands skin converts with `io: 'output'`
+  where zod refuses — "Transforms cannot be represented in JSON Schema" — while the MCP
+  SDK converts with `io: 'input'` and never sees it. Only the in-process parity test
+  caught that.
+- Confirmed in the client that rejected them: before the fix VS Code logged the error 26
+  seconds after our server connected; after it, all 13 `mcp_kiln_*` tools list, `kiln_edit`
+  included. Copilot Chat logs only validation failures and never successes, so this rests
+  on the before/after, not on a passing log line.
+- Gated two ways: no array in any advertised schema may have a falsy `items`, and a camera
+  vector must still reject two, four, and non-numeric members at runtime. The second gate
+  exists because the first one alone would pass on a schema that had quietly become an
+  unbounded number list.
+
+## Asset links now say how big they are and who they are for — 2026-09-12
+
+- A user reported "massive token usage" from VS Code Copilot, attributing it to
+  `resource_link` mishandling. Measuring first: `kiln_save`/`kiln_export` put **941 B of
+  URIs** on the wire and no file bytes, and a JSON-RPC tap showed the Copilot **CLI**
+  never calls `resources/read` at all. So the stated mechanism does not exist in our
+  responses — but the report was standing next to something real.
+- Kiln emitted only four of `ResourceLink`'s fields. The spec also carries **`size`** and
+  **`annotations.audience`**, which are exactly how a server tells a client "this artifact
+  is for the human to download, not for the model to read". Emitting neither left every
+  client guessing from a MIME type, including the ones that guess "inline everything".
+  Both are now set, with `priority`: `asset.glb` and `preview.png` are `['user']` because
+  the model already receives rendered views as image blocks and geometry as metrics;
+  `source.kiln.js` is addressed to both.
+- `editable.zip` is no longer advertised. It is a bundle of the files listed beside it, so
+  a client resolving every link paid for the same bytes twice — and it was the largest
+  entry while being the only derived one. It stays readable at its URI (which is what the
+  widget's download button uses) and stays in `downloadUrls`.
+- Net wire cost went **941 B → 1,017 B**. This is not a size win and is not claimed as
+  one: it trades 76 bytes for every client being *able* to decide correctly. The `size` is
+  compared in the test against the bytes `resources/read` actually returns for that URI,
+  because a declared size a client cannot trust is worse than no size at all.
+
+## 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
+  runner. The first read of it here was wrong, and the number that refutes it was in the
+  log all along: **the test failed in 123 ms**, while both hang guards are 10 and 15
+  seconds away. Nothing was slow. A worker died, fast.
+- The only way `compareAndSet` does that is the `throw error` beside its lock, reached
+  whenever `mkdir` reports contention with a code other than `EEXIST`. **Windows has
+  exactly that case**: directory deletion is not synchronous, so a directory whose last
+  handle has not closed sits in pending-delete, where `mkdir` on that name answers `EPERM`
+  or `EACCES`. Every release runs `rmdir` in a `finally`, so with eight processes
+  contending, one landing in that window is ordinary contention — and it was rethrown.
+- `isLockContention` now recognises those two codes **on Windows only**. Widening it to
+  every platform would be the over-fix: on POSIX, `EPERM`/`EACCES` from `mkdir` means the
+  parent directory is not writable, and swallowing that would report a permission fault as
+  "busy". Both mistakes are pinned by tests — reverting to `EEXIST`-only fails the Windows
+  case, over-widening fails the POSIX guard.
+- Lock release stopped being able to decide the call's outcome. `rmdir` has no `force`, and
+  on Windows it can fail while a scanner holds the directory — which inside a `finally`
+  would replace a precise `Alias conflict` with an unrelated errno, or turn a successful
+  write into a failure. Cleanup failures are now swallowed, and a lingering lock degrades
+  to "busy" rather than corrupting anything.
+- Asserted on the decision rather than through a real Windows filesystem, so a Linux host
+  checks every branch and the platform is a parameter. The worker timings added alongside
+  are what made the failure legible in the first place, and they stay: one `FAILED` beside
+  seven fast children points at the code, where all eight slow points at the host.
+
+## `--receipt` was relative to the wrong directory — 2026-09-12
+
+- `scripts/verify-package-receipt.mjs` resolved `--receipt` against `--root` rather than the
+  working directory. Those are **the same directory in the CI step**, which is why the
+  original passed its own tests and every CI run — and different everywhere else.
+- Found by using it. Assembling the release from downloaded artifacts puts the receipts in
+  a staging directory while `root` is the repository, so every path silently became
+  `<repo>/linux-package.json` and all four verifications failed with `ENOENT`. The
+  assembly refused to publish, which is what it is for.
+- A path a person types on a command line belongs to where they typed it. `root` now
+  locates `package.json` and nothing else.
+- The test that passed while the bug existed is the finding worth keeping: its fixture had
+  `root` and the receipt in the same temp directory, mirroring the CI step, so it could not
+  tell the two rules apart. It now addresses the receipt explicitly and a second case pins
+  the resolution rule with `root` and the receipt in *different* directories. Both fail if
+  the old behaviour is reintroduced — the doubled path in the error is its signature.
+
+## webgpu 0.6.1 is held out of 0.7.0 — 2026-09-12
+
+- The bump was slated for this release and then held, because reading what is in it
+  changed the decision. `webgpu@0.6.1` was published **the same day**, and
+  `v0.6.0...v0.6.1` bumps the `third_party/dawn` submodule to "latest" alongside a real
+  fix — unmapping a device's buffers when the device is destroyed, with 114 lines of new
+  tests upstream.
+- The fix is worth having: render-service creates and destroys a device per capture, and
+  buffer unmapping on destroy is the readback path. That is not what holds it.
+- What holds it is that **nothing here can exercise it.** CI installs render-service with
+  `--ignore-scripts` so the 37 pure tests run without a device — which means they prove
+  the package resolves and nothing more. `render-service/src/`, `package.json` and
+  `package-lock.json` all ship inside the engine tarball, so an untested native bump would
+  be in the release artifact, attested by four receipts that never touched a GPU.
+- So 0.7.0 ships from what CI has fully proven, and this is the first change after it,
+  gated on the GPU smoke that already holds Phase 4 §7 and the two conformance runs.
+- Noted while looking, not changed: `render-service/package.json` has an `allowScripts`
+  field keyed `{"webgpu@0.6.0": true}` that **nothing reads** — not Bun's
+  `trustedDependencies`, no `@lavamoat/allow-scripts` in the tree, and the README says
+  plain `npm install`, which runs scripts anyway. It looks like a control over native
+  build execution and is not one. Left for a deliberate decision rather than deleted.
+
+## All four platform receipts come from CI now — 2026-09-12
+
+- The 2026-09-05 release attached `linux-package.json` and `windows-package.json`, but
+  `test:package` ran only in the macOS job — so two of the four platforms a release
+  attests to had **no reproducible source** and were produced by hand. `linux-package`
+  and `windows-package` jobs close that; CI now emits the tarball and all four receipts
+  from one run.
+- The receipt check left the workflow. It was a ~400-character `node -e` one-liner inside
+  the macOS job, which is tolerable at one platform and not at four: the expected platform
+  differs per job, so copying it is three chances to assert `darwin` on a Linux runner and
+  have the receipt pass anyway. **A receipt that cannot fail is not evidence.** It is now
+  `scripts/verify-package-receipt.mjs`, one line in each of the four jobs.
+- Extracting it bought two things beyond deduplication. Expected Node and npm versions
+  come from `engines` rather than being written a second time, so `check-toolchain.mjs`
+  stays the single source; and because the receipt records `engineVersion`, each platform
+  receipt is now checked against `package.json` — so a release's receipts are tied to its
+  version rather than merely sitting beside it.
+- `--tarball` overrides the path the receipt recorded, which is what makes one verifier
+  serve both uses. In the job the receipt names a tarball sitting right there. At
+  release-assembly time the receipts are downloaded artifacts whose absolute paths belong
+  to a runner that no longer exists — but their `tarballSha256` is exactly what must be
+  checked against the file about to be published.
+- Verified against a real receipt rather than only fixtures: the Linux smoke was run on a
+  Linux host first (16 checks, `engineVersion 0.7.0`), then that receipt was accepted,
+  **rejected when asked to assert `darwin`** — the precise bug copying the one-liner would
+  have caused — and rejected again after one byte was appended to the tarball, naming both
+  hashes.
+- `REQUIRED_CHECKS` goes to eight, and the gate added two changes ago is what forced that
+  edit: adding a job without deciding whether it gates a merge fails the suite. First time
+  one of this phase's gates caught the next change instead of a past one.
+
+## 0.7.0 — the version moves with what ships — 2026-09-12
+
+- `version` sat at `0.6.0` from the OSS release through **21 shipped changes**, while CI
+  named every tarball from it. Two people could hold `kiln-engine-0.6.0.tgz` and have
+  materially different software — across a three.js major, a history rewrite and a `dist/`
+  re-add. It moves per shipped change now: patch for a fix, minor for changed or added
+  capability, which is the normal case pre-1.0.
+- **0.7.0 rather than a patch.** What accumulated is behaviour: three.js r186, the
+  CommonJS removal it exposed, 128 lines of previously understated tool schema in
+  `docs/tools.md`, and a `shadows.type` contract that now selects a filter from
+  `basic`/`pcf`/`vsm` instead of naming one that no longer exists.
+- A bump has to be rebuilt, because `runtimeBuildIdentity` hashes the version into each
+  entry's `identity` in `dist/build.json` — the value a build receipt cites. A test now
+  asserts `package.json` and every `dist/build.json` entry agree.
+- **Nothing caught that drift before, and this was verified rather than assumed.** With
+  the version at 0.7.0 and `dist/` still recording 0.6.0, the full suite passed — 1860
+  tests, zero failures. `mcp-bundle.test.ts` rebuilds `dist/mcp-server.mjs` and compares
+  bytes, but the version is read from `package.json` at runtime rather than inlined, so
+  the bytes are identical and the stale record is invisible to it. Confirmed by the
+  rebuild: `dist/build.json` was the only file that changed.
+
+## The documented offline gate did not run two of the repository's checks — 2026-09-12
+
+- `bun run test` is `bun test src scripts`, so it never reached `render-service/`. Its 37
+  tests ran only in CI, in the job 13.7 added — so a contributor editing that subsystem
+  got **no local signal at all** and found out from a red pull request. `check:skills`
+  was the same shape in the other direction: a step in CI's `checks` job that the
+  documented gate never named.
+- The subsystem cannot fold into `bun test src scripts`: it is a separate npm project
+  with its own lockfile and a native dependency. It gets `bun run test:render-service`
+  instead, which needs `npm --prefix render-service ci --ignore-scripts` once. All 37
+  tests are pure — framing arithmetic, PNG readback packing, cache identity, contract and
+  preset validation — so none needs a GPU or the Dawn build, which is the CI job's own
+  recorded reason `--ignore-scripts` suffices.
+- Both are now in the gate in `AGENTS.md` and `CONTRIBUTING.md`, and a test asserts the
+  general defect rather than the instance: **every `bun run` command the agent guide
+  names must exist as a script**, and the two that were missing must appear in the gate
+  block itself.
+- Reading the fenced block rather than the whole file is what makes that discriminate.
+  The first version checked "named anywhere in `AGENTS.md`" and stayed green when the
+  line was deleted from the gate — because the prose underneath mentions the same
+  command. Verified three ways after narrowing: a guide naming a script that does not
+  exist, the line dropped from the block, and the script removed from `package.json` all
+  fail.
+
+## Three CI jobs reported and blocked nothing — 2026-09-12
+
+- `build portable Node package` and both `Node package · macOS` jobs run on every push
+  and every pull request, and were required by nothing. Measured before changing
+  anything: **24 of 24 green across the last 8 runs on main**, and a pull request that
+  broke macOS packaging would still have merged.
+- The test named `every CI job blocks; none of them merely reports` was green throughout,
+  because it checked only `continue-on-error` — the narrower of the two ways a job can
+  fail to block. Its own comment already described the gap it did not cover: *"the other
+  half is a GitHub setting."* For three jobs that setting had simply never been made.
+- 13.4 set the precedent that a context is required only once it has reported, since a
+  required context that never reports blocks every merge instead of guarding it. It
+  promoted the Windows job on nine runs with seven green; these three clear that bar.
+- The test now derives every context `ci.yml` can produce — expanding the macOS matrix
+  into its two legs, because GitHub requires the expanded name — and compares it against
+  the list that has to be required. Adding a job without deciding whether it gates a
+  merge now fails the suite. Verified three ways: a new job, a renamed job, and a dropped
+  matrix leg each fail, naming the exact context gained or lost.
+- **`build the gallery` is deliberately not required.** `pages.yml` is path-filtered, so
+  it stays silent on any pull request touching none of `examples/`, `site/`, `src/`,
+  `scripts/authorship.ts` or `README.md`. Requiring it would block every such merge —
+  the exact trap 13.4 named. The rule is now written down: unconditional workflow,
+  required; conditional workflow, unrequired.
+
+## The documented way to convert an old clone did not work — 2026-09-12
+
+- The 2026-09-10 rewrite moved `refs/tags/oss-2026-09-05` as well as `main`, and a tag
+  is the one ref `git fetch` will not update on its own. So the README's remedy
+  — `git fetch origin && git reset --hard origin/main` — left the old tag in place,
+  holding every removed file reachable. Measured on the clone this was found in:
+  `.git` at 228 MB where a fresh clone is 26 MB, with identical content.
+- Reproduced by running the documented commands verbatim in a throwaway copy. The two
+  obvious next guesses are not merely ineffective, they are **refused**: plain
+  `git fetch --tags` and even `--prune-tags` both report `would clobber existing tag`,
+  so a reader has no route to the answer without already knowing `--force`.
+- The instructions now force the tag and then reclaim. Verified end to end on the real
+  stale clone: 228 MB to 23 MB, `fsck` clean, `HEAD` and the working tree hash
+  byte-identical before and after. The plan document already recorded that "the tag was
+  the whole rewrite" for the *push* side; this is the same fact on the clone side, which
+  is the side a reader is on.
+- `scripts/reliability.test.mjs` pins it, and asserts the **absence** of the broken form
+  as well as the presence of the working one — the short version is what a later
+  simplification reaches for.
+- Clone figures re-measured: 60 MB full and 49 MB with `--filter=blob:none`, where the
+  README said 52 MB and 48 MB. `.git` grew from 18 MB to 26 MB when the runtime bundles
+  were re-added after the rewrite; the checkout is unchanged at 34 MB. The timing claims
+  are removed rather than restated — they are network-bound and cannot be honestly
+  re-verified from a different link.
+
+## Skill bytes are canonical, and the SEP-2640 record is corrected — 2026-09-12
+
+- Re-read SEP-2640 from the spec text on its PR branch and the working group's own
+  repository, rather than from a page about it. Three things this project had recorded
+  were wrong.
+- **The design changed, and not cosmetically.** The extension defines `skills/list`,
+  `skills/get`, and an optional `resources/directory/read`. **`skills/activate` is
+  gone**, and with it the bundle, the scoped tools revealed on activation, and
+  progressive disclosure inside the protocol. The SEP now "defines only the transport
+  binding" and delegates the format and disclosure model to the Agent Skills
+  specification.
+- **The status heuristic was backwards.** The note here said "read the labels, not the
+  prose", after a summary twice reported the SEP as Final. The SEP document's own
+  `Status:` field *does* read Final; the pull request's label still reads `draft`, and
+  under the SEP process the document is the status of record. The note pointed at the
+  weaker signal.
+- **"Nothing to build against" is no longer true.** The spec depends on nothing beyond
+  base Resources, capability declaration rides SEP-2133, and the pinned
+  `@modelcontextprotocol/sdk@1.30.0` already carries `extensions` in
+  `ServerCapabilitiesSchema` while `setRequestHandler` takes any schema. Conformance
+  tests merged 2026-09-11.
+- 7.12 still waits, for a different and checkable reason: **nothing public consumes it.**
+  The TypeScript SDK's convenience wrappers PR is closed unmerged, every public host is a
+  prototype in one contributor's forks, Claude Code's is internal and not public, and the
+  GitHub MCP server prototype is closed. Shipping it now adds a third transport no host
+  can call. **Re-check the TypeScript SDK, not the SEP's status.**
+- The re-read found one real gap. `skills/list` publishes a per-file `digest` and `size`
+  over raw bytes, and this project already publishes sha256 digests of skill artifacts at
+  `/.well-known/agent-skills/index.json` — but `skills/**` was `-text` in
+  `.gitattributes` and carried the same accidental line-ending mix found in
+  `render-service/src`: five files fully CRLF, two mixed, seven LF. It went unnoticed
+  because the frontmatter parser is tolerant of both. Tolerant parsing is right;
+  publishing a digest over whichever ending an editor happened to write is not.
+- Normalized to LF across `skills/` and both registry copies, and `check:skills` now
+  rejects CRLF in any skill file. Verified by reintroducing one — and then by `git
+  checkout` restoring the pre-normalization bytes and the gate firing on that too, which
+  is the regression path that actually happens.
+- Two pieces of the eventual work are already in place: the digest derivation extends
+  7.13's rather than being invented, and `check:skills` has enforced the SEP's
+  name-equals-directory rule since Phase 7.
+
+## The published tool reference is correct again — 2026-09-12
+
+- `docs/tools.md` is generated from the tool registry, and `docs/` is in the package's
+  `files` list — so a stale reference is not an internal note being wrong, it is shipped
+  to every install. It was stale: regenerating moved **128 lines**.
+- The cause was an in-range dependency bump. `zod` 4.4.3 → 4.6.2 changed
+  `z.toJSONSchema` to emit `items: false`, `minItems` and `maxItems` for fixed-length
+  tuples, so every tuple input in the published reference understated its own schema.
+- Nothing caught it because the generator's `--check` mode appeared in **no workflow and
+  no test** — the same shape as the render service's 37 tests running nowhere. An
+  offline gate that runs nowhere is worth exactly as much as no gate.
+- It is a test now rather than a workflow step: the generator exports
+  `toolReferenceMarkdown()` with its CLI behaviour behind a direct-entry guard, and
+  `scripts/tool-reference.test.mjs` compares the published file to the registry. `bun
+  test` already runs on Linux, Windows and both macOS architectures, so this needs no
+  new job — and cannot become a job somebody forgets to add, which is the failure mode
+  being fixed.
+- Compared whole rather than section by section: the drift that shipped was four added
+  lines inside one nested schema, which any summary comparison would have missed.
+  Verified by dropping a single `minItems` line and watching the test name the file and
+  the command that fixes it.
+
+## Every directory that holds code is linted now — 2026-09-12
+
+- 14.4 left the one-off tools in `scripts/` out and priced the alternative at 26 lint
+  findings, a 1,530-line reflow, and 162 lines of coverage slack. After the ratchet got
+  a scope the third term is **zero** — `scripts/**` is not instrumented at all — so what
+  was left was a diff, and it is taken. **480 files where 442 were.**
+- Thirty-four format findings and thirty-two real ones, over `.mjs` and `.ts` alike; the
+  `.ts` files under `scripts/` had never been linted either, since the pattern was
+  `src/**/*.ts`.
+- Twenty-five `useTemplate`, seventeen of them one idiom: `JSON.stringify(…) + '\n'`,
+  the receipt-file shape, across eleven files. A shared helper is the obvious DRY move
+  and is deliberately not taken — `package-plugin.mjs` ships in the package `files`
+  list, so importing one means shipping another file for a cosmetic win.
+- Three findings were not cosmetic. **Two `any` in the pilot evaluation host**: one read
+  as `previous.config` / `previous?.deadline`, now typed; one feeding a budget estimator
+  through optional chains, now a declared `PilotToolInput` that names exactly the fields
+  the image-cell budget depends on — documentation the estimator did not have. A loop's
+  update step hiding in its condition in `smoke-package.mjs`. And **a literal ESC byte**
+  in `harness.mjs`'s ANSI stripper, invisible in every diff and editor, now `\u001B`.
+- Also surfaced, and deliberately left for its own change: `docs/tools.md` is stale and
+  its `docs:tools --check` drift checker runs in no workflow and no test. The cause is
+  the `zod` 4.4.3 → 4.6.2 bump — `z.toJSONSchema` now emits `items: false`, `minItems`
+  and `maxItems` for fixed-length tuples — so the published tool reference has
+  understated every tuple schema since. Ledger 14.8.
+
+## render-service joins the lint surface — 2026-09-12
+
+- It was left out because `render-service/src/**` is `-text` in `.gitattributes` and the
+  formatter would rewrite the line endings. Looking at what the attribute protected
+  turned that reason into the finding.
+- **It was sweeping, not deliberate.** The line arrived in the OSS release commit
+  alongside the other `-text` entries, and what it froze is inconsistent: four files
+  fully CRLF, `renderer.mjs` at 395 of 399 lines, three carrying a single stray CRLF
+  line, four fully LF. One stray CRLF line in an otherwise-LF file is an editor's
+  signature, not a decision.
+- **Those bytes are genuinely hashed**, so the replacement matters:
+  `fingerprintRendererInputs` walks that directory into the renderer's capture identity.
+  But `-text` only guarantees "whatever was committed", while the `* text=auto eol=lf`
+  rule guarantees what the fingerprint needs — one line ending on every platform. The
+  normalization is a stricter guarantee than the attribute it replaces.
+- **Nothing re-validates the old digest.** `capture-producer.v1` fingerprints in
+  checked-in provenance receipts record the renderer build a poster was made under; no
+  test recomputes one. 13.6 already edited two of these files and every gate stayed
+  green — a later build hashing differently is the point of recording it.
+- Eight files to LF, the attribute removed with the reasoning left where the next reader
+  will ask, and the directory linted: **442 files where 416 were.** Twenty-two format
+  findings, then five real ones. One of them, `useIterableCallbackReturn` in
+  `presentation-presets.mjs`, is the same defect 13.5 fixed in the Bradley-Terry fit —
+  a one-expression arrow in a `forEach` returning a value the contract discards — sitting
+  in production render-service code that was outside every lint gate this repo has.
+- `reliability.test.mjs` pins both include patterns and asserts the `-text` line stays
+  gone. render-service's own 37 tests pass on the normalized sources.
+
+## The coverage ratchet has a scope now — 2026-09-12
+
+- The previous entry blamed 162 lines of lost coverage slack on helper scripts being
+  measured and never executed. The number was right; the mechanism was wrong. Bun
+  instruments only files it loads, and `coveragePathIgnorePatterns` already dropped
+  `**/*.test.mjs`, so those tools were never in the report — there is no `SF:` record
+  for `dispatch-asset`, `upload-posters`, `geometry-experiments` or `harness`.
+- Exactly **four** files under `scripts/` were instrumented, because tests import them:
+  `evaluation/observe-shipping.mjs`, `build-runtime.mjs`, `evaluation/conditions.ts` and
+  `authorship.ts`. 229 lines against the engine's 45,726 — 0.5% of the denominator, and
+  worth 0.10 points. Two of the four are dense single-expression files, so reflowing
+  them inflated their line counts while their covered lines stayed put. That is where
+  the 162 lines went.
+- So the finding is narrower and worse than "helper scripts dilute the ratchet": the
+  engine's coverage contract had a **repo-only formatting input**. A number this
+  repository enforces as policy could be moved by reformatting code that does not ship.
+- `bunfig.toml` now ignores `scripts/**` for coverage. Those tests still run — they are
+  the gates — but their sources leave the denominator, so the ratchet is a statement
+  about the shipped engine and nothing else. Re-measured on the narrowed scope: **95.39%
+  functions, 92.59% lines**.
+- Narrowing hands back 44 lines of slack no new test earned, so `lines` goes 92 → **92.1**
+  to hold the 224-line margin 13.3 chose rather than pocket it. `functions` stays at 94,
+  where the margin is unchanged in practice. Tightening further is a separate decision.
+- And the record carries its own scope now. `measuredBaseline` requires `measuredOver`,
+  the gate refuses a baseline without it, and it prints it: `Recorded baseline:
+  functions 95.39%, lines 92.59% (over src/, bun@1.4.2, 2026-09-12)`. A percentage
+  without its scope is as ambiguous as a threshold without a baseline — which is what
+  made the wrong explanation above plausible enough to write down.
+
+## The repository's own gates are linted now — 2026-09-12
+
+- Adding a file to `scripts/` and running `biome check` on its path printed "No files
+  were processed." Biome's `files.includes` was `src/`, `site/src/` and `site/*.ts`, so
+  the directory holding this repository's gates — and which `test:coverage` already
+  measures — sat outside the lint surface. The zero-warning baseline 13.5 established
+  was zero across a subset.
+- Taken: `scripts/check-*.mjs` and `scripts/**/*.test.mjs` — the checks are now checked.
+  416 files where 405 were. Ten findings were behind the hole: seven format, and three
+  real ones. A dead `const` in `check-vision.mjs`, easy to miss because the identical
+  line two loops down is load-bearing. Two `useTemplate` on the
+  `JSON.stringify(…) + '\n'` idiom. `reliability.test.mjs` asserts both include
+  patterns, verified by dropping one and watching it fail.
+- Left, with the cost measured rather than guessed. The rest of `scripts/` is one-off
+  tools, several authored as dense single-expression lines. Taking the whole directory
+  is 26 lint findings, a 1,530-line reflow (3,078 lines to 4,608, pure formatting), and
+  **162 lines of coverage slack** — lines fall 92.49% to 92.14% against a threshold of
+  92. Measured by taking the full pass and running the gate.
+- **Corrected below**: the mechanism first given for that third cost was wrong, and it
+  pointed at the wrong fix.
+- `render-service/` stays out for an unrelated reason: its sources are CRLF by
+  `.gitattributes`, and the formatter would rewrite the line endings.
+- One incidental finding: Biome prints at most 20 diagnostics by default, so a count
+  read off `bun run lint` is a floor, not a total. The gate still fails either way.
+
+## The prompt-cache breakpoint is asserted on the wire — 2026-09-12
+
+- The two deferred rows in the queue were both deferred *with a reason*. Checking the
+  reasons rather than inheriting them changed both answers.
+- **The `ai` 7 family is blocked upstream, and money was never the constraint.** The
+  recorded reason was that only `test:live` exercises those paths and it spends money.
+  What actually blocks it: `@strands-agents/sdk@1.17.0` is the latest release, declares
+  peer `@ai-sdk/provider: ^3.0.0`, and types its `VercelModel` on `LanguageModelV3`,
+  while `@openrouter/ai-sdk-provider@3` requires `ai@^7`, which depends on
+  `@ai-sdk/provider@4`. No budget moves that.
+- And `typecheck` would not have caught it. `@ai-sdk/provider@4` still exports
+  `LanguageModelV3` beside V4, so the import keeps compiling; the break is a v4 model
+  handed to a v3 wrapper, at runtime, on the one path no offline suite drives. There is
+  a gate for it now: `scripts/peer-ranges.test.mjs` walks the installed tree and fails
+  on a peer range the version beside it does not meet.
+- **It found a mismatch that already exists.** `@strands-agents/sdk` declares peer
+  `@anthropic-ai/sdk: ^0.109.1` — on a 0.x version that means `>=0.109.1 <0.110.0` —
+  and the last dependency refresh took 0.125.0. Fifteen minors past the declared
+  range, moved by a routine in-range update, noticed by nothing. Kept, and listed with
+  its reasoning in the gate's `ACCEPTED` table, so the next one fails while this one is
+  a decision on the record rather than a silence.
+- **The native cache breakpoint is now asserted against the bytes.** The OpenRouter
+  half already was: it drives `doStream` with `fetch` replaced and reads the outgoing
+  JSON. The native half asserted that `toCachedSystemPrompt` returns
+  `[TextBlock, CachePointBlock]` — the input to the transport, never its output. So the
+  claim the design rests on, that a cache point becomes `cache_control` on the wire,
+  was carried by a comment, on two dependencies that move inside their caret ranges on
+  every refresh. Losing it bills full price for every prefix that should have been a
+  cache read, with every offline gate green.
+- Both native transports are captured now, offline: the Anthropic client takes a
+  `fetch` that records and throws, Bedrock a `requestHandler` that does the same. Both
+  tests are differential — a plain string goes out with no breakpoint — so the
+  breakpoint has one possible origin. Establishing that took an injected defect, which
+  disproved the first draft's premise: Bedrock does *not* auto-inject a system cache
+  point here, because that needs a `cacheConfig` and Kiln passes none. Patching the
+  installed adapters to drop `cache_control` and the converse `cachePoint` fails
+  exactly the new tests while every pre-existing test stays green — including the one
+  named "the adapter emits `cache_control`", which never checked that it did.
+- **7.12 / SEP-2640 stays deferred, for a better reason.** PR 2640 is open and still
+  labelled `draft`; a page summary reported it Final for the second time and was wrong
+  again. But the row turns on something downstream: `@modelcontextprotocol/sdk`
+  publishes 1.30.0 as latest, the version already installed, so there is no TypeScript
+  surface for `skill://` resources to build against whatever the SEP does next. Check
+  the SDK's version, not the pull request.
+
+## A preset's shadow filter now selects a filter — 2026-09-12
+
+- Going to compare shadow filters by eye turned up the reason there was nothing to
+  compare: **no shipped presentation preset enables shadows.** `neutral-studio-v1` sets
+  `shadows.enabled: false` to preserve the pre-registry visual, `gallery-studio-v1` is a
+  spread of it, and every light has `castsShadow: false`. So r186 deleting the PCFSoft
+  implementation is not a visible regression here, and yesterday's switch to
+  `PCFShadowMap` corrected a line that never runs. Its claim to keep the log clean was
+  overstated: the assignment sits inside `if (preset.shadows.enabled)`, so three's
+  deprecation warning never fired from this service either.
+- What was actually wrong is that `shadows.type` described a filter and selected nothing.
+  The validator demanded the exact string `pcf-soft` while the renderer ignored the field
+  and hardcoded a constant — and after r186, the one name the schema accepted was the one
+  name that no longer exists.
+- It selects a filter now. `SHADOW_FILTERS` is `basic`, `pcf`, `vsm` — what r186 left —
+  and the renderer maps each to its three constant. `vsm` is the soft option that
+  survives, with one catch recorded where someone choosing it will read it: under VSM
+  every shadow receiver also casts, so a ground plane starts casting too.
+- The names live in the schema that validates them and the constants live in the module
+  that imports three, so the renderer checks at load that the map covers the list. A name
+  the validator accepts and the map lacks would set `shadowMap.type` to `undefined` mid
+  render — not a crash, just a quietly different image. Verified by adding `pcf-soft` back
+  to the list and watching the service refuse to start.
+- The gallery is not affected either, for a different reason: neither `<Canvas>` in the
+  site sets r3f's `shadows` prop, so `renderer.shadowMap.enabled` stays false there too,
+  and the only shadowing on that surface is drei's `ContactShadows` — its own depth pass to
+  a texture, which never consults `shadowMap.type`. Between the two paths, r186's PCFSoft
+  removal changes nothing anyone can see in this repository.
+- **`render-service` is in CI now**, which it never was. Thirty-seven tests guarding a
+  shipped subsystem ran on nobody's machine but a maintainer's — including, until this
+  commit, the change above it. It is a separate npm project with a native dependency,
+  which is presumably the reason; but the tests do not need it. All 37 are pure: framing
+  arithmetic, PNG readback packing, cache identity, contract and preset validation, and
+  not one acquires a device. So the job installs with `--ignore-scripts`, skipping the
+  `webgpu` package's Dawn build. Verified against exactly that install with no binding
+  built: 37 pass, 0 fail. The GPU smoke and the two conformance runs stay manual, because
+  those genuinely need a device.
+
+## The lint baseline is zero, and stays zero — 2026-09-12
+
+- `bun run lint` reported **14 warnings and 11 infos** and exited 0. All 25 are fixed;
+  the tree now reports nothing. The point is not tidiness: a baseline everyone agrees to
+  ignore is a baseline the twenty-sixth finding arrives invisible against.
+- Two of them were not style. `isFinite` in the render inspector is the coercing global,
+  where `Number.isFinite` is not — identical on a `Box3` component, taken because the next
+  caller to pass something looser is the one the coercion silently accepts. And
+  `ids.forEach((id, i) => index.set(id, i))` in the Bradley-Terry fit returned the map
+  from a callback whose contract discards it; the index is built from its pairs instead.
+- Three `any` bounds in `buildSandboxGlobals` carried
+  `// eslint-disable-next-line @typescript-eslint/no-explicit-any`. This repository lints
+  with Biome and has no ESLint config, so those suppressed nothing while reading as
+  reviewed-and-accepted. Rather than translate them, the `any` is gone: `never[]` is the
+  correct bound for "any parameter list" and `unknown` for "any return", with one narrow
+  assertion where tsc resolves a call through the constraint and can only see `unknown`.
+- The quaternion fixture's `0.7071` is now `Math.SQRT1_2` — exact, and it says which angle
+  a quarter turn about Y actually is.
+- **Warnings now fail.** `lint` runs with `--error-on-warnings`, and because that flag
+  does not reach Biome's info severity — where `useTemplate` and several others sit by
+  default — the seven rules this cleanup touched carry an explicit `error` in
+  `biome.json`. Each of the seven was verified by reintroducing its defect and confirming
+  the gate fails and names the rule.
+- The `useIterableCallbackReturn: "warn"` downgrade is gone with the finding it was
+  written around. A test asserts the seven severities and the `lint` script itself: a rule
+  lowered to keep a build green is indistinguishable from a rule nobody wanted, and that
+  has happened here before.
+- `CONTRIBUTING.md` says the contract plainly — the tree reports nothing, so any
+  diagnostic a change produces belongs to that change, to fix or to suppress with a
+  `biome-ignore` comment that says why.
+
+## The gates stop reporting and start blocking — 2026-09-12
+
+- **The Windows job blocks.** It landed reporting-only on purpose, because the fault it
+  was added to rule out — a native GLib `g_system_thread_free` / invalid `CloseHandle`
+  inside libvips/sharp under Bun's threading — was intermittent, and a required check
+  that fails at random is worse than no check. Its whole history is now nine runs: seven
+  green, two red, and not one recurrence. Both reds were new code from the session that
+  added the job — a `require('sharp/package.json')` that sharp's `exports` map blocks,
+  and a `new URL('..', import.meta.url).pathname` that yields `/D:/a/kiln/src/` — and
+  neither is reachable from a POSIX host. The failures were true, which is the argument
+  for blocking rather than against it.
+- Blocking means a hang is a blocked merge rather than a slow report, so the job now has
+  a 30-minute bound. The suite runs there in about two minutes.
+- A test asserts no CI job carries `continue-on-error` at job level, so this cannot be
+  demoted by one line slipping back in. The single step-level exception is the native
+  dependency inventory, which exists to attach libvips and GLib versions to a run if the
+  fault ever returns and must never be why Windows reports red. Indentation is the
+  distinction and the test reads it as such.
+- **The coverage ratchet moves to 94% functions / 92% lines**, from 92/91. Measured
+  95.27% and 92.49% on this tree, which leaves 42 functions and 224 lines of room.
+- That "42 functions" is the other half of the change: the gate now reports its margin
+  in the unit a person can act on. A percentage says whether the gate passed; turning it
+  into work needs LCOV totals that are not in front of whoever tripped it. Slack rounds
+  down and a shortfall rounds up, so neither reads as more comfortable than it is.
+- The gate also refuses a threshold set above the baseline it records. That is the one
+  mistake the coverage comparison cannot catch by itself: a threshold above anything
+  ever measured fails in whatever change happens to run next, and reads there as that
+  change's regression. A thresholds file with no recorded baseline is refused for the
+  same reason — a ratchet is raised to a number somebody measured.
+
+## Dependencies current in range, and the toolchain gate gets its own test — 2026-09-12
+
+- In-range refresh, deliberately kept apart from the deferred majors: `ai` 6.0.222 →
+  6.0.282, `openai` 6.46.0 → 6.49.0, `@ai-sdk/provider` 3.0.14 → 3.0.16,
+  `@aws-sdk/client-bedrock-runtime` 3.1083.0 → 3.1131.0, and in `site/` react and
+  react-dom 19.2.8 → 19.3.0 with their types, plus vite 8.2.2 → 8.3.0.
+- The `ai` 7 / `@ai-sdk/provider` 4 / `@openrouter/ai-sdk-provider` 3 family stays
+  where it was. Only `test:live` exercises those paths and it spends money, and the
+  deliberate prompt-cache transport asymmetry is exactly what a provider major breaks
+  without a test noticing. Nothing enforces that decision in prose and nothing needs
+  to: the caret ranges cannot resolve to a new major, so the boundary is structural.
+- The `@types/three` parity rule added yesterday now reads as what it always was — a
+  rule about types, not about three. Every `@types/*` whose runtime package the same
+  manifest pins must sit on that runtime's release line. That is what brought
+  `@types/react` and `@types/react-dom` along with react 19.3: the site compiles its
+  `@react-three/fiber` JSX against those types, and types a release line behind make
+  new API invisible to `tsc` while removed API still typechecks.
+- **`check-toolchain.mjs` now has a test.** It had grown three times, each extension
+  verified by injecting the defect by hand, once, at the time — the right check made in
+  the wrong place, because nothing stopped a later edit from leaving a rule that could
+  no longer fail. A vacuous gate is worse than no gate, since it is believed. The gate
+  takes an optional `--root`, and each case stages a real copy of the repository's own
+  files, mutates exactly one value, and asserts the gate names it: stale engine pin,
+  prose that installs the wrong Bun, three drifting in either the site or the render
+  service, types off their runtime's line, an Action pinned to a mutable tag, and a
+  Pages workflow left behind. Staging the real files rather than a synthetic fixture is
+  the point: a rule whose phrasing drifts out of step with the document it reads fails
+  the baseline case immediately.
+- A mutation that changes nothing fails the test. A search string that no longer
+  appears injects no defect, the gate correctly reports a clean tree, and the case goes
+  green having checked nothing — the exact rot the file exists to prevent, so it is
+  caught rather than trusted.
+
+## The r186 bump missed the site, and now a gate catches that — 2026-09-12
+
+- `site/` was still on three 0.185.1 while the engine and `render-service` moved to
+  0.186.0. Substantive rather than untidy: kiln emits `EXT_mesh_gpu_instancing`, and
+  r186 fixed that extension's custom instance attribute sharing in `GLTFLoader`, so
+  the site was rendering the gallery with an unfixed loader for an extension the
+  engine writes.
+- `check:toolchain` now asserts `three` is byte-identical in every manifest that pins
+  it, and that `@types/three` tracks its minor. Verified by injecting three defects —
+  the exact drift that shipped, a `render-service` drift, and a stale `@types/three` —
+  and confirming each is caught and names the offending manifest.
+- The reason this is a gate and not a note: the same class of defect, a value that
+  must agree across files with nothing enforcing it, had been caught in the prose that
+  same morning by a person. Twice in one day is an argument for a check.
+
+## Finishing the CommonJS removal the r186 bump started — 2026-09-12
+
+- The previous entry's fix was incomplete, and looked complete.
+  `src/ops.ts` moved to the ESM build, but `src/__tests__/subdivide-normals.test.ts`
+  still imported the bare specifier — so the CommonJS build kept loading and kept
+  emitting `THREE_CJS_DEPRECATED`, while the production import read as corrected.
+  The whole suite now reports **zero** occurrences of that warning.
+- `three-subdivide` is pinned **exactly** rather than by caret. The deep path
+  `three-subdivide/build/index.module.js` is legal precisely because the package
+  declares no `exports` map; a minor release that added one would make the path
+  unresolvable, and a caret range would have taken that release silently.
+- `src/__tests__/three-subdivide-esm.test.ts` guards the whole tree rather than one
+  file, which is the lesson from the partial fix: it walks every `.ts` under `src/`,
+  asserts the ESM build has no `require(` call, and asserts the pin is exact.
+  Verified by injecting the bare specifier into `src/ops.ts` and confirming the guard
+  fails *and names the offending file*, rather than by observing a pass.
+- Timing, since it reads as urgent and is not: three deprecated the CommonJS build in
+  r186 and has not announced a removal release. Its own precedent — `build/three.js`
+  deprecated at r150, removed at r160 — suggests roughly ten releases of runway. The
+  reason to fix it now is the warning users see today, not the removal.
+
+## three.js r186, and the CommonJS load it exposed — 2026-09-11
+
+- `three` and `@types/three` to 0.186.0 in both the engine and `render-service`.
+  The types were the blocker and they shipped; r186's three named breaking changes
+  — `Source` → `TextureSource`, `toTrianglesDrawMode()` mutating in place,
+  `Object3D.dispose()` needing `super.dispose()` — touch nothing here, checked
+  before the bump rather than discovered by it.
+- **`three-subdivide` was pulling three in through the deprecated CommonJS build.**
+  It has no `exports` map, so a bare specifier resolves to `main`, which is a UMD
+  bundle doing `require("three")`. r186 did not create this; it made it audible, by
+  emitting `THREE_CJS_DEPRECATED` on stderr — which every `kiln` CLI invocation
+  would then have printed. Fixed by importing the ESM build the package already
+  ships, `three-subdivide/build/index.module.js`, which has zero `require(` calls.
+  `three-subdivide@1.1.5` is the latest release, so there is no upstream fix to
+  wait for, and three has announced the CJS build's removal.
+- Worth recording because it is tempting and wrong: this does **not** fix a
+  dual-THREE instance hazard. `src/primitives.ts` documents one, and it was
+  measured here rather than assumed — geometry from both the CJS and the ESM build
+  satisfies `instanceof THREE.BufferGeometry`. The `isBufferGeometry` flag tests
+  stay, because they are correct defensively regardless.
+- **The GPU service was requesting a shadow filter that no longer exists.** r186
+  removed the `PCFSoftShadowMap` implementation while keeping the constant; three
+  warns and substitutes `PCFShadowMap`. `render-service` now names the filter it
+  actually gets. Material conformance returns numbers identical in every region
+  before and after, which is the proof the substitution was already happening.
+- Verified on hardware, not only offline: 1,831 pass / 0 fail, typecheck clean,
+  lint at the unchanged 14/11 baseline, and `material-conformance` `PASS` on
+  `dawn-vulkan` across all six channels. One number to watch —
+  `normalHalfLumaDelta` moved 1.51 → 1.2 against a threshold of 1, consistent with
+  r186's diffuse energy-conservation change. It passes with less margin than 11.5
+  measured, which is an argument for that row's follow-up rather than for a new
+  threshold.
+
+## The guide was pinning a toolchain the gate rejects — 2026-09-11
+
+- `AGENTS.md`, `CONTRIBUTING.md`, `README.md`, `docs/google.md` and
+  `docs/install.md` still named Bun 1.3.14, Node 22.23.1 and npm 12.0.1 after the
+  bump to 1.4.2/22.23.2/12.0.2. `AGENTS.md` is the guide every harness reads, so
+  the first command a new contributor ran installed a Bun that
+  `bun run check:toolchain` — the next command in the same list — then rejected.
+- `scripts/check-toolchain.mjs` now asserts those five documents state the
+  supported triple, and that `pages.yml` pins the same Bun as `ci.yml`. The gate
+  had enforced `package.json` and `ci.yml` and nothing else, so both the prose and
+  the second workflow could drift silently; `pages.yml` was correct today only
+  because it was set by hand in the same change. Verified by injecting each of the
+  three defects and confirming a non-zero exit, rather than by observing a pass.
+- Dated receipts under `docs/evaluation/` are deliberately excluded from the
+  check. They record the toolchain a run actually used, and rewriting one to match
+  a new pin would falsify it.
+
+## Skills are fetchable by URL — 2026-09-11
+
+- The six skills are published at
+  `https://kilnstudio.tools/.well-known/agent-skills/index.json`, per
+  [Cloudflare's Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc)
+  v0.2.0 — which is what OpenCode's `skills.urls` consumes. One `skill-md` entry
+  and five archives for the skills carrying `references/`, each with a sha256 of
+  the artifact's raw bytes so a client can verify what it fetched.
+- The archives are built by hand as POSIX ustar with every non-content field
+  pinned — mode 0644, uid/gid 0, mtime 0, sorted entries — because the digest is
+  *published*. Neither the system `tar` nor a convenience library gives that by
+  default, and an archive whose bytes move on every build publishes a digest that
+  is wrong the moment it is written. The test asserts those header fields
+  directly rather than only comparing two builds, since two builds agreeing is
+  also what a tar with a coarse clock does inside one second.
+- Verified end to end: real `tar` extracts the archives with `SKILL.md` at the
+  root and contents byte-identical to `skills/`, and Vite copies the
+  dot-directory into the published output.
+- **This path carries skills and no MCP server**, so a client that loads them has
+  the workflows and none of the tools they describe. `docs/install.md` says so
+  where it offers the URL.
+- **Follow-up:** the first deployment served a 404, and neither the build nor
+  Pages was at fault. `actions/upload-pages-artifact` v5 archives with
+  `--exclude=.[^/]*` unless `include-hidden-files` is set, so it strips *every*
+  hidden path — and a well-known URI is under a dotted directory by definition.
+  The artifact had 465 entries and not one dot-entry, while the same build
+  locally produced all seven files. Fixed by setting the flag, verified to add
+  exactly `.well-known` and nothing else.
+
+## Bun-only APIs cannot reach a Node bundle unnoticed — 2026-09-11
+
+- Audited the shipped bundles for the defect class behind the MCP server's
+  `import.meta.main` bug. The bundles were clean of all nine patterns checked —
+  but the audit found the identifier still live in
+  `src/experiments/geometry-acceptance.ts`, which **ships** (`files` carries
+  `src/**/*.ts`). Unbundled under plain `node`, `import.meta.main` is `undefined`,
+  so that guard was always *false* and running the script with node did nothing
+  at all, silently. The same defect as the MCP one with its sign flipped: there,
+  bundling made the guard always *true* and started a server nobody asked for.
+  Both now use `isDirectEntry`, which decides from `process.argv[1]`.
+- A new guard asserts both halves — no Bun-only API in any committed bundle, and
+  no `import.meta.main` deciding an entry point in shipped source. It was
+  verified by injecting a defect into each and watching it fail, rather than
+  trusted for passing green: the whole reason this class survived is that nothing
+  was looking.
+
+## The GPU material check runs for the first time — 2026-09-11
+
+- `render-service/test/material-conformance.mjs` is the only automated evidence
+  that the GPU path applies textures at all, and it had never passed. It replaces
+  `globalThis.fetch` with a thrower to prove an embedded fixture never crosses a
+  network boundary — but `blob:` is an **in-memory** object URL, and three's
+  `GLTFLoader` mints one per embedded image that `ImageBitmapLoader` reads back
+  through `fetch`. The guard blocked the only path a texture has into the
+  renderer, so the file measured an untextured render and asserted against it:
+  `lumaSpread: 0` on the albedo checker, with the real cause printed as a loader
+  warning nobody read. `blob:` is now exempt, and the guard self-checks that an
+  `https:` fetch still throws.
+- Its normal-map threshold was `>= 3` and had **never been evaluated**, because
+  the albedo assertion above it always failed first. Recalibrated to `>= 1` from
+  measurement. The small number is the tone curve rather than a weak response:
+  that panel sits at mean luma ~242 of 255 under the fixture's own exposure of
+  1.38, past the ACES shoulder. Measured 1.51 at exposure 1.38 and 2.61 at 0.9
+  with nothing else changed — which is also the proof that the map applies. An
+  absent normal map reads near zero, the way the albedo checker read exactly 0.
+- All six channels now verify: albedo, normal, shared ORM, AO, emissive, alpha.
+
+## Artifact identity stops tracking the serializer's version — 2026-09-11
+
+- **`asset.generator` is now a stable `"Kiln"`.** It defaulted to the serializer's
+  own version string, so `glTF-Transform v4.4.1` sat inside every artifact's
+  bytes and therefore inside `artifactHash`. Taking 4.5.0 moved all 83 recorded
+  hashes and failed the gallery build — and the *entire* difference between the
+  two GLBs was that one string. Identical BIN chunk, identical accessor min/max,
+  identical semantic digest. With the generator pinned, **all 86 examples are
+  byte-identical across 4.4.1 and 4.5.0**, including the ones using `palette()`,
+  which 4.5.0 changed. A dependency's version number is provenance about the
+  tool, not identity of the asset.
+- `@gltf-transform/*` moves to an exact **4.5.0**. Still exact, deliberately —
+  the version-string cause is gone but other serialization changes are not
+  impossible, and a serializer bump should stay a measured decision.
+- **A poster receipt no longer asserts `artifactHash`.** It asserts `sourceHash`
+  and `imageHash` — this image was rendered from this source — which is what it
+  could always honestly claim. Asserting the container's bytes claimed something
+  glTF never promised: that rebuilding a source on another platform reproduces
+  it byte for byte. The hash stays in the record as provenance, naming the bytes
+  the poster was rendered from on the machine that recorded it, and the prose in
+  all 83 records no longer calls the poster a render of "the exact downloadable
+  GLB".
+- Within-run integrity checks are untouched and still hash bytes: the gallery
+  index against the files built beside it, the build receipt against the index,
+  and both demo receipts against their own run's GLBs.
+- **The gallery now builds on Linux.** `bun run site:assets` followed by
+  `site/scripts/verify-assets.mjs` completes — 80 source/GLB pairs, posters, both
+  edit-demo revisions and the geometry example. Before this it failed on the
+  first example.
+- `pages.yml` now runs `site/scripts`'s tests explicitly. **Correction:** this
+  entry first said those tests had never run in any workflow. They had. `bun run
+  test` is `bun test src scripts`, bun treats those as substring filters on
+  paths, and `site/scripts` matches `scripts` — so both files were already in the
+  suite CI runs. The step stays for a smaller reason: that coverage is
+  incidental, and spelling the script `bun test ./src ./scripts` would drop it
+  silently.
+- **The gallery no longer builds on Windows.** `pages.yml` is `ubuntu-latest`,
+  which closes Phase 6.
+- New `scripts/glb-chunk-hashes.mjs` splits a GLB by chunk, and it answered the
+  question Phase 6 opened with. Measured on 8 examples across both platforms at
+  one commit: the JSON chunk diverges in **all 8**, the BIN chunk in **2 of 8**,
+  and totals move by 4, 8 and 264 bytes — digit counts changing, which a
+  formatting difference cannot do, because ECMAScript specifies number-to-string
+  exactly. So the divergence is the float values themselves, most likely the
+  transcendentals, which IEEE-754 does not bit-specify. That means no canonical
+  serialization could ever have fixed it, and narrowing the receipt was the only
+  option that works.
+
+## The renderer starts itself, and now ships — 2026-09-11
+
+- The MCP server **starts the GPU render service on demand**. Installing it
+  (`cd render-service && npm install`) is the whole setup: there is no longer a
+  second process to start first, and nothing to restart to pick one up. The
+  first view that needs PBR shading starts the renderer, the rest of the session
+  reuses it, and it stops when the server does. Measured end to end on the
+  shipped bundle with nothing listening: the first `kiln_render` came back
+  material-faithful from the GPU in 5.4 s, the second in 1.7 s.
+  - A service already listening is **joined, not replaced**, and a session that
+    merely found one does not stop it on the way out -- so one GPU shared by a
+    batch of dispatched agents keeps working, and the agent that finishes first
+    cannot pull the renderer out from under the others.
+  - A machine that did not install the renderer is **unchanged**, deliberately
+    and at the level of the attached port rather than the rendered result: the
+    absence of a render port is what makes an ordinary CPU view read as ordinary
+    instead of as a degrade.
+  - `KILN_RENDER_PORT_URL` and `--render-port` short-circuit all of it, so a
+    hosted or remote GPU is still exactly one flag. `KILN_RENDER_SERVICE_PORT`
+    moves the local one off 8000.
+  - The CLI is deliberately not on this path: a one-shot `kiln render` should not
+    pay a GPU process's startup to draw one sheet.
+- **`render-service/` now ships in the package.** The MCP server told every model
+  that a GPU renderer "ships as render-service/ in this installation"; that was
+  false for anyone installing from npm, because the directory was in no `files`
+  entry. Its source travels with the package now (104 KB) while its ~94 MB of
+  native dependencies stay an explicit opt-in install.
+- `webgpu` 0.4.0 -> 0.6.0, smoked on hardware: 36/36 service unit tests, display
+  conformance passed, end-to-end smoke all pass.
+- A service started **for** you binds loopback; one you start yourself still binds
+  every interface, which is what a container deployment needs. `HOST` is now
+  honoured either way.
+
+## Review surfaces say what they mean — 2026-09-11
+
+- `viewFidelity.exactArtifact` was a hard-coded `false` literal at every
+  `kiln_render` site, never computed. A flag that is always false carries no
+  information, and this one invited the opposite of the truth: a model could
+  read it as "these bytes differ from what I would export" when the bytes are
+  frequently identical. The value is still false -- this surface only ever
+  renders an in-loop build -- but it now carries the reason code
+  `IN_LOOP_BUILD_NOT_PERSISTED`, so the false value is readable rather than
+  ominous.
+- `kiln_screenshot_animation` was reported to rotate a whole asset where the
+  clip drives one joint. **It does not.** Measured on world matrices rather than
+  pixels: a one-channel clip moves the joint's subtree through a clean
+  180-degree yaw while the un-animated sibling holds the origin at every phase.
+  An image cannot tell a turret sweeping from a scene spinning, which is why the
+  report was plausible; a regression test now stands where the doubt was.
+- `arrayLinear` and `arrayRadial` say outright that `count` is the total
+  including the source, which survives as copy 0 -- so `count: 8` gives eight
+  bolts, not nine. The program contract states that
+  `kiln_screenshot_animation` requires `clip` by name, that `frameTimes` is
+  phases in 0..1 rather than seconds, and that a clip that renders frozen means
+  a joint-name mismatch surfaced in `unresolvedTracks`.
+
+## Dependency refresh — 2026-09-11
+
+- Patch and minor bumps with no API surface change: `@types/three` 0.185.4,
+  `acorn` 8.18.0, `manifold-3d` 3.5.3, `sharp` 0.35.4, `zod` 4.6.2,
+  `@anthropic-ai/sdk` 0.125.0, `@biomejs/biome` 2.5.13, `@google/genai` 2.22.0,
+  `@strands-agents/sdk` 1.17.0. `biome.json` follows Biome's own version, which
+  the linter checks and which is what actually failed the gate; one test file
+  picks up the new formatter's line fitting.
+- **`@gltf-transform/*` is now pinned to exactly 4.4.1**, joining `three` and
+  `gltf-validator`. 4.5.0 changes the bytes of every exported GLB: all 83
+  recorded `artifactHash` values move, and the gallery build fails on a stale
+  poster. A caret range on the library that serializes the artifact means the
+  artifact's identity can change on an unrelated install, which is not a
+  property this project can have. Taking 4.5.0 is a deliberate act with receipts
+  re-recorded in the same pass, not a refresh.
+- `three` stays at 0.185.1. `@types/three` has no 0.186.x published, and r186
+  renames `Source` to `TextureSource` and makes
+  `BufferGeometryUtils.toTrianglesDrawMode()` mutate in place rather than clone.
+  Taking the runtime without the types would be a net loss.
+
+## Toolchain moved to Bun 1.4.2, and the MCP bundle stopped starting itself — 2026-09-11
+
+- Development toolchain pins move to Bun 1.4.2, Node 22.23.2 and npm 12.0.2.
+  Bun 1.4 also fixes the early-exit behaviour above at its source: the pre-fix
+  CLI, which produced empty output in 6 of 8 concurrent runs on 1.3.14, produced
+  full output in 16 of 16 on 1.4.2. The `withProcessAlive` guard stays -- it
+  holds for anyone still on 1.3.x, and nothing in the runtime contract promises
+  otherwise. The offline suite runs about 18% faster.
+- **`dist/mcp-server.mjs` started a stdio server when merely imported, and had
+  done so for as long as the bundle has existed.** The source guarded its entry
+  block with `import.meta.main`, a Bun property that no Bun release lowers
+  correctly for a `--target=node` bundle. Every lowering emits
+  `__require.main == __require.module`; under Node ESM both sides are
+  `undefined`, so the guard was always true. Bun 1.4 then stopped emitting the
+  `__require` helper that line still references, which turned the same
+  expression into a `ReferenceError` before the server could speak -- loud where
+  it had been silent, and how this was finally caught. Both entries now decide
+  from `process.argv[1]` through a shared `isDirectEntry`, which needs no
+  lowering and means the same thing on both runtimes.
+
+## `kiln` commands no longer exit 0 in silence under Bun — 2026-09-11
+
+- Under Bun, a CLI command could exit 0 having written nothing at all: no output,
+  no error, no rejection. `kiln save` did it reproducibly under load. The command
+  was not failing, it was still running -- Bun does not register the in-flight work
+  as an active resource, so the event loop went idle and the process exited before
+  `main()` settled. Every entry point was exposed, the generated workspace
+  `kiln.mjs` launcher included, because all of them await `main()` and then set
+  `process.exitCode`. `main` now holds the process open for its own duration.
+  Node was unaffected in practice, but the guard is runtime-agnostic.
+- Every CLI destination now creates the directories leading to it. `--out` and
+  `--views` failed with a bare `ENOENT` on a missing parent, and failed *after*
+  the build had run and printed a `programRef` -- a successful render followed by
+  an error naming a path but not the directory as the thing to fix. Covers
+  `render --out`, `render --views`, `generate`, `source <ref> --out` and
+  `export --out`.
+
+## Usable from a bare clone by any harness; isolate honored on GPU — 2026-09-10
+
+- A bare clone is now usable by claude, codex, opencode, hermes and agy. The root
+  `.mcp.json` pointed at `${PLUGIN_ROOT}`, which only Antigravity defines, so the
+  server failed to start with MODULE_NOT_FOUND in every other host; it now uses
+  `${CLAUDE_PROJECT_DIR:-.}`, which resolves whether or not the variable is set.
+  `CLAUDE.md` imports `AGENTS.md` rather than duplicating it, and the
+  `kiln-setup-workspace` skill is registered at `.claude/skills/` and
+  `.agents/skills/` so a clone opened for an asset task is told to build a
+  workspace instead of authoring in the engine checkout.
+- `visibility: 'isolate'` and the legacy `isolate: true` were silently ignored
+  whenever a GPU service was attached. Both hide geometry by clearing
+  `mesh.visible`; the CPU rasterizer culls on that flag, but glTF carries no
+  per-mesh visibility, so the derivative GLB shipped the hidden meshes and the
+  service drew them. `kiln_inspect` was reporting "nothing in this image occludes
+  it" about images where everything still did. The derivative serialization now
+  prunes hidden meshes from a copy, leaving the caller's scene untouched. The
+  only previous test framed a single-mesh scene, where isolation cannot change
+  the image.
+- The generated workspace guide is organised around the authoring loop rather
+  than a flat tool list, and presents the MCP server and `node kiln.mjs` as equal
+  surfaces that may be mixed, naming the two things that actually differ: where
+  the rendered image lands, and that a CPU view is not material evidence. It also
+  names the GPU render service, resolving the engine path through
+  `.kiln/workspace.json` so `--repair` keeps it accurate, and asks the session to
+  report skills and MCP servers it inherited from user-level configuration.
+- `START.md` printed a literal `/current/kiln/` in its repair command; it now
+  prints the recorded installation path plus how to recover if that moved.
+
+## Smaller clone; gallery images served from R2 — 2026-09-10
+
+- Gallery renders and launch video are no longer carried in git history. A clone
+  costs 52 MB and 8 seconds rather than 440 MB and 79 seconds, 48 MB with
+  `--filter=blob:none`, and a plugin install no longer pays for 539 MB of
+  repository content twice. Packed history went from 226.06 MiB to 17.41 MiB.
+- The 88 gallery images moved to Cloudflare R2 byte for byte and are served from
+  `assets.kilnstudio.tools`. Nothing was re-encoded: all 83 poster receipts still
+  verify against the stored objects, and `scripts/verify-posters.mjs` checks that
+  on every gallery build.
+- **This rewrote history.** All 177 commits survived and the tree is unchanged
+  apart from the removed images and video, but every commit hash changed. Clones
+  predating this cannot fast-forward; see the note in `README.md`. Links pinned to
+  an old commit SHA will stop resolving; links through `main` are unaffected.
+- The launch video was never what the README served -- that comes from GitHub's
+  asset CDN -- so the README is unaffected. `assets/gallery/` deliberately stays
+  in the repository, so the README grid needs no network.
+- Re-encoding the posters to shrink them was considered and rejected: image tokens
+  scale with pixel dimensions, not file size, so it would have saved no agent
+  context while voiding all 83 receipts.
+
+Full record, including everything rejected and why, in
+[docs/plans/repo-size-and-r2-migration-2026-09-10.md](docs/plans/repo-size-and-r2-migration-2026-09-10.md).
+
+## Collections and chat viewing — 2026-09-06
+
+- Save assets into project or personal collections with immutable revisions,
+  hashed provenance, original source, and portable editable ZIP bundles.
+- Browse collections and imported GLBs in a local viewer with animation controls,
+  revision inspection, and GLB/source/bundle downloads.
+- Present saved assets in supporting MCP App clients with `kiln_present`.
+  ChatGPT viewing was verified; native GLB/ZIP attachment delivery remains
+  unverified. Host-provided download links are supported.
+- Package complete skills independently or bind them to a ChatGPT connector.
+- Add a canonical-only sitemap and crawler discovery file to the project site.
+
+See [dogfood results and remaining work](docs/collections-dogfood.md) and
+[indexing diagnostics](docs/site-indexing.md). Package version remains 0.6.0;
+this change does not publish a new npm package or promote dogfood assets.
+
+## Public OSS snapshot — 2026-09-05
+
+- Short, immutable source references work across rendering, source reads, edits,
+  CLI exports, and MCP restarts. Full hashes remain compatible.
+- Project-local setup and skills support authoring, inspection, and refinement
+  through the CLI, MCP server, and TypeScript tools.
+- Geometry modifiers and configurable asset/part cameras extend the authoring
+  and review workflow.
+- The redesigned site includes 62 selected assets with source downloads, GLB
+  viewers, attribution, and recorded revision histories where available.
+- Mechanical Peacock and Deco Radio include documented maintainer repairs.
+  Brass Tellurion and Victorian Greenhouse remain archived outside the gallery.
+- Package checks cover Windows, Linux, and hosted Apple Silicon/Intel Macs.
+
+The snapshot retains package version 0.6.0. Earlier development notes follow;
+their asset counts and workflow descriptions describe those earlier revisions.
+
+## [Unreleased]
+
+### Changed
+- **`site/` is a project site now, not a gallery.** The front page was a wall of
+  specimens with a tally of triangles above it, which answered a question nobody
+  arriving from a link was asking. It now opens on what Kiln is, the offline command
+  that proves the engine works with no model and no key, the exact configuration for
+  each of the five harnesses with the gotcha that cost time in each one, and a map of
+  where to look in the repository; the specimens moved behind `#/gallery` and are
+  reached from a strip of eight. The aggregate counts are gone -- a number is a claim
+  about the library, and the library is the thing on the other page. Per-card model
+  attribution stays, because that is not a statistic. `REPO` and `asset()` moved out of
+  `App.tsx` into a leaf module: once `App` imported a page that read one at module
+  scope the cycle turned into a blank screen at first paint, and a module that imports
+  nothing cannot be in a cycle.
+
+### Fixed
+- **The carousel and orrery GIFs no longer show something the programs beside them
+  stopped producing.** Both were flagged in review as showing an earlier revision, and
+  both were regenerated on the GPU port from the current source. Nothing in the repo
+  ties a GIF to the revision it was rendered from, so the staleness was caught by
+  somebody remembering rather than by a gate -- the stills have the same exposure.
+  A frame overlay confirms the camera is fixed across both loops and only the authored
+  motion moves.
+
+### 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-up
+  coordinate semantics, world bounds, ground offset, role, render metrics, and
+  structural-validator counts. `inspectGlbIntegration(bytes)` derives the same
+  contract 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 now
+  set the glTF default scene, and optimize/palette rewrites repair legacy files whose
+  first scene existed without being selected. Consumers no longer have to guess which
+  scene 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
+
+### Added
+- **`measureGlbBounds(bytes)` (H-41).** World-space AABB straight from stored GLB
+  bytes (WebIO + `getBounds`, EXT_mesh_gpu_instancing registered) so consumers that
+  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 the
+  3/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.
+  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 effort
+  keywords → `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
+  preserved unless a consumer opts in. NOTE for consumers: registry rows that
+  carried a decorative Google `maxTokens` now BIND -- set them to the intended
+  ceiling 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 cap
+  at 50% of `maxTokens` (dropped entirely when even the 1024 floor exceeds that
+  half), and 'high'/'xhigh' downgrade to 'medium' when OpenRouter's ~80%
+  translation would leave < 8,192 visible tokens (the cycle-2 step-1 MaxTokens
+  deaths: a 32K model at 'high' kept only ~6.4K for visible output). 64K/48K
+  configurations are untouched.
+- **QA-blocked render errors are actionable (H-40(3)).** `AssetQaBlockedError`'s
+  message 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
+  the agent reads when a mid-loop `kiln_render` is QA-blocked, and what the
+  salvage path records for QA-blocked step-cap programs.
+
+### Measured
+- **Per-render QA cost (H-40(4), `scripts/qa-cost-bench.ts`):** registry rules add
+  1–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.
+
+## [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
+  pass reaches prod with no wire change. Repeated geometry (>= 5 nodes sharing one mesh
+  after 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
+  count and does not move** (tests assert grade + triangle parity). Skipped for
+  animated/skinned docs and any asset carrying `Joint*` pivot names (Kiln City targets
+  those by name). Results are recorded as `InstancingSummary` (`meta.instancing`,
+  `RenderSceneResult.instancing`, `OptimizeGlbResult.instancing` -- and
+  `OptimizeGlbResult.summary` is now optional: an instancing-only pass has no
+  consolidation 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).
+- **M3 composer role/tier awareness (plan/05 §4.1).** `CatalogEntry` gains optional
+  `role` (`CatalogAssetRole` -- the M1d asset taxonomy) + `tier` (A–F); `catalogList()`
+  (and therefore `scene_list_assets`) surfaces them. Placement roles now DEFAULT from
+  the catalog asset's role via `placementRoleForAsset` (wonder/poi → hero, fill → fill,
+  else support) in `place`/`placeExact`/`cluster`/`ring`/`layout` -- an explicit agent
+  role still wins. The composer system prompt teaches the mapping, wonder scale-up, and
+  D/F-tier density budgeting.
+
+## [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
+  surgical, unlike the composer's whole-transcript collapse: no messages are added or
+  removed, toolUseIds are untouched (tool-use/tool-result pairing stays valid on every
+  provider), 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
+  later model calls. Opt out per run with `imageCompaction: 'off'`. New helpers exported
+  from `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
+  sprawl (>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
+  (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
+  across the extra invoke. New helpers exported from `agent`: `assessProgramGrade`,
+  `shouldGradeRefine`, `buildGradeRefineMessage`, `gradeRank`.
+
+### Fixed
+- **Step-cap abort no longer discards a rendered program.** A run halted by the model-call
+  cap used to return only an error, throwing away the working-buffer program the sink
+  already held. If the captured program renders, the run now returns it with the new
+  `RunKilnAgentResult.capped: true` flag (mirrors the composer's `capped` semantics); a
+  cap with nothing renderable is still an `error`.
+
+## [0.2.0] -- 2026-07-02
+
+The 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)
+plus the fixes below.
+
+### Fixed
+- **`auto` consolidation now fires on 4-material assets.** `PALETTE_MIN` dropped 5 → 4,
+  aligning the trigger with the instanceability rubric (grade B tops out at 3 materials,
+  so 4 is the first grade-C count). Previously a 4-material asset graded C and `auto`
+  never consolidated it.
+- **Uint32 indices for >65,535-vertex geometry.** `bridgeGeometry` always wrote
+  `Uint16Array` indices, silently wrapping values past 65,535 (corrupt GLB). It now
+  selects `Uint32Array` when the vertex count exceeds the Uint16 ceiling; the GLB
+  writer emits the matching `componentType` (5125).
+- **BYOK `apiKey` reaches Anthropic/OpenAI.** `makeKilnModel` dropped `opts.apiKey` on
+  the `anthropic` and `openai` branches (only google/openrouter passed it through), so
+  BYOK silently fell back to the provider env vars.
+
+### Changed
+- Comments in `agent/tools.ts` / `agent/run.ts` updated: the `unified` tool surface is
+  the production surface (Kiln Studio runs `KILN_TOOL_SURFACE=unified`), no longer
+  "flag-gated until a bench A/B clears it"; `current` remains the library default.
+
+### Housekeeping
+- Added the missing `LICENSE` file (MIT, already declared in `package.json`).
+- Rewrote the stale `@pixel-forge/core` module headers (`metrics.ts`, `agent/index.ts`,
+  `agent/run.ts`, `palette.ts`) to the `@kiln/engine` reality and removed dangling
+  references to files that do not exist in this repo.
+
+## [0.1.1] -- 2026-06-30
+
+### Documentation
+- Clarified that `@kiln/engine` remains private execution infrastructure. External developer access
+  is mediated by Studio `/v1`, private SDK/skills, and future AgentCore Gateway product tools rather
+  than direct engine, raw Forge, or composer harness exposure.
+
+### Changed
+- Treat native `claude-sonnet-5` as adaptive-only for Anthropic thinking controls: numeric
+  `KILN_THINKING` budgets are ignored for this model so the agent harness does not send
+  manual extended-thinking params that Sonnet 5 rejects.
+
+### Added -- scene composer (`@kiln/engine/composer`, `/composer/agent`)
+A THREE-free scene-composition surface: a `PlacementModel` single-source-of-truth with a
+small scene DSL (`scene()`/`asset()`), terrain-agnostic hierarchy-aware layout, an overlap
+validator (MTV resolution), a ground sampler, and a `SceneRenderPort`; plus the Strands
+agent loop (`runKilnComposer`, 14 `scene_*` tools) isolated under `/composer/agent` so the
+SDK never leaks into the pure core. Transcript compaction collapses to `serialize(model)`
+past a threshold (the externalized model IS the state), with a soft step-cap backstop and a
+`scene_layout`-first prompt so large many-asset scenes converge. ~990 lines of new tests.
+
+> 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
+
+Initial extraction of the Kiln 3D engine from `pixel-forge/packages/core/src/kiln`
+(source `d396c10`), file history preserved via `git subtree split`.
+
+### Included (the reachable runtime closure of agent/render/palette/views/arena)
+- `agent/` Strands agent loop · `arena/` ranking math · `render.ts` GLB bake/grade/optimize/snap/composeScene
+- `primitives.ts` · `solids.ts` (CSG) · `ops.ts` · `gears.ts` · `uv.ts`/`uv-shapes.ts` · `textures.ts`
+- `validation.ts` (AST) · `inspect.ts` · `metrics.ts` · `palette.ts`/`palette-snap.ts`
+- `list-primitives.ts` · `prompt.ts`/`prompt-api.ts` · `tools/registry.ts` · `views/` (CPU rasterizer + PNG)
+
+### 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
+  image path.
+- Legacy single-shot `generate.ts` (Studio uses the agent path) and the entangled root
+  `index.ts` barrel (Studio consumes subpaths, not the barrel).
+- Dropped deps: `@anthropic-ai/*`, `@ai-sdk/{anthropic,google,openai}`, `@google/genai`,
+  `openai`, `@fal-ai/client`, Vercel `ai`, `playwright`, `meshoptimizer`, `xatlas-three`,
+  `@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/...')`).
+
+### Tests
+- 36 source test files ported (382 pass / 2 skip / 0 fail offline). Live agent tests
+  gated behind `KILN_SPIKE_LIVE=1` (off in CI). Dropped: the 6 OUT-module test suites,
+  `deps-smoke` (old dep set), `spike`/`top-level-generate` (tested the deleted barrel
+  `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
+  the multi-provider `makeKilnModel` factory in `providers.test.ts`; they never enter
+  runtime `dependencies`. The kiln-glb skill-drift gate is `skipIf`-guarded (the skill
+  lives outside the engine repo).
+
+### Tooling
+- **Biome 2.5.1** adopted (lint + format). Source formatted to Biome style (single
+  quotes, 2-space, 100-col); `bun run lint` is green. A baseline of 19 stylistic
+  warnings (`noExplicitAny`/`useTemplate`/`useOptionalChain`/`noGlobalIsFinite`/…) is
+  left 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)
+- Burn down the 19 Biome warnings + re-promote `useIterableCallbackReturn` to error.
+- Tighten `tsconfig` (`exactOptionalPropertyTypes`); currently mirrors pixel-forge core
+  for a zero-drift green typecheck.
+- Consider `tsup` `dist` build + Vitest golden-image render harness (engine ships TS
+  source today for drop-in parity with how Studio consumes core).
+- Rename the live-test gate `KILN_SPIKE_LIVE` → `KILN_LIVE`.