@metamesh/cli 0.0.0-stage → 0.14.0

package/dist/authoring/worker.js

@@ -0,0 +1,163 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { captureSnapshot } from "./artifacts.js";
+import { AuthoringError, authoringFailure, isRecord } from "./errors.js";
+function program(value) {
+    return isRecord(value) && value.kind === "metamesh-model" && typeof value.generate === "function";
+}
+async function execute(request) {
+    let snapshot;
+    let dispose;
+    let phase = "execute";
+    try {
+        const entry = await import(pathToFileURL(request.modulePath).href);
+        if (!isRecord(entry))
+            throw new AuthoringError("execute", "INVALID_ENTRY", "Author entry is not a module.", 1);
+        let model;
+        let definition;
+        let parameters = request.params;
+        if (request.kind === "generator") {
+            phase = "parameters";
+            if (request.packagesPath === undefined || request.parametersPath === undefined)
+                throw new AuthoringError("environment", "SDK_NOT_INSTALLED", "Generator execution requires the installed SDK.");
+            const packages = (await import(pathToFileURL(request.packagesPath).href));
+            const params = (await import(pathToFileURL(request.parametersPath).href));
+            definition = packages.parseGeneratorDefinition(entry.definition);
+            const parsed = params
+                .createParamCodec(definition)
+                .safeParse({ ...params.getDefaultParameters(definition), ...request.params });
+            if (!parsed.success)
+                return {
+                    success: false,
+                    phase: "parameters",
+                    exitCode: 1,
+                    diagnostics: parsed.issues.map((issue) => ({ ...issue, severity: "error" })),
+                };
+            parameters = parsed.data;
+            const runtime = entry.default;
+            if (!isRecord(runtime) ||
+                runtime.formatVersion !== packages.GENERATOR_PACKAGE_FORMAT_VERSION ||
+                runtime.generatorId !== definition.id ||
+                runtime.version !== definition.version ||
+                !program(runtime.generate))
+                throw new AuthoringError("execute", "INVALID_GENERATOR_MODULE", "Default export must be the Generator module envelope matching definition.", 1);
+            model = runtime.generate;
+        }
+        else {
+            if (!program(entry.default))
+                throw new AuthoringError("execute", "INVALID_MODEL_PROGRAM", "Default export must be an ordinary ModelProgram.", 1);
+            model = entry.default;
+        }
+        phase = "assets";
+        const loaded = request.fontFixtures === undefined
+            ? undefined
+            : await (await import("@metamesh/testkit/font-fixtures")).loadFontFixtures(request.fontFixtures);
+        let services;
+        if (definition !== undefined) {
+            if (loaded !== undefined)
+                services = await loaded.prepareServices(definition, parameters);
+            else if (definition.parameters.some(({ type }) => type === "font"))
+                throw new AuthoringError("assets", "FONT_FIXTURES_REQUIRED", "Generator Font parameters require --font-fixtures <local-descriptors.json>.", 1);
+            else {
+                if (request.sdkPath === undefined)
+                    throw new AuthoringError("environment", "SDK_NOT_INSTALLED", "Generator execution requires the installed SDK.");
+                services = (await import(pathToFileURL(request.sdkPath).href))
+                    .UNPREPARED_GENERATOR_SERVICES;
+            }
+        }
+        phase = "execute";
+        const { createModelEngine } = (await import(pathToFileURL(request.enginePath).href));
+        const engine = await createModelEngine();
+        const session = services === undefined
+            ? engine.createSession(model, {
+                limits: request.metadata.policy.limits,
+            })
+            : engine.createSession(model, {
+                services,
+                limits: request.metadata.policy.limits,
+            });
+        dispose = () => session.dispose();
+        snapshot = session.run(parameters);
+        const exported = request.export3mf ? await engine.export3mf(snapshot.parts) : undefined;
+        phase = "artifact";
+        const selectedAssets = definition === undefined
+            ? (loaded?.selections ?? [])
+            : definition.parameters
+                .filter(({ type }) => type === "font")
+                .map(({ id }) => parameters[id])
+                .filter((value) => isRecord(value) &&
+                typeof value.faceId === "string" &&
+                typeof value.revision === "string" &&
+                typeof value.weight === "number");
+        const manifest = await captureSnapshot(request.directory, snapshot, { ...request.metadata, assets: selectedAssets, parameters }, exported);
+        return { success: true, runDirectory: request.directory, manifest };
+    }
+    catch (error) {
+        if (error instanceof AuthoringError)
+            return authoringFailure(error);
+        if (isRecord(error) || error instanceof Error) {
+            const shaped = error;
+            if (Array.isArray(shaped.issues))
+                return {
+                    success: false,
+                    phase,
+                    exitCode: 1,
+                    diagnostics: shaped.issues.map((issue) => ({
+                        ...issue,
+                        code: issue.code ?? "INVALID_DEFINITION",
+                        severity: "error",
+                    })),
+                };
+            if (Array.isArray(shaped.diagnostics))
+                return {
+                    success: false,
+                    phase,
+                    exitCode: 1,
+                    diagnostics: shaped.diagnostics.map((issue) => ({
+                        ...issue,
+                        code: issue.code ?? "GENERATION_ASSERTION",
+                    })),
+                };
+            if (typeof shaped.code === "string" && isRecord(shaped.context))
+                return {
+                    success: false,
+                    phase,
+                    exitCode: 1,
+                    diagnostics: [
+                        {
+                            code: shaped.code,
+                            severity: "error",
+                            message: error instanceof Error ? error.message : "Geometry failure",
+                            context: shaped.context,
+                        },
+                    ],
+                };
+        }
+        return {
+            success: false,
+            phase,
+            exitCode: phase === "artifact" ? 2 : 1,
+            diagnostics: [
+                {
+                    code: phase === "assets" ? "ASSET_PREPARATION_FAILED" : "EXECUTION_FAILED",
+                    severity: "error",
+                    message: error instanceof Error ? error.message : String(error),
+                    ...(error instanceof Error && error.stack !== undefined
+                        ? { context: { stack: error.stack } }
+                        : {}),
+                },
+            ],
+        };
+    }
+    finally {
+        snapshot?.dispose();
+        dispose?.();
+    }
+}
+const requestFile = process.argv[2];
+const resultFile = process.argv[3];
+if (requestFile !== undefined && resultFile !== undefined) {
+    const result = await execute(JSON.parse(await readFile(requestFile, "utf8")));
+    await writeFile(resultFile, JSON.stringify(result));
+}
+//# sourceMappingURL=worker.js.map

package/dist/authoring/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../../src/authoring/worker.ts"],"names":[],"mappings":"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"}

package/dist/authoring.d.ts

@@ -0,0 +1,12 @@
+/** Node-only authoring tools for trusted local MetaMesh source. */
+export { AUTHORING_PROTOCOL_VERSION } from "./authoring/types.js";
+export type { AuthoringDiagnostic, AuthoringEnvironment, AuthoringFailure, AuthoringKind, AuthoringPhase, CapturedBuffer, CapturedGeometry, CapturedPart, CapturedResource, CapturedRun, CapturedRunManifest, CheckOptions, CheckSuccess, DocumentationEntry, DocumentationManifest, InstalledAuthoringPackage, RunOptions, RunSuccess, } from "./authoring/types.js";
+export { AuthoringError, authoringFailure } from "./authoring/errors.js";
+export { discoverAuthoringEnvironment, searchAuthoringDocumentation, showAuthoringDocumentation, } from "./authoring/environment.js";
+export type { DocumentationSearchResult } from "./authoring/environment.js";
+export { checkAuthoringSource } from "./authoring/check.js";
+export { runAuthoringSource } from "./authoring/run.js";
+export { inspectCapturedRun, readCapturedRun } from "./authoring/artifacts.js";
+export { renderCapturedRun, installAuthoringBrowser } from "./authoring/render.js";
+export type { RenderOptions, RenderResult, RenderView, RenderFormat, RenderCamera, RenderedImage, } from "./authoring/render-types.js";
+//# sourceMappingURL=authoring.d.ts.map

package/dist/authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,mBAAmB,EACnB,YAAY,EACZ,YAAY,EACZ,kBAAkB,EAClB,qBAAqB,EACrB,yBAAyB,EACzB,UAAU,EACV,UAAU,GACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACnF,YAAY,EACV,aAAa,EACb,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,YAAY,EACZ,aAAa,GACd,MAAM,6BAA6B,CAAC"}

package/dist/authoring.js

@@ -0,0 +1,9 @@
+/** Node-only authoring tools for trusted local MetaMesh source. */
+export { AUTHORING_PROTOCOL_VERSION } from "./authoring/types.js";
+export { AuthoringError, authoringFailure } from "./authoring/errors.js";
+export { discoverAuthoringEnvironment, searchAuthoringDocumentation, showAuthoringDocumentation, } from "./authoring/environment.js";
+export { checkAuthoringSource } from "./authoring/check.js";
+export { runAuthoringSource } from "./authoring/run.js";
+export { inspectCapturedRun, readCapturedRun } from "./authoring/artifacts.js";
+export { renderCapturedRun, installAuthoringBrowser } from "./authoring/render.js";
+//# sourceMappingURL=authoring.js.map

package/dist/authoring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.js","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAqBlE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EACL,4BAA4B,EAC5B,4BAA4B,EAC5B,0BAA0B,GAC3B,MAAM,4BAA4B,CAAC;AAEpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/docs/guides/agent-authoring.md

@@ -0,0 +1,240 @@
+# Author and inspect models with an agent
+
+Find installed documentation, check TypeScript, generate a captured model, and inspect its measurements and rendered views locally.
+
+The `metamesh` CLI gives coding agents and developers the same local workflow: look up the
+installed API, check source, execute the real engine, and inspect a captured result. It runs trusted
+local TypeScript with your ordinary Node permissions. The child process is disposable; it is not a
+security sandbox.
+
+## Install and discover the environment
+
+Install Modeling for your model code and the CLI for the local authoring workflow:
+
+```bash
+pnpm add @metamesh/modeling
+pnpm add -D @metamesh/cli
+pnpm exec metamesh environment --json
+pnpm exec metamesh setup
+```
+
+`environment` reports project-resolved versions, documentation locations, available capabilities,
+and `authoringProtocolVersion: 1`. An agent integration should check that protocol value before
+using the commands. Missing packages, mismatched releases, or an unsupported protocol need an
+environment fix before authoring.
+
+Add the Generator SDK as a direct dependency when defining Generators, and Testkit when writing
+automated tests. A project that only runs ordinary models needs Modeling and the CLI as its direct
+dependencies. Keep installed MetaMesh packages on matching releases.
+
+| Component                 | Responsibility                                                                                |
+| ------------------------- | --------------------------------------------------------------------------------------------- |
+| `@metamesh/modeling`      | Geometry operations, synchronous generation, engine sessions, and completed snapshots         |
+| `@metamesh/generator-sdk` | Serializable controls, parameter types and validation, and Generator module envelopes         |
+| `@metamesh/cli`           | Installed documentation lookup, TypeScript checking, captured runs, inspection, and rendering |
+| `@metamesh/testkit`       | Test runners, fixtures, and assertions used by your existing test framework                   |
+
+Every public package exposes its offline documentation manifest through `./docs/manifest.json`.
+The CLI searches the packages installed in the selected project. Find a topic in the bounded index,
+then read the returned document ID:
+
+```bash
+pnpm exec metamesh docs search "cylinder"
+pnpm exec metamesh docs show modeling/reference/model/cylinder
+```
+
+Documentation is resolved from the selected project through package exports. No global installation
+or documentation fetched from a moving Git branch replaces the installed version.
+
+### Give an agent the same workflow
+
+`setup` prints skill installation guidance and a project-instruction snippet for review. It does
+not modify files, install a skill, or initialize a model. The optional `metamesh-developer` skill
+describes the authoring and verification workflow; `metamesh-docs` supports documentation work.
+Both are maintained separately in `metamesh-studio/metamesh-skills`.
+
+Use a reviewed skill snapshot provided by your project or installed through your agent's skill
+tooling. The printed GitHub installation source must be published before that command can work;
+a skill is optional for the CLI workflow below. Skills teach the process. The installed npm
+documentation owns exact signatures, import paths, units, lifecycle, and availability.
+
+Project instructions should ask the agent to discover the environment, look up relevant installed
+topics, check and run the current source, then inspect measurements and render useful views from
+that same run directory. Include the commands and required checks that belong to your project.
+When targeting another project directory, pass `--project PATH` consistently so discovery, lookup,
+checking, and execution resolve the same installation.
+
+## Model entries
+
+A model entry default-exports an ordinary `ModelProgram`. It imports the real package; Studio's
+virtual `@metamesh/project` module is not available in local Node projects.
+
+
+
+```ts
+import { box, cylinder, generate } from "@metamesh/modeling";
+
+export default generate<Record<never, never>>(({ part }) => {
+  const body = box({ size: [30, 20, 6] });
+  const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+  return part("plate", body.subtract([bore]));
+});
+```
+
+
+
+Save this as `model.ts`, then check and run it:
+
+```bash
+pnpm exec metamesh check model.ts --kind model
+pnpm exec metamesh run model.ts --kind model --export-3mf
+```
+
+Both commands perform semantic TypeScript checking. They use the nearest project TypeScript
+configuration, or an explicit `--tsconfig`, with strict checking enforced. Ordinary local imports
+and installed dependencies are supported. `check` does not evaluate your source.
+
+Use `--params values.json` for a model's JSON parameter map; the default is `{}`. Models do not
+receive injected Generator services. A standalone module can prepare licensed local fonts before
+constructing its synchronous generation program.
+
+For standalone font provenance, also pass `--font-fixtures fonts.json`. The CLI verifies those local
+bytes and records their declared font selections and immutable revisions in the capture; the model
+still prepares its own fonts and receives no injected services. Arbitrary filesystem or network
+reads are not intercepted, so their asset identities cannot be inferred. The source fingerprint
+covers bundled source, while fixture descriptors provide explicit asset provenance.
+
+## Generator entries
+
+Install the Generator contract layer in addition to Modeling and the CLI:
+
+```bash
+pnpm add @metamesh/generator-sdk
+```
+
+A Generator entry named-exports `definition` and default-exports its module envelope:
+
+
+
+```ts
+import {
+  defineGenerator,
+  defineGeneratorModule,
+  type GeneratorParams,
+} from "@metamesh/generator-sdk";
+import { box, generate } from "@metamesh/modeling";
+
+export const definition = defineGenerator({
+  id: "plate",
+  version: "0.1.0",
+  title: "Plate",
+  groups: [],
+  parameters: [{ id: "width", label: "Width", type: "number", default: 30, min: 1 }],
+});
+
+const model = generate<GeneratorParams<typeof definition>>(({ params, part }) =>
+  part("plate", box({ size: [params.width, 20, 6] }))
+);
+
+export default defineGeneratorModule({ definition, generate: model });
+```
+
+
+
+```bash
+pnpm exec metamesh check generator.ts --kind generator
+pnpm exec metamesh run generator.ts --kind generator --params values.json
+```
+
+Generator runs merge declared defaults with explicit overrides, then validate strictly. Unknown
+keys, invalid values, and unsupported combinations produce diagnostics. They are not silently
+clamped or repaired. Use assertions for relationships between parameters.
+
+Generators with Font controls supply a local font-fixture descriptor with `--font-fixtures fonts.json`.
+Fixtures resolve beside that descriptor and must match their immutable revisions. Missing
+bytes and revision mismatches fail before generation; the CLI does not fetch catalog fonts.
+
+## Inspect the captured result
+
+Each run creates a unique directory under `.metamesh/runs`, or the explicit output parent. Use the
+run directory reported by that command as `RUN_DIRECTORY` below:
+
+```bash
+pnpm exec metamesh inspect RUN_DIRECTORY
+pnpm exec metamesh inspect RUN_DIRECTORY --part plate
+pnpm exec metamesh browser install
+pnpm exec metamesh render RUN_DIRECTORY
+pnpm exec metamesh render RUN_DIRECTORY --views top --format webp --transparent
+```
+
+Inspection reads finalized geometry facts, including semantic part IDs, placements, colors,
+measurements, diagnostics, and execution provenance. Rendering reads the same captured buffers
+without executing the model again. Artifacts remain usable after the engine session is disposed or
+the run directory is moved. Corrupt or incomplete artifacts reject.
+
+Rendering requires the separately installed pinned Chromium. It is never downloaded implicitly;
+checking, generation, and inspection work without it. Standard orthographic views are isometric,
+front, top, and right. The default is an isometric 1024 × 1024 PNG on a neutral background. WebP is
+lossless; PNG and WebP both support explicit transparent output. Images record their run, camera,
+renderer, and browser versions. Compare pixels only within the pinned capture environment.
+
+`--export-3mf` exports that run's finalized snapshot. A failed attempt never exposes an older
+successful result as its output. Match the captured parameters and source fingerprint to the
+revision you intended to verify.
+
+## Test models
+
+Install Testkit separately when you want assertions and fixtures for your existing test runner:
+
+```bash
+pnpm add -D @metamesh/testkit
+```
+
+Use `createGeneratorTestRunner(definition, runtime)` for a Generator's persistent generation
+session. Its `execute` method returns a discriminated result: handle `type: "invalid"` before
+reading a generated `model`. Dispose each successful `model` when finished and dispose the runner
+separately; snapshots remain usable after the runner is disposed.
+Unexpected execution or malformed-output errors reject instead of returning an `invalid` result.
+For an ordinary `ModelProgram`, use an [engine session](https://metamesh.studio/docs/engine/hosting) and the same assertions
+against its completed snapshot.
+
+The runner normalizes saved values. To probe deliberately invalid typed inputs without that
+recovery, call `runner.validate(parameters, { normalize: false })`. Validation checks declarations
+and reached assertions without finalizing output; execute representative valid combinations too.
+The CLI's strict overrides serve a different purpose: they reject invalid or unknown values
+before execution instead of recovering saved state.
+
+| Helper                         | What to check                                                      |
+| ------------------------------ | ------------------------------------------------------------------ |
+| `expectSerializableDefinition` | Strict definition parsing and a canonical JSON round trip          |
+| `expectValidDefaults`          | Strict parameter decoding and agreement with defaults              |
+| `expectValidPresets`           | Serializable preset metadata; execute presets for domain rules     |
+| `expectValidParts`             | Part metadata, closed oriented topology, and native reconstruction |
+| `expectMeshMeasurements`       | Bounds, area, signed volume, and connected-component count         |
+
+Compare physical measurements with explicit absolute tolerances; bounds use millimetres, area
+square millimetres, and volume cubic millimetres. Component counts are exact. Rendered views
+complement those assertions. A valid solid alone does not prove a suitable fit or manufacturable
+wall thickness.
+
+For Font controls, supply the runner's `prepareServices` option using checked-in licensed bytes.
+`prepareFontTestServices` from `@metamesh/testkit/fonts` verifies immutable font revisions and
+prepares services without catalog downloads. Modeling's optional font peers are still required.
+Use installed documentation for the exact runner and fixture signatures:
+
+```bash
+pnpm exec metamesh docs show testkit/guide/testing
+```
+
+Testkit has no compiler, renderer, or browser dependencies. The CLI owns those tools and its
+reusable Node functions under `@metamesh/cli/authoring`; integrations can call them without
+spawning the command.
+
+## Command results
+
+The CLI defaults to concise human output. Add `--json` for one structured stdout result, with
+bounded author logs on stderr. Exit status is `0` for success, `1` for source, parameter, or
+generation failure, and `2` for invocation, environment, artifact, or tooling failure. Runs have a
+30-second default execution deadline and can lower engine resource ceilings.
+
+Modeling and the Generator SDK remain independent of the CLI and its local Node tooling.

package/dist/docs/guides/package.md

@@ -0,0 +1,87 @@
+# `@metamesh/cli`
+
+Check, execute, inspect, and render trusted local MetaMesh source. The `metamesh` executable and
+Node-only `/authoring` functions use the production engine and version-matched installed documentation.
+
+> **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
+> same minor line.
+
+## Installation
+
+Install the same exact release of each MetaMesh package in the project where you author models:
+
+```bash
+pnpm add @metamesh/modeling
+pnpm add -D @metamesh/cli
+```
+
+Add `@metamesh/generator-sdk` when your source defines Generators. Add `@metamesh/testkit` as a
+development dependency when importing testing helpers. CLI internally reuses Testkit font fixtures
+and its SDK contracts; neither package needs to be directly declared for standalone model authoring.
+The compiler, bundler, Three renderer, and Playwright belong to CLI; Testkit does not install them.
+Chromium is installed separately and never downloaded by checking or generation.
+
+## Local workflow
+
+```bash
+pnpm exec metamesh environment --json
+pnpm exec metamesh docs search "extrude"
+pnpm exec metamesh docs show TOPIC_ID
+pnpm exec metamesh check model.ts --kind model
+pnpm exec metamesh run model.ts --kind model
+pnpm exec metamesh inspect RUN_DIRECTORY
+pnpm exec metamesh browser install
+pnpm exec metamesh render RUN_DIRECTORY --views isometric,front,top,right
+```
+
+`environment` reports `authoringProtocolVersion: 1`, installed package versions, capabilities,
+and documentation manifest paths. Mixed package versions or stale documentation fail before
+generation. Commands resolve packages and relative paths from the current project; pass
+`--project PATH` to select another project explicitly. `TOPIC_ID` comes from documentation search;
+`RUN_DIRECTORY` comes from a successful run.
+
+`run` includes semantic TypeScript checking and executes in a disposable child process with a
+30-second default deadline. It saves each attempt beneath `.metamesh/runs` with source identity,
+parameters, diagnostics, measurements, and hashed geometry buffers. `inspect` and `render` validate
+those captured buffers without importing the original source. Use `--json` for one structured stdout
+result; bounded author logs go to stderr. Exit codes are 0 for success, 1 for source or generation
+failure, and 2 for invocation, environment, artifact, or tooling failure. This executes trusted local
+code and is not a security sandbox.
+
+For Generators, use `--kind generator`. Entries named-export `definition` and default-export the
+Generator module envelope. Defaults merge with `--params parameters.json`, then strict validation
+rejects unknown or invalid overrides. Standalone model entries default-export a `ModelProgram` and
+receive no injected services. Both support normal local imports and installed dependencies; Studio's
+virtual `@metamesh/project` module is unavailable.
+
+Use `--help` on each command for parameters, fonts, resource limits, export, and image options.
+`metamesh setup` prints installation guidance for `metamesh-developer` from the canonical
+`metamesh-studio/metamesh-skills` repository and a project-instruction suggestion without modifying
+files. Its printed GitHub installation command becomes usable when that repository is published;
+the skill supplies the workflow, while installed package documentation supplies exact API facts.
+
+## Programmatic API and documentation
+
+```ts
+import { inspectCapturedRun, runAuthoringSource } from "@metamesh/cli/authoring";
+
+const result = await runAuthoringSource({ entry: "model.ts", kind: "model" });
+if (result.success) {
+  console.log(await inspectCapturedRun(result.runDirectory));
+}
+```
+
+Resolve `@metamesh/cli/docs/manifest.json` for the installed Markdown reference, or run
+`pnpm exec metamesh docs show cli/guide/agent-authoring` for the complete authoring workflow.
+The [authoring guide source](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/agent-authoring.mdx)
+also covers local font fixtures, artifacts, rendering, and agent integration. Until the public
+documentation site launches, use installed documentation, repository sources, or
+[run the docs locally](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/README.md#local-use).
+
+The reusable authoring functions and command implementation stay in this package; geometry and
+Generator contracts retain their existing owners. Testing assertions and font-fixture adapters
+remain in Testkit.
+
+## License
+
+[Apache-2.0](https://github.com/JasonKoolman/metamesh/blob/main/packages/cli/LICENSE).