@instruktlabs/kiln 1.0.0 → 1.2.0

package/dist/mcp-server.mjs

@@ -2085,7 +2085,7 @@ import { readFile } from "node:fs/promises";
 var KILN_ASSET_WIDGET_URI = "ui://kiln/asset-v5.html";
 
 // src/engine-identity.ts
-var ENGINE_VERSION = "1.0.0";
+var ENGINE_VERSION = "1.2.0";
 var ENGINE_INSTALL_URL = new URL("../", import.meta.url).href;
 
 // src/requirements-json.ts

package/docs/architecture.md

@@ -4,11 +4,11 @@ Kiln builds JavaScript programs into GLB assets, validates structure, and render
 
 ## Entry points
 
-The v1 checkout prepares `@instruktlabs/kiln` with compiled ESM and TypeScript
+The npm package `@instruktlabs/kiln` ships compiled ESM and TypeScript
 declarations. Node consumers need no source loader. Build the SDK on a fresh source
 checkout before using package imports; the installed archive already contains it.
 See the [SDK contract](sdk.md) for runtime and experimental-feature boundaries.
-There is no published npm release yet.
+See [installation](install.md) for package, source-checkout and plugin setup.
 
 | Subpath | Purpose |
 |---|---|
@@ -66,12 +66,15 @@ CPU render paths are deterministic for the same inputs. GPU images can vary by d
 ## Development
 
 ```bash
+node scripts/example-archive.mjs --fetch
 bun run typecheck
 bun run lint
 bun run test
 bun run test:coverage
 ```
 
-Offline tests pin CPU rendering and exercise the checked-in example programs. The coverage ratchet lives in [scripts/check-coverage.mjs](https://github.com/instruktlabs/kiln/blob/main/scripts/check-coverage.mjs). Threshold decreases require an explicit measured rationale. Live provider tests require an explicit opt-in.
+Prepare the pinned historical corpus once with the explicit fetch command above.
+Subsequent tests stay offline, pin CPU rendering and include those archived programs.
+The coverage ratchet lives in [scripts/check-coverage.mjs](https://github.com/instruktlabs/kiln/blob/main/scripts/check-coverage.mjs). Threshold decreases require an explicit measured rationale. Live provider tests require an explicit opt-in.
 
 Core dependencies include Three.js, glTF Transform, Manifold, Acorn, and Zod. The agent SDK is an optional peer. Keep provider adapters compatible with the SDK's declared interface version; a TypeScript cast cannot fix a runtime protocol mismatch.

package/docs/chatgpt.md

@@ -2,17 +2,27 @@
 
 Kiln's local CLI and stdio MCP server share the same collection store and tool registry. ChatGPT web needs a reachable MCP connection: a private Secure MCP Tunnel can carry this existing stdio server without making a public endpoint. The tunnel process must remain running while ChatGPT discovers or calls tools.
 
+This is an owner-managed development connection. Kiln's public hosted service and
+directory listing are deferred. Local CLI/MCP use needs no Kiln account; the
+optional OpenAI tunnel separately requires Platform access and a runtime API key.
+
 ## Connect a private development server
 
-1. Build with the supported toolchain: `bun run build:runtime`.
-2. Create a tunnel in OpenAI Platform, scoped to the intended ChatGPT workspace. The account needs Tunnels Read and Manage; its runtime API key needs Read and Use. Existing organization roles may already grant these. Do not broaden other permissions.
-3. Download a pinned official `openai/tunnel-client` release and verify its release digest. This dogfood used Windows amd64 v0.0.14. Keep credentials in the environment or a supported secret reference, never in the plugin.
+1. [Install Kiln](install.md) and create a dedicated asset workspace. The npm package already contains the built server; an engine checkout needs `bun run build:runtime` first.
+2. Create a tunnel in OpenAI Platform and associate it with the intended ChatGPT workspace and Platform organization. Creating it requires Tunnels Read and Manage; running or selecting it requires Read and Use. ChatGPT workspace policy also applies.
+3. Obtain the client through the [official tunnel setup guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels#set-up-tunnel-client). Record the version you test. Keep credentials outside the plugin and source repository.
 4. Configure the tunnel's stdio command to launch `node /absolute/path/dist/mcp-server.mjs` in a dedicated asset workspace. Set `KILN_PROGRAM_STORE` and `KILN_COLLECTIONS` explicitly. The server does not need provider keys. The tunnel control process needs its OpenAI key, which should not be inherited by the MCP child.
-5. Run `tunnel-client doctor`, then `tunnel-client run` with the configured profile. In ChatGPT's Plugins page choose Create app, Tunnel, the intended tunnel, and No Auth for the stdio server. Access is still controlled by the private tunnel; this does not create a public unauthenticated service.
+5. Run `tunnel-client doctor --profile NAME --explain`, then `tunnel-client run --profile NAME`. In ChatGPT Plugins, use the plus button, Add custom MCP server, then Tunnel. Select your tunnel, configure authentication, review the warning and create the plugin. Kiln's local stdio server has no separate OAuth; access is controlled by the private tunnel.
 6. Verify the seventeen-tool MCP surface appears, including `kiln_discover`, `kiln_renderer`, `kiln_present` and `kiln_project`. Test source submission, actual render-image visibility, save/list, copy, restore/edit, and exact revision export. Refresh connector metadata after changing tools.
 
 Local subprocess evaluation has deadlines and a sanitized environment; it is not the Linux isolated evaluator's OS security boundary. This setup is for an owner-controlled development test. A hosted multi-user deployment needs tenant-scoped storage, authentication, and the isolated evaluator posture.
 
+A private tunnel is not eligible as a public plugin endpoint. OpenAI's
+[connection guide](https://developers.openai.com/plugins/deploy/connect-chatgpt)
+requires a public HTTPS endpoint for submission. The steps above were checked
+against official documentation on 7 October 2026; that is a documentation check,
+not a new end-to-end ChatGPT qualification.
+
 ## Expose the skills
 
 Keep `skills/*/SKILL.md` and their adjacent `references/` directories as the maintained source. Skill descriptions provide discovery; instructions load on selection, and reference files provide modeling detail when needed. Avoid pasting the complete modeling catalog into every tool description or prompt.
@@ -45,4 +55,9 @@ The local viewer (`kiln view`) provides browser downloads, revision selection, c
 
 The Node and Bun JavaScript runtimes can produce tiny floating-point differences in regenerated GLB JSON. Preserve the original artifact for byte-exact delivery and rebuild with the recorded engine's supported Node toolchain for reproducibility. ZIP import/export preserves original bytes regardless of runtime.
 
-Official references checked September 6, 2026: [Connect ChatGPT](https://developers.openai.com/plugins/deploy/connect-chatgpt), [Secure MCP Tunnels](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels), and [Package plugins](https://developers.openai.com/plugins/build/plugins). Surface availability can change; verify the actual host before claiming installation or download support.
+The uploader and download observations above are historical tests from September 6,
+2026, not claims about every current account. Check the actual client's installation,
+image display and file download behavior before advertising support. See
+[Connect ChatGPT](https://developers.openai.com/plugins/deploy/connect-chatgpt),
+[Secure MCP Tunnels](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
+and [Package plugins](https://developers.openai.com/plugins/build/plugins).

package/docs/examples.md

@@ -1,171 +1,41 @@
-# Example collection
-
-[How credits and build records work](https://github.com/instruktlabs/kiln/blob/main/docs/example-provenance.md).
-
-The public gallery contains 62 selected examples. Archived studies remain in the
-repository but are not presented in this gallery.
-
-These are historical showcases generated with earlier Kiln versions. They have
-not been fully vetted and may contain intersections, disconnected parts or other
-modeling errors. They are not golden outputs or reference solutions. Replaying
-one can reveal a change in engine behavior; a passing replay does not establish
-asset quality. Gallery repair, regeneration and replacement are separate
-from engine releases.
-
-Listed triangle counts describe those historical builds. They are not fixed
-targets for the upgraded engine's tessellation or geometry cleanup.
-
-Browse the [interactive gallery](https://kilnstudio.tools/#/gallery), or open a program and its render below. Credits distinguish historical source headers from recorded current runs. These examples span different briefs and authoring runs; they are not a model ranking.
-
-<table>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/mechanical-peacock.png"><img src="https://assets.kilnstudio.tools/renders/mechanical-peacock.png" alt="Brass mechanical peacock with an articulated jewel-colored fan"></a><br><b><a href="../examples/mechanical-peacock.kiln.js">mechanical-peacock</a></b><br>44,896 tris &middot; Claude Opus 5<br><sub>Articulated enamel fan; neck connection repaired by a Codex maintainer agent</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/orbital-station.png"><img src="https://assets.kilnstudio.tools/renders/orbital-station.png" alt="a rotating-torus orbital station with lit window bands, four spokes, a docking hub and solar wings, generated by Kiln"></a><br><b><a href="../examples/orbital-station.kiln.js">orbital-station</a></b><br>15,040 tris &middot; GPT-6 Astra<br><sub>Habitat ring, solar arrays and docking modules</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/abyssal-surveyor.png"><img src="https://assets.kilnstudio.tools/renders/abyssal-surveyor.png" alt="Custom curved hull, guarded thrusters and articulated sampling arm"></a><br><b><a href="../examples/abyssal-surveyor.kiln.js">abyssal-surveyor</a></b><br>34,456 tris &middot; GPT-6 Astra<br><sub>Custom curved hull, guarded thrusters and articulated sampling arm</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/kestrel-rescue-craft.png"><img src="https://assets.kilnstudio.tools/renders/kestrel-rescue-craft.png" alt="Sculpted rescue aircraft with articulated tilt rotors"></a><br><b><a href="../examples/kestrel-rescue-craft.kiln.js">kestrel-rescue-craft</a></b><br>54,272 tris &middot; GPT-6 Astra<br><sub>Sculpted rescue aircraft with articulated tilt rotors</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/solar-sail-courier.png"><img src="https://assets.kilnstudio.tools/renders/solar-sail-courier.png" alt="Faceted gold sails on four trussed spars"></a><br><b><a href="../examples/solar-sail-courier.kiln.js">solar-sail-courier</a></b><br>27,756 tris &middot; Gemini 3.8 Flash<br><sub>Faceted gold sails on four trussed spars</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/orrery.png"><img src="https://assets.kilnstudio.tools/renders/orrery.png" alt="a brass orrery with an emissive sun and planets on arms, generated by Kiln"></a><br><b><a href="../examples/orrery.kiln.js">orrery</a></b><br>15,720 tris &middot; Gemini 3.8 Flash<br><sub>Geared arms and orbiting planetary spheres</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/typewriter.png"><img src="https://assets.kilnstudio.tools/renders/typewriter.png" alt="a cast-iron typewriter with a fan of type bars, brass trim and a sheet in the platen, generated by Kiln"></a><br><b><a href="../examples/typewriter.kiln.js">typewriter</a></b><br>14,128 tris &middot; Muse Spark 1.3<br><sub>Rows of keys and typebars arranged on an arc</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/twisting-canopy.png"><img src="https://assets.kilnstudio.tools/renders/twisting-canopy.png" alt="Twisting canopy with curved ribs and offset supports"></a><br><b><a href="../examples/twisting-canopy.kiln.js">twisting-canopy</a></b><br>5,304 tris &middot; Gemini 3.8 Flash<br><sub>Twisting roof surface with curved ribs and offset supports</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/bench-refractor.png"><img src="https://assets.kilnstudio.tools/renders/bench-refractor.png" alt="Lofted pedestal, recessed optical opening and focusing slide"></a><br><b><a href="../examples/bench-refractor.kiln.js">bench-refractor</a></b><br>7,476 tris &middot; Muse Spark 1.3<br><sub>Lofted pedestal, recessed optical opening and focusing slide</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/research-vessel.png"><img src="https://assets.kilnstudio.tools/renders/research-vessel.png" alt="Workboat hull with an offset crane and sliding service platform"></a><br><b><a href="../examples/research-vessel.kiln.js">research-vessel</a></b><br>24,306 tris &middot; GPT-6 Astra<br><sub>Workboat hull with an offset crane and sliding service platform</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/field-gun.png"><img src="https://assets.kilnstudio.tools/renders/field-gun.png" alt="a Napoleonic field gun on a wooden carriage, generated by Kiln"></a><br><b><a href="../examples/field-gun.kiln.js">field-gun</a></b><br>15,544 tris &middot; Claude Opus 5<br><sub>Cut breech geometry and repeated wheel spokes</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/cathedral.png"><img src="https://assets.kilnstudio.tools/renders/cathedral.png" alt="a Gothic cathedral with flying buttresses and lit stained glass, generated by Kiln"></a><br><b><a href="../examples/cathedral.kiln.js">cathedral</a></b><br>19,888 tris &middot; Claude Opus 5<br><sub>Repeated stone bays and recessed window openings</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/mech.png"><img src="https://assets.kilnstudio.tools/renders/mech.png" alt="a walking mech with plated limbs, generated by Kiln"></a><br><b><a href="../examples/mech.kiln.js">mech</a></b><br>18,398 tris &middot; Claude Opus 5<br><sub>Articulated limbs with fitted armour panels</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/diving-helmet.png"><img src="https://assets.kilnstudio.tools/renders/diving-helmet.png" alt="a brass standard diving helmet, generated by Kiln"></a><br><b><a href="../examples/diving-helmet.kiln.js">diving-helmet</a></b><br>16,420 tris &middot; Claude Opus 5<br><sub>Brass housing, glass ports and copper fittings</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/cafe-racer.png"><img src="https://assets.kilnstudio.tools/renders/cafe-racer.png" alt="a cafe racer motorcycle, generated by Kiln"></a><br><b><a href="../examples/cafe-racer.kiln.js">cafe-racer</a></b><br>16,966 tris &middot; Claude Opus 5<br><sub>Curved frame tubes and a tapered fuel tank</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/penny-farthing.png"><img src="https://assets.kilnstudio.tools/renders/penny-farthing.png" alt="a penny-farthing bicycle, generated by Kiln"></a><br><b><a href="../examples/penny-farthing.kiln.js">penny-farthing</a></b><br>12,450 tris &middot; Claude Opus 5<br><sub>Curved frame and radial wire spokes</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/sushi-store.png"><img src="https://assets.kilnstudio.tools/renders/sushi-store.png" alt="a two-storey Japanese sushi shopfront with a tiled roof, generated by Kiln"></a><br><b><a href="../examples/sushi-store.kiln.js">sushi-store</a></b><br>24,082 tris &middot; Claude Opus 5<br><sub>Layered shopfront, awning and recessed display</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/street-lamp.png"><img src="https://assets.kilnstudio.tools/renders/street-lamp.png" alt="a cast-iron gas street lamp, generated by Kiln"></a><br><b><a href="../examples/street-lamp.kiln.js">street-lamp</a></b><br>13,036 tris &middot; Claude Opus 5<br><sub>Revolved metal profiles and glass lanterns</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/arcade-cabinet.png"><img src="https://assets.kilnstudio.tools/renders/arcade-cabinet.png" alt="an upright arcade cabinet, generated by Kiln"></a><br><b><a href="../examples/arcade-cabinet.kiln.js">arcade-cabinet</a></b><br>19,916 tris &middot; Gemini 3.8 Flash<br><sub>Swept cabinet profile with recessed controls</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/robot-arm.png"><img src="https://assets.kilnstudio.tools/renders/robot-arm.png" alt="a six-axis industrial robot arm with a parallel gripper, generated by Kiln"></a><br><b><a href="../examples/robot-arm.kiln.js">robot-arm</a></b><br>15,324 tris &middot; Claude Opus 5<br><sub>Animated chain of articulated joints</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/carousel.png"><img src="https://assets.kilnstudio.tools/renders/carousel.png" alt="a fairground carousel with a striped canopy and horses, generated by Kiln"></a><br><b><a href="../examples/carousel.kiln.js">carousel</a></b><br>16,356 tris &middot; Gemini 3.8 Flash<br><sub>Rotating platform with repeated horses and supports</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/ferris-wheel.png"><img src="https://assets.kilnstudio.tools/renders/ferris-wheel.png" alt="a ferris wheel with lit gondolas on a braced frame, generated by Kiln"></a><br><b><a href="../examples/ferris-wheel.kiln.js">ferris-wheel</a></b><br>10,452 tris &middot; Gemini 3.8 Flash<br><sub>Radial steel lattice and suspended cabins</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/longcase-clock.png"><img src="https://assets.kilnstudio.tools/renders/longcase-clock.png" alt="a mahogany longcase clock with a painted dial, generated by Kiln"></a><br><b><a href="../examples/longcase-clock.kiln.js">longcase-clock</a></b><br>12,600 tris &middot; Gemini 3.8 Flash<br><sub>Panelled wooden case and an exposed clock face</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/radio-telescope.png"><img src="https://assets.kilnstudio.tools/renders/radio-telescope.png" alt="a steerable parabolic radio telescope on a pedestal, generated by Kiln"></a><br><b><a href="../examples/radio-telescope.kiln.js">radio-telescope</a></b><br>16,532 tris &middot; Gemini 3.8 Flash<br><sub>Tracking dish with a supporting truss</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/anglerfish.png"><img src="https://assets.kilnstudio.tools/renders/anglerfish.png" alt="a deep-sea anglerfish with warty skin, a gaping jaw of needle teeth and a glowing lure on an arched illicium, generated by Kiln"></a><br><b><a href="../examples/anglerfish.kiln.js">anglerfish</a></b><br>19,108 tris &middot; Claude Opus 5<br><sub>Curved body, tapered fins and an illuminated lure</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/hot-air-balloon.png"><img src="https://assets.kilnstudio.tools/renders/hot-air-balloon.png" alt="a hot-air balloon with a striped envelope and a wicker basket, generated by Kiln"></a><br><b><a href="../examples/hot-air-balloon.kiln.js">hot-air-balloon</a></b><br>9,816 tris &middot; Gemini 3.8 Flash<br><sub>Twenty-four envelope gores above a suspended basket</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/vending-machine.png"><img src="https://assets.kilnstudio.tools/renders/vending-machine.png" alt="a lit drinks vending machine behind glass, generated by Kiln"></a><br><b><a href="../examples/vending-machine.kiln.js">vending-machine</a></b><br>12,468 tris &middot; Claude Opus 5<br><sub>Recessed product rows and illuminated controls</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/gramophone.png"><img src="https://assets.kilnstudio.tools/renders/gramophone.png" alt="an acoustic gramophone with a faceted brass horn on a hinged mahogany case, generated by Kiln"></a><br><b><a href="../examples/gramophone.kiln.js">gramophone</a></b><br>10,724 tris &middot; Gemini 3.8 Flash<br><sub>Brass horn, wooden cabinet and hinged lid</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/lighthouse.png"><img src="https://assets.kilnstudio.tools/renders/lighthouse.png" alt="a stone lighthouse with a copper-domed lantern, a gallery rail and a keeper&#39;s cottage on a rocky islet, generated by Kiln"></a><br><b><a href="../examples/lighthouse.kiln.js">lighthouse</a></b><br>16,492 tris &middot; Muse Spark 1.3<br><sub>Tower, keeper’s buildings and a rocky base</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/steam-locomotive.png"><img src="https://assets.kilnstudio.tools/renders/steam-locomotive.png" alt="a green 4-4-0 steam locomotive with a cowcatcher, brass domes and side rods, generated by Kiln"></a><br><b><a href="../examples/steam-locomotive.kiln.js">steam-locomotive</a></b><br>19,256 tris &middot; Muse Spark 1.3<br><sub>Coupled driving wheels and connecting rods</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/windmill.png"><img src="https://assets.kilnstudio.tools/renders/windmill.png" alt="a Dutch tower windmill in brick with a shingled cap, a stage gallery and four lattice sails, generated by Kiln"></a><br><b><a href="../examples/windmill.kiln.js">windmill</a></b><br>9,872 tris &middot; DeepSeek V4 Flash<br><sub>Masonry tower with a rotating sail assembly</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/aircraft-carrier.png"><img src="https://assets.kilnstudio.tools/renders/aircraft-carrier.png" alt="an aircraft carrier with an angled flight deck, deck markings and an island superstructure, generated by Kiln"></a><br><b><a href="../examples/aircraft-carrier.kiln.js">aircraft-carrier</a></b><br>17,904 tris &middot; Claude Opus 5<br><sub>Flight deck, island and aircraft at ship scale</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/air-defense-radar.png"><img src="https://assets.kilnstudio.tools/renders/air-defense-radar.png" alt="a truck-mounted air-defence phased-array radar with the panel raised, generated by Kiln"></a><br><b><a href="../examples/air-defense-radar.kiln.js">air-defense-radar</a></b><br>16,094 tris &middot; Claude Opus 5<br><sub>Modelled antenna grid on a mobile platform</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/fighter-jet.png"><img src="https://assets.kilnstudio.tools/renders/fighter-jet.png" alt="a single-seat multirole fighter on its landing gear with canted tails and open nozzles, generated by Kiln"></a><br><b><a href="../examples/fighter-jet.kiln.js">fighter-jet</a></b><br>18,172 tris &middot; Claude Opus 5<br><sub>Lofted fuselage and tapered wing sections</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/comms-satellite.png"><img src="https://assets.kilnstudio.tools/renders/comms-satellite.png" alt="a geostationary communications satellite with gold thermal blankets, two solar wings and three dish antennas, generated by Kiln"></a><br><b><a href="../examples/comms-satellite.kiln.js">comms-satellite</a></b><br>18,824 tris &middot; Claude Opus 5<br><sub>Solar arrays extending from a compact satellite bus</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/gothic-gatehouse.png"><img src="https://assets.kilnstudio.tools/renders/gothic-gatehouse.png" alt="a Gothic castle gatehouse with two drum towers, machicolations and a lowered drawbridge, generated by Kiln"></a><br><b><a href="../examples/gothic-gatehouse.kiln.js">gothic-gatehouse</a></b><br>10,428 tris &middot; Gemini 3.8 Flash<br><sub>Twin towers, arched passage and approach bridge</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/cable-stayed-bridge.png"><img src="https://assets.kilnstudio.tools/renders/cable-stayed-bridge.png" alt="a cable-stayed road bridge with a portal pylon and fanned stay cables, generated by Kiln"></a><br><b><a href="../examples/cable-stayed-bridge.kiln.js">cable-stayed-bridge</a></b><br>7,580 tris &middot; Omen Alpha<br><sub>Deck segments, pylons and individual stay cables</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/tram.png"><img src="https://assets.kilnstudio.tools/renders/tram.png" alt="a 1920s city tram on rails with a trolley pole reaching up to the overhead wire, generated by Kiln"></a><br><b><a href="../examples/tram.kiln.js">tram</a></b><br>12,540 tris &middot; Gemini 3.8 Flash<br><sub>Windowed passenger body with roof-mounted fittings</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/tugboat.png"><img src="https://assets.kilnstudio.tools/renders/tugboat.png" alt="a harbour tugboat with a rope fender belt, an orange funnel and a raised wheelhouse, generated by Kiln"></a><br><b><a href="../examples/tugboat.kiln.js">tugboat</a></b><br>9,856 tris &middot; Gemini 3.8 Flash<br><sub>Lofted hull, deck equipment and raised wheelhouse</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/deep-sea-diver.png"><img src="https://assets.kilnstudio.tools/renders/deep-sea-diver.png" alt="an atmospheric diving suit with a copper helmet, jointed limbs and weighted boots, generated by Kiln"></a><br><b><a href="../examples/deep-sea-diver.kiln.js">deep-sea-diver</a></b><br>10,876 tris &middot; Gemini 3.8 Flash<br><sub>Jointed pressure suit with a rigid helmet</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/pumpjack.png"><img src="https://assets.kilnstudio.tools/renders/pumpjack.png" alt="an oilfield pumpjack with a walking beam, horsehead and counterweights on a skid, generated by Kiln"></a><br><b><a href="../examples/pumpjack.kiln.js">pumpjack</a></b><br>10,236 tris &middot; Gemini 3.8 Flash<br><sub>Walking beam and crank-driven linkage</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/drilling-rig.png"><img src="https://assets.kilnstudio.tools/renders/drilling-rig.png" alt="a land drilling rig with a derrick over its substructure, mud tanks and a pipe rack, generated by Kiln"></a><br><b><a href="../examples/drilling-rig.kiln.js">drilling-rig</a></b><br>11,048 tris &middot; Gemini 3.8 Flash<br><sub>Derrick, pipework and raised operating platforms</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/harbour-crane.png"><img src="https://assets.kilnstudio.tools/renders/harbour-crane.png" alt="a rail-mounted harbour crane with a luffing jib and a spreader on the hoist, generated by Kiln"></a><br><b><a href="../examples/harbour-crane.kiln.js">harbour-crane</a></b><br>10,568 tris &middot; Gemini 3.8 Flash<br><sub>Braced steel frame with suspended lifting gear</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/crawler-crane.png"><img src="https://assets.kilnstudio.tools/renders/crawler-crane.png" alt="a lattice-boom crawler crane on tracks with the hook block hanging, generated by Kiln"></a><br><b><a href="../examples/crawler-crane.kiln.js">crawler-crane</a></b><br>12,660 tris &middot; MiniMax M3<br><sub>Repeated lattice boom sections on a tracked base</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/excavator.png"><img src="https://assets.kilnstudio.tools/renders/excavator.png" alt="a tracked hydraulic excavator with the boom, stick and bucket curled in, generated by Kiln"></a><br><b><a href="../examples/excavator.kiln.js">excavator</a></b><br>12,400 tris &middot; Omen Alpha<br><sub>Articulated boom, bucket and hydraulic rams</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/printing-press.png"><img src="https://assets.kilnstudio.tools/renders/printing-press.png" alt="a wooden hand printing press with a screw platen, type cases and ink balls, generated by Kiln"></a><br><b><a href="../examples/printing-press.kiln.js">printing-press</a></b><br>10,188 tris &middot; Gemini 3.8 Flash<br><sub>Rollers, drive wheels and an exposed feed mechanism</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/pipe-organ.png"><img src="https://assets.kilnstudio.tools/renders/pipe-organ.png" alt="a church pipe organ with ranks of display pipes above a console and pedalboard, generated by Kiln"></a><br><b><a href="../examples/pipe-organ.kiln.js">pipe-organ</a></b><br>10,340 tris &middot; Gemini 3.8 Flash<br><sub>Pipe ranks, wooden casework and keyboard console</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/planetarium-projector.png"><img src="https://assets.kilnstudio.tools/renders/planetarium-projector.png" alt="a dumbbell planetarium projector with two star globes on a trunnion mount, generated by Kiln"></a><br><b><a href="../examples/planetarium-projector.kiln.js">planetarium-projector</a></b><br>10,932 tris &middot; Gemini 3.8 Flash<br><sub>Dark optical housings on a central support</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/astronomical-clock.png"><img src="https://assets.kilnstudio.tools/renders/astronomical-clock.png" alt="an astronomical clock with a gilt astrolabe dial in a carved stone case, generated by Kiln"></a><br><b><a href="../examples/astronomical-clock.kiln.js">astronomical-clock</a></b><br>9,324 tris &middot; Gemini 3.8 Flash<br><sub>Layered astronomical dial and exposed mechanisms</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/espresso-machine.png"><img src="https://assets.kilnstudio.tools/renders/espresso-machine.png" alt="a three-group commercial espresso machine with portafilters, steam wands and cups warming on top, generated by Kiln"></a><br><b><a href="../examples/espresso-machine.kiln.js">espresso-machine</a></b><br>19,080 tris &middot; GLM 5.3 Flash<br><sub>Polished metal housing, fittings and group heads</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/pinball-machine.png"><img src="https://assets.kilnstudio.tools/renders/pinball-machine.png" alt="a pinball machine with a lit backbox, a glassed playfield and a rear cabinet bay, generated by Kiln"></a><br><b><a href="../examples/pinball-machine.kiln.js">pinball-machine</a></b><br>8,700 tris &middot; GLM 5.3 Flash<br><sub>Sloped playfield cabinet and raised backbox</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/trebuchet.png"><img src="https://assets.kilnstudio.tools/renders/trebuchet.png" alt="a counterweight trebuchet with a slung beam, a ballast box and the sling laid out on the ground, generated by Kiln"></a><br><b><a href="../examples/trebuchet.kiln.js">trebuchet</a></b><br>2,652 tris &middot; Gemini 3.8 Flash<br><sub>Timber frame, counterweight and throwing arm</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/rigid-airship.png"><img src="https://assets.kilnstudio.tools/renders/rigid-airship.png" alt="a 1930s rigid passenger airship moored at its mast, with a promenade window row, engine cars and a cruciform tail, generated by Kiln"></a><br><b><a href="../examples/rigid-airship.kiln.js">rigid-airship</a></b><br>11,764 tris &middot; GPT-6 Astra<br><sub>Lofted envelope with gondola and tail surfaces</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/blast-furnace.png"><img src="https://assets.kilnstudio.tools/renders/blast-furnace.png" alt="a blast furnace with three hot-blast stoves, downcomer piping, galleries and a cast house, generated by Kiln"></a><br><b><a href="../examples/blast-furnace.kiln.js">blast-furnace</a></b><br>11,964 tris &middot; GPT-6 Astra<br><sub>Furnace stack, hot-blast stoves and connecting pipework</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/clock-tower.png"><img src="https://assets.kilnstudio.tools/renders/clock-tower.png" alt="a Gothic clock tower with gilt dials, a louvred belfry, crocketed pinnacles and a leaded spire, generated by Kiln"></a><br><b><a href="../examples/clock-tower.kiln.js">clock-tower</a></b><br>11,664 tris &middot; GPT-6 Astra<br><sub>Four clock faces within a detailed tower housing</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/nautilus-habitat.png"><img src="https://assets.kilnstudio.tools/renders/nautilus-habitat.png" alt="Spiral shell roof around an open two-level habitat"></a><br><b><a href="../examples/nautilus-habitat.kiln.js">nautilus-habitat</a></b><br>41,380 tris &middot; GPT-6 Astra<br><sub>Spiral shell roof around an open two-level habitat</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/ribbon-tea-pavilion.png"><img src="https://assets.kilnstudio.tools/renders/ribbon-tea-pavilion.png" alt="Curved timber roof over an open tea pavilion"></a><br><b><a href="../examples/ribbon-tea-pavilion.kiln.js">ribbon-tea-pavilion</a></b><br>19,384 tris &middot; Gemini 3.8 Flash<br><sub>Curved timber roof over an open tea pavilion</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/seed-vault.png"><img src="https://assets.kilnstudio.tools/renders/seed-vault.png" alt="Open seed-pod shell around a specimen carousel"></a><br><b><a href="../examples/seed-vault.kiln.js">seed-vault</a></b><br>33,632 tris &middot; Gemini 3.8 Flash<br><sub>Open seed-pod shell around a specimen carousel</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/kinetic-wave.png"><img src="https://assets.kilnstudio.tools/renders/kinetic-wave.png" alt="Articulated teal and bronze fins on a dark plinth"></a><br><b><a href="../examples/kinetic-wave.kiln.js">kinetic-wave</a></b><br>18,960 tris &middot; Gemini 3.8 Flash<br><sub>Articulated teal and bronze fins on a dark plinth</sub></td>
-</tr>
-<tr>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/alpine-cable-terminal.png"><img src="https://assets.kilnstudio.tools/renders/alpine-cable-terminal.png" alt="Timber station with an exposed pulley and suspended cabin"></a><br><b><a href="../examples/alpine-cable-terminal.kiln.js">alpine-cable-terminal</a></b><br>10,000 tris &middot; Gemini 3.8 Flash<br><sub>Timber station with an exposed pulley and suspended cabin</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/deco-radio.png"><img src="https://assets.kilnstudio.tools/renders/deco-radio.png" alt="Stepped walnut cabinet with a brass grille and tuning controls"></a><br><b><a href="../examples/deco-radio.kiln.js">deco-radio</a></b><br>13,216 tris &middot; Gemini 3.8 Flash<br><sub>Stepped walnut cabinet with a brass grille and tuning controls</sub></td>
-  <td width="33%" valign="top"><a href="https://assets.kilnstudio.tools/renders/polar-rover.png"><img src="https://assets.kilnstudio.tools/renders/polar-rover.png" alt="Tracked expedition rover with folding solar panels and instruments"></a><br><b><a href="../examples/polar-rover.kiln.js">polar-rover</a></b><br>22,478 tris &middot; Gemini 3.8 Flash<br><sub>Tracked expedition rover with folding solar panels and instruments</sub></td>
-</tr>
-</table>
-
-Still images are rendered from the source by `bun scripts/hero-shots.ts`. The [interactive gallery](https://matthew-kissinger.github.io/kiln/#/gallery) builds GLBs from the same programs and provides orbit, wireframe, and source views.
-
-The collection includes historical studies and current authoring runs. Each example retains its recorded model credit and any known refinement history; missing isolation evidence is marked as unrecorded. These examples are not a comparative model benchmark.
-
-These are examples, not a controlled model ranking. The [dogfooding notes](https://github.com/instruktlabs/kiln/blob/main/docs/dogfooding.md) distinguish new-asset generation from targeted editing and explain the context supplied for the latest runs.
-
-## Animation
-
-`animate()` is part of the same program. It returns named clips built from rotation and position
-tracks against the parts the program already created, so a joint that moves is the joint that was
-modelled -- there is no separate rig to keep in sync, and a diff of the motion is a diff of the same
-file. The model reviews a clip the way it reviews a still: `kiln_screenshot_animation` poses the
-scene across the clip and hands back the frames, which is how a walk that slides, a knee that bends
-backwards, or an arm that swings through its own base gets caught before the GLB is written.
-
-<table>
-<tr>
-  <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/robot-arm.gif" alt="an industrial robot arm running a pick-and-place cycle"><br><b><a href="../examples/robot-arm.kiln.js">robot-arm</a></b><br><sub>a six-axis pick-and-place cycle</sub></td>
-  <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/carousel.gif" alt="a fairground carousel turning, with horses rising and falling"><br><b><a href="../examples/carousel.kiln.js">carousel</a></b><br><sub>a turn, with the horses on their own phase</sub></td>
-</tr>
-<tr>
-  <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/orrery.gif" alt="an orrery with planets orbiting a lit sun"><br><b><a href="../examples/orrery.kiln.js">orrery</a></b><br><sub>planets on nested arms off one drive</sub></td>
-  <td width="50%" valign="top"><img src="https://assets.kilnstudio.tools/renders/radio-telescope.gif" alt="a radio telescope dish slewing in azimuth and elevation"><br><b><a href="../examples/radio-telescope.kiln.js">radio-telescope</a></b><br><sub>a slew in azimuth and elevation</sub></td>
-</tr>
-</table>
-
-These are rendered by `bun scripts/anim-gifs.ts` from the checked-in programs, through the same PBR
-port as the stills. One detail in that script is worth borrowing if you build something similar: the
-port fits its camera to whatever bounding box it is handed, so a sequence whose posed extent changes
--- the arm above varies by 63% between folded and reaching -- will appear to breathe as the camera
-refits every frame. Because the projection is orthographic and the fit is exact, each frame can be
-put back onto one shared camera by a scale and a translation that are both computable, which is a
-correction rather than an approximation.
-
-![Six-view contact sheet of a procedurally generated field gun](https://github.com/instruktlabs/kiln/blob/main/examples/hero-sheet.png)
-
-*The contact sheet the model looks at. `../examples/field-gun.kiln.js`, 15,544 triangles: a revolved
-bronze barrel bored with a boolean, a stepped oak carriage carrying strapwork and bolt heads, and
-twelve-spoke wheels with iron tyres.*
-
-```bash
-bun run kiln render ../examples/field-gun.kiln.js --views sheet.png
+# Asset examples
+
+For recent work, browse the [gallery](https://kilnstudio.tools/gallery/) and
+[interactive scenes](https://kilnstudio.tools/scenes/). Download Runtime assets for
+an application or Editable assets to retain the authored sources and revisions.
+
+| Collection | Sources and examples |
+| --- | --- |
+| Troy | [Horse, ships, characters, buildings and props](https://github.com/instruktlabs/kiln/tree/main/packs/troy) |
+| Farm | [Buildings, animals, crops and equipment](https://github.com/instruktlabs/kiln/tree/main/packs/farm) |
+| Vehicles | [Six road vehicles and saved revisions](https://github.com/instruktlabs/kiln/tree/main/packs/vehicles) |
+| Golden Gate Bridge | [Standalone bridge sources](https://github.com/instruktlabs/kiln/tree/main/packs/golden-gate-bridge) |
+| Foundry Floor | [Factory asset sources](https://github.com/instruktlabs/kiln/tree/main/packs/foundry-floor) |
+
+Follow the [asset source guide](https://github.com/instruktlabs/kiln/blob/main/packs/README.md)
+to restore a collection into a separate workspace. Saved material dependencies
+and the recorded engine version matter when rebuilding an existing asset.
+Scene interaction code is separate from the models.
+
+For small examples of current APIs, use `kiln_discover` or `kiln discover`. Its
+helper examples and recipes come from the maintained engine catalog, not the
+repository's historical `examples/` folder. Neither that folder nor the asset
+packs are bundled into the npm package or automatically supplied to an agent.
+
+## Historical collection
+
+The old standalone examples are preserved in the [website archive](https://kilnstudio.tools/gallery/archive/)
+and [Git history](https://github.com/instruktlabs/kiln/tree/fda71ac775750f25390b6ee30082ebc56463edc6/examples).
+They are historical showcases, not recommended implementations or quality baselines.
+
+They are no longer part of the active source tree. Contributors building the
+archive gallery or running the full regression corpus can restore the exact
+programs, credits and image records into an ignored cache:
+
+```sh
+node scripts/example-archive.mjs --fetch
 ```
+
+Run this from an engine checkout. It does not add files to a user's asset workspace
+or change the npm installation. No teaching collection or asset-discovery index
+is added. Small engine-specific regression fixtures remain under tests.

package/docs/install.md

@@ -1,6 +1,6 @@
 # Install Kiln for your coding agent
 
-This guide covers **Kiln 1.0** under the package name `@instruktlabs/kiln`.
+This guide describes **Kiln 1.1** under the package name `@instruktlabs/kiln`.
 Use a version available in the [npm registry](https://www.npmjs.com/package/@instruktlabs/kiln),
 or build a [local package](#install-a-local-package) to test an unpublished checkout.
 [CHANGELOG.md](../CHANGELOG.md) lists changes; read the
@@ -12,45 +12,104 @@ same engine and saved-source contracts.
 
 ## Install the package
 
-Once stable 1.0 is published, install it with Node.js and npm:
+Install the current stable package with Node.js and npm:
 
 ```sh
 mkdir kiln-install
 cd kiln-install
 npm init -y
-npm install @instruktlabs/kiln@1.0.0 --omit=dev --include=optional
-npm exec --offline -- kiln-init ../my-assets --harness codex  # or claude, opencode, hermes, agy, copilot, cursor-agent
+npm install @instruktlabs/kiln
+npx --offline --no -- kiln-init ../my-assets --harness codex  # or claude, opencode, hermes, agy, copilot, cursor-agent
 cd ../my-assets
 # Follow START.md for your harness
 ```
 
-Until that exact version is available, use `@instruktlabs/kiln@next` or the public
-`@instruktlabs/kiln@1.0.0-rc.1` instead. The unqualified package name selects
-`latest`, which must no longer be the temporary `0.0.0-stage` holding version
-before using it. After stable publication, `npm install @instruktlabs/kiln` is the
-normal command; the explicit version above keeps this guide reproducible.
+This selects npm's stable `latest` tag. Existing-project adoption and the new SDK
+host interfaces require 1.1 or later. Check the installed version with
+`npm ls @instruktlabs/kiln`. When qualifying an unpublished candidate, use a
+[local package](#install-a-local-package). The `next` tag is only for prereleases.
+
+The package includes the built CLI/MCP runtimes, renderer code, plugins and skills.
+You do not need Bun, a source checkout, a build step or a separate model API key
+to use its tools. Choose the appropriate harness and follow `START.md` in the
+generated workspace.
+
+## Run the CLI
+
+The executable is named **`kiln`**, even though its npm package is `@instruktlabs/kiln`.
+For a terminal-wide command:
+
+```sh
+npm install -g @instruktlabs/kiln
+kiln discover --capabilities --json
+kiln render my-asset.kiln.js --out my-asset.glb --views sheet.png
+```
+
+npm puts global commands directly in its prefix on Windows and in `PREFIX/bin` on
+macOS/Linux. If the shell cannot find `kiln`, run `npm prefix -g`, ensure that
+executable directory is on PATH, and open a new terminal. See
+[npm's executable locations](https://docs.npmjs.com/cli/v12/configuring-npm/folders/#executables).
+`kiln-init` and `kiln-mcp` are available the same way.
+
+For a project-local installation, run from the project that contains the dependency:
+
+```sh
+npm install @instruktlabs/kiln
+npx --no -- kiln discover --capabilities --json
+# Equivalent:
+npm exec --offline -- kiln discover --capabilities --json
+```
+
+`npx --no --` refuses an automatic package download when the command is missing.
+Install the scoped package first; the unscoped package name `kiln` is a different
+package. npm scripts can call `kiln` directly because npm adds local executables to
+their PATH. See [npm exec](https://docs.npmjs.com/cli/v12/commands/npm-exec/).
+In PowerShell, use `npm.cmd exec --offline -- kiln …` for the equivalent command:
+PowerShell's npm script wrapper can consume the separator before forwarding flags.
+
+Generated asset workspaces also contain **`kiln.mjs`**. Run `node kiln.mjs …` there
+to use the exact installation, Node interpreter and source store selected for that
+workspace's MCP server. It also checks whether the managed setup needs an upgrade
+or repair. This is useful when multiple Kiln versions are installed: a global
+`kiln` command uses whichever installation your PATH selects. Without an explicit
+`KILN_WORKSPACE` or `KILN_PROGRAM_STORE`, the direct CLI stores work beneath the
+current directory's `.kiln/`; run it from the intended workspace root.
+
+## Add Kiln to an existing project
+
+With Kiln 1.1+, run these commands from the installation directory:
+
+```sh
+npx --offline --no -- kiln-init /absolute/path/to/my-project --adopt --harness codex --check
+npx --offline --no -- kiln-init /absolute/path/to/my-project --adopt --harness codex
+```
+
+The first command previews changes without writing and exits 1 when setup is
+needed. The second adds Kiln while preserving existing instructions, unrelated
+MCP settings and user files. Conflicting owned paths stop setup before it replaces
+them. Read `.kiln/START.md` and `.kiln/AGENTS.md` alongside your project's existing
+instructions. Repeat with another supported `--harness` to add its connection
+around the same source store and assets.
+
+Adoption also works for a new directory. To update an already managed workspace,
+use [check and upgrade](#move-or-repair-an-installation). Do not copy a new set of
+skills over local customizations by hand.
+
+## Install a release archive
 
 Archives are also supported. The package packs as `instruktlabs-kiln-VERSION.tgz`; earlier releases
 used `kiln-engine-VERSION.tgz`. Install the actual tarball with Node.js and
-npm. Use the tarball and checksum actually attached to the current
-[release](https://github.com/instruktlabs/kiln/releases) (for 0.10.0, the
-[v0.10.0 release](https://github.com/instruktlabs/kiln/releases/tag/v0.10.0)): download
-the tarball and `SHA256SUMS.txt`, check the tarball against the checksum file before
-installing (`sha256sum -c SHA256SUMS.txt` beside it, or `Get-FileHash` on Windows), and read
-that release's documentation; the release also attaches the installed-package receipts that
-name the tarball. A source-only release does not imply that a built tarball is available;
-a source-only release, like a checkout ahead of the release, builds its own package under
-[Install a local package](#install-a-local-package).
-The package includes the built CLI/MCP runtimes, renderer code, plugins and skills.
-You do not need Bun, a source checkout, a build step or a separate model API key to
-use the CLI/MCP tools. Use the real tarball path and filename:
+npm. Download the archive and `SHA256SUMS.txt` from the selected
+[release](https://github.com/instruktlabs/kiln/releases), then verify its checksum
+with `sha256sum -c SHA256SUMS.txt` or Windows `Get-FileHash`. Use that release's
+documentation and the actual downloaded filename:
 
 ```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
+npx --offline --no -- kiln-init ../my-assets --harness opencode  # or claude, codex, hermes, agy, copilot, cursor-agent
 cd ../my-assets
 # Follow START.md for your harness
 ```
@@ -247,7 +306,7 @@ npm exec --offline -- kiln-init ../my-assets --harness opencode  # or claude, co
 
 `kiln` renders programs and imports/exports source revisions. `kiln-init` creates a
 workspace, and `kiln-mcp` starts the stdio server. These are installed commands from
-the still-unpublished `@instruktlabs/kiln` package. Library consumers use its compiled
+that exact build of `@instruktlabs/kiln`. Library consumers use its compiled
 ESM and TypeScript declarations through the [SDK entrypoints](sdk.md), without a
 source loader. The optional
 `kiln generate` adapter is separate and needs its agent/provider dependencies;
@@ -281,11 +340,13 @@ other CLI/MCP workflows do not need any of these peers.
 | Codex | `.codex/config.toml`, read once `$CODEX_HOME/config.toml` marks the project trusted | `node codex.mjs` (applies the same values per run) |
 | OpenCode | `opencode.json` | `opencode` |
 | Antigravity | `.agents/mcp_config.json` | `node agy.mjs` |
-| Hermes | Separate `.hermes/config.yaml` profile | `node hermes.mjs --ignore-rules` |
+| Hermes | One user-level MCP registration; workspace launcher supplies paths | `node hermes.mjs` |
 
-Sign in to your harness and accept its normal project/MCP trust prompts. Hermes's
-separate profile needs its own authentication or provider credentials supplied
-through the environment; setup does not copy credentials. The Antigravity launcher
+Sign in to your harness and accept its normal project/MCP trust prompts. Hermes
+has no project-local MCP registration; follow its generated `START.md` for the
+one user-level registration. Its launcher preserves your existing provider and
+authentication and supplies this workspace's paths per run. Do not add
+`--ignore-rules` unless you intend to suppress project instructions. The Antigravity launcher
 sets the absolute project directory and disables automatic skill expansion in print
 mode. Name `kiln_workspace` in the brief, use the project skill copies, and pass
 absolute task-file paths. See [clean-room setup](https://github.com/instruktlabs/kiln/blob/main/docs/clean-room.md) for evaluation controls and limitations.
@@ -422,11 +483,14 @@ The v1 local plugin below uses a smaller bundle and creates an explicit workspac
 
 ## Local Claude Code and Codex plugins
 
-**The current branch is a development candidate.** The `v1.0.0` tag and npm release
-must exist before using these release commands. Maintainers qualify development
-bundles with the reviewed local engine archive instead.
+The commands below select the 1.1.0 plugin, which supports new workspaces and
+existing-project adoption. Use them once the matching GitHub tag and npm version
+are available. To qualify an unpublished candidate, select its exact source ref
+and supply the matching local engine archive as described in its bundled setup
+reference. Normal use should select a published release tag.
 
-The plugin is `kiln-engine` in the Instrukt Labs marketplace `instruktlabs`. Its
+The product is Kiln; its local plugin installation ID is `kiln-engine` in the
+Instrukt Labs marketplace `instruktlabs`. Its
 cache contains setup guidance and an installer, while the pinned engine and asset
 workspaces stay in persistent directories outside that cache. Installing the plugin
 does not start a second global Kiln MCP server.
@@ -434,14 +498,14 @@ does not start a second global Kiln MCP server.
 For Claude Code:
 
 ```sh
-claude plugin marketplace add instruktlabs/kiln#v1.0.0 --sparse .claude-plugin plugins/kiln-engine
+claude plugin marketplace add instruktlabs/kiln#v1.1.0 --sparse .claude-plugin plugins/kiln-engine
 claude plugin install kiln-engine@instruktlabs
 ```
 
 For Codex:
 
 ```sh
-codex plugin marketplace add instruktlabs/kiln --ref v1.0.0 --sparse .agents/plugins --sparse plugins/kiln-engine
+codex plugin marketplace add instruktlabs/kiln --ref v1.1.0 --sparse .agents/plugins --sparse plugins/kiln-engine
 codex plugin add kiln-engine@instruktlabs
 ```
 
@@ -449,8 +513,9 @@ Ask your agent to set up a Kiln asset workspace. The setup skill installs the ex
 package version in `runtime.json` through npm, with optional dependencies included
 and lifecycle scripts disabled. Node.js and npm are required; an engine checkout,
 Bun and a separate model API key are not. An existing working workspace can be used
-as-is. Otherwise choose an empty directory and follow its generated `START.md` to
-open a new authoring session. Accept the host's project/MCP trust prompts, then
+as-is. Otherwise choose a new workspace or preview adoption of an existing project,
+then follow the generated startup instructions to open an authoring session.
+Accept the host's project/MCP trust prompts, then
 verify `kiln_discover({capabilities:true})` on `kiln_workspace` and an actual render.
 
 The workspace owns its author/refine/QA skills and MCP configuration. The plugin

package/docs/migration.md

@@ -4,6 +4,26 @@ Existing inline-code transport and the legacy capture format remain supported. T
 Discovery and authoring-helper changes below require explicit migration; retired
 names have no callable compatibility aliases.
 
+## Changes in 1.1
+
+Version 1.1 adds existing-project setup
+and host SDK entrypoints without changing the stable 1.0 tool contracts.
+
+Use `kiln-init PROJECT --adopt --harness NAME --check` to preview adding Kiln to an
+existing project, then omit `--check` to apply. Existing instructions and unrelated
+configuration remain in place; Kiln's guidance lives under `.kiln/`. Multiple
+supported clients can share the same workspace. Existing managed workspaces
+continue to use `--check` and `--upgrade`. See [setup and recovery](install.md).
+
+Hosts can replace internal-file imports with the public `mcp`, `tools/input`,
+`views/port` and `discovery/portable` entrypoints. The portable Discovery API reads
+an engine-generated catalog without loading its Node builder. The [SDK guide](sdk.md)
+describes each boundary. No migration is required for ordinary CLI/MCP use.
+
+The local plugin helper is now `bin/kiln-setup-workspace.mjs`; version 1.0 used
+`scripts/setup-workspace.mjs`. Follow the helper path documented by the installed
+plugin. Updating a plugin cache does not automatically upgrade existing workspaces.
+
 ## Changes in 1.0
 
 These changes describe version 1.0 and its public RC, following the downloadable