@metamesh/cli 0.18.0 → 0.20.0

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

@@ -0,0 +1,216 @@
+# Check and render with the CLI
+
+Look up installed APIs, check TypeScript, run local models, and inspect, render, or export the captured result.
+
+Use the `metamesh` CLI from your terminal, scripts, or coding agent. It finds the installed API
+documentation, checks TypeScript, runs models, and produces captures you can inspect, render,
+and export. You choose how these tools fit into your workflow.
+
+
+
+**Run source you trust**
+
+Local model code runs with your ordinary Node permissions. The disposable child process is not a
+  security sandbox.
+
+
+
+## Install and discover the environment
+
+Use Node.js 24 or newer. The package APIs publish ES modules only. TypeScript API consumers
+use TypeScript 6.0 or newer with `strict` checking and `NodeNext` or `Bundler` resolution;
+the CLI includes its source-checking compiler.
+
+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
+```
+
+`environment` reports project-resolved versions, documentation locations, available capabilities,
+and `authoringProtocolVersion: 1`. An agent integration should check that protocol value before
+using the commands. Fix missing packages, mismatched releases, or an unsupported protocol before
+authoring.
+
+Add the Generator SDK as a direct dependency when defining Generators, and Testkit when writing
+automated tests. Ordinary models need only Modeling and the CLI as 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`       | Generation runners, fixtures, and assertions for your 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 show modeling/guide/standalone-model
+pnpm exec metamesh docs search "cylinder"
+pnpm exec metamesh docs show modeling/reference/model/cylinder
+```
+
+Start with the [standalone model example](https://metamesh.studio/docs/develop/standalone-model), or use the
+[construction map](https://metamesh.studio/docs/develop/geometry-recipes#choose-a-technique) to choose an approach
+for your shape. You can also search for a shape or symbol and read its recipe or reference.
+Search matches distinct words in titles, headings, keywords, and summaries. Exact titles, IDs, and imports take priority;
+equally complete intent matches favor guides.
+
+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.
+
+For optional portable skills and project instructions, see
+[Work with a coding agent](agent-authoring.md). Use `--project PATH` consistently when
+targeting another directory so discovery, lookup, and execution resolve the same installation.
+
+## Model entries
+
+A model entry default-exports a `ModelProgram` and imports the installed package directly.
+Studio's virtual `@metamesh/project` module isn't available in local Node projects.
+
+Save the complete, rendered [standalone example](https://metamesh.studio/docs/develop/standalone-model) as `model.ts`,
+then check and run it:
+
+```bash
+pnpm exec metamesh typecheck model.ts --kind model
+pnpm exec metamesh run model.ts --kind model
+```
+
+Both commands check TypeScript types using the nearest project TypeScript configuration, or an
+explicit `--tsconfig`, with strict checking enforced. You can use ordinary local imports and
+installed dependencies. `typecheck` doesn't 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.
+
+To record which local fonts you used, also pass `--font-fixtures fonts.json`. The CLI verifies those
+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 aren't intercepted, so the CLI can't infer their asset identities. The source fingerprint
+covers bundled source, while fixture descriptors provide explicit asset provenance.
+
+## Generator entries
+
+Install the Generator SDK alongside Modeling and the CLI to define controls and package metadata:
+
+```bash
+pnpm add @metamesh/generator-sdk
+```
+
+A Generator entry named-exports `definition` and default-exports its module envelope:
+
+
+
+```ts
+import { defineGenerator } from "@metamesh/generator-sdk";
+import { defineGeneratorModel } from "@metamesh/generator-sdk/modeling";
+import { box } 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 }],
+});
+
+export default defineGeneratorModel(definition, ({ params, part }) =>
+  part("plate", box({ size: [params.width, 20, 6] }))
+);
+```
+
+
+
+`defineGeneratorModel` from the optional SDK `/modeling` adapter infers controls, prepared services,
+and assertion parameter IDs. It declares the ordinary Modeling program and package identity;
+the host still owns normalization, asset preparation, execution, and cleanup.
+
+```bash
+pnpm exec metamesh typecheck generator.ts --kind generator
+pnpm exec metamesh run generator.ts --kind generator --overrides 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 export RUN_DIRECTORY --format 3mf --output plate.3mf
+pnpm exec metamesh browser install
+pnpm exec metamesh render RUN_DIRECTORY
+pnpm exec metamesh render RUN_DIRECTORY --views top --format webp --transparent
+```
+
+
+
+**Inspect and render the same result**
+
+Both commands read the captured geometry without rerunning source. Your measurements and images
+  describe one completed run, even after its engine session has closed.
+
+
+
+Inspection reports part IDs, placements, colors, measurements, diagnostics, and execution provenance.
+Captures remain usable when their directory moves. Corrupt or incomplete artifacts are rejected.
+
+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` reads the completed capture and writes `3mf`, `stl`, or `glb` without rerunning source.
+The required `--output` selects the destination file; the result reports format limitations as
+structured diagnostics. 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
+
+Add Testkit when you want repeatable assertions in your own test runner:
+
+```bash
+pnpm add -D @metamesh/testkit
+pnpm exec metamesh docs show testkit/guide/testing
+```
+
+Testkit runs plain models and Generator entries and supplies geometry assertions. Test the real
+entry point with defaults, limits, and representative combinations. For cached models, exercise
+edits within one session and compare with uncached output; isolated runs cannot verify reuse.
+The installed testing guide owns the runner, fixture, and assertion signatures.
+
+Compare bounds in millimetres, area in square millimetres, and volume in cubic millimetres with
+explicit absolute tolerances. Use renders alongside assertions: closed topology alone does not
+establish fit, strength, or adequate wall thickness.
+
+Testkit has no compiler, renderer, or browser dependency. The CLI owns those tools and exposes
+reusable Node functions under `@metamesh/cli/authoring` for integrations that don't spawn a command.
+
+## Command results
+
+Add `--json` for one structured result on stdout; bounded author logs go to stderr. The default
+output is concise text. Exit codes are:
+
+- `0`: success;
+- `1`: source, parameter, or generation failure;
+- `2`: invocation, environment, artifact, or tooling failure.
+
+Runs default to a 30-second 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

@@ -1,8 +1,8 @@
 # `@metamesh/cli`
 
-Check, run, inspect, and render local MetaMesh models. The `metamesh` executable brings
-version-matched documentation, TypeScript checks, and captured geometry into one authoring workflow.
-The same tools are available through a Node API.
+Check and run MetaMesh models from your terminal. Save generated geometry, inspect its dimensions,
+and render previews from the same result. The `metamesh` command also reads documentation for
+your installed packages, and its tools are available through a Node.js API.
 
 > **Preview:** `0.x` minor releases may break compatibility. Patches remain compatible within the
 > same minor line.
@@ -20,62 +20,78 @@ The executable and Node API require Node.js 24 or newer. The API publishes ES mo
 TypeScript source and API consumers need TypeScript 6.0 or newer with `strict` checking and
 `NodeNext` or `Bundler` module resolution. The CLI includes its source-checking compiler.
 
-Add Generator SDK for Generator source and Testkit when importing testing helpers directly.
-Standalone model authoring needs neither as a direct dependency. Chromium setup is separate;
-checking, generation, and inspection work without a browser.
+Add the [Generator SDK](https://github.com/JasonKoolman/metamesh/blob/main/packages/generator-sdk/README.md)
+to author Generators, or [Testkit](https://github.com/JasonKoolman/metamesh/blob/main/packages/testkit/README.md)
+to import testing helpers directly. Standalone models need neither as a direct dependency.
+Only rendering needs Chromium; checking, generation, and inspection work without a browser.
 
 ## Local workflow
 
-Save a model entry as `model.ts`, default-exporting a `ModelProgram` from Modeling. Then discover
-the installed environment, look up the API, and build a captured result:
+Save this plate with a through hole as `model.ts`:
+
+```ts
+import { box, cylinder, generate } from "@metamesh/modeling";
+
+export default generate(({ part }) => {
+  const plate = box({ size: [30, 20, 6] });
+  const bore = cylinder({ height: 8, radius: 3, sizing: "face" });
+  return part("plate", plate.subtract(bore));
+});
+```
+
+From the same project, discover the installed packages, check the source, and capture a run:
 
 ```bash
 pnpm exec metamesh environment --json
 pnpm exec metamesh docs search "sweep"
 pnpm exec metamesh docs show modeling/guide/concepts
 pnpm exec metamesh typecheck model.ts --kind model
-pnpm exec metamesh run model.ts --kind model --export-3mf
+pnpm exec metamesh run model.ts --kind model
 pnpm exec metamesh inspect RUN_DIRECTORY
+pnpm exec metamesh export RUN_DIRECTORY --format 3mf --output plate.3mf
 ```
 
-Replace `RUN_DIRECTORY` with the path reported by `run`. Commands resolve packages and paths
-from the current project; use `--project PATH` to select another. `environment` reports the
-supported authoring protocol, package versions, and local documentation. Version mismatches fail
-before generation.
+Replace `RUN_DIRECTORY` with the path reported by `run`. Export that capture as 3MF, STL, or GLB.
+Commands resolve packages and paths from the current project; use `--project PATH`
+to select another. `environment` reports package versions, local documentation, and the supported
+authoring protocol. Version mismatches fail before generation.
 
+Local model entries default-export a `ModelProgram` created with Modeling's `generate` helper.
 For Generators, use `--kind generator` with a named `definition` export and a default Generator
-module. Pass `--overrides parameters.json` for input values. Generator overrides merge with defaults
-and undergo strict validation; standalone model parameters pass through directly. Studio's virtual
-`@metamesh/project` import is unavailable in local entries.
+module. Local entries import from the installed packages; Studio's virtual `@metamesh/project`
+module is unavailable here.
+
+Use `--params values.json` for a standalone model's complete input map, or
+`--overrides values.json` for a Generator. Generator overrides merge with defaults and undergo
+strict validation. Standalone model parameters pass through directly. The Node API uses the
+matching `params` and `overrides` fields, selected by `kind`.
 
 ## Authoring tools
 
-| Command                     | Purpose                                                                                |
-| --------------------------- | -------------------------------------------------------------------------------------- |
-| `environment`               | Discover project-local packages, capabilities, and documentation.                      |
-| `docs search` / `docs show` | Find and read exact-version guides and API references offline.                         |
-| `typecheck`                 | Check TypeScript and entry-point export types without executing the model.             |
-| `run`                       | Check and execute source, capture geometry and diagnostics, and optionally export 3MF. |
-| `inspect`                   | Read captured parts, bounds, measurements, and diagnostics.                            |
-| `render`                    | Create standard views from a capture.                                                  |
-| `setup`                     | Print skill installation and project-instruction guidance.                             |
-
-`run` uses a disposable child process with a 30-second default deadline and saves attempts under
-`.metamesh/runs`. Captures retain source identity, effective parameters, and hashed geometry.
-`inspect` and `render` validate those saved buffers without rerunning the source.
-
-Source executes with your account's permissions; this is trusted local execution, not a security
-sandbox. Use `--json` for structured stdout; 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. Each command's `--help` lists its options and limits.
-
-Use `--params values.json` for a standalone model's complete input map. For a Generator,
-use `--overrides values.json`; those values merge with definition defaults before strict
-validation. The Node API uses the matching `params` and `overrides` fields, discriminated by `kind`.
+| Command                     | Purpose                                                                    |
+| --------------------------- | -------------------------------------------------------------------------- |
+| `environment`               | Discover project-local packages, capabilities, and documentation.          |
+| `docs search` / `docs show` | Find and read exact-version guides and API references offline.             |
+| `typecheck`                 | Check TypeScript and entry-point export types without executing the model. |
+| `run`                       | Check and execute source, then capture geometry and diagnostics.           |
+| `export`                    | Save a capture as STL, 3MF, or GLB.                                        |
+| `inspect`                   | Read captured parts, bounds, measurements, and diagnostics.                |
+| `render`                    | Create standard views from a capture.                                      |
+| `setup`                     | Print skill installation and project-instruction guidance.                 |
+
+`run` executes source in a disposable child process with a 30-second default deadline and saves
+attempts under `.metamesh/runs`. Each capture records the source identity, effective parameters,
+and geometry hashes. `inspect`, `export`, and `render` validate the saved buffers and read that same result
+without rerunning the source.
+
+Source runs with your account's permissions. The child process is not a security sandbox; run
+source you trust. Use `--json` for structured stdout; author logs are bounded and sent to stderr.
+Exit codes are 0 for success, 1 for source or generation failure, and 2 for invocation, environment,
+artifact, or tooling failure. Each command's `--help` lists its options and limits.
 
 ## Render a capture
 
-Install the pinned Chromium explicitly, then choose views of the captured model:
+Install the CLI's pinned Chromium version, then choose views of the captured model:
 
 ```bash
 pnpm exec metamesh browser install
@@ -97,16 +113,21 @@ if (result.success) {
 ```
 
 `@metamesh/cli/authoring` also exposes environment discovery, documentation lookup, source checking,
-and rendering. `metamesh setup` prints guidance without changing project files. The portable
-`metamesh-developer` skill supplies the workflow; installed package documentation supplies API facts.
-Install a reviewed skill snapshot from the canonical `metamesh-studio/metamesh-skills` repository
-or its local checkout when public installation is unavailable.
+export, and rendering.
+
+For coding agents, `metamesh setup` prints skill installation and project-instruction guidance
+without changing files. The portable `metamesh-developer` skill describes the authoring workflow
+and uses installed package documentation for API details.
+Install a reviewed skill snapshot from
+[`metamesh-studio/metamesh-skills`](https://github.com/metamesh-studio/metamesh-skills) using your
+agent's skill tooling. The [agent guide](https://metamesh.studio/docs/develop/agent-authoring)
+explains how the skills and CLI fit into your own workflow.
 
 ## Documentation
 
 Resolve `@metamesh/cli/docs/manifest.json` for exact-version Markdown guidance and API references,
-or run `pnpm exec metamesh docs show cli/guide/agent-authoring`. The
-[authoring guide](https://github.com/JasonKoolman/metamesh/blob/main/apps/web/content/docs/develop/agent-authoring.mdx)
+or run `pnpm exec metamesh docs show cli/guide/local-authoring`. The
+[authoring guide](https://metamesh.studio/docs/develop/cli)
 covers entry contracts, parameters, fonts, captures, and rendering. See
 [Contributing](https://github.com/JasonKoolman/metamesh/blob/main/CONTRIBUTING.md) for package development.