rtistree 0.5.0 → 0.6.0

package/docs/decisions/005-programmable-digital-art.md

@@ -12,4 +12,4 @@ Workers provide cancellation and V8 heap limits; helper allocations and output d
 
 Dense region editing uses existing promoted raster regions, extended with explicit `replace` and `over` semantics. Exact-size PNGs carry dense data instead of JSON pixel arrays. Transactions check stale scene hashes and edit locality. Attached patches follow object transforms. The trial found a near-zero pressure gradient failure; a minimum subpixel dab radius fixes it. Region testing also corrected final print-region copy bounds to use the transformed frame.
 
-The artistic evaluation is kept separate from mechanical verification. The wheel trial reproduces its pixels without external image inputs, but still reads as a synthetic illustration. Successful software tests and deterministic replay are not evidence of human-level artistic skill or photographic realism. See [the studio guide](../studio.md) and [trial](../../examples/manual-wheel-trial/README.md).
+The artistic evaluation is kept separate from mechanical verification. The wheel trial reproduces its pixels without external image inputs, but still reads as a synthetic illustration. Successful software tests and deterministic replay are not evidence of human-level artistic skill or photographic realism. See [the studio guide](../studio.md) and [trial](https://github.com/Coly010/rtistree/blob/main/examples/manual-wheel-trial/README.md).

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,57 +1,52 @@
 # Make your first image
 
-Rtistree runs locally on Node.js 22 or newer. It needs no GPU or model API key.
-Start in an empty directory:
+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.
+
+## Create your project
 
 ```sh
-mkdir my-art
+npx rtistree@latest init my-art
 cd my-art
-npm init -y
-npm install https://github.com/Coly010/rtistree/releases/download/v0.5.0/rtistree-0.5.0.tgz
+npm install
+npm run render
 ```
 
-This installs the checked release tarball from GitHub. npm registry publication is pending;
-the installed package and `graphics` executable are the same.
+If npm asks to install Rtistree for the first command, accept. `init` creates a new
+`my-art` directory with a starter scene and a package.json that pins the Rtistree version.
+It refuses existing paths, so choose a different name if `my-art` already exists.
 
-## Render a scene
+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 `hello.png.evidence.json`.
 
-Save this as `scene.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.
 
-```json
-{
-  "version": 1,
-  "canvas": { "width": 640, "height": 400, "background": "#14251f" },
-  "layers": [
-    {
-      "id": "disc",
-      "type": "vector",
-      "bounds": [360, 60, 200, 200],
-      "shape": { "type": "ellipse", "fill": "#95b85c" }
-    },
-    {
-      "id": "title",
-      "type": "text",
-      "bounds": [48, 275, 544, 80],
-      "content": "Hello, Rtistree.",
-      "style": { "font": "inter", "size": 44, "weight": "bold", "colour": "#edf3e8" }
-    }
-  ]
-}
-```
+## Understand the starter
+
+| 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       |
 
-Or copy the same scene from `node_modules/rtistree/examples/hello/scene.json`.
+`npm run render` runs `rtistree render scene.json -o hello.png`.
+To inspect the scene's layers and bounds:
 
 ```sh
-npx graphics render scene.json -o hello.png
-npx graphics inspect scene.json
+npx rtistree inspect scene.json
 ```
 
-Open `hello.png`: a green disc and a title on a dark background. An adjacent evidence JSON
-records the scene hash, dimensions, fonts and renderer/runtime information.
+The starter is deliberately small so you can see what each edit does. Once comfortable,
+use the [scene format](scene-format.md) to add shapes, text, images and masks.
 
-## Change one part
+## Make a focused edit
 
-Save this as `refine.json`:
+The supplied `refine.json` applies a brightness operation to the disc:
 
 ```json
 {
@@ -66,29 +61,60 @@ Save this as `refine.json`:
 }
 ```
 
+Apply it and save a second image:
+
 ```sh
-npx graphics apply scene.json refine.json
-npx graphics render scene.json -o brighter.png
-npx graphics undo scene.json
-npx graphics render scene.json -o restored.png
+npx rtistree apply scene.json refine.json
+npx rtistree render scene.json -o brighter.png
 ```
 
-The disc becomes brighter. Undo restores the first image. Changes are journaled beside
-the scene; the original authoring file remains intact. On the same runtime and platform,
-`restored.png` should have the same bytes as `hello.png`.
+Compare **hello.png** and **brighter.png**. Only the disc becomes brighter; the title and
+background stay the same. The reason and edit are recorded in `history/`. The authoring
+JSON remains intact; the rendered state includes the journaled edits.
 
-## Export a portable project
+## Undo and export
 
 ```sh
-npx graphics export scene.json -o portable/scene.json
-npx graphics render portable/scene.json -o portable.png
+npx rtistree undo scene.json
+npx rtistree render scene.json -o restored.png
 ```
 
-The export includes referenced assets and fonts. Keep the exported directory together.
+**restored.png** should match **hello.png** byte for byte on the same runtime and platform.
+Use `npx rtistree redo scene.json` if you want to restore the edit again.
+
+Export the current state as a portable project:
+
+```sh
+npx rtistree export scene.json -o portable/scene.json
+npx rtistree render portable/scene.json -o portable.png
+```
+
+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
+
+Read the built-in art-direction guidance, then follow [agent setup](agent-setup.md)
+to connect an MCP client or your own agent host:
+
+```sh
+npx rtistree art-guide
+```
+
+A useful first task is: “Inspect this scene, render it, and change the disc while preserving
+the title and background.” For art creation, ask the agent to inspect silhouettes, values
+and intended display size. Technical verification does not establish artistic quality.
 
 ## Use the SDK
 
-Save this as `render.mjs` beside `scene.json`:
+The starter includes `render.mjs`. Run it with:
+
+```sh
+npm run render:sdk
+```
+
+Its core is:
 
 ```js
 import { Project } from 'rtistree';
@@ -99,9 +125,14 @@ const result = await project.render();
 await writeFile('sdk-output.png', result.png);
 ```
 
-Run `node render.mjs`. The SDK and CLI use the same engine.
+The SDK and CLI use the same engine. For an existing Node project, install with
+`npm install rtistree` and import from `rtistree` directly.
 
-## Next steps
+## Where next?
 
-Read [agent setup](agent-setup.md) to connect an MCP client, or the [scene format](scene-format.md)
-to add layers, text, assets and masks. For generated painting programs, use the [studio guide](studio.md).
+- [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,25 +1,25 @@
-# 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.
 
 ## Recommended order
 
-1. Introduce a project manifest, physical document model, and `graphics project new` together.
+1. Introduce a project manifest, physical document model, and `rtistree project new` together.
 2. Add JPEG, TIFF and physically sized PDF exports, with colour management and output validation.
 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
-graphics project new alpine --size A3 --orientation landscape --ppi 300 --bleed 3mm --output-dir output
-graphics render alpine --preset screen
-graphics export alpine --preset print
-graphics preflight alpine --preset print
+rtistree project new alpine --size A3 --orientation landscape --ppi 300 --bleed 3mm --output-dir output
+rtistree render alpine --preset screen
+rtistree export alpine --preset print
+rtistree preflight alpine --preset print
 ```
 
 Create a project manifest describing the scene entry point, output directory and export presets; a scene referencing layer fragments; `assets/`, `fonts/`, `profiles/`, `layers/`, `history/`, and the designated output directory. Include a useful starter scene, schema references, a short project README, and ignore rules for generated artifacts. Relative paths resolve consistently from the project root. Creating a project must not overwrite an existing one. Existing scene-file commands remain usable.
@@ -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