rtistree 0.5.1 → 0.6.0

package/docs/engine-overview.md

@@ -1,174 +1,130 @@
-# Rtistree
-
-A deterministic raster graphics engine that agents can inspect, edit, verify, and replay. A persistent scene is the source of truth; PNG, JPEG, TIFF, PDF and SVG are outputs.
-
-Version 0.4 adds a programmable digital-art studio: seeded raster programs, pressure brushes, texture fields, warps, displacement, height-field lighting and dense regional edits. Programs bake to pinned assets with portable, replayable recipes; normal rendering never executes code. See the [studio guide](studio.md), [decision](decisions/005-programmable-digital-art.md) and [wheel trial made without image generation](../examples/manual-wheel-trial/README.md).
-
-TypeScript provides the scene schema, transactions, CLI, and MCP tool server. The next-stage implementation includes attached painting, adaptive patches, incremental layer rendering, visual critique and source rebasing. **Native CPU Skia** performs rendering through `@napi-rs/canvas`. No browser, WebGL, GPU, model API key, or external service is required.
-
-![Poster rendered by Rtistree](previews/poster.png)
-
-## Print production and new projects
-
-Version 0.3 adds physical documents, ICC-managed CMYK exports, embedded PDF fonts/vector geometry, project creation, source crops/perspective, mask algebra, tonal adjustments, clone/heal, path booleans and richer typography. See the [production guide](production.md), [recorded decisions](decisions/004-print-production-and-projects.md) and [masked generated-asset print trial](../examples/print-trial/README.md).
-
-```sh
-graphics project new artwork --size A3 --orientation landscape --ppi 300 --bleed 3mm
-graphics render artwork --preset screen
-# Configure the printer/paper ICC profile in rtistree.yaml before CMYK export.
-graphics preflight artwork --preset print
-graphics export artwork --preset print --format pdf
-```
-
-Print PDFs encode exact trim/bleed dimensions and are reopened for validation. PDF/X certification, spot colours and overprint are not claimed. The engine remains an 8-bit sRGB working renderer with explicit colour-managed output.
-
-## Run it
-
-Requires Node.js 22 or newer. Dependencies and bundled fonts are pinned in `package-lock.json`.
-
-```sh
-npm ci
-npm run build
-npm test
-npm run demo
-```
-
-The demo renders a poster, measures an underlit region, applies a local correction, and checks replay, undo, redo, and a self-contained export. It writes before/after images and evidence into `examples/poster/renders/`, plus a landscape into `examples/landscape/renders/`. Every demo run uses a fresh working project and leaves the example's authoring files untouched.
-
-The recorded poster benchmark changes **4,704 pixels inside a 56 × 84 region, zero pixels outside**, improves rule verification from fail to pass, and reproduces identical PNG bytes after reopen, undo/redo, and export. This establishes mechanical correctness, not a general measure of artistic quality. See [recorded evidence](previews/benchmark.json).
-
-Use the executable after building:
-
-```sh
-node dist/cli.js render examples/poster/scene.yaml -o /tmp/poster.png
-node dist/cli.js inspect examples/poster/scene.yaml
-node dist/cli.js inspect-region examples/poster/scene.yaml 755 610 56 84
-node dist/cli.js apply examples/poster/scene.yaml examples/poster/refine.json
-node dist/cli.js verify examples/poster/scene.yaml
-node dist/cli.js render examples/poster/scene.yaml -o /tmp/refined.png
-node dist/cli.js undo examples/poster/scene.yaml
-node dist/cli.js redo examples/poster/scene.yaml
-node dist/cli.js export examples/poster/scene.yaml -o /tmp/rtistree-export/scene.json
-```
-
-`npm run graphics -- …` runs the same CLI from source. Installing the package exposes the `graphics` executable. `graphics --help` lists commands. JSON goes to stdout; errors go to stderr. Verification failures exit with code 2, other failures with code 1.
-
-## Compose a project from files
-
-A manifest can reference as many independently authored fragments as needed:
-
-```yaml
-version: 1
-canvas:
-  width: 1024
-  height: 1024
-  background: '#102c31'
-include:
-  - layers/background.yaml
-  - layers/product.yaml
-  - layers/typography.yaml
-```
-
-Each fragment contains `layers`, optional `assets`, and optional nested `include` paths. Paths resolve relative to the declaring file and must stay inside the project. Layer and asset IDs share a project namespace. Included layers compose in declaration order, followed by local layers; sibling `z` values determine paint order. Groups preserve hierarchy.
-
-The [poster example](../examples/poster/scene.yaml) uses this format. [Scene format documentation](scene-format.md) describes coordinates, layout, operations, and validation.
+# Engine overview
+
+Rtistree is a local TypeScript/Node.js graphics engine with a CLI, SDK and stdio MCP
+server. Native CPU Skia renders the scene; Sharp and PDFKit handle artwork exports.
+The renderer needs no browser, GPU, model API key or external service. An agent host
+supplies its own model, image inspection and visual judgment.
+
+Start with [getting started](getting-started.md) for an installed npm package.
+The commands in the development section below require a repository checkout.
+
+## Scene and authoring model
+
+JSON/YAML source scenes can include fragments and parameterized components. The loader
+expands them into one validated layer tree. Layers support groups, paths, text,
+local image assets, procedural fills, layouts, transforms, masks and adjustments.
+Raster operations, sparse palette tiles and promoted regions add focused pixel edits.
+See [scene format](scene-format.md) and [editing workflows](evolution.md).
+
+Pixel-art scenes can opt into explicit integer, palette and nearest-neighbour
+guardrails. Sprite manifests describe frame rectangles, pivots, durations, tags and
+animation ordering; the sprite exporter packs them into a deterministic atlas without
+making Rtistree responsible for a game engine's runtime. See [pixel art, sprites and
+spritesheets](sprites.md).
+
+Layer IDs are unique throughout the tree. Assets, fonts and components each have their
+own ID map; they do not share the layer-ID namespace. Relative include and asset paths
+resolve from the declaring source file and must remain inside the root scene directory.
+
+For painting, trusted JavaScript programs use Canvas, seeded brushes, fields and pixels.
+Programs bake to ordinary image assets and pin source, parameters and inputs in recipes.
+[Explicit pipelines](atelier.md) rebuild changed dependencies with caching. Rendering and
+opening a scene do not execute those programs. The VM is not a security sandbox.
+
+Physical document dimensions and print sampling resolution are separate from design pixels.
+[Print production](production.md) covers PNG/JPEG/TIFF/PDF/SVG exports, profiles,
+physical page boxes, preflight and soft proofs. The working renderer is 8-bit sRGB;
+PDF/X certification, spot colours and overprint are not implemented.
+
+## Editing and persistence
+
+`Project.open(path)` accepts a scene file, `rtistree.yaml` or a configured project directory.
+`project.scene()` returns the current resolved state. `project.render()` returns PNG bytes,
+pixels and evidence; `project.inspect()` and `project.inspectLayer(id)` return structure.
+`project.apply({reason, expected_hash, commands})` validates and commits a typed transaction.
+The SDK exports `Project`, `SkiaRenderer`, schemas, command helpers, render/verification
+functions, `runProgram`, `buildPipeline`, `exportSpriteSheet`, `production` and the
+art-direction guide.
+
+Authoring files remain the baseline. Mutations append to
+`history/<scene-filename>.operations.jsonl`; journal records include state snapshots,
+commands, hashes, timestamps and measured locality. Failed transactions leave the working
+scene unchanged. Scoped raster edits compare the final composite before and after and
+reject pixels changed outside the allowed area. Structural edits have no general locality promise.
+
+Undo and redo append records. After manual source changes, `rebase` merges disjoint edits
+against the retained baseline and reports conflicts without committing. `compact` compresses
+journal records while retaining undo/redo; replay still reads the full history. Remove a stale
+lock only after confirming its recorded writer is no longer active.
+
+Portable export creates a new baseline with referenced assets, custom fonts, recipes and
+configured print profiles. It preserves the current artwork and inline pipeline graph,
+but does not copy edit history, critiques or production-session reviews and candidates.
 
 ## Agent interface
 
-Art-direction guidance ships with the engine. MCP clients receive concise rules
-at connection time and can read the full versioned guide through `studioHelp` or
-the `rtistree://guides/art-direction` resource. CLI agents use `graphics art-guide`
-without opening a project. SDK hosts can include `rtistreeAgentInstructions` in
-their agent context and expose `artDirectionGuide`.
-
-The guide includes representative-sample workflows, connected figure construction,
-shared prop perspective, ground-contact animation checks, lessons from failed
-asset trials and a starter production plan using existing review gates. Technical,
-functional and visual acceptance are separate. This makes the knowledge available
-to new agents; it does not guarantee that every client presents it or every model
-follows it. See [the agent workflow](agent-art-workflow.md).
-
-Start the MCP server with a scene:
-
-```sh
-node dist/cli.js serve /absolute/path/to/scene.yaml
-```
-
-Configure an MCP client to launch `node`, with the absolute path to `dist/cli.js`, `serve`, and the absolute scene path as arguments. Transport is stdio; the server writes only protocol messages to stdout.
-
-Tools: `inspectScene`, `inspectLayer`, `inspectRegion`, `render`, `renderRegion`, `apply`, `undo`, `redo`, `verify`, `history`, `recordCritique`, `readCritique`, `rebase`, `compactHistory`, `exportArtwork`, `preflight`, `softProof`, `studioHelp`, `runProgram`, `replayProgram`, `readRasterRegion`, `writeRasterRegion`. Image tools return PNG image content so a vision-capable agent can inspect the result. `apply` advertises a typed command schema and requires an explanation. Supply the scene hash returned by inspection to reject stale edits.
-
-```json
-{
-  "reason": "Brighten the underlit detail without changing the surrounding composition",
-  "expected_hash": "sha256:…",
-  "commands": [
-    {
-      "type": "applyRasterOperation",
-      "target": "cover",
-      "operation": {
-        "type": "brightness",
-        "bounds": [755, 610, 56, 84],
-        "amount": 0.06
-      }
-    }
-  ]
-}
-```
-
-The SDK also exposes `Project`, `SkiaRenderer`, `parseScene`, layout and verification functions, and `runIterations(project, editingAgent, options)`. The injected agent receives the scene, PNG, and verifier report and returns a patch or `null`. Iteration budgets, stale-state checks, stall thresholds, and cancellation bound the loop. An optional typed `critic` callback adds visual feedback; `requireCritique: true` requires a current critique before passing, and unresolved medium/high findings prevent success. Model choice and vision critique stay outside the renderer; there is no built-in LLM or diffusion service.
-
-## Persistence and reproducibility
-
-Authoring fragments remain intact. Successful mutations append a transaction to `history/<scene-filename>.operations.jsonl`. Each record stores its commands, reason, full resolved state, previous-record hash, input/output scene hashes, asset hashes, and measured locality. Reads replay this journal over the original scene. Undo/redo append records rather than deleting history. Full state snapshots favor correctness and recovery over storage efficiency in this MVP.
-
-A failed batch leaves the scene unchanged. A project lock prevents concurrent writers; an expected scene hash handles stale agents. Incomplete or altered journal records are rejected. If a writer crashes, inspect the PID in the `.lock` file before removing the stale lock. After manual source edits, run `graphics rebase scene.yaml` to merge nonconflicting changes into the working state. Conflicts report exact paths without committing. `graphics compact scene.yaml` compresses history while retaining every undo/redo state. New histories retain their source baseline; legacy histories require restoring/exporting the original source before rebasing. Changed raster asset bytes are also rejected after history exists.
-
-Exports copy raster assets and custom fonts into content-addressed files and pin their hashes. Every PNG has a `.evidence.json` sidecar recording renderer/backend/runtime versions, scene hash, asset hashes, bundled font hashes, dimensions, quality, and PNG hash. Byte identity is tested on the same pinned runtime and platform. Cross-platform Skia byte identity is **not** promised.
-
-## Implemented scope
-
-- JSON/YAML scenes and recursive multi-file composition; strict validation and JSON Schema generation.
-- Groups, semantic roles, shapes and SVG-style paths, text wrapping, local PNG/JPEG/WebP assets, gradients, seeded noise, transforms, row/column layouts, anchors, percentages, opacity, and nine blend modes.
-- Rectangle, ellipse, polygon and semantic-alpha masks; feathering, layer blur, and adjustment layers.
-- Scoped fill, paint/erase strokes, blur, brightness, contrast, saturation, hue shifts, noise, colour replacement, direct pixels, and palette tiles. Binary rasters remain external assets.
-- Exact region crops, structural/color inspection, append-only transactions, undo/redo, self-contained export, CLI, and MCP.
-- Text overflow, declared contrast, safe-area, overlap, copy/role and region-luma rules, issue heatmaps, measured edit locality, and bounded agent iterations.
-
-The remaining extensions are automatic quadtree subdivision, a general dirty-tile compositor, advanced SVG import, mesh warp/smudge, general segmentation, provider-specific model integrations, learned asset generation, and animation. Draft still downsamples after rendering. Safe pointwise region scenes use smaller viewport surfaces; antialias-sensitive scenes fall back to a full composite and exact crop.
-
-## Next-stage examples and agent trials
-
-See [the new API and workflows](evolution.md) and [ADR 003](decisions/003-editing-refinement-and-agent-validation.md). New features include mutable effects/operations, object-relative paint, promoted patches at 1–4× resolution, layer caching, rendered contrast/visibility rules, hash-bound visual critiques, component instances, custom fonts, source rebasing and compressed history.
-
-Three interactive trials are recorded in [agent-trials/results.json](../examples/agent-trials/results.json), with before/after images, briefs, complete audit snapshots and portable final scenes. Corrections were selected after inspecting the images. The visual scores are same-agent judgments; these are not independent quality evaluations, and token usage was unavailable. All three final scenes passed their configured checks and reproduced after export. The pear trial preserved every checked nonfruit pixel.
-
-```sh
-node dist/cli.js render examples/agent-trials/reading-club/final/scene.json -o /tmp/reading-club.png
-node dist/cli.js render examples/agent-trials/pear/final/scene.json -o /tmp/pear.png
-npm run performance
-```
-
-The performance probe records cache counters and local timings in `docs/previews/performance.json`. Its 16-layer edit reuses 15 surfaces and rasterizes one, while matching an uncached render exactly.
-
-See [architecture decisions](decisions/001-runtime-and-renderer.md), [multi-file persistence decision](decisions/002-composable-scenes-and-history.md), and the original [architecture proposal](../agentic-raster-graphics-architecture.md).
-
-## Development
+The [agent setup guide](agent-setup.md) explains CLI, MCP and SDK integration.
+MCP tools are:
+
+- Inspection and images: `inspectScene`, `inspectLayer`, `inspectRegion`, `render`, `renderRegion`.
+- Editing and history: `apply`, `undo`, `redo`, `history`, `rebase`, `compactHistory`.
+- Verification and review: `verify`, `recordCritique`, `readCritique`.
+- Painting: `studioHelp`, `runProgram`, `replayProgram`, `readRasterRegion`, `writeRasterRegion`.
+- Staged work: `buildPipeline`, `production`.
+- Artwork export: `exportArtwork`, `exportSprites`, `preflight`, `softProof`.
+
+MCP rendering/crop tools return PNG image content. Production capture and comparison return
+artifact paths in JSON; the host needs a way to open those images. The MCP server operates
+on the project passed to `serve`; project creation, SVG import, portable scene export and
+interactive benchmarks are available through the CLI/SDK, not separate MCP tools.
+
+The exported `runIterations(project, editingAgent, options)` supports bounded edit loops.
+The injected agent receives the scene, PNG and verifier report and returns a patch or `null`.
+An optional `critic` callback supplies visual feedback. `requireCritique: true` requires a
+current critique before passing, and unresolved medium/high findings prevent success.
+There is no built-in model client or automatic visual critic.
+
+## Evidence and limits
+
+The [art-direction guide](agent-art-workflow.md) separates technical correctness, functional
+behaviour and observed visual quality. Production gates enforce declared criteria and hashes;
+they cannot authenticate reviewers, judge taste or prove that images were inspected.
+
+PNG writes through the CLI/artifact helper include an evidence sidecar. SDK `render()` returns
+evidence in memory; use `writeRender()` to write both files. Same-runtime/platform replay,
+undo and portable export are tested. Cross-platform or cross-version byte identity is not promised.
+
+A bounded layer cache reuses unchanged surfaces. Simple pointwise region scenes use a smaller
+viewport; antialias-sensitive cases use a full render and exact crop. `cache: false` and
+`regionMode: 'full'` request reference paths. Draft downsamples after rendering. A general
+dirty-tile compositor, automatic quadtree refinement, a native animation timeline, mesh warp,
+smudge and general segmentation remain unimplemented. Sprite manifests and atlas export
+package authored frames but do not provide inverse kinematics, retargeting or automatic
+visual approval. Procedural programs can still author individual animation frames, as the
+[asset trial](https://github.com/Coly010/rtistree/tree/main/examples/warden-asset-trial) demonstrates.
+
+The [poster benchmark](previews/benchmark.json) records 4,704 changed pixels inside a
+56 × 84 region and zero outside, with successful replay/undo/export checks. It is recorded
+mechanical evidence, not a visual-quality benchmark. The [performance probe](previews/performance.json)
+records local timings and cache reuse; it is not a portable speed guarantee.
+
+## Repository development
 
 ```sh
+git clone https://github.com/Coly010/rtistree.git
+cd rtistree
+npm ci
 npm run check
-npm run format:check
-npm run schema
+npm run demo
+npm run docs:check
+npm run package:check
 ```
 
-Subsystems are separate modules in `src/`: schema, loader, layout, assets, paint, renderer, commands, project transactions, verification, workflow, CLI and MCP. The `Renderer` interface makes backend replacement independent of scene authoring or agent logic. The original proposal's package boundaries are module boundaries until independent packaging has a concrete benefit.
-
-Bundled fonts are Inter and DM Serif Display from Fontsource, under their bundled SIL Open Font Licenses. They cover Latin text; custom project fonts can supply broader script coverage. Arbitrary system-font fallback remains disabled. Example artwork and book-cover raster are built from this engine's own primitives; regenerate the cover with `node --import tsx scripts/create-fixtures.ts`.
-
-## Staged 2D art production
-
-Dependency-aware painting pipelines, immutable candidate comparisons, hash-bound visual reviews and gated production stages are available through the CLI, SDK and MCP. Seeded oil/filbert/scumble/ink brushes complement native Canvas paths and raw pixels. See [the atelier workflow](atelier.md) and the hand-authored dragon trial in `examples/dragon-oil-trial`. No image-generation or 3D dependency is used.
-
-Read [Art direction for agents](agent-art-workflow.md) before making art. The foundation-first protocol, named 2D construction guides, explicit blocking issues and parent-linked revisions are also discoverable through `graphics studio-help`. The [grayscale dragon study](../examples/dragon-foundation/README.md) demonstrates the process and records its unresolved artistic failures.
+`npm run rtistree -- ...` runs the CLI from source. `npm run schema` regenerates the
+schemas. `npm run performance` reruns the cache/timing probe. The demo uses a temporary
+working project and writes preview images/evidence without editing the example source scenes.
 
-The [dragon head lighting experiment](../examples/dragon-head-study/README.md) uses the existing 2D tools for an original head, reflected green fire and two local revisions. It remains below the supplied artistic quality reference; code-only reproduction is verified separately from that verdict.
+The [architecture decisions](decisions/001-runtime-and-renderer.md) retain historical
+context. The [original proposal](https://github.com/Coly010/rtistree/blob/main/agentic-raster-graphics-architecture.md)
+is not an API reference. See [contributing](https://github.com/Coly010/rtistree/blob/main/CONTRIBUTING.md)
+for development setup and [releasing](releasing.md) for maintainer release instructions.

package/docs/evolution.md

@@ -1,8 +1,10 @@
 # Editing and agent workflows
 
-## Complete edits
+## Core edit commands
 
 `apply` is still a transaction containing `reason`, optional `expected_hash` and `commands`. The generated [command schema](../schemas/command.schema.json) is authoritative.
+The table covers core edits; [print production and editing](production.md) lists the
+additional document, path, crop, text and adjustment commands.
 
 | Area             | Commands                                                                                                                   |
 | ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
@@ -110,7 +112,7 @@ For visual critique, render and inspect the PNG, then submit:
 }
 ```
 
-`graphics critique scene.yaml critique.json` or the MCP `recordCritique` tool stores it. Stale scene/PNG hashes are rejected. `readCritique` returns only the current critique. A callback of type `VisualCritic` can perform this review in `runIterations`; use `requireCritique: true` to require it for success. Visual and rule scores inform stall detection; unresolved medium/high visual findings prevent a pass. The adapter is provider-neutral and requires the caller to supply the actual vision-capable reviewer. No synthetic review is substituted when one is absent.
+`rtistree critique scene.yaml critique.json` or the MCP `recordCritique` tool stores it. Stale scene/PNG hashes are rejected. `readCritique` returns only the current critique. A callback of type `VisualCritic` can perform this review in `runIterations`; use `requireCritique: true` to require it for success. Visual and rule scores inform stall detection; unresolved medium/high visual findings prevent a pass. The adapter is provider-neutral and requires the caller to supply the actual vision-capable reviewer. No synthetic review is substituted when one is absent.
 
 ## Components and fonts
 
@@ -142,7 +144,7 @@ Components can live in included fragments. Instance children become `new-badge-p
 fonts:
   brand-display:
     source: fonts/BrandDisplay.otf
-    hash: sha256:...
+    # Optional hash: sha256: followed by the font file’s 64 hex digest characters
 ```
 
 Choose `style.font: brand-display`. Fonts are registered under content-based aliases; changing a font file without updating its expected hash fails. History checks custom-font provenance, and exports copy font files. A custom file supplies one face; register a separate ID for another weight. Bundled names are reserved.
@@ -154,13 +156,13 @@ Layout supports `aspect_ratio`, positive `grow` weights and `layout.justify: sta
 After changing a source fragment or a component definition:
 
 ```sh
-graphics rebase scene.yaml
+npx rtistree rebase scene.yaml
 ```
 
 This merges disjoint source and agent changes using the retained authoring baseline. Conflicts report paths such as `/layers/headline/style/colour` and leave history untouched. Resolve the conflicting source fields and retry, or export the working scene into a new project. Rebase is audited and undoable. Histories created before baseline retention require their original source to be restored and exported first.
 
 ```sh
-graphics compact scene.yaml
+npx rtistree compact scene.yaml
 ```
 
 Compaction compresses full records into an immutable gzip archive with a content-hashed pointer, then starts an empty active log. Every undo/redo state remains accessible. It reduces storage; replay still reads all records. Missing/tampered archives fail closed. Do not delete archives referenced by the pointer.
@@ -170,10 +172,11 @@ Compaction compresses full records into an immutable gzip archive with a content
 `BenchmarkSession` requires visual review before each checkpoint. Briefs describe the objective and optional allowed region; the driver does not contain a solution or choose an edit.
 
 ```sh
-graphics benchmark scene.yaml brief.json before
+# Render and record a current critique before the first checkpoint.
+npx rtistree benchmark scene.yaml brief.json before
 # Inspect, critique, apply edits, then inspect and critique again.
-graphics benchmark scene.yaml brief.json after
-graphics benchmark scene.yaml brief.json finish
+npx rtistree benchmark scene.yaml brief.json after
+npx rtistree benchmark scene.yaml brief.json finish
 ```
 
-The report records actual edit/command counts, rule results, visual scores, locality, uncached equality and self-contained export equality. Token counts are nullable rather than guessed. The [recorded trials](../examples/agent-trials/results.json) were performed interactively by the assistant in this task, with self-authored briefs and same-agent visual critique. They establish a usable end-to-end workflow; broader held-out evaluation and independent human review remain future evidence to collect.
+The report records actual edit/command counts, rule results, visual scores, locality, uncached equality and self-contained export equality. Token counts are nullable rather than guessed. The [recorded trials](https://github.com/Coly010/rtistree/blob/main/examples/agent-trials/results.json) were performed interactively by the assistant in this task, with self-authored briefs and same-agent visual critique. They establish a usable end-to-end workflow; broader held-out evaluation and independent human review remain future evidence to collect.

package/docs/getting-started.md

@@ -1,5 +1,8 @@
 # Make your first image
 
+New to Rtistree? Read [Core concepts: an agent is the interface](core-concepts.md)
+for how you, your agent and the engine work together.
+
 Create a small artwork, render it, change one part, and undo that change.
 You need **Node.js 22 or newer** and npm. No GPU or model API key is required.
 
@@ -17,19 +20,19 @@ If npm asks to install Rtistree for the first command, accept. `init` creates a
 It refuses existing paths, so choose a different name if `my-art` already exists.
 
 Open **hello.png** in the new directory. You should see a green disc and the text
-“Hello, Rtistree.” on a dark background. Rendering also writes an evidence JSON file.
+“Hello, Rtistree.” on a dark background. Rendering also writes `hello.png.evidence.json`.
 
 The commands below run from inside `my-art` and use the locally installed package.
 The executable is `rtistree`; older installations used `graphics`, which remains an alias.
 
 ## Understand the starter
 
-| File           | Purpose                                                |
-| -------------- | ------------------------------------------------------ |
-| `scene.json`   | Canvas, disc and title, each with an editable ID       |
-| `refine.json`  | A sample patch that brightens only the disc            |
-| `render.mjs`   | The same rendering workflow through the JavaScript SDK |
-| `package.json` | Pinned dependency and the `npm run render` script      |
+| File           | Purpose                                                 |
+| -------------- | ------------------------------------------------------- |
+| `scene.json`   | Canvas settings and disc/title layers with editable IDs |
+| `refine.json`  | A sample patch that brightens only the disc             |
+| `render.mjs`   | The same rendering workflow through the JavaScript SDK  |
+| `package.json` | Pinned dependency and the `npm run render` script       |
 
 `npm run render` runs `rtistree render scene.json -o hello.png`.
 To inspect the scene's layers and bounds:
@@ -86,7 +89,9 @@ npx rtistree export scene.json -o portable/scene.json
 npx rtistree render portable/scene.json -o portable.png
 ```
 
-The export includes referenced assets and fonts. Keep the exported directory together.
+The export includes the current resolved scene, referenced assets, fonts and any baked
+program recipes. It starts a new baseline: edit history, critiques and production-session
+reviews are not copied. Keep the exported directory together.
 
 ## Use an agent
 
@@ -127,5 +132,7 @@ The SDK and CLI use the same engine. For an existing Node project, install with
 
 - [CLI reference](cli-reference.md) — inspect, edit, render and export commands.
 - [Scene format](scene-format.md) — layers, coordinates, assets and effects.
+- [Pixel art, sprites and spritesheets](sprites.md) — indexed tiles, frame metadata,
+  deterministic atlases and animation review.
 - [Studio](studio.md) — trusted JavaScript painting programs and replayable recipes.
 - [Staged production](atelier.md) — compare candidates and record visual review.

package/docs/next-milestone.md

@@ -1,4 +1,4 @@
-# Proposed next milestone: print documents and coherent projects
+# Historical proposal: print documents and coherent projects
 
 Status: delivered as the v0.3 milestone. This document retains the original proposal; see [the production guide](production.md) and [ADR 004](decisions/004-print-production-and-projects.md) for the implemented scope, selected backends and explicit limits.
 
@@ -9,11 +9,11 @@ Status: delivered as the v0.3 milestone. This document retains the original prop
 3. Preserve text and vector geometry in PDF; add practical compositing, selection and path tools.
 4. Run a more demanding generated-asset integration trial, including subject extraction or seamless extension, and print the result through the new export pipeline.
 
-The first generated-asset fitting trial is already recorded in [the example](../examples/generated-asset-trial/README.md). It uses one built-in image-generation call followed by deterministic Rtistree composition. It establishes asset ingestion, aspect-preserving placement, editable surrounding content and exact preservation of the placed photograph. It does not establish seamless photographic outpainting, segmentation or print readiness.
+The first generated-asset fitting trial is already recorded in [the example](https://github.com/Coly010/rtistree/blob/main/examples/generated-asset-trial/README.md). It uses one built-in image-generation call followed by deterministic Rtistree composition. It establishes asset ingestion, aspect-preserving placement, editable surrounding content and exact preservation of the placed photograph. It does not establish seamless photographic outpainting, segmentation or print readiness.
 
 ## Project creation
 
-Proposed syntax (not current commands):
+Syntax proposed at the time (now implemented; use the current production guide):
 
 ```sh
 rtistree project new alpine --size A3 --orientation landscape --ppi 300 --bleed 3mm --output-dir output
@@ -32,7 +32,7 @@ Keep physical trim dimensions authoritative, independently of pixel dimensions.
 
 Record the PDF MediaBox, TrimBox and BleedBox correctly; actually render artwork into the bleed. Offer crop marks as an explicit option outside trim. Report effective ppi of placed source images and whether the requested output resamples them. The file can encode exact size, but downstream printer/viewer scaling remains outside the engine's control.
 
-The current schema caps canvas dimensions at 4,096 pixels and the renderer holds full-canvas layer surfaces. A3 at 300 ppi is about 4,961 by 3,508 pixels before bleed. Print therefore needs a bounded-memory strategy and expanded dimension support, not merely a new encoder or a higher schema limit. Tiled rendering must retain context for filters and match reference crops.
+At the time of this proposal, the schema capped canvas dimensions at 4,096 pixels and the renderer held full-canvas layer surfaces. A3 at 300 ppi is about 4,961 by 3,508 pixels before bleed. Print therefore needs a bounded-memory strategy and expanded dimension support, not merely a new encoder or a higher schema limit. Tiled rendering must retain context for filters and match reference crops.
 
 ## Colour and formats
 

package/docs/production.md

@@ -1,16 +1,22 @@
-# Projects, print production and editing in v0.3
+# Projects, print production and editing
 
 ## Start a project
 
+Run these commands from a directory where `npm install rtistree` has completed.
+`project new` creates the artwork files and presets, not a Node package or dependency installation.
+
 ```sh
-rtistree project new alpine --size A3 --orientation landscape --ppi 300 --bleed 3mm --output-dir output
-rtistree render alpine --preset screen
-rtistree preflight alpine --preset print
+npx rtistree project new alpine --size A3 --orientation landscape --ppi 300 --bleed 3mm --output-dir output
+npx rtistree render alpine --preset screen
+npx rtistree preflight alpine --preset screen
 ```
 
 `project new` accepts A3, A4, A5, Letter, or a custom pair such as `160x100` (mm) or `8.5inx11in`. It creates `rtistree.yaml`, a scene with layer fragments, assets/fonts/profiles/history directories, local JSON Schemas, a README and a designated output directory. The destination must be new. Existing scene-file commands remain available; opening a configured entry-point scene also discovers its project settings.
 
-Generated projects start with an sRGB screen preset and a CMYK print preset. Before using the print preset, copy your printer/paper ICC file into `profiles/` and set `presets.print.profile`. Set `profile_hash` to its SHA-256 digest to pin it. CMYK export rejects missing, invalid, changed or non-CMYK profiles. The demo profile is for exercising the pipeline, not a recommendation for a printing process.
+Generated projects start with an sRGB screen preset and a CMYK print preset. Before using the print preset, copy your printer/paper ICC file into `profiles/` and set `presets.print.profile`. Set `profile_hash` to `sha256:` followed by its 64-character hexadecimal digest to pin it. CMYK export rejects missing, invalid, changed or non-CMYK profiles. The demo profile is for exercising the pipeline, not a recommendation for a printing process.
+An unconfigured print preset fails preflight with exit code 2; the first example deliberately
+uses the screen preset. After configuring a real profile, run `npx rtistree preflight alpine --preset print`
+before the CMYK export and proof commands below.
 
 Project paths are local to the project root. CLI/MCP renders and artwork exports use `output_dir`; CLI verification and preflight reports use it too. History and critique records remain persistent project state. Explicit CLI `--output` paths override artifact destinations.
 
@@ -37,12 +43,12 @@ The renderer accepts edges up to 8,192 pixels. Print preflight also enforces a 3
 ## Formats and colour
 
 ```sh
-rtistree export alpine --preset print --format pdf
-rtistree export alpine --preset print --format tiff
-rtistree export alpine --preset screen --format jpeg
-rtistree export alpine --format svg -o alpine/output/artwork.svg
-rtistree proof alpine --preset print
-rtistree export alpine --format project -o /tmp/alpine-copy/scene.json
+npx rtistree export alpine --preset print --format pdf
+npx rtistree export alpine --preset print --format tiff
+npx rtistree export alpine --preset screen --format jpeg
+npx rtistree export alpine --format svg -o alpine/output/artwork.svg
+npx rtistree proof alpine --preset print
+npx rtistree export alpine --format project -o /tmp/alpine-copy/scene.json
 ```
 
 Known artwork extensions are inferred for `export` and full `render`. Region renders remain PNG. A filename extension must agree with the actual format. Portable scene export keeps its original meaning with `--format project` or a JSON/YAML destination, and copies configured print profiles/presets when exporting a project.
@@ -71,7 +77,7 @@ Preflight checks physical geometry, render capacity, output profiles, font glyph
 
 Each artwork export has a `.evidence.json` containing the scene hash, output hash, resolved settings, ICC hash, backend versions and inspection of the actual encoded bytes. Raster inspection reads format, dimensions, channels, profile and density. PDF inspection reads page boxes, image colour-space declarations, embedded font descriptors and profile streams. This complements visual proof inspection; it does not replace press validation.
 
-## New editing operations
+## Editing operations
 
 Commands are available through `apply` in the CLI, SDK and MCP. See generated command/patch schemas for complete inputs.
 
@@ -93,15 +99,15 @@ Shapes support stroke caps, joins, dash arrays and dash offsets. Text styles sup
 
 Masks now support editable SVG-style paths, image alpha/luminance/colour-range selections, and union/intersection/subtraction/XOR. Combined masks use one coordinate space; children inherit the outer space and reference size. The processing order is selection/algebra, inversion, grow/shrink, then feathering. Image masks reference an asset directly, making external segmentation masks usable without a visible mask layer.
 
-New scoped operations are levels, piecewise-linear RGB/channel curves, white balance, clone and heal. Cloning samples a frozen copy of the target using `source_offset`. Healing adds a local mean-colour correction to that cloned texture; this is a deterministic colour-matched clone, not a Poisson or learned healing algorithm. All operate non-destructively through the existing history and scoped-pixel checks.
+Additional scoped operations are levels, piecewise-linear RGB/channel curves, white balance, clone and heal. Cloning samples a frozen copy of the target using `source_offset`. Healing adds a local mean-colour correction to that cloned texture; this is a deterministic colour-matched clone, not a Poisson or learned healing algorithm. All operate non-destructively through the existing history and scoped-pixel checks.
 
 ## SVG interchange and trial
 
 ```sh
-rtistree import-svg drawing.svg -o drawing.scene.json
-rtistree export drawing.scene.json --format svg -o drawing.svg
+npx rtistree import-svg drawing.svg -o drawing.scene.json
+npx rtistree export drawing.scene.json --format svg -o drawing.svg
 ```
 
 The importer supports static paths, rectangles, circles, ellipses, lines, polygons, polylines, groups, transforms and basic stroke/fill styling. Unsupported elements/attributes, remote resources, scripts and entities are rejected rather than silently dropped. Text, filters and arbitrary CSS are not imported. Exported text is outlined; complex export fallbacks are embedded images. Full round-trip equivalence for arbitrary SVG is not promised.
 
-The [print trial](../examples/print-trial/README.md) generates a ceramic vase/leaf photograph, extracts its silhouette using the new masks, adds a contact shadow and colour adjustment, adapts it to two aspect ratios, and exports CMYK PDF/TIFF/JPEG. The source, exact prompt, edits, critiques, final scenes and output evidence are retained.
+The [print trial](https://github.com/Coly010/rtistree/blob/main/examples/print-trial/README.md) used an external image-generation tool to create a ceramic vase/leaf photograph. Rtistree then extracted its silhouette with masks, added a contact shadow and colour adjustment, adapted it to two aspect ratios, and exported CMYK PDF/TIFF/JPEG. The source, exact prompt, edits, critiques, final scenes and output evidence are retained.