@instruktlabs/kiln 0.0.0-stage → 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to Kiln
+
+Small fixes, clear bug reports, examples and documentation improvements are welcome.
+For a behavior bug, include a minimal `.kiln.js` program, the command or tool call,
+and the error or image you saw. Include your OS, Node version and whether rendering
+used CPU or GPU. Remove credentials and private paths from shared logs.
+
+## Work on the engine
+
+Read [AGENTS.md](AGENTS.md) and the [README](README.md). Contributor checks use Bun
+1.4.2, Node 22.23.3 and npm 12.2.0. End users only need Node/npm for a built package.
+
+```sh
+bun install --frozen-lockfile
+bun run check:toolchain
+bun run check:skills
+bun run build:sdk
+bun run typecheck
+bun run lint
+bun run test
+bun run test:render-service
+bun run test:coverage
+```
+
+`bun run test` is `bun test src scripts`, so it never reaches `render-service/` -- a
+separate npm project with its own lockfile and a native dependency.
+`bun run test:render-service` does, after `npm --prefix render-service ci
+--ignore-scripts` once. This suite needs no GPU or Dawn build; CI requires it.
+
+The maintained scenes have a separate lockfile and validation commands:
+
+```sh
+cd scenes
+bun install --frozen-lockfile
+bun run check:toolchain
+bun run check:pins
+bun run typecheck
+bun run lint
+bun run test
+bun test ./scripts/tests --timeout 20000
+```
+
+The pin check reads the engine, render service and site from the same checkout.
+The portable test runner covers scene source contracts; the separate script-test
+command covers the validation and evidence tooling. Asset and browser qualification
+require staged inputs; see [scenes/README.md](scenes/README.md).
+
+`lint` reports **nothing** on a clean tree, and a warning fails it. There is no
+tolerated baseline to compare against, so any diagnostic your change produces is
+yours -- either fix it, or suppress it with a `biome-ignore` comment that says why.
+
+The surface is every directory that holds code: `src/`, `site/src/`, `site/*.ts`,
+`render-service/` and `scripts/`. If you add
+a directory, add it to `files.includes` in `biome.json`: Biome silently processes
+nothing outside that list, which is how `scripts/` went unlinted while the coverage
+run measured it. Note that `biome` prints at most 20 diagnostics by default, so a
+count read off the output is a floor.
+
+### Version
+
+Maintainers should follow the [v1 release runbook](https://github.com/instruktlabs/kiln/blob/main/docs/releasing.md) for exact
+archive qualification, npm staging and owner promotion.
+
+`version` in `package.json` identifies the installable release. Changes on `main`
+ahead of that release go in the changelog's `Unreleased` section and can retain the
+released version until the next release is prepared. A new release must bump the
+version before producing its tarball: two different releases must never share a
+package version. Patch for a fix, minor for changed or added capability; this
+package is pre-1.0 and unpublished, so a minor is the normal case.
+
+Bumping it means rebuilding: `runtimeBuildIdentity` hashes the version into each
+entry's `identity` in `dist/build.json`, which is the value a build receipt cites. Run
+`bun run build:runtime` and commit `dist/`. A test asserts the two agree -- nothing else
+does, because the version is read from `package.json` at runtime rather than inlined, so
+the bundle bytes are identical either way and a byte comparison cannot see the drift.
+
+For behavior changes, first add a focused failing test, then make the smallest fix
+and run the relevant checks. Keep the coverage thresholds. Ordinary tests use CPU
+rendering and make no model calls. Live provider tests are optional and can spend
+credits; they are not required for a documentation or platform contribution.
+
+Rebuild the runtime bundles after changing the CLI, MCP server or evaluator:
+
+```sh
+bun run build:runtime
+```
+
+Try the result in a separate authoring workspace:
+
+```sh
+node scripts/create-workspace.mjs ../kiln-test-assets --harness opencode
+```
+
+Choose your installed harness and follow the generated `START.md`. The directory
+must be empty and outside the engine installation. Setup copies project-local
+skills and configuration without changing global agent settings or authentication.
+
+In a pull request, describe the problem, resulting behavior and checks you ran.
+Keep generated source examples and their provenance together. If you change a
+public tool, update its shared registry definition rather than duplicating a
+transport-specific definition.
+
+## Check a built package
+
+```sh
+bun run build:runtime
+npm pack --ignore-scripts
+npm run test:package -- --tarball /absolute/path/to/the-generated-package.tgz
+```
+
+Use the actual filename printed by `npm pack`. The check installs runtime
+dependencies in a temporary directory and exercises the packaged CLI, MCP server,
+workspace setup and exports. It uses npm registry access but makes no model calls
+and publishes nothing.
+
+## Help verify macOS
+
+Windows, Linux and hosted macOS runners have passing package checks, including
+Apple Silicon and Intel. The [Mac setup guide](docs/install.md) still benefits from
+reports on real user installations and optional GPU support.
+
+If you have a Mac, try the built-package workflow and report the package hash,
+macOS version, Node/npm versions, architecture (`node -p process.arch`) and package
+check result. A small PR fixing a reproduced installation issue is useful; a clear
+passing or failing receipt is useful too. CI already contains native jobs for both
+architectures. No model generation or paid provider account is needed.
+
+Keep CPU package verification separate from Apple GPU/Metal testing. A successful
+installation does not establish GPU support. There is no need to install a new
+global skill set or copy authentication files to contribute either check.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Kissinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,444 @@
-# Temporary Holding Version
+# Kiln
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/instruktlabs/kiln/actions/workflows/ci.yml/badge.svg)](https://github.com/instruktlabs/kiln/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Build and revise 3D assets with your coding agent.**
+
+**The package name is `@instruktlabs/kiln`.** This checkout targets version 1.0.0.
+Stable releases use npm's `latest` tag; release candidates use `next`.
+Until 1.0.0 is available in the [npm registry](https://www.npmjs.com/package/@instruktlabs/kiln),
+install the public RC with `npm install @instruktlabs/kiln@next`, or pin
+`@instruktlabs/kiln@1.0.0-rc.1`. Do not use the unqualified name while `latest`
+still points to the temporary `0.0.0-stage` holding version.
+Package publication and the hosted service have separate release gates. The [SDK guide](docs/sdk.md)
+describes the compiled ESM library; use the [local package build](docs/install.md#install-a-local-package)
+to test this checkout. The 0.10.0 release described below remains a historical release.
+
+The agent writes JavaScript using Kiln's geometry and material helpers. Kiln runs the
+program and returns rendered views and structural checks so the agent can review its
+work. Export the asset as a GLB and keep the source for later changes.
+
+Kiln runs locally. It includes an MCP server, a CLI, a TypeScript library, and skills
+for authoring, editing, animation review, and scene composition. Your agent supplies
+the model; Kiln does not require a separate model API key for its tools.
+
+Walk the [Farm](https://kilnstudio.tools/scenes/farm/), drive across
+[Golden Gate](https://kilnstudio.tools/scenes/golden-gate/), or explore the
+[Foundry Floor](https://kilnstudio.tools/scenes/foundry-floor/), or fight as Achilles
+or Hector in [Troy](https://kilnstudio.tools/scenes/troy/).
+The scenes put Kiln assets to work with animation, levels of detail and interactive controls.
+
+| Farm | Golden Gate |
+| --- | --- |
+| [![Explore the Farm scene](assets/readme/farm-v09.png)](https://kilnstudio.tools/scenes/farm/) | [![Golden Gate over the water](assets/readme/golden-gate-v09.png)](https://kilnstudio.tools/scenes/golden-gate/) |
+| Crops, animals and working farm buildings. | Bridge, terrain, water and drivable traffic. |
+
+| Foundry Floor: the campus | Inside the fab |
+| --- | --- |
+| [![Foundry campus exterior](assets/readme/foundry-campus-v09.png)](https://kilnstudio.tools/scenes/foundry-floor/) | [![Container transport inside the Foundry Floor](assets/readme/foundry-floor-v09.png)](https://kilnstudio.tools/scenes/foundry-floor/) |
+
+Foundry Floor pairs a factory campus with a representative floor in its southwest
+building. AMRs, robot arms and overhead transport move containers through the fab.
+
+Six reusable vehicles, shown with the gallery's live body-paint controls:
+
+| Hatchback · yellow | Sedan · blue | SUV · green |
+| --- | --- | --- |
+| [![Yellow hatchback](assets/readme/hatchback-yellow.png)](https://kilnstudio.tools/gallery/hatchback/) | [![Blue sedan](assets/readme/sedan-blue.png)](https://kilnstudio.tools/gallery/sedan/) | [![Green SUV](assets/readme/suv-green.png)](https://kilnstudio.tools/gallery/suv/) |
+| Pickup · red | Box truck · silver | Transit bus · blue |
+| [![Red pickup](assets/readme/pickup-red.png)](https://kilnstudio.tools/gallery/pickup/) | [![Silver box truck](assets/readme/box-truck-silver.png)](https://kilnstudio.tools/gallery/box-truck/) | [![Blue transit bus](assets/readme/transit-bus-blue.png)](https://kilnstudio.tools/gallery/transit-bus/) |
+
+[Browse the current assets](https://kilnstudio.tools/gallery/) ·
+[Farm pack](https://kilnstudio.tools/packs/farm/) ·
+[Vehicles pack](https://kilnstudio.tools/packs/vehicles/) ·
+[Scenes](https://kilnstudio.tools/scenes/)
+
+All five packs offer **Runtime assets** for applications and **Editable assets** with
+authoring sources, materials and the available revisions. The vehicle viewer includes
+live paint colours. [Pack source](packs/README.md) and the maintained
+[Farm, Bridge, Foundry and Troy scene code](scenes/README.md) are in this repository.
+Large generated models and archives are downloaded explicitly from Cloudflare.
+The [Blender and Unity guide](https://kilnstudio.tools/docs/engine-handoff/)
+describes the tested import workflows and their limits.
+
+Kiln's local dashboard adds [optional projects, a material library and Live Review](docs/projects-and-live-review.md).
+Standalone assets remain a complete workflow; projects add shared briefs, inventories,
+art direction and material pins when useful.
+
+Earlier examples remain in the gallery and [example provenance](docs/example-provenance.md).
+They are historical showcases, not golden outputs or a model ranking.
+Screenshots above show the v0.9 review builds; [image provenance](assets/readme/README.md).
+
+Version **0.10.0** is the v1 readiness release: the stdio server serves protocol revision
+2026-07-28 beside the 2025 handshakes and answers before the engine loads, the three
+record tools are flat objects with an `action` field, every tool result is bounded and
+leads with its verdict, and the generated workspace guide and skills are shorter. It
+builds on 0.9.0's optional projects, material library, Live Review and calibrated
+`review-neutral-v1` lighting rig. [CHANGELOG.md](CHANGELOG.md) lists the changes with
+each breaking one marked, and the [migration notes](docs/migration.md#changes-in-0100)
+list what an existing author will notice.
+
+**0.10.0 was the source and site release for dogfooding.** Its package tarball is attached
+to the [v0.10.0 release](https://github.com/instruktlabs/kiln/releases/tag/v0.10.0)
+with `SHA256SUMS.txt` and the installed-package receipts, as later releases' tarballs are
+on the [releases page](https://github.com/instruktlabs/kiln/releases).
+The public npm release candidate and stable release process are described above;
+site deployment does not publish a package.
+
+## Install and start an asset workspace
+
+Use Node.js **20.15.0+ on the 20.x line**, or **22.2.0 and later**, with npm.
+Download the tarball and `SHA256SUMS.txt` from the release and check the tarball
+against the checksum file before installing. Use only a tarball actually attached to
+a release, with that release's documentation; a checkout ahead of the release
+[builds its own package](docs/install.md#install-a-local-package). Bun and a separate
+model API key are not required to install the tarball:
+
+```sh
+mkdir kiln-install
+cd kiln-install
+npm init -y
+npm install /absolute/path/to/PACKAGE.tgz --omit=dev --include=optional
+npm exec --offline -- kiln-init ../my-assets --harness opencode  # or claude, codex, hermes, agy, copilot, cursor-agent
+cd ../my-assets
+# Follow START.md for your harness
+```
+
+The installation stays separate from your asset workspace. Choose `claude`, `codex`,
+`opencode`, `hermes`, `agy`, `copilot`, or `cursor-agent` for `--harness`.
+The [installation guide](docs/install.md#install-the-package) covers checksums,
+local package builds, existing-workspace upgrades and platform qualification. For a new
+installation, a maintained Node 22 or 24 LTS release is recommended; Node 20
+compatibility accommodates existing distribution-managed installations.
+
+## Run from a checkout
+
+For engine development, install [Bun](https://bun.sh) 1.4.2, then:
+
+```sh
+git clone --filter=blob:none https://github.com/instruktlabs/kiln
+cd kiln
+bun install --frozen-lockfile
+bun run kiln render examples/crate.kiln.js --out crate.glb --views sheet.png
+```
+
+`--filter=blob:none` checks out the current tree in full and leaves historical
+file contents on the server, fetching them only if you ask for an old revision.
+A plain `git clone` also works and gives you the whole history up front.
+
+This writes a GLB and a six-view image of an existing program. It makes no model call.
+Rendering uses the CPU unless a compatible local GPU service is available.
+Use `--render cpu` to select the CPU explicitly. Sheets sit on a neutral grey; add
+`--backdrop dark` or `--backdrop light` when an asset's silhouette merges with it; `kiln save`
+takes the same flag for the preview it stores.
+
+For anchored CLI edits, import source with `kiln source asset.kiln.js`, then run
+`kiln edit RETURNED_REF --edits edits.json`. The file contains an array of
+`{ "oldString": "exact existing text", "newString": "replacement text" }` objects.
+The command returns a new immutable reference and diff without executing source;
+render that new reference to inspect the result. `kiln edit --help` describes
+batch limits and `replaceAll`.
+
+**Using assets in Blender or Unity?** Read the [handoff guide](docs/engine-handoff.md) for direct GLB import,
+materials, backfaces, named pivots and animation checks. The established exporter remains
+the default. An **experimental community exporter** is available for explicit comparison
+when you need its additional feature preservation; the guide includes activation, rollback
+and known limitations. Both converters are included in this installation.
+
+<details>
+<summary>For clones made before the September 10 history cleanup</summary>
+
+History was rewritten on 2026-09-10 to drop 288 MB of gallery renders and launch
+video that no tool reads, taking a clone from 440 MB to 60 MB, or 49 MB with
+`--filter=blob:none`; measured 2026-09-12. Every commit survived and the tree is
+unchanged apart from those files, but every commit hash changed, so a clone made
+before that date cannot fast-forward.
+
+Re-cloning is simplest. Before converting an old clone, back up uncommitted work
+and local branches: the commands below reset the checkout and prune recovery
+history. Move the **tag** as well as the branch:
+
+```sh
+git fetch --tags --force origin
+git reset --hard origin/main
+git reflog expire --expire=now --all
+git gc --prune=now
+```
+
+`--force` is the load-bearing flag. `oss-2026-09-05` was rewritten too, and git
+will not move a tag that already exists without it: plain `git fetch --tags`, and
+even `--prune-tags`, both report `would clobber existing tag` and leave the old
+one in place, holding every removed file reachable. Omit it and `.git` stays at
+228 MB where a fresh clone is 26 MB; run it and the same clone packs to 23 MB.
+
+The gallery images are served from `assets.kilnstudio.tools`; the 83 poster
+receipts that attest their bytes stayed in `examples/renders/`.
+
+</details>
+
+## Connect your agent
+
+The [agent reading guide](site/public/llms.txt) links to setup, tool schemas and the
+source revision workflow in plain text.
+
+The installation commands above create a separate asset workspace, register MCP
+and copy the Kiln skills. Follow its START.md to launch your harness. Setup writes
+project-local configuration and leaves your global settings unchanged. A user-level server
+named `kiln` from another installation can still load beside the workspace's
+`kiln_workspace`; author with `kiln_workspace`, and disable the other server for these
+sessions when the harness lists both ([how to tell them apart](docs/harnesses.md)).
+
+If you are developing Kiln from a source checkout, create that workspace with:
+
+```sh
+bun run build:runtime
+node scripts/create-workspace.mjs ../my-assets --harness opencode
+cd ../my-assets
+# Follow START.md for your harness
+```
+
+Choose `claude`, `codex`, `opencode`, `hermes`, `agy`, `copilot`, or `cursor-agent` for `--harness`, then open that harness in the
+new directory using its generated START.md instructions and accept its project and MCP trust prompts. Sign in to your harness
+first. The compiled MCP server and CLI accept Node.js 20.15.0+ on the 20.x line,
+or 22.2.0 and later. Bun is for building and testing the engine; installed commands
+do not require it. The optional native Strands agent requires Node 22.2.0+.
+See the [runtime requirements and qualification limits](docs/install.md).
+
+If the brief depends on textures, roughness, metalness, glass, or other material evidence,
+check the optional [GPU renderer setup](docs/rendering.md#running-the-gpu-renderer) before
+the first authoring session. Auto mode starts a compatible local service lazily when its
+dependencies are available. CPU views are useful for shape and contact, but not for judging
+materials. After dependency repair or a failed startup, call
+`kiln_renderer({action:"reprobe"})` inside the MCP session to refresh its connection.
+Restart after changing Kiln, environment variables or credentials. A compatible
+renderer can also run on another device: configure the MCP server's
+`KILN_RENDER_PORT_URL` and `KILN_RENDER_TOKEN`, or use CLI `--render-port URL` with
+the token in its environment. The [rendering guide](docs/rendering.md#running-the-gpu-renderer)
+covers remote service authentication and lifecycle.
+
+**Follow START.md rather than launching the harness directly.** Some harnesses keep all
+configuration in a user-level home and read nothing from a project directory, so the workspace
+reaches them through a small generated launcher -- `node codex.mjs`, `node agy.mjs`,
+`node hermes.mjs` -- which passes the server, the program store and the directory per
+invocation. Nothing is written outside the workspace and your existing configuration and
+sign-in are left alone. Starting those harnesses with their bare command in the workspace finds
+no Kiln tools. START.md names the right command for the harness you chose, and hermes needs one
+extra user-level registration that it prints for you.
+
+Try: “Read AGENTS.md, then make a wooden workbench with a lower shelf. Render it,
+review the result, and save the source and GLB.”
+
+Setup installs the core authoring, refinement and QA skills. Composition and batch workflows are opt-in.
+These skills work with your chosen harness through CLI/MCP. The optional built-in
+Strands agent adds its own workflow internally; do not copy that context into your
+harness. See [the workflow boundary](docs/runtime.md#optional-native-strands-workflow).
+
+The workspace contains your brief, assets, and skills. The engine source and example
+collection stay in the installation directory. See [clean-room setup](docs/clean-room.md)
+for the exact boundaries and headless use, or [installation](docs/install.md) for other
+harnesses and the plugin path.
+
+For Google models, see [Antigravity and Gemini setup](docs/google.md). Local coding
+agents use stdio directly; browser chat connections have different setup requirements.
+
+## Revise an asset
+
+Save finished work into this workspace with
+`node kiln.mjs save workbench.kiln.js --name "Workbench"`, or add
+`--collection library` when you explicitly want it in your cross-workspace user library.
+Run `node kiln.mjs view` to browse **This project** and **Your library**, inspect revisions,
+and download Original GLB, Runtime GLB with companion metadata, or editable ZIP
+bundles. Both collections use the same portable format and viewer. See [saved assets and the viewer](docs/collections.md).
+
+For application delivery, export with `--profile runtime --out asset.glb` to move
+Kiln's animation review metadata into a hash-linked JSON sidecar. Native glTF animation
+still plays without that sidecar. The default `editable` profile preserves saved files
+exactly; keep its ZIP for source and build records. The delivery profile is independent
+of the established/experimental converter selected during generation. An export never
+replaces an existing file, unlike `render --out`, because it hands off one exact saved
+revision; `--json` prints a receipt with each file's `bytes` and `sha256`.
+[Which options to use, why they exist, and examples](docs/export-profiles.md#which-option-should-i-use)
+are also included in the authoring and QA skills installed into new asset workspaces.
+
+## Use Kiln in a chat client
+
+Create and refine assets in ChatGPT through a private MCP connection, then ask to
+see a saved revision. `kiln_present` opens that exact revision in an interactive 3D card in
+supporting MCP App clients. Every coding harness receives exact artifact descriptors and readable
+resource URIs in the JSON result; a verified host can opt into core MCP `resource_link` blocks.
+An agent can also launch the local viewer on the saved revision and provide its loopback URL.
+Orbit the model and inspect its animation without leaving chat.
+ChatGPT viewing was verified with real saved assets.
+
+1. Install Kiln (or build the runtime from a checkout) and connect its stdio MCP server through an OpenAI Secure
+   MCP Tunnel scoped to your workspace.
+2. Install the authoring and refinement skills with their reference files using
+   ChatGPT's native skill uploader.
+3. Ask: “Make a field recorder, review the renders, save it to my project
+   collection, and show it with `kiln_present`.”
+
+The [ChatGPT setup guide](docs/chatgpt.md) covers connection, skill packaging, and
+host requirements. This currently needs developer setup; it is not a public
+one-click ChatGPT app. Local GLB and editable ZIP downloads work through
+`kiln view`. ChatGPT-native GLB/ZIP attachments remain unverified; download support
+depends on the client or a host-provided delivery link.
+
+## Restore source for another edit
+
+Import an existing program from your asset workspace:
+
+```sh
+node kiln.mjs source workbench.kiln.js
+```
+
+The command prints a short `programRef`, such as `p_7c94a132b8e0`, identifying that
+exact source. Copy it exactly for later calls:
+
+```js
+// programRef is the value returned by Kiln.
+kiln_source({ programRef, query: "shelfHeight" })
+kiln_edit({
+  programRef,
+  edits: [{ oldString: "shelfHeight = 0.2", newString: "shelfHeight = 0.35" }]
+})
+```
+
+`kiln_source` reads a bounded portion of the source. `kiln_edit` applies the changes
+and renders the result, returning a new reference and a diff. The original revision
+remains available. Text outside the replacements stays unchanged, and a failed edit
+does not modify the base.
+
+Save the new revision and export it without copying its source through the model:
+
+```sh
+node kiln.mjs source RETURNED_REF --out workbench-v2.kiln.js
+node kiln.mjs render RETURNED_REF --out workbench-v2.glb --views workbench-v2.png
+```
+
+Replace `RETURNED_REF` with the new reference from the edit. Short references survive
+local server restarts while you keep the workspace's store. Full SHA-256 references
+are still accepted. Inline `code` still works for new drafts and
+existing integrations. [Program storage and API details](docs/programs.md).
+
+## Shape geometry and choose views
+
+Keep equations and custom modeling functions in the program. For example, this
+samples a curved sheet; the [complete canopy example](site/examples/equation-canopy.kiln.js)
+adds its material, posts and sockets.
+
+```js
+const surface = parametricSurface(
+  (u, v) => [u, 1.35 + 0.22 * Math.sin(u * 2) + 0.12 * v * v, v],
+  { u: [-1.6, 1.6], v: [-0.8, 0.8],
+    uSegments: 48, vSegments: 24, orientation: 'vu' }
+);
+```
+
+Use `meshGeo` for explicit topology, or shape existing geometry with bends, twists,
+lofts and sweeps. [Geometry contracts and limits](docs/geometry.md).
+
+To check an attachment, request a close-up beside a whole-asset view. Reuse the
+`programRef` and exact `partPath` from the render result:
+
+```js
+kiln_render({ programRef, capture: {
+  version: 'kiln.capture.v1', cols: 2,
+  shots: [
+    { name: 'Whole asset' },
+    { name: 'Attachment', subject: { path: partPath },
+      visibility: 'context', camera: { type: 'orbit', relativeTo: 'part',
+        azimuthDeg: 65, elevationDeg: -18, padding: 3 } }
+  ]
+}});
+```
+
+The close-up follows the part's local axes while retaining surrounding geometry.
+You can also set explicit camera positions, return separate images, or sample
+animation frames. Either capture shape also takes `backdrop: 'neutral' | 'dark' |
+'light'`, and every result echoes the one used as `capture.backdrop`. `kiln_save` takes the
+same field for the preview it stores, and the manifest records it as `preview.backdrop`.
+[Camera controls](docs/cameras.md).
+
+## Tool reference
+
+Use `kiln_discover` to find operations, assemblies and optional recipes in ordinary
+modeling language. An empty request returns a compact overview with starting
+signatures and six summaries. For example, search with `{ query: "curved hollow tube" }`,
+then request `{ ids: ["sweepProfile"] }` for a complete contract and example. Exact
+batches accept up to six distinct IDs or executable names. Recipes take the id the
+search prints, with or without its prefix: `{ ids: ["recipe:material-wood-v1"] }` or
+`{ ids: ["material-wood-v1"] }`. A material recipe's summary names the call it stands
+for, `await materialRecipe("kiln.material.wood.v1")`. Search is local and needs no
+separate model, network call, or asset-category selection.
+
+The same workflow is available from your asset workspace in the CLI:
+
+```sh
+node kiln.mjs discover --query "curved hollow tube"
+node kiln.mjs discover --id sweepProfile --id createPart --json
+node kiln.mjs discover --kind recipe
+node kiln.mjs discover --capabilities
+```
+
+Search and overview accept `family`, `kind`, `tags`, `offset` and `limit` (default six,
+maximum twelve). CLI uses `--family`, `--kind`, repeated `--tag`, `--offset` and `--limit`.
+Browse current filter labels in the overview. Search relevance does not certify that
+a helper supports the entire requested asset; read its limitations and exact contract.
+
+`kiln_list_primitives` and its `name`, `names`, and `category` selectors are removed,
+with no callable alias. Stop the harness/MCP session, then run `kiln-init WORKSPACE
+--check` and `kiln-init WORKSPACE --upgrade` from the updated installation. Upgrade
+preserves assets and refuses conflicting local changes; resolve those explicitly
+before retrying. Restart the session to load current schemas. A fresh workspace is
+also supported. `--repair` repairs paths without upgrading copied skills. Use
+`kiln migrate intent|manifest OLD.json --out REVIEW.json` for an explicit legacy-data
+review; unresolved obligations prevent activation. See [migration](docs/migration.md).
+The
+[generated tool reference](docs/tools.md) covers source editing, validation,
+rendering, part inspection, animation and interior views. The shared factory is
+`createKilnProgramToolRegistry` in `@instruktlabs/kiln/tools`.
+
+## Uses and limitations
+
+The examples cover props, machinery, vehicles, buildings and rigid-part animation.
+Programs are useful when you want named parts, adjustable dimensions and repeatable
+variants. Organic shapes and detailed character work are less well demonstrated.
+Kiln is not a reconstruction tool: a reference image does not establish unseen geometry.
+
+Structural checks help find problems, but do not establish visual quality or suitability
+for a particular game. Review scale, performance, collision and appearance in your target
+scene. The CPU renderer shows geometry and base colours; inspect `viewFidelity` before
+judging textures or PBR materials. [GPU setup and materials](docs/rendering.md).
+
+## Development
+
+```sh
+bun run typecheck
+bun run lint
+bun run test
+bun run test:coverage
+```
+
+Tests run without model calls and use CPU rendering. Coverage thresholds are checked
+in CI. Runtime changes to the MCP server or CLI must also rebuild their committed bundles:
+
+```sh
+bun run build:runtime
+```
+
+For bug reports, include the smallest program that reproduces the problem and the
+render or error you saw. [CONTRIBUTING.md](CONTRIBUTING.md) covers setup, checks and
+pull requests; [AGENTS.md](AGENTS.md) covers repository conventions.
+
+- [Library and architecture](docs/architecture.md)
+- [Headless generation](docs/dispatch.md)
+- [Headless harnesses](docs/harnesses.md)
+- [Program-reference design](docs/programs.md)
+- [Example collection](docs/examples.md)
+- [Production history](docs/history/production-architecture.md)
+
+Kiln began as the engine behind Kiln Studio. The hosted product has retired; this
+repository contains the open-source engine and local tools.
+
+MIT licensed. Built by Matthew Kissinger.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,62 @@
+# Third-party notices
+
+Kiln uses dependencies under their own licenses. Their package license files remain part
+of the installed dependency tree. The optional renderer uses `webgpu` 0.6.1; it is resolved
+as a dependency, not repacked or stripped. Its distributed `LICENSE.md` contains the Dawn
+and Tint notice below. This notice is reproduced from the pinned installed artifact; npm's
+short license metadata is not a replacement for that file.
+
+## Dawn and Tint (webgpu 0.6.1)
+
+Copyright 2017-2025 The Dawn & Tint Authors
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+## Candidate native/WASM dependency inventory
+
+Inspected October 6, 2026. Runtime bundles keep npm dependencies external;
+installation retains their own package files and notices. This table identifies
+the native/WASM packages used by this candidate, not a replacement license for
+their transitive components. Optional Strands/provider dependencies are separate
+and are not required for CLI/MCP authoring.
+
+| Package inspected | Package license metadata | Distributed notice / provenance |
+| --- | --- | --- |
+| `webgpu@0.6.2` | MIT metadata; distributed Dawn/Tint notice is BSD-3-Clause | `webgpu/LICENSE.md`, reproduced above; native Dawn/Tint supplied by the package |
+| `@napi-rs/canvas@1.0.10` | MIT | `@napi-rs/canvas/LICENSE`; platform package contains the Skia-based native binding |
+| `sharp@0.35.5` | Apache-2.0 | `sharp/LICENSE` |
+| `@img/sharp-win32-x64@0.35.5` | Apache-2.0 AND LGPL-3.0-or-later | package `LICENSE` and `versions.json`; the inspected binary includes libvips 8.18.7 and additional native libraries |
+| `manifold-3d@3.5.4` | Apache-2.0 | `manifold-3d/LICENSE`, JavaScript and WASM distribution |
+| `xatlasjs@0.2.0` | MIT | `xatlasjs/LICENSE`, copyright Jonathan Young; JavaScript and WASM distribution |
+
+Sharp selects platform-specific binaries during installation; consult the
+[upstream installation documentation](https://sharp.pixelplumbing.com/install/)
+and the exact installed platform package. A Windows receipt does not inventory
+another platform's native artifacts. If distributing a self-contained archive
+with dependencies, retain their license files and complete that archive's native
+notice/source inventory before publication. Kiln's npm tarball does not embed
+these native binaries. Full standalone-binary redistribution is not qualified by
+this inventory.