@instruktlabs/kiln 1.1.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.1.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",
@@ -299,6 +299,7 @@
     "docs/runtime.md",
     "docs/sdk.md",
     "docs/tools.md",
+    "docs/tools-operations.md",
     "README.md",
     "CONTRIBUTING.md",
     "LICENSE",

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.1.0",
+  "version": "1.2.0",
   "license": "MIT",
   "homepage": "https://github.com/instruktlabs/kiln",
   "keywords": [

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

@@ -1,6 +1,6 @@
 {
   "name": "kiln-engine",
-  "version": "1.1.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",

package/plugins/kiln-engine/README.md

@@ -1,7 +1,7 @@
 # Kiln local plugin
 
-Plugin version 1.1.0, maintained by Instrukt Labs under the MIT license.
-This plugin pins engine 1.1.0. Registry setup requires that exact version
+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`.
@@ -31,7 +31,7 @@ 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.1.0` outside the project and configures your chosen
+`@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

package/plugins/kiln-engine/package-provenance.json

@@ -1,20 +1,20 @@
 {
   "schemaVersion": 1,
   "kind": "kiln-local-plugin",
-  "pluginVersion": "1.1.0",
-  "engineVersion": "1.1.0",
+  "pluginVersion": "1.2.0",
+  "engineVersion": "1.2.0",
   "executables": [
     "bin/kiln-setup-workspace.mjs"
   ],
   "files": {
     ".claude-plugin/icon.png": "sha256:b4b651c402793b7e27cab780f04b14f80daec6d0cd5b7e4e90313930581a54e9",
-    ".claude-plugin/plugin.json": "sha256:189394253cf57f988fd82b31dad05012d693615a50126eebb29bab3e80e3a2a9",
+    ".claude-plugin/plugin.json": "sha256:616a6a61da072fcfdd4d0e1cf513e0e91bf1e56fb61b9b02d23e72fa291556bc",
     "bin/kiln-setup-workspace.mjs": "sha256:3d9a30236919a6ca91acb6b26f808cec442e6edc3dd88fe010645b010d76e838",
     "LICENSE": "sha256:cdba278ebf1d6de618869936226bf03be4887179c128efc7aaa13d22034826a5",
-    "plugin.json": "sha256:428ab085c6257ccc0e2dec3c7d4f9b6e02db0024a5f0b355410a30d6282dcd1d",
+    "plugin.json": "sha256:3437107d46ad4fef4a710a8e821e56b43894cc1722504fe4e8ff0120fa6a8d8d",
     "PRIVACY.md": "sha256:5f58d981667e40441e21c2dec411f269a9a67a6141cec61976d27088fb12573b",
-    "README.md": "sha256:6a7fc436113f7493c884b2c495629351b01b2cd7e82e7b808f3abe73b9eb9af4",
-    "runtime.json": "sha256:253f76044dcc162295ca760ff584d1d6894068357c727a56b077b44278f38eb3",
+    "README.md": "sha256:0b82e6eb8b679f8b991c1a5567957574ed7b3341a87ef989403e5521f83ab50e",
+    "runtime.json": "sha256:5ebac8387f4bedcc7cac02a36f73c5ffba969ce6c8c6e2b0e356ef569168d0a5",
     "skills/kiln-setup-workspace/references/plugin-install.md": "sha256:c338fb792e7fad0364c3e1a13c94c506afa1395489ec1b6e83b36d04728935fb",
     "skills/kiln-setup-workspace/references/renderer-setup.md": "sha256:b743b1b2827fa814385990e1e5b849391cb427413e9c016d273aa19cebd46031",
     "skills/kiln-setup-workspace/SKILL.md": "sha256:65ed926b3503a33f4fe793e84e4a045ce36e3967f0e6b340e456a15dd010ce54"

package/plugins/kiln-engine/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "kiln-engine",
-  "version": "1.1.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",

package/plugins/kiln-engine/runtime.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruktlabs/kiln",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "harnesses": [
     "claude",
     "codex",

package/src/discovery/index.ts

@@ -21,6 +21,7 @@ export function createDiscovery(
     discovery: { mode: 'lexical', offline: true, requiresModel: false },
   }),
   notes: () => Promise<string[]> = async () => [],
+  capabilitiesCall = 'capabilities:true',
 ) {
   snapshot ??= (() => {
     const entries = listDiscoveryEntries();
@@ -32,5 +33,6 @@ export function createDiscovery(
     capabilities,
     REMOVED_AUTHORING_HELPERS,
     notes,
+    capabilitiesCall,
   );
 }

package/src/discovery/service.ts

@@ -63,6 +63,8 @@ export function createDiscoveryService(
   retirements: Readonly<Record<string, string>> = {},
   /** Host notes for the overview, such as the project an omitted `projectId` selects. */
   notes: () => Promise<string[]> = async () => [],
+  /** Host-selected capability entrypoint, never a model-provided instruction. */
+  capabilitiesCall = 'capabilities:true',
 ): (input: unknown) => Promise<DiscoveryResponse> {
   const entries = parseCatalog(source);
   const byId = new Map(entries.map((entry) => [entry.id, entry]));
@@ -94,7 +96,7 @@ export function createDiscoveryService(
       'Parts auto-add to opts.parent; do not wrap createPart in parent.add. Part rotation uses degrees.',
       'Custom THREE.BufferGeometry and ordinary JavaScript functions remain available. Recipes offer guidance and never restrict modeling.',
       'Send source once and reuse programRef for reads, edits, inspection and rendering. Review geometry, materials and destination constraints separately.',
-      'Search for the operation you need in ordinary language, then fetch exact contracts with ids. Use capabilities:true for the current host.',
+      `Search for the operation you need in ordinary language, then fetch exact contracts with ids. Use ${capabilitiesCall} for the current host.`,
     ],
   };
   const error = (

package/src/engine-identity.ts

@@ -27,7 +27,7 @@
  * `src/__tests__/package-contents.test.ts` fails if it disagrees with the manifest
  * or with any plugin manifest, which is what keeps the literal honest.
  */
-export const ENGINE_VERSION = '1.1.0';
+export const ENGINE_VERSION = '1.2.0';
 
 /**
  * Where this engine was loaded from, as a `file://` URL of the package root.

package/src/mcp-core.ts

@@ -65,6 +65,9 @@ export const MCP_SERVER_VERSION = ENGINE_VERSION;
 export const MCP_SERVER_INSTRUCTIONS =
   "Kiln turns JavaScript you write into GLB assets and returns rendered views. Work by reference: send a program once to kiln_validate or kiln_render, keep the returned programRef exactly, and use it for every later render, inspect, kiln_source and kiln_edit call; never resend a program to change part of it. Call kiln_discover first for helper contracts, with capabilities:true for the host's runtime, project and camera facts. Read viewFidelity before judging materials: a CPU view shows shape, not material; GPU views need the render service in render-service/. Agent Skills for authoring, refining, QA and scenes ship in skills/ beside this server's dist/; read the matching SKILL.md first.";
 
+export const MCP_OPERATION_INSTRUCTIONS =
+  'Kiln turns authored JavaScript into editable GLB assets and rendered views. Send source once to kiln_validate or kiln_render, then preserve the exact programRef for later reads, edits and renders. Use kiln_discover for helper contracts and full input shapes; use kiln_capabilities for host configuration and limits. Read viewFidelity before judging materials: CPU geometry views are not material evidence. Search saved assets with kiln_assets_search; reopen exact source with kiln_assets_restore. Browse materials with kiln_material_search and create with kiln_material_create. Save only when requested. Pin collection, asset and revision IDs for reuse and export.';
+
 /** One MCP content block. Mirrors the SDK's `CallToolResult['content']` element. */
 export type KilnContentBlock =
   | AssetLink

package/src/mcp-engine.ts

@@ -26,6 +26,7 @@ import {
   type KilnResourceContents,
   type KilnToolResult,
   withoutLocalPaths,
+  MCP_OPERATION_INSTRUCTIONS,
 } from './mcp-core';
 import { buildMcpManifest } from './mcp-manifest';
 import { localProgramStore } from './program-store-node';
@@ -33,6 +34,7 @@ import { validateRequirementsBinding } from './requirements-context';
 import { describeInputError, schemaFields } from './tools/actions';
 import {
   createKilnProgramToolRegistry,
+  createKilnOperationToolRegistry,
   type KilnToolContext,
   type KilnToolDef,
 } from './tools/registry';
@@ -42,6 +44,8 @@ export type { KilnToolResult } from './mcp-core';
 
 /** Optional wire features whose support is not negotiated by core MCP. */
 export type KilnMcpCompatibilityOptions = {
+  /** Opt-in domain operation presentation generated from the shared registry. */
+  toolPresentation?: 'grouped' | 'operations';
   /**
    * Add core `resource_link` blocks for saved artifact files.
    *
@@ -160,7 +164,10 @@ export function createKilnToolHost(
       };
     },
   };
-  const defs = kilnMcpToolDefs(requestContext);
+  const defs =
+    options.toolPresentation === 'operations'
+      ? createKilnOperationToolRegistry(requestContext)
+      : kilnMcpToolDefs(requestContext);
   const byName = new Map(defs.map((def) => [def.name, def] as const));
   return {
     defs,
@@ -259,6 +266,9 @@ export function createKilnMcpServer(
 ): Server {
   const host = createKilnToolHost(context, options);
   return createKilnServer({
+    ...(options.toolPresentation === 'operations'
+      ? { instructions: MCP_OPERATION_INSTRUCTIONS }
+      : {}),
     manifest: buildMcpManifest(host.defs, context),
     host: async () => host,
   });

package/src/tools/discovery.ts

@@ -11,10 +11,14 @@ import { resolveGltfExporter } from '../community-exporter';
 import { approvedTextureCatalogV1 } from '../material-resources';
 
 /** Shared native tool definition; all transports use the same Discovery service. */
-export function createKilnDiscoveryDef(context: KilnToolContext): KilnToolDef {
+export function createKilnDiscoveryDef(
+  context: KilnToolContext,
+  presentation: 'grouped' | 'operations' = 'grouped',
+): KilnToolDef {
   const run = createDiscovery(
-    () => currentCapabilities(context),
+    () => currentCapabilities(context, presentation),
     async () => projectNotes(context),
+    presentation === 'operations' ? 'kiln_capabilities({})' : 'capabilities:true',
   );
   return {
     name: 'kiln_discover',
@@ -48,7 +52,10 @@ function projectNotes(context: KilnToolContext): string[] {
     : [];
 }
 
-async function currentCapabilities(context: KilnToolContext) {
+async function currentCapabilities(
+  context: KilnToolContext,
+  presentation: 'grouped' | 'operations',
+) {
   const externalEvaluator =
     Boolean(context.evaluatorPort) || context.evaluatorProfile === 'evaluator-required';
   const approvedTextures = context.approvedTextureResources
@@ -102,12 +109,15 @@ async function currentCapabilities(context: KilnToolContext) {
     // you -- so the workspace guide's "do not substitute it silently" had
     // nothing to check against. Compare with `runtime` in .kiln/workspace.json.
     engine: engineIdentity(),
-    project: {
-      configured: configuredProject(context),
-      select:
-        'projectId per call; omitted uses the configured project, null selects standalone work',
-      read: 'kiln_project { action: "get", projectId } returns the brief, design, inventory and material pins',
-    },
+    project:
+      presentation === 'operations' && !context.projectStore
+        ? { available: false }
+        : {
+            configured: configuredProject(context),
+            select:
+              'projectId per call; omitted uses the configured project, null selects standalone work',
+            read: 'kiln_project { action: "get", projectId } returns the brief, design, inventory and material pins',
+          },
     renderer,
     execution:
       context.localExecution ??
@@ -128,7 +138,7 @@ async function currentCapabilities(context: KilnToolContext) {
       available: Boolean(context.assetLibrary),
       collections: context.assetLibrary?.collections() ?? [],
       save: 'kiln_save persists exact GLB, source and provenance; draft renders do not populate collections',
-      resume: 'kiln_assets action=restore imports a saved revision into the current program store',
+      resume: `${presentation === 'operations' ? 'kiln_assets_restore' : 'kiln_assets action=restore'} imports a saved revision into the current program store`,
       downloads: 'kiln_export returns GLB/source/ZIP resource links; client presentation varies',
       viewer:
         'kiln_present opens a saved revision in supporting chat clients with 3D viewing and downloads; kiln view opens a local collection or standalone GLB/ZIP',

package/src/tools/materials.ts

@@ -14,6 +14,7 @@ import { createMaterialRecordV1, decodeMaterialLibraryPayload } from '../materia
 import { createMaterialPresetDraft, listMaterialPresets } from '../material-presets';
 import { nestedRecordDescription, requireActionFields } from './actions';
 import type { KilnToolDef } from './registry';
+import type { KilnActionContract } from './operation-contract';
 
 const MATERIAL_ACTIONS = [
   'presets',
@@ -24,13 +25,43 @@ const MATERIAL_ACTIONS = [
   'import',
 ] as const;
 type MaterialAction = (typeof MATERIAL_ACTIONS)[number];
-const REQUIREMENTS: Record<MaterialAction, Parameters<typeof requireActionFields>[3]> = {
-  presets: { required: [] },
-  'create-preset': { required: ['presetId', 'seed', 'creator', 'license'] },
-  list: { required: [] },
-  get: { required: ['materialId'] },
-  'create-procedural': { required: ['draft'], shapes: { draft: 'shape:material-draft' } },
-  import: { required: ['payload'], shapes: { payload: 'shape:material-import' } },
+const MATERIAL_CONTRACT: Record<MaterialAction, KilnActionContract> = {
+  presets: {
+    fields: ['tag'],
+    required: [],
+    description: 'List shipped material recipes, optionally filtered by tag.',
+  },
+  'create-preset': {
+    fields: ['presetId', 'seed', 'creator', 'license', 'size', 'materialId'],
+    required: ['presetId', 'seed', 'creator', 'license'],
+    description:
+      'Create an immutable material from a shipped preset with explicit seed, creator and license.',
+  },
+  list: {
+    fields: ['tag'],
+    required: [],
+    description: 'List saved immutable material revisions, optionally filtered by tag.',
+  },
+  get: {
+    fields: ['materialId', 'revisionId'],
+    required: ['materialId'],
+    description:
+      'Read a material revision, provenance and portable specification. Omit revisionId only when exactly one revision exists.',
+  },
+  'create-procedural': {
+    fields: ['draft'],
+    required: ['draft'],
+    shapes: { draft: 'shape:material-draft' },
+    description:
+      'Create an immutable material from a bounded procedural draft. Does not fetch URLs or execute source.',
+  },
+  import: {
+    fields: ['payload'],
+    required: ['payload'],
+    shapes: { payload: 'shape:material-import' },
+    description:
+      'Import complete normalized material records and embedded PNGs. Does not fetch URLs or execute source.',
+  },
 };
 const record = (description: string) =>
   z.record(z.string(), z.unknown()).optional().describe(description);
@@ -74,9 +105,9 @@ const materialResult = (material: MaterialManifestV1) => ({
   material,
   portableSpec: materialLibraryPortableSpec(material),
 });
-const unknownMaterial = (materialId: string, revisionId?: string) =>
+const unknownMaterial = (materialId: string, revisionId: string | undefined, listCall: string) =>
   new Error(
-    `Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ''}. kiln_material { action: 'list' } lists the materials in this workspace with their revision IDs.`,
+    `Unknown material ${materialId}${revisionId ? ` at ${revisionId}` : ''}. ${listCall} lists the materials in this workspace with their revision IDs.`,
   );
 /**
  * The revision a `get` without `revisionId` means: the material's only one.
@@ -84,13 +115,17 @@ const unknownMaterial = (materialId: string, revisionId?: string) =>
  * caller to choose (two live sessions of 1 October 2026 called get with the
  * id alone and were refused).
  */
-async function onlyRevision(library: MaterialLibrary, materialId: string): Promise<string> {
+async function onlyRevision(
+  library: MaterialLibrary,
+  materialId: string,
+  listCall: string,
+): Promise<string> {
   const revisions = (await library.list())
     .filter((material) => material.materialId === materialId)
     .map((material) => material.revisionId)
     .sort();
   if (revisions.length === 1) return revisions[0]!;
-  if (revisions.length === 0) throw unknownMaterial(materialId);
+  if (revisions.length === 0) throw unknownMaterial(materialId, undefined, listCall);
   throw new Error(
     `Material ${materialId} has ${revisions.length} revisions: ${revisions.join(', ')}. Pass revisionId to get one.`,
   );
@@ -111,12 +146,20 @@ function aliasMaterialId(raw: unknown): unknown {
     );
   return { ...rest, materialId: resourceId };
 }
-export function createKilnMaterialDef(library: MaterialLibrary): KilnToolDef {
+export function createKilnMaterialDef(
+  library: MaterialLibrary,
+  presentation: 'grouped' | 'operations' = 'grouped',
+): KilnToolDef {
+  const listCall =
+    presentation === 'operations'
+      ? 'kiln_material_search({ scope: "saved" })'
+      : "kiln_material { action: 'list' }";
   return {
     name: 'kiln_material',
     description:
       'Manage optional immutable material resources in this workspace. presets discovers shipped architecture, wood, metal, fabric and ground recipes; create-preset bakes one with an explicit seed, creator and license; list returns compact material/revision summaries; get returns full provenance, hashes, map conventions, physical repeat scale and a code-ready portable material spec; create-procedural bakes bounded editable layer recipes including optional height-derived normals; import accepts complete normalized records with embedded PNG bytes. No action downloads URLs or executes source. Pin the returned materialId/revisionId through per-invocation materialDependencies or project dependencies before authored evaluation resolves the resources; no project is required.',
     inputSchema: materialToolInput,
+    actionContract: MATERIAL_CONTRACT,
     annotations: {
       readOnlyHint: false,
       destructiveHint: false,
@@ -126,7 +169,7 @@ export function createKilnMaterialDef(library: MaterialLibrary): KilnToolDef {
     async run(raw) {
       assertMaterialJson(raw);
       const input = materialToolInput.parse(aliasMaterialId(raw));
-      requireActionFields('kiln_material', input.action, input, REQUIREMENTS[input.action]);
+      requireActionFields('kiln_material', input.action, input, MATERIAL_CONTRACT[input.action]);
       switch (input.action) {
         case 'presets':
           return {
@@ -170,13 +213,14 @@ export function createKilnMaterialDef(library: MaterialLibrary): KilnToolDef {
           };
         }
         case 'get': {
-          const revisionId = input.revisionId ?? (await onlyRevision(library, input.materialId!));
+          const revisionId =
+            input.revisionId ?? (await onlyRevision(library, input.materialId!, listCall));
           try {
             return materialResult((await library.read(input.materialId!, revisionId)).manifest);
           } catch (error) {
             // Rule 9: an unknown id names the call that lists the known ones.
             if ((error as NodeJS.ErrnoException).code === 'ENOENT')
-              throw unknownMaterial(input.materialId!, revisionId);
+              throw unknownMaterial(input.materialId!, revisionId, listCall);
             throw error;
           }
         }