@instruktlabs/kiln 1.0.0 → 1.2.0

package/lib/tools/registry.js

@@ -13,6 +13,7 @@ import { createKilnMaterialDef } from "./materials.js";
 import { createKilnReviewDef } from "./review.js";
 import { withWorkspaceContext } from "./workspace.js";
 import { describeInputError } from "./actions.js";
+import { projectOperationDefs } from "./operations.js";
 import { advancedCaptureInput, cameraShotInput, cameraShotRecordInput, cameraVec3Input, captureInput, captureRecordInput, } from "./capture-input.js";
 import { compactEditResult, compactReviewResult, partsHint, requestedDetail, reviewDetailInput, } from "./review-detail.js";
 import { createCachedEvaluatorPort, MemoryBuildCache } from "../build-cache.js";
@@ -1605,22 +1606,25 @@ const rendererInput = z.strictObject({
     action: z.enum(['status', 'reprobe']).default('status'),
 });
 /** A saved-revision read whose failure names the listing call instead of a filesystem path (rule 9). */
-async function readSavedRevision(target, collection, assetId, revisionId) {
+async function readSavedRevision(target, collection, assetId, revisionId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
     try {
         return await target.read(collection, assetId, revisionId);
     }
     catch (error) {
         if (error.code === 'ENOENT')
-            throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. kiln_assets { action: 'list', collection: '${collection}' } lists the saved revisions.`);
+            throw new Error(`Unknown asset ${assetId} revision ${revisionId} in collection ${collection}. ${listCall} lists the saved revisions.`);
         throw error;
     }
 }
 export function createKilnProgramToolRegistry(suppliedContext = {}) {
+    return createProgramDefs(suppliedContext, 'grouped');
+}
+function createProgramDefs(suppliedContext, presentation) {
     toolRequirements(suppliedContext);
     const store = suppliedContext.programStore ?? new MemoryProgramStore();
     const context = withCaptureCache(withBuildCache({ ...suppliedContext, programStore: store }));
     return [
-        createKilnDiscoveryDef({ ...suppliedContext, programStore: store }),
+        createKilnDiscoveryDef({ ...suppliedContext, programStore: store }, presentation),
         {
             name: 'kiln_renderer',
             description: 'Inspect status, or reprobe after renderer setup/repair to refresh this session and reset failed starts. Never installs, starts, stops or renders. Preserves CPU/local/remote selection; environment/credential changes require a host restart. Read viewFidelity after rendering.',
@@ -1665,7 +1669,9 @@ export function createKilnProgramToolRegistry(suppliedContext = {}) {
         ...(context.projectStore
             ? [createKilnProjectDef(context.projectStore, context.projectBundleReader)]
             : []),
-        ...(context.materialLibrary ? [createKilnMaterialDef(context.materialLibrary)] : []),
+        ...(context.materialLibrary
+            ? [createKilnMaterialDef(context.materialLibrary, presentation)]
+            : []),
         ...(context.reviewStore && context.assetLibrary
             ? [
                 createKilnReviewDef({
@@ -1675,7 +1681,7 @@ export function createKilnProgramToolRegistry(suppliedContext = {}) {
                 }),
             ]
             : []),
-        ...createKilnAssetDefs({ ...context, programStore: store }),
+        ...createKilnAssetDefs({ ...context, programStore: store }, presentation),
     ]
         .map((def) => withWorkspaceContext(def, context))
         .map((def) => ({
@@ -1689,6 +1695,10 @@ export function createKilnProgramToolRegistry(suppliedContext = {}) {
         },
     }));
 }
+/** Opt-in named domain operations; grouped local/native contracts remain unchanged. */
+export function createKilnOperationToolRegistry(context = {}) {
+    return projectOperationDefs(createProgramDefs(context, 'operations'), context);
+}
 /** Canonical native workflow: shared definitions plus one host-owned terminal. */
 export function createKilnNativeToolRegistry(suppliedContext, completion) {
     const active = toolRequirements(suppliedContext);
@@ -1772,15 +1782,42 @@ const assetSelector = {
     assetId: z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
     revisionId: z.string().regex(/^[a-z][a-z0-9_-]{0,79}$/),
 };
+const ASSET_CONTRACT = {
+    collections: {
+        fields: [],
+        required: [],
+        description: 'List configured asset storage collections. Collection is not project membership.',
+    },
+    catalog: {
+        fields: ['assetId', 'query', 'offset', 'limit'],
+        required: [],
+        description: 'Search saved assets across configured collections with pagination.',
+    },
+    list: {
+        fields: ['collection', 'assetId', 'query', 'offset', 'limit'],
+        required: [],
+        description: 'Search saved assets in one collection with pagination.',
+    },
+    get: {
+        fields: ['collection', 'assetId', 'revisionId'],
+        required: ['assetId'],
+        description: 'Read a saved revision and its download descriptors. Omit revisionId for the newest revision.',
+    },
+    restore: {
+        fields: ['collection', 'assetId', 'revisionId'],
+        required: ['assetId'],
+        description: 'Restore exact saved source as programRef for editing or rendering. Omit revisionId for the newest revision. Does not overwrite the saved revision. Binary-only assets have no source.',
+    },
+};
 /**
  * The revision a get or restore without `revisionId` means: the newest, the
  * one no later revision names as its parent, ties to the latest `createdAt`
  * (c40 of 1 October 2026 called get with the asset id alone and was refused).
  */
-export async function newestRevision(target, collection, assetId) {
+export async function newestRevision(target, collection, assetId, listCall = `kiln_assets { action: 'list', collection: '${collection}' }`) {
     const revisions = (await target.list(collection)).filter((a) => a.assetId === assetId);
     if (!revisions.length)
-        throw new Error(`Unknown asset ${assetId} in ${collection}; kiln_assets { action: 'list', collection: '${collection}' } lists them.`);
+        throw new Error(`Unknown asset ${assetId} in ${collection}; ${listCall} lists them.`);
     const parents = new Set(revisions.map((a) => a.parentRevision).filter(Boolean));
     const heads = revisions.filter((a) => !parents.has(a.revisionId));
     const newest = (heads.length ? heads : revisions).sort((a, b) => a.createdAt < b.createdAt ? 1 : a.createdAt > b.createdAt ? -1 : 0);
@@ -1857,7 +1894,16 @@ export async function buildProgramAssetDraft(code, context, backdrop) {
     };
 }
 /** All asset operation schemas live here, alongside the existing tool definitions. */
-export function createKilnAssetDefs(context) {
+export function createKilnAssetDefs(context, presentation = 'grouped') {
+    const listCall = (collection) => presentation === 'operations'
+        ? `kiln_assets_search({ collection: '${collection}' })`
+        : `kiln_assets { action: 'list', collection: '${collection}' }`;
+    const selector = presentation === 'operations'
+        ? {
+            ...assetSelector,
+            collection: assetSelector.collection.describe('Collection ID from kiln_assets_collections; default project.'),
+        }
+        : assetSelector;
     const library = () => {
         if (!context.assetLibrary)
             throw new Error('No asset library configured. The local CLI/MCP host supplies workspace collections; embedded hosts must inject assetLibrary.');
@@ -1886,11 +1932,11 @@ export function createKilnAssetDefs(context) {
         downloadUrls: await context.assetDownloadUrls?.(collection, asset.assetId, asset.revisionId),
     });
     const saveInput = z.object({
-        collection: assetSelector.collection,
+        collection: selector.collection,
         programRef: z.string(),
         name: z.string().min(1).max(200),
-        assetId: assetSelector.assetId.optional(),
-        parentRevision: assetSelector.revisionId.optional(),
+        assetId: selector.assetId.optional(),
+        parentRevision: selector.revisionId.optional(),
         tags: z.array(z.string().max(80)).max(30).optional(),
         brief: z.string().max(8000).optional(),
         description: z.string().max(4000).optional(),
@@ -1908,16 +1954,16 @@ export function createKilnAssetDefs(context) {
     });
     const assetsInput = z.object({
         action: z.enum(['collections', 'catalog', 'list', 'get', 'restore']).default('list'),
-        collection: assetSelector.collection,
-        assetId: assetSelector.assetId.optional(),
-        revisionId: assetSelector.revisionId
+        collection: selector.collection,
+        assetId: selector.assetId.optional(),
+        revisionId: selector.revisionId
             .optional()
             .describe('get, restore: the saved revision; omitted, the newest.'),
         query: z.string().max(200).optional(),
         offset: z.number().int().min(0).default(0),
         limit: z.number().int().min(1).max(50).default(20),
     });
-    const exportInput = z.object(assetSelector);
+    const exportInput = z.object(selector);
     const profileExportInput = exportInput.extend({
         profile: z
             .enum(['editable', 'runtime'])
@@ -1925,8 +1971,8 @@ export function createKilnAssetDefs(context) {
             .describe('editable preserves canonical source/GLB/build resources. runtime returns a standalone GLB and versioned review-metadata sidecar; no source bundle or geometry optimization.'),
     });
     const importInput = z.object({
-        ...assetSelector,
-        sourceCollection: assetSelector.collection,
+        ...selector,
+        sourceCollection: selector.collection,
     });
     return [
         {
@@ -1942,7 +1988,7 @@ export function createKilnAssetDefs(context) {
                     requirements: activeRequirements.binding,
                 };
                 if (input.assetId && input.parentRevision) {
-                    const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision);
+                    const previous = await readSavedRevision(target, input.collection, input.assetId, input.parentRevision, listCall(input.collection));
                     assertSavedRequirementsAuthorized(previous.manifest, activeRequirements);
                 }
                 const code = await context.programStore.get(input.programRef);
@@ -1957,6 +2003,7 @@ export function createKilnAssetDefs(context) {
             name: 'kiln_assets',
             description: 'Browse saved assets: collections discovers storage; catalog searches all configured collections; list searches one. Both searches paginate. get returns a build record/downloads; restore loads exact source for kiln_source/kiln_edit. Collection is not project membership. Binary-only assets cannot restore source.',
             inputSchema: assetsInput,
+            actionContract: ASSET_CONTRACT,
             run: async (raw) => {
                 const input = assetsInput.parse(raw);
                 const activeRequirements = toolRequirements(context);
@@ -2005,10 +2052,11 @@ export function createKilnAssetDefs(context) {
                         })),
                     };
                 }
-                if (!input.assetId)
+                if (ASSET_CONTRACT[input.action].required.some((field) => !input[field]))
                     throw new Error(`kiln_assets ${input.action} requires assetId; kiln_assets { action: 'list', collection: '${input.collection}' } lists them.`);
-                const revisionId = input.revisionId ?? (await newestRevision(target, input.collection, input.assetId));
-                const record = await readSavedRevision(target, input.collection, input.assetId, revisionId);
+                const revisionId = input.revisionId ??
+                    (await newestRevision(target, input.collection, input.assetId, listCall(input.collection)));
+                const record = await readSavedRevision(target, input.collection, input.assetId, revisionId, listCall(input.collection));
                 if (input.action === 'get')
                     return links(input.collection, record.manifest);
                 const saved = assertSavedRequirementsAuthorized(record.manifest, activeRequirements);
@@ -2080,7 +2128,7 @@ export function createKilnAssetDefs(context) {
             inputSchema: profileExportInput,
             run: async (raw) => {
                 const input = profileExportInput.parse(raw);
-                const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId);
+                const record = await readSavedRevision(library(), input.collection, input.assetId, input.revisionId, listCall(input.collection));
                 const { inspectDrawDiagnostics } = await import("../draw-diagnostics.js");
                 if (input.profile === 'runtime') {
                     const output = await (await import("../asset-export.js")).exportAssetGlb(record, {
@@ -2114,7 +2162,7 @@ export function createKilnAssetDefs(context) {
             run: async (raw) => {
                 const input = importInput.parse(raw);
                 const target = library();
-                const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId);
+                const record = await readSavedRevision(target, input.sourceCollection, input.assetId, input.revisionId, listCall(input.sourceCollection));
                 await target.import(input.collection, [record]);
                 return links(input.collection, record.manifest);
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruktlabs/kiln",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Create and refine procedural 3D assets with JavaScript, image feedback, and reusable source revisions.",
   "license": "MIT",
   "author": "Matthew Kissinger",
@@ -83,6 +83,14 @@
       "types": "./lib/tools/registry.d.ts",
       "import": "./lib/tools/registry.js"
     },
+    "./tools/input": {
+      "types": "./lib/tools/actions.d.ts",
+      "import": "./lib/tools/actions.js"
+    },
+    "./mcp": {
+      "types": "./lib/mcp.d.ts",
+      "import": "./lib/mcp.js"
+    },
     "./arena": {
       "types": "./lib/arena/index.d.ts",
       "import": "./lib/arena/index.js"
@@ -115,6 +123,10 @@
       "types": "./lib/views/index.d.ts",
       "import": "./lib/views/index.js"
     },
+    "./views/port": {
+      "types": "./lib/views/port.d.ts",
+      "import": "./lib/views/port.js"
+    },
     "./validation": {
       "types": "./lib/validation.d.ts",
       "import": "./lib/validation.js"
@@ -207,6 +219,10 @@
       "types": "./lib/discovery/index.d.ts",
       "import": "./lib/discovery/index.js"
     },
+    "./discovery/portable": {
+      "types": "./lib/discovery/portable.d.ts",
+      "import": "./lib/discovery/portable.js"
+    },
     "./metrics": {
       "types": "./lib/metrics.d.ts",
       "import": "./lib/metrics.js"
@@ -253,6 +269,9 @@
     "plugins/kiln-engine/",
     ".mcp.json",
     "scripts/create-workspace.mjs",
+    "scripts/workspace-config.mjs",
+    "scripts/workspace-project.mjs",
+    "scripts/workspace-transaction.mjs",
     "scripts/package-plugin.mjs",
     "render-service/src/",
     "render-service/package.json",
@@ -280,6 +299,7 @@
     "docs/runtime.md",
     "docs/sdk.md",
     "docs/tools.md",
+    "docs/tools-operations.md",
     "README.md",
     "CONTRIBUTING.md",
     "LICENSE",
@@ -327,10 +347,12 @@
     "acorn": "^8.18.0",
     "acorn-walk": "^8.3.5",
     "gltf-validator": "2.0.0-dev.3.10",
+    "jsonc-parser": "3.3.1",
     "manifold-3d": "^3.5.4",
     "minisearch": "7.2.0",
     "pngjs": "7.0.0",
     "sharp": "^0.35.5",
+    "smol-toml": "1.9.0",
     "three": "0.186.1",
     "three-subdivide": "1.1.5",
     "xatlasjs": "^0.2.0",

package/plugin.json

@@ -2,7 +2,7 @@
   "name": "kiln",
   "displayName": "Kiln",
   "description": "Build and revise 3D assets with your coding agent. Write JavaScript, inspect selected views, edit saved source revisions, and export GLB files locally.",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "license": "MIT",
   "homepage": "https://github.com/instruktlabs/kiln",
   "keywords": [

package/plugins/kiln-engine/.claude-plugin/plugin.json

@@ -1,9 +1,10 @@
 {
   "name": "kiln-engine",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Set up a local Kiln workspace to create, inspect and revise editable 3D assets with Claude Code or Codex.",
   "author": {
-    "name": "Instrukt Labs"
+    "name": "Instrukt Labs",
+    "email": "support@instruktlabs.com"
   },
   "homepage": "https://github.com/instruktlabs/kiln",
   "repository": "https://github.com/instruktlabs/kiln",
@@ -14,5 +15,10 @@
     "gltf",
     "asset-generation",
     "gamedev"
-  ]
+  ],
+  "icon": "./.claude-plugin/icon.png",
+  "documentationUrl": "https://github.com/instruktlabs/kiln/tree/main/plugins/kiln-engine",
+  "supportUrl": "https://github.com/instruktlabs/kiln/blob/main/plugins/kiln-engine/README.md#support-and-security",
+  "privacyPolicyUrl": "https://github.com/instruktlabs/kiln/blob/main/docs/local-plugin-privacy.md",
+  "termsOfServiceUrl": "https://github.com/instruktlabs/kiln/blob/main/LICENSE"
 }

package/plugins/kiln-engine/PRIVACY.md

@@ -0,0 +1,100 @@
+# Kiln local plugin privacy
+
+Draft for owner review before directory submission. Updated 7 October 2026.
+
+This notice covers the `kiln-engine` local plugin maintained by Instrukt Labs and
+the local workspace it sets up. It does not cover the separate hosted Kiln service
+or your coding assistant's account and conversation history. The local plugin does
+not require a Kiln account, an email address, payment details or a model API key.
+
+## What stays on your computer
+
+Setup reads its public package/version pin, locates Node and npm, and checks the
+workspace and runtime directories you select. It installs the engine in a persistent
+data directory outside the plugin cache. Paths can contain your device account
+name; paths, package identity and file hashes appear in local configuration,
+installation records and command results returned to your assistant.
+
+When adding Kiln to an existing project, setup reads the selected client's
+configuration and records ownership of Kiln's own entries. It preserves unrelated
+settings and existing project instructions. A recoverable setup transaction
+temporarily copies the affected files into private local recovery storage outside
+the project. Those copies can contain credentials already present in the client's
+configuration. They are not uploaded, printed or added to the workspace manifest.
+This storage uses filesystem permissions; Kiln does not encrypt these snapshots.
+
+Your workspace and configured asset libraries hold authored JavaScript, material
+files, asset names, metadata, previews and GLBs. Local tools read and write the
+work you ask them to handle and return requested source, images and results to
+your coding assistant. Avoid putting personal or confidential information in a
+source file, asset name or tool argument unless you intend your assistant to see it.
+
+The local plugin does not send these assets to an Instrukt Labs service or add
+analytics reporting. Your assistant can send prompts and tool results to its own
+provider. That processing, and any assistant history or backups, follows the
+assistant's settings and privacy policy. Kiln does not control those copies.
+
+## Network access and other services
+
+- Installing or updating the marketplace/plugin contacts GitHub through your
+  coding assistant or Git. Setup downloads the exact engine version and its
+  dependencies through npm using `https://registry.npmjs.org`. Those services
+  receive download requests and ordinary connection information, including your
+  IP address. No asset upload is part of setup.
+- npm runs with lifecycle scripts, audit and funding requests disabled. It can
+  still use your existing npm configuration and inherited environment, including
+  registry authentication you already configured. Kiln does not request an npm
+  login or registry token for this public package, copy credentials into the
+  plugin, or promise to strip npm's normal credential configuration. npm also
+  writes to its normal cache and log directories.
+- CPU rendering is local. An optional local render service stays on your machine.
+  If you explicitly configure a renderer on another machine, Kiln sends the GLB
+  and capture settings to that chosen endpoint and uses its configured
+  authentication. Review that operator's privacy and retention practices first.
+- Opening documentation, filing a GitHub issue or contacting support uses the
+  service you choose. Information in a public issue is public; it is not private
+  telemetry from your local workspace.
+
+Relevant service policies: [npm](https://docs.npmjs.com/policies/privacy/),
+[GitHub](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement),
+[Claude](https://www.anthropic.com/legal/privacy) and
+[OpenAI](https://openai.com/policies/privacy-policy/). Other assistants and optional
+renderer operators provide their own policies.
+
+## Retention and deletion
+
+Local source, saved assets, runtime installations and workspace configuration
+remain until you delete them. Uninstalling the plugin removes neither your assets
+nor its separately installed engine. Plugin updates also leave existing
+workspaces on their installed engine until you request a managed upgrade.
+
+Setup removes recovery snapshots after a successful transaction or completed
+recovery. Interrupted setup can leave them until recovery succeeds or you resolve
+the interruption. The default location is
+`%LOCALAPPDATA%/InstruktLabs/Kiln/setup-transactions` on Windows, or
+`$XDG_DATA_HOME/instruktlabs/kiln/setup-transactions` elsewhere, falling back to
+`~/.local/share/instruktlabs/kiln/setup-transactions`. Use the setup helper's
+`--recover` operation before retrying an interrupted change. Do not upload recovery
+files to a public issue or delete them while setup or recovery is active.
+
+There is no automatic seven-day expiry for local work; that is a separate hosted
+service policy. Remove selected local work using Kiln's library controls or your
+filesystem, and manage independent exports, backups, npm caches and assistant
+histories through their respective applications. Preserve copies you want before
+deleting a workspace or runtime.
+
+## Support and security
+
+Contact [support@instruktlabs.com](mailto:support@instruktlabs.com) for privacy
+questions, deletion requests concerning information you sent to support, or
+private security reports. Support receives only what you send, including your
+email address and message. Support mail is forwarded through Cloudflare to the
+maintainer's Google inbox; see [Cloudflare's privacy policy](https://www.cloudflare.com/privacypolicy/)
+and [Google's privacy policy](https://policies.google.com/privacy). We use support
+correspondence to handle the request; this is not an automatic local-plugin alert
+or a mailing-list signup.
+
+Do not send passwords, tokens, recovery codes or private assets with a bug report.
+Sanitize logs and paths before posting publicly. Instrukt Labs cannot remotely
+access or erase your local workspace, your assistant's copies or a renderer
+operator's records through this plugin.

package/plugins/kiln-engine/README.md

@@ -1,25 +1,110 @@
-# Kiln Engine local plugin
+# Kiln local plugin
 
-Version 1.0.0, published by Instrukt Labs under the MIT license.
+Plugin version 1.2.0, maintained by Instrukt Labs under the MIT license.
+This plugin pins engine 1.2.0. Registry setup requires that exact version
+to be published. Use a published release tag for normal installation or a reviewed
+local archive for development qualification. The installation ID remains
+`kiln-engine@instruktlabs`.
 
-Ask your coding agent to set up a Kiln workspace. The setup skill installs
-`@instruktlabs/kiln@1.0.0` with npm and creates a separate asset workspace.
-Use a supported Node.js installation with npm; no Bun, engine clone or separate
-model API key is required. The workspace's START.md explains how to reopen it.
+Set up Kiln in an existing project or a new asset workspace, then create and revise
+editable 3D assets with your coding agent. Use a supported Node.js installation
+with npm. No Bun, engine checkout, Kiln account or separate model API key is needed.
+The plugin requires a local shell and filesystem; Claude chat and Cowork are not
+supported by this local bundle.
 
-The plugin registers setup only. The workspace supplies the authoring skills
-and one local MCP server, `kiln_workspace`. Open Claude Code in that workspace;
-launch Codex there with `node codex.mjs`. Accept the host's ordinary trust prompts
-and verify live tool discovery before authoring.
+## Install
+
+For Claude Code:
+
+```sh
+claude plugin marketplace add instruktlabs/kiln
+claude plugin install kiln-engine@instruktlabs
+```
+
+For Codex:
+
+```sh
+codex plugin marketplace add instruktlabs/kiln
+codex plugin add kiln-engine@instruktlabs
+```
+
+Restart or reload your coding agent's plugins as its installation message directs.
+Then ask it to set up a Kiln workspace. The maintained setup skill runs this
+plugin's `bin/kiln-setup-workspace.mjs` with Node, installs
+`@instruktlabs/kiln@1.2.0` outside the project and configures your chosen
+workspace. The same initializer supports existing projects and new workspaces.
+
+The plugin registers setup only. The workspace supplies authoring skills and one
+local MCP server, `kiln_workspace`. Open Claude Code in that workspace or launch
+Codex there with `codex`. For headless Codex execution, use
+`node codex.mjs "TASK"` with an explicit prompt. Read `.kiln/START.md` after
+adoption or `START.md` in a legacy workspace, accept the host's ordinary trust
+prompts and verify live tool discovery before authoring.
+
+## Setup examples
+
+1. **Create:** “Set up a new Kiln workspace in an empty directory outside this
+   checkout, using my current coding agent. Verify its tools before I author an
+   asset.” The installer downloads the pinned engine when needed, creates the
+   selected workspace and keeps its engine in a separate runtime store. npm also
+   uses its normal cache and log directories.
+2. **Adopt:** “Add Kiln to this project without replacing my instructions or other
+   MCP settings. Show the planned changes first.” Use `--adopt --check` to
+   preview, then `--adopt` to apply. Read `.kiln/AGENTS.md` alongside the
+   project's instructions. Repeat with another supported `--harness` to add
+   that integration around the same saved assets. The engine's adapter list is
+   included in `runtime.json`; it does not imply this plugin can be installed
+   in every listed client. Published engine 1.0.0 does not support adoption.
+3. **Check:** “Check my existing Kiln workspace without changing it.” The helper's
+   `--check` mode reports whether managed files and the installed engine are
+   current. A missing runtime is reported without installing one.
+4. **Upgrade:** “Upgrade my managed Kiln workspace while preserving my sources,
+   saved assets and customizations.” Stop the workspace's harness session first.
+   The helper's `--upgrade` mode uses the pinned engine and refuses conflicts
+   rather than replacing customized managed files.
 
 The engine installation and your assets stay outside the disposable plugin cache.
-Plugin removal or updating its cached files does not delete them. An existing
-workspace remains on its installed engine until an explicit managed upgrade.
-Read [setup and upgrade guidance](skills/kiln-setup-workspace/references/plugin-install.md).
+Removing or updating the plugin does not delete them. Existing workspaces stay on
+their installed engine until an explicit managed upgrade. Read the
+[setup and upgrade guide](skills/kiln-setup-workspace/references/plugin-install.md)
+for paths, repair and failure recovery.
+
+## Execution and network access
+
+The setup skill asks your coding agent to execute a bundled Node installer. That
+installer runs npm with lifecycle scripts disabled and invokes Kiln's workspace
+generator. It does this before the workspace MCP server exists; it does not
+silently install a global MCP server or grant itself shell permissions.
+
+Adoption and managed project updates temporarily keep recovery copies outside
+the project. Client configuration can already contain credentials, so these
+private copies may too. They are removed after successful setup or recovery;
+interrupted transactions retain them. See [local privacy](PRIVACY.md) for the
+storage location and protection limits. Use `--recover` before retrying an
+interrupted project update.
+
+Marketplace installation and updates contact `https://github.com`. First engine
+installation and dependency downloads use `https://registry.npmjs.org`. npm can
+use your existing npm configuration and environment. No npm login or token is
+required for this public package. Normal local asset work does not upload your
+assets to Instrukt Labs. Tool results can enter your coding assistant's model
+context; its provider handles those copies.
+
+CPU rendering is local. Material appearance needs a compatible local renderer or
+one you explicitly configure on another machine; a remote renderer receives the
+GLB and requested capture settings. Follow the setup skill's renderer checks.
+The separate hosted Kiln integration has its own authentication and privacy notice.
+
+## Support and security
+
+Send private security or privacy questions to
+[support@instruktlabs.com](mailto:support@instruktlabs.com). Never include
+passwords, tokens, recovery codes or private assets in public issues. For a normal
+bug report, provide the plugin and engine versions, operating system and a small
+sanitized reproduction at [GitHub issues](https://github.com/instruktlabs/kiln/issues).
 
-CPU rendering is available locally. Material appearance requires a qualified
-renderer; follow the setup skill's renderer checks rather than assuming GPU support.
-Hosted ChatGPT access is a separate integration, and this local bundle is not a
-public OpenAI directory submission.
+If setup fails, retain the error, check Node/npm and network access, and follow the
+setup guide. Do not delete an unfamiliar runtime or another installer's lock.
 
-[Source and issues](https://github.com/instruktlabs/kiln)
+[Local privacy notice](PRIVACY.md) · [MIT license](LICENSE) ·
+[Source](https://github.com/instruktlabs/kiln)