@instruktlabs/kiln 1.0.0 → 1.2.0

package/docs/sdk.md

@@ -2,7 +2,7 @@
 
 This describes the v1 package contract. Examples use `@instruktlabs/kiln`; install
 a published version or a qualified local archive as described in the
-[installation guide](install.md). Registry publication is a separate release gate.
+[installation guide](install.md). Use documentation matching the installed version.
 
 ## Imports
 
@@ -22,7 +22,8 @@ const result = await renderGLB(code);
 ```
 
 The complete authoring and host APIs remain available through documented subpaths.
-The existing 55 export paths are retained. The root exposes rendering, validation,
+The original 55 export paths are retained; version 1.1 adds four
+host entrypoints below. The root exposes rendering, validation,
 Discovery and engine identity; it does not re-export every name from every module.
 CommonJS is not part of this release's contract.
 
@@ -37,8 +38,8 @@ Use the existing material payload and asset-bundle encoders for portable deliver
 | Root library | `@instruktlabs/kiln` |
 | Authoring | `primitives`, `geometry`, `deform`, `sweep`, `architecture`, `assembly`, `character`, `vehicle`, `palette` |
 | Materials | `material-library`, `material-library/node`, `material-presets`, `material-recipes`, `material-resources`, `material-recipe-runtime`, `material-recipe-prompt`, `material-metrics`, `texture-resolver` |
-| Rendering and inspection | `render`, `views`, `validation`, `metrics`, `inspect`, `qa`, `asset-export`, `kit` |
-| Host contracts | `tools`, `evaluator`, `discovery`, `requirements`, `requirements/migration`, `contracts`, `prompt-api`, `profile` |
+| Rendering and inspection | `render`, `views`, `views/port`, `validation`, `metrics`, `inspect`, `qa`, `asset-export`, `kit` |
+| Host contracts | `tools`, `tools/input`, `mcp`, `evaluator`, `discovery`, `discovery/portable`, `requirements`, `requirements/migration`, `contracts`, `prompt-api`, `profile` |
 | Records and storage | `assets`, `projects`, `project-bundle`, `workspace`, `live-review`, `programs`, `cache`, and each corresponding `/node` adapter |
 | Composition | `composer`, `world-runtime` |
 | Ranking math | `arena` |
@@ -52,7 +53,7 @@ entrypoint list. Files inside `lib/`, including declaration dependencies under
 
 ## Stability in 1.x
 
-The table classifies all 55 public entrypoints. The root and every listed subpath
+The table classifies all 59 public entrypoints in version 1.1. The root and every listed subpath
 except `implicit` are stable entrypoints for v1: their declared public signatures,
 record shapes and documented behavior receive normal semantic-versioning
 compatibility. Optional dependencies do not make the two agent APIs experimental.
@@ -86,6 +87,26 @@ the remaining names do not by themselves promise browser compatibility. Portable
 record modules retain their existing boundaries. Browser use must follow a
 documented, qualified entrypoint rather than importing the entire Node host.
 
+### Embedding interfaces added in 1.1
+
+- `mcp` exports `createKilnMcpServer`, `createKilnToolHost` and `kilnMcpToolDefs`
+  for Node hosts, using the shared tool registry and injected `KilnToolContext`.
+  It is an in-process embedding API. The `kiln-mcp` executable keeps its separate
+  lazy engine loading; importing `mcp` loads the Node engine.
+- `discovery/portable` provides catalog/request validation, lexical indexing,
+  `createDiscoveryService` and retired-helper guidance. Supply a catalog generated
+  from the matching engine version. This browser-qualified entrypoint does not
+  import Node's built-in catalog construction or execute authored programs.
+- `tools/input` exposes the shared action requirements and input-error formatting
+  helpers without importing the engine registry or Node runtime.
+- `views/port` exposes the existing renderer-port helpers and types, including
+  `captureViewPngsViaPort`. Reuse their deadline, cancellation and PNG-validation
+  policy rather than implementing a second renderer adapter. It does not provide
+  a renderer or authorize trusted execution of untrusted source.
+
+These entries require 1.1 or later; 1.0.0 does not expose them.
+They contain no cloud-provider, account, tenant or hosted-service policy.
+
 `renderGLB` defaults to trusted in-process execution. A hosted service accepting
 untrusted programs must inject or select the qualified isolated evaluator described
 in the runtime contract. A subprocess provides a worker boundary; it does not alone
@@ -115,6 +136,29 @@ the stability of the helpers it uses. Exact details retain the same structured
 `stability` field. Implicit modeling remains available without a new opt-in switch;
 the community exporter retains its explicit selection.
 
+## Named operation presentation
+
+In package version 1.2.0 and later, embeddings can select
+`createKilnMcpServer(context, { toolPresentation: 'operations' })`, or obtain the
+same definitions through `createKilnOperationToolRegistry(context)` from `tools`.
+The default MCP and native interfaces retain their existing grouped tools.
+
+With asset and material storage, and without project/review or renderer-control
+callbacks, the named presentation exposes 21 tools. Asset browsing becomes
+`kiln_assets_search` with an optional collection; material browsing becomes
+`kiln_material_search` with `scope: 'all' | 'presets' | 'saved'`. Material creation
+uses `kiln_material_create` with a required `definition` discriminated by
+`kind: 'preset' | 'procedural'`. Saving, importing, retrieval and source restoration
+remain explicit operations. Renderer controls appear only when their callbacks
+exist. Connected `tools/list` remains authoritative.
+
+Action requirements and field constraints come from the shared engine registry.
+Generation rejects unclassified action/field additions and missing required
+fields. Hosts select supported operations and add their actual execution and
+persistence policy; do not copy domain schemas or assume a local read hint
+describes a quota-admitted cloud job. This API change does not publish a package
+or deploy a hosted service. Actual client acceptance is still required.
+
 ## Maintainer qualification
 
 `node scripts/build-runtime.mjs all` builds both executable bundles and the ESM SDK.