rtistree 0.5.0

package/dist/workflow.d.ts

@@ -0,0 +1,53 @@
+import { type VisualCritic, type VisualCritique } from './critique.js';
+import type { Patch } from './commands.js';
+import { Project } from './project.js';
+import type { RenderResult } from './render.js';
+import type { Scene } from './schema.js';
+import { type VerificationReport } from './verify.js';
+export interface Observation {
+    iteration: number;
+    scene: Scene;
+    render: RenderResult;
+    verification: VerificationReport;
+    critique?: VisualCritique;
+}
+export type EditingAgent = (observation: Observation) => Promise<Patch | null>;
+export interface IterationOptions {
+    maxIterations?: number;
+    maxStalled?: number;
+    minimumImprovement?: number;
+    stopOnPass?: boolean;
+    signal?: AbortSignal;
+    critic?: VisualCritic;
+    requireCritique?: boolean;
+}
+/** The agent is injected. This module contains no model credentials or graphics algorithms. */
+export declare function runIterations(project: Project, agent: EditingAgent, options?: IterationOptions): Promise<{
+    reason: string;
+    iterations: number;
+    observations: {
+        iteration: number;
+        score: number;
+        status: string;
+        scene_hash: string;
+    }[];
+    render: RenderResult;
+    verification: VerificationReport;
+    critique: {
+        scene_hash: string;
+        png_hash: string;
+        reviewer: string;
+        method: "human" | "vision-agent";
+        summary: string;
+        score: number;
+        issues: {
+            id: string;
+            category: "coherence" | "composition" | "lighting" | "semantic" | "texture" | "typography";
+            severity: "high" | "low" | "medium";
+            target?: string | undefined;
+            region?: [number, number, number, number] | undefined;
+            message: string;
+            suggestion?: string | undefined;
+        }[];
+    } | null;
+}>;

package/dist/workflow.js

@@ -0,0 +1,66 @@
+import { validateCritique } from './critique.js';
+import { verifyRendered } from './verify.js';
+/** The agent is injected. This module contains no model credentials or graphics algorithms. */
+export async function runIterations(project, agent, options = {}) {
+    const max = options.maxIterations ?? 6, stallLimit = options.maxStalled ?? 2, threshold = options.minimumImprovement ?? 0.01;
+    if (!Number.isInteger(max) || max < 0 || max > 100)
+        throw new Error('maxIterations must be an integer between 0 and 100');
+    if (!Number.isInteger(stallLimit) ||
+        stallLimit < 1 ||
+        !Number.isFinite(threshold) ||
+        threshold < 0)
+        throw new Error('Invalid stopping criteria');
+    const observations = [];
+    let stalled = 0, previous = -1;
+    for (let iteration = 0; iteration <= max; iteration++) {
+        options.signal?.throwIfAborted();
+        const scene = await project.scene(), render = await project.renderer.render(scene, project.root), verification = await verifyRendered(scene, project.root, project.renderer, render);
+        const critique = options.critic
+            ? validateCritique(await options.critic({ scene, render, verification, signal: options.signal }), scene, render)
+            : await project.critique();
+        if (critique)
+            await project.recordCritique(critique);
+        observations.push({
+            iteration,
+            score: verification.score,
+            status: verification.status,
+            scene_hash: render.evidence.scene.hash,
+        });
+        const qualityScore = critique ? (verification.score + critique.score) / 2 : verification.score;
+        const result = (reason) => ({
+            reason,
+            iterations: iteration,
+            observations,
+            render,
+            verification,
+            critique,
+        });
+        if ((options.stopOnPass ?? true) &&
+            verification.status === 'pass' &&
+            (!options.requireCritique || !!critique) &&
+            (!critique || !critique.issues.some((i) => i.severity === 'high' || i.severity === 'medium')))
+            return result('passed');
+        if (iteration === max)
+            return result('iteration-budget');
+        if (previous >= 0 && qualityScore - previous < threshold)
+            stalled++;
+        else
+            stalled = 0;
+        if (stalled >= stallLimit)
+            return result('stalled');
+        previous = qualityScore;
+        const patch = await agent({
+            iteration,
+            scene,
+            render,
+            verification,
+            critique: critique ?? undefined,
+        });
+        options.signal?.throwIfAborted();
+        if (!patch)
+            return result('agent-finished');
+        await project.apply({ ...patch, expected_hash: render.evidence.scene.hash });
+    }
+    throw new Error('Unreachable iteration state');
+}
+//# sourceMappingURL=workflow.js.map

package/dist/workflow.js.map

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

package/docs/agent-art-workflow.md

@@ -0,0 +1,201 @@
+# Art direction for agents
+
+Read this before creating illustration, painting or procedural assets. The versioned
+protocol is returned by `graphics art-guide`, included in `graphics studio-help`
+and MCP `studioHelp`, and exported as `artDirectionGuide` by the SDK.
+
+MCP connections receive the core rules in the server's initialization
+`instructions`. The full guide is also a discoverable JSON resource at
+`rtistree://guides/art-direction`. Authoring tool descriptions point agents to it.
+All of these surfaces share `src/art-direction.ts`; consumers do not need access
+to this repository or its example files. SDK hosts should put the exported
+`rtistreeAgentInstructions` in their agent context and expose the full guide.
+CLI hosts should read `graphics art-guide` before authoring. A client decides how
+to present instructions to its model; shipping guidance cannot force every client
+or agent to read it, follow it, or exercise good visual judgment.
+
+This is a repeatable process for detecting and correcting failures. It cannot guarantee better art on every attempt. The agent must be capable of drawing, observing and revising; the software cannot certify taste, anatomical understanding or the truth of a review.
+
+## Establish the standard before producing detail
+
+Write the brief, intended medium, audience and quality expectation in plain language. Separate **prompt compliance** from **artistic success**. A recognisable dragon may still have poor construction; a technically valid PDF may still have poor composition.
+
+Study relevant references. Record each source, an actual observation and how it changes the drawing. Open images before making visual claims; search-result descriptions are not visual inspection. Use references for structure, gesture, lighting and quality calibration. Do not substitute tracing, imported pixels or image-generation output when the brief prohibits them. Distinguish real anatomy from invented anatomy.
+
+For an unfamiliar subject, include both a structural reference and an example of the intended quality. A diagram can explain a joint without demonstrating good composition or expressive drawing. Sources may be URLs or project-local notes; source claims are recorded, not automatically verified by Rtistree.
+
+## Follow the dependency of artistic decisions
+
+For an asset family, begin with a representative sample: one character and one
+prop that exercise the difficult construction. Establish their quality before
+multiplying variants. The guide's `starter_plan` is a valid production plan
+template with exploration, sample review and family review stages. Replace its
+brief and adapt criteria before submitting it to `production`. Reference studies
+can be supplied with the plan or appended through `study`. The template uses
+the existing gates; it does not create an automatic visual critic.
+
+1. **Gesture and composition.** Produce at least three substantially different proposals. Change action, balance, overlap and negative space. Scaling or translating the same drawing does not explore a new pose.
+2. **Silhouette.** Inspect the subject at thumbnail size. Identify the focal contour, negative spaces and accidental mergers. A head merging into a wing is a drawing failure even if shading might reveal it later.
+3. **Construction.** Name landmarks and connect them through guide curves. Establish coherent mass, joints, perspective and overlap. Attach contours to shared landmarks so corrections propagate. In a creature, distinguish the skeleton, muscle masses and surface; in lettering, establish stroke proportions and spacing; in a product illustration, establish axes, proportions and perspective.
+4. **Values.** Use a plain background and grayscale. Group large light and shadow masses under a stated light direction. Inspect at full size and thumbnail size, then mirror the view. Examine both structure and rendering artifacts. Smooth gradients can expose form, but a set of shaded tubes is not automatically convincing anatomy.
+5. **Targeted revision.** Name the defect, predict a correction and capture the parent. Make the structural edit, capture the revision, then compare the actual images. Record improved, unchanged or worse, with visible evidence. A local fix is not proof that the whole drawing is good.
+6. **Foundation checkpoint.** Keep all blocking defects active. Seek human or independent review when required by the plan. Do not proceed to colour, textures, scenery or effects while construction remains inadequate.
+7. **Materials and finish.** Only after the foundation passes, develop surface, edge hierarchy and detail. Recheck the earlier decisions after significant edits. Complexity, brush count and time spent are not quality metrics.
+
+If two structural revisions do not improve the drawing, revisit the construction model or the pose. Further detail is unlikely to rescue it. If there are local improvements but the overall result is still weak, say so explicitly and retain the failed gate.
+
+## Subject-specific checks learned from the asset trial
+
+**Figures:** name and trace each shoulder–elbow–wrist and hip–knee–ankle chain,
+including hidden portions. State which hand holds each object. In the Verdigris
+Watch trial, the sword elbow crossed the torso beneath the shield arm. Moving
+the elbow outside and above the body fixed that relationship. A valid landmark
+graph can encode a bad pose; inspect balance, joint angles and negative spaces.
+Helmet dome, eye slit, visor and jaw must read as connected forms.
+
+**Props:** use one shared perspective grid for the body, lid, planks and fittings.
+The first chest used unrelated angles. A reconstruction also briefly showed the
+hidden backs of its hoops over the near lid, where they looked like handles.
+Both shared geometry and correct occlusion matter. Distinct shaded faces and a
+common palette are insufficient evidence of sound construction.
+
+**Animation:** declare facing, travel direction, ground plane, stride distance,
+cycle duration and contact/recovery phases. Play a full loop against ground
+markers and inspect contact, passing and recovery frames at the intended size.
+For ordinary forward walking, planted feet move backward relative to the body;
+their relative velocity plus body velocity should approximately cancel in world
+space. Recovering feet move forward while lifted. Check reachability, segment
+lengths, knee flexion, lift, pivots, frame order and the loop boundary. Bind those
+checks to the actual rig source used to draw the frames.
+
+The original trial produced eight different PNGs but walked backward. Correcting
+direction still left excessive knee bend, an odd helmet and crossed guard arms.
+The user eventually called revision 4 “much better.” Record that as relative
+improvement, without extrapolating it into approval of every asset. The distilled
+lessons are embedded in the shipped guide; the full trial history lives in
+`examples/warden-asset-trial` in the source repository and is not required by the
+installed package.
+
+Report three separate axes: **technical** (valid files and reproducibility),
+**functional** (subject-specific behaviour/geometry), and **visual** (observed
+appearance against the brief). An unobserved image or loop is unreviewed. A user
+rejection supersedes an earlier favourable agent review. Keep failed candidates
+and parent-linked corrections. Technical checks cannot override visual failures.
+
+## Enforced gates and their limits
+
+Production plans support these stage fields:
+
+```json
+{
+  "minimum_alternatives": 3,
+  "require_references": true,
+  "required_reviewer": "human"
+}
+```
+
+Use minimum alternatives on the exploration stage. Use the human checkpoint when
+the user or agreed plan requires human acceptance; do not invent an approval
+requirement for every task. Set concrete `criteria` and appropriate numerical
+thresholds as well. Do not lower thresholds after seeing a weak result merely to advance.
+
+- `minimum_alternatives` counts initial candidates with distinct PNG hashes. Revisions do not count as independent alternatives. The software can verify pixel differences; the reviewer must verify meaningful compositional differences.
+- `require_references` requires a reference log. The software does not know whether the agent actually studied it.
+- `required_reviewer: "human"` prevents a review declared as `vision-agent` from approving the stage. Reviewer identities and methods are declarations in a trusted local project, not authenticated identities. An agent must never mark its own opinion as human feedback.
+- Blocking review issues prevent selection and advancement regardless of high overall scores. A criterion cannot simultaneously pass and have a blocking issue.
+- Revision reviews must compare against the declared parent. A revision judged unchanged or worse cannot be selected.
+- Re-reviewing a candidate appends to `review_history`. Earlier criticism is retained.
+- `status` reports candidate readiness and `compare` reports gate reasons. Existing technical, stale-hash, candidate-restoration and undo checks continue to apply.
+
+The engine cannot stop an observer from writing an inaccurate review. These gates expose decisions and prevent common shortcuts; they do not replace artistic judgment. A completed workflow means its declared checks passed, not that excellent art has been objectively established.
+
+## Requests an agent should use
+
+Reference study can be supplied in the initial plan's `references` array, or appended during work:
+
+```json
+{
+  "action": "study",
+  "session": "creature",
+  "reference": {
+    "id": "wing-construction",
+    "source": "<reference URL or project-local study>",
+    "observation": "The elbow precedes the wrist; the long fingers radiate from the wrist.",
+    "application": "Move the wrist independently from the shoulder and attach membrane contours to the finger ends."
+  }
+}
+```
+
+Reference IDs are unique. Appending a study does not rewrite criteria or earlier reviews.
+
+Capture a revision after making the edit:
+
+```json
+{
+  "action": "capture",
+  "session": "creature",
+  "candidate": "separated-jaw",
+  "expected_hash": "<current scene hash>",
+  "revision": {
+    "parent": "first-values",
+    "hypothesis": "Lowering the far wing will open a clear gap beneath the jaw."
+  }
+}
+```
+
+A review includes the normal candidate hashes, reviewer, method, strengths, weaknesses, scores and complete criterion verdicts. Add explicit issues and a comparison for revisions:
+
+```json
+{
+  "issues": [
+    {
+      "criterion": "construction",
+      "severity": "blocking",
+      "observation": "The wing and foreleg terminate at one unexplained joint.",
+      "correction": "Design separate attachments and the intervening torso mass before adding detail."
+    }
+  ],
+  "comparison": {
+    "parent": "first-values",
+    "verdict": "improved",
+    "evidence": "The jaw is now separated from the far wing, but the shared shoulder joint is still unresolved."
+  }
+}
+```
+
+The construction criterion must be `pass: false` in this example. A comparison can truthfully say improved while the candidate remains blocked.
+
+## Named 2D construction guides
+
+```js
+const drawing = art.guides({
+  points: {
+    shoulder: [200, 300],
+    elbow: { anchor: 'shoulder', offset: [-70, -20] },
+    wrist: { anchor: 'elbow', offset: [-40, -90] },
+    tip: { anchor: 'wrist', offset: [-120, -40] },
+  },
+  paths: {
+    leadingEdge: [
+      { op: 'M', to: 'shoulder' },
+      { op: 'Q', control: 'elbow', to: 'wrist' },
+      { op: 'L', to: 'tip' },
+    ],
+  },
+});
+ctx.stroke(art.path(drawing.paths.leadingEdge));
+```
+
+Points can be coordinates, aliases or anchored offsets. Paths support M/L/Q/C/Z segments with shared point references. Moving the shoulder above moves its dependent elbow, wrist and tip. Use absolute points where independent articulation is intended. Cycles, unknown points, invalid coordinates and malformed paths fail validation.
+
+This is a general construction graph, not inverse kinematics or anatomical knowledge. It is useful for creatures, botanical forms, lettering, diagrams and other drawings whose contours share control points. Programs still have native Canvas and raw pixels for anything the abstraction cannot express.
+
+## The dragon trials are calibration evidence
+
+The original oil-style dragon met the requested subject beats and reproduced deterministically, but the user rejected its artistic quality. Its earlier favourable scores were false positives. Do not use that result as a passing quality reference.
+
+The follow-up in `examples/dragon-foundation` studies anatomy references, rejects two silhouettes for losing the head in a wing, then makes two structural/value revisions to the remaining pose. It preserves failed reviews and stops at the foundation checkpoint. The image remains a weak construction study; improved separation and reproducibility do not make it excellent art.
+
+Read `examples/dragon-foundation/README.md` for the actual observations, limitations and replay evidence. Treat the process as a way to learn from visible failures rather than manufacture a successful score.
+
+The narrower experiment in `examples/dragon-head-study` draws a head illuminated by green fire. Replacing regular scale rows with irregular cells and a glowing line with turbulent fire improved those specific defects. The result still falls short in anatomy, light interaction and purposeful painting. A brush treatment over a weak drawing remains a weak drawing. This was a single-composition lighting experiment, not a successful run of the full foundation protocol; its assessment keeps the artistic failures explicit.

package/docs/agent-setup.md

@@ -0,0 +1,83 @@
+# Connect an agent
+
+Rtistree provides a CLI, an MCP server and a TypeScript SDK. The engine renders locally;
+your host supplies the model and any vision capability.
+
+## MCP over stdio
+
+Install Rtistree in a project and create a scene using the [quickstart](getting-started.md).
+Use this configuration shape in an MCP client that accepts `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "rtistree": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/my-art/node_modules/rtistree/dist/cli.js",
+        "serve",
+        "/absolute/path/to/my-art/scene.json"
+      ]
+    }
+  }
+}
+```
+
+Replace both paths with real absolute paths. Use an absolute path to your Node executable
+if the host does not inherit your terminal's PATH. Configuration location and field wrappers
+vary by client; the underlying command is always `node <cli.js> serve <scene>`.
+The server writes protocol messages only to stdout.
+
+On connection, the client receives concise art-direction instructions. The full versioned
+guide is available as the `rtistree://guides/art-direction` resource and through `studioHelp`.
+Some clients do not automatically expose server instructions or resources to the model;
+in that case, explicitly tell the agent to call `studioHelp` first.
+
+Example task:
+
+> Read Rtistree's art-direction guide, inspect this project and render it. Create one
+> representative asset before expanding the family. Compare its silhouette and grayscale
+> values, inspect it at the intended display size, and record technical, functional and
+> visual findings separately. Revise failed criteria before exporting.
+
+The server exposes inspection, rendering, crop inspection, typed edits, undo/redo, verification,
+critiques, program execution, pipelines and staged production. Rendering tools return PNG image
+content; use a vision-capable agent to judge appearance. Structured inspection alone cannot
+establish that an image looks good.
+
+## CLI agents
+
+```sh
+npx graphics art-guide
+npx graphics inspect scene.json
+npx graphics render scene.json -o review.png
+npx graphics studio-help
+```
+
+Read the JSON guide, open the rendered image, then choose a focused edit. Do not substitute a
+successful `verify` result for visual review. CLI command details are in the [reference](cli-reference.md).
+
+## SDK hosts
+
+```js
+import { rtistreeAgentInstructions, artDirectionGuide, Project } from 'rtistree';
+
+const project = await Project.open('./scene.json');
+const image = await project.render();
+// Include rtistreeAgentInstructions in your host's agent instructions.
+// Expose artDirectionGuide and image.png to the agent through your host's tools.
+```
+
+These exports contain guidance; importing them does not automatically insert anything into
+an external agent's context. The host must perform that integration. The renderer has no
+built-in model client, API key handling or automatic visual critic.
+
+## Trust and review
+
+Run only painting programs and recipes you trust. The JavaScript VM is not a security sandbox.
+Normal rendering does not execute recipes. Keep an agent's access scoped to the intended
+project, and inspect its proposed changes and outputs as appropriate to your workflow.
+
+The [art-direction workflow](agent-art-workflow.md) documents sample selection, connected
+construction, ground contact and existing production review gates. It makes lessons available;
+it does not guarantee model compliance or artistic quality.

package/docs/atelier.md

@@ -0,0 +1,117 @@
+# Producing art in stages
+
+Start with [Art direction for agents](agent-art-workflow.md): reference study, distinct silhouettes, construction, grayscale values and targeted revision. Its protocol is included in CLI/MCP `studioHelp`.
+
+Rtistree provides the tools and records; a human or agent still makes visual decisions. No image-generation service or 3D renderer is required. Start with `graphics studio-help` for the synchronous painting API and technique catalogue.
+
+## Working sequence
+
+1. Describe the brief and create a production plan. Set stage-specific criteria before making candidates: composition at thumbnail size; value masses at block-in; anatomy and lighting at form; directional paint and depth at materials; focal hierarchy and consistency at finishing. Do not demand finished texture from thumbnails.
+2. Author separate painting programs and an editable pipeline JSON. Generate two or three inexpensive compositions by reducing node dimensions. Auto-created raster layers fill the scene canvas, so small assets can serve as previews.
+3. Build explicitly, capture each candidate and compare their images. Open the returned PNG and relevant detail crops. Record what you actually see against every criterion.
+4. Select an eligible candidate. Selection restores its layers, assets and frozen inline pipeline, and can be undone. A candidate cannot replace an incumbent with a lower fidelity or quality rating. Unreviewed candidates and technical failures cannot be selected.
+5. Advance only while the selected scene is still current. Repeat at the next stage and higher resolution. If a criterion fails, make another candidate; do not lower the criterion merely to finish.
+6. Export the selected scene and audit a cold render, portable render and recipe replay. Report remaining aesthetic limitations separately from technical checks.
+
+CLI actions also have SDK equivalents (`buildPipeline`, `production`) and MCP tools (`buildPipeline`, `production`). Structured errors stop the operation. Normal rendering reads baked images and never runs program code.
+
+## Editable dependency graph
+
+```json
+{
+  "version": 1,
+  "id": "painting",
+  "shared": { "warmth": 0.4 },
+  "nodes": [
+    {
+      "id": "ground",
+      "target": "ground",
+      "source": "programs/ground.js",
+      "width": 1200,
+      "height": 800,
+      "bindings": { "warmth": "warmth" },
+      "seed": 42
+    },
+    {
+      "id": "glaze",
+      "target": "glaze",
+      "code": "const c=art.input('base'); art.techniques.glaze(c,'#a88152',0.08); return c;",
+      "width": 1200,
+      "height": 800,
+      "inputs": { "base": { "node": "ground" } }
+    }
+  ]
+}
+```
+
+`graphics pipeline my-project pipeline.json` reports `built` or `cached` for each node. An input can instead use `{ "asset": "registered-asset-id" }`. Source and inline code are mutually exclusive. Only subscribed shared parameters enter a node's key. Per-node parameters override nothing implicitly: an explicit binding takes precedence over a parameter of the same name. A changed node whose PNG is identical need not rebuild its dependants. Node array order defines auto-created layer order; dependency order defines execution order. Existing layer geometry is preserved. Changing output resolution changes cache keys. Removing a node does not remove previously authored layers or assets; use normal scene commands for removal.
+
+All node artifacts are baked before one scene transaction. A failed build can leave unused immutable files in the cache, but never a partially updated scene. Identical builds add no history. Use `expected_hash` with the SDK/MCP to reject a scene changed since inspection.
+
+The exact executed graph, including inline source, is stored under `scene.metadata.pipeline_<id>`. After restoring a candidate, use that graph to resume its settings; a working `pipeline.json` file is deliberately not overwritten by selection. Portable export includes the selected graph and registered input assets, so it can rebuild without the original source files.
+
+## Production requests
+
+Create a plan with `graphics production my-project plan.json`:
+
+```json
+{
+  "action": "plan",
+  "plan": {
+    "id": "landscape",
+    "brief": "A quiet mountain valley at dawn",
+    "stages": [
+      {
+        "id": "thumbnails",
+        "goal": "Choose the value composition",
+        "minimum_fidelity": 0.7,
+        "minimum_quality": 0.7,
+        "criteria": [
+          { "id": "depth", "description": "Three distance planes read at thumbnail size" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Use `{ "action": "capture", "session": "landscape", "candidate": "warm-dawn", "expected_hash": "<current scene hash>", "crops": [[100,100,200,150]] }`. The result includes a directory containing the image, thumbnail, scene and requested `detail-N.png` files. Candidate IDs cannot be overwritten. Capture supports up to 8 integer canvas-space crops. Session capacity is 64 candidates.
+
+Use `compare` with the session ID for a labelled contact sheet and ranked reviews. Ranking is eligibility first, then artistic quality, then brief fidelity; it never blends technical and visual scores.
+
+A `review` request includes session and a review object with `candidate`, exact `scene_hash` and `png_hash` from capture, `reviewer`, `method` (`human` or `vision-agent`), `fidelity` and `quality` in 0–1, `strengths`, `weaknesses`, and `criteria: [{id, pass, evidence}]`. Every criterion must be covered exactly once. These fields must be authored after visual inspection; Rtistree does not provide an automatic critic.
+
+Use `select` with session, candidate and current `expected_hash`, then `advance` with session and the resulting scene hash. The final advance marks the session complete. `status` returns the plan, stage, candidates and selections. Session metadata writes are locked; scene writes use the existing journal lock and stale-scene guard. A failure writing session metadata after selection may require repeating selection; the scene transaction remains undoable.
+
+JSON schemas: `schemas/pipeline.schema.json` and `schemas/production.schema.json`.
+
+## Painting techniques and escape hatches
+
+```js
+const canvas = art.canvas();
+const ctx = canvas.getContext('2d');
+ctx.fillStyle = '#263e45';
+ctx.fillRect(0, 0, art.width, art.height);
+ctx.save();
+ctx.clip(art.path('M20 180 Q160 30 300 180 L300 230 L20 230Z'));
+art.techniques.stroke(
+  canvas,
+  [
+    { x: 30, y: 170, pressure: 0.3 },
+    { x: 130, y: 120, pressure: 1 },
+    { x: 260, y: 170, pressure: 0.2 },
+  ],
+  { preset: 'oil', size: 24, colour: '#c7b685', dryness: 0.25, opacity: 0.6 },
+);
+art.techniques.glaze(canvas, '#b69357', 0.08);
+ctx.restore();
+return canvas;
+```
+
+`oil`, `filbert`, `scumble` and `ink` presets expose size, bristle count, variation, opacity, dryness and taper. Pressure controls width; overlapping strands accumulate paint. Presets are starting settings, not complete art styles. All methods respect current clipping and transforms, preserve context state and use the seeded RNG. Keep the runtime and technique version pinned for replay.
+
+`art.techniques.mix` interpolates sRGB palette colours. `atmosphere` is the same operation applied toward a haze colour; it does not establish perspective for you. `weave` overlays sparse crossed lines; it should remain subordinate to form. See `examples/technique-study` for an executable swatch sheet.
+
+For anything these helpers cannot express, use `canvas.getContext('2d')`, `art.path(svgPathData)`, pixel buffers, coordinate warps, custom masks and explicit raster edits. No new abstraction is required to paint a new subject.
+
+The user rejected the artistic quality of the first dragon trial. The follow-up in `examples/dragon-foundation` retains failed reviews and stops before decoration. The original trial in `examples/dragon-oil-trial` records three composition candidates, successive stage reviews, editable source and a reproducibility audit. It is one stylized painting trial, not evidence of universal artistic excellence.

package/docs/cli-reference.md

@@ -0,0 +1,61 @@
+# CLI reference
+
+Installing Rtistree exposes `graphics`. In a local npm project, use `npx graphics`.
+Run `graphics --help` for the complete installed-version reference. Structured results go to
+stdout as JSON; errors go to stderr. Verification failure exits 2; other errors exit 1.
+
+## Inspect and edit
+
+```sh
+graphics inspect scene.json
+graphics inspect scene.json --layer title
+graphics inspect-region scene.json 0 0 100 100
+graphics render scene.json -o image.png
+graphics render-region scene.json 0 0 100 100 -o crop.png
+graphics apply scene.json patch.json
+graphics undo scene.json
+graphics redo scene.json
+graphics history scene.json
+```
+
+Coordinates are `x y width height` in canvas pixels. A patch contains a reason and a typed
+commands array. Supply the current `expected_hash` when coordinating concurrent edits.
+See [scene format](scene-format.md) for command shapes and coordinate rules.
+
+## Verify, review and export
+
+```sh
+graphics verify scene.json -o report.json --heatmap heatmap.png
+graphics critique scene.json critique.json
+graphics export scene.json -o portable/scene.json
+graphics export scene.json --format png -o image.png
+```
+
+Verification measures configured technical constraints. Critiques are authored after inspecting
+images and bound to the current scene. Exports for physical documents and printer profiles are
+described in [print production](production.md).
+
+## Studio and production
+
+```sh
+graphics art-guide
+graphics studio-help
+graphics program scene.json program.json
+graphics program-replay scene.json asset-id
+graphics pipeline scene.json pipeline.json
+graphics production scene.json request.json
+```
+
+Read [studio](studio.md) for program requests and [staged production](atelier.md) for plans,
+candidate captures, reviews and selection. Program execution is for trusted code only.
+
+## Project creation and integration
+
+```sh
+graphics project new artwork --size A3 --orientation landscape --ppi 300 --bleed 3mm
+graphics schema --kind scene
+graphics schema --kind command
+graphics serve /absolute/path/to/scene.json
+```
+
+The MCP server uses stdio. See [agent setup](agent-setup.md).

package/docs/decisions/001-runtime-and-renderer.md

@@ -0,0 +1,35 @@
+# ADR 001: TypeScript control plane and native CPU Skia renderer
+
+Status: accepted for the MVP. Later extensions and superseded limitations are documented in [ADR 003](003-editing-refinement-and-agent-validation.md).
+
+## Context
+
+The architecture proposal suggests TypeScript and a Canvas-style renderer. This is not a requirement. The implementation needs reproducible text, paths, assets, masks, compositing, raster operations, and an ergonomic agent interface. It does not need a browser, interactive GUI, or GPU. The user explicitly authorized choosing any suitable language and ecosystem.
+
+## Decision
+
+Use TypeScript on Node.js 22+, with native Skia supplied by `@napi-rs/canvas`. Use Zod for runtime validation and typed commands, YAML/JSON for authoring, and the official MCP TypeScript SDK for stdio agent tools. Keep renderer, verifier, and agent decisions separate. Use ordinary modules in one package, rather than prematurely publishing a monorepo of packages.
+
+TypeScript serves the structured data and agent-facing control plane. CPU Skia supplies the expensive graphics primitives in native code. Pixel adjustments currently use typed arrays in TypeScript; that is the first candidate for profiling-driven native optimization.
+
+This is **not a WebGL implementation**. There is no browser, DOM, canvas element, GPU driver requirement, or browser automation in the rendering path. The native package offers a familiar Canvas 2D API, which is an API shape rather than a browser dependency.
+
+## Alternatives considered
+
+| Alternative                 | Strength                                  | Reason not selected initially                                                                                                                        |
+| --------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Python + Pillow/Cairo       | Mature image analysis and raster tooling  | More integration work to unify paths, font layout, compositing and the chosen typed command surface; remains reasonable for verification extensions. |
+| Rust + Skia/tiny-skia       | Tight memory control and efficient pixels | Larger build/distribution surface before proving the agent representation. A native raster kernel can be added behind the same API.                  |
+| Browser Canvas/WebGL/WebGPU | Interactive previews and GPU throughput   | Browser/driver variation and setup add complexity to a CPU-first, headless engine.                                                                   |
+| SVG + rasterization         | Excellent vector composition              | Local raster editing, operation history and tiles still need a separate raster subsystem.                                                            |
+
+## Consequences
+
+- Rendering works locally with prebuilt native binaries, bundled fonts and no service credentials.
+- Same input bytes, package lock, font bytes, renderer version and runtime/platform produce repeatable PNGs. Cross-platform or cross-version byte identity is not claimed.
+- System font loading is disabled by the native adapter. Latin font packages and hashes are explicit dependencies. Applications embedding the SDK should not preload a separate native canvas font registry.
+- Region rendering initially composites the full canvas, then crops exact pixels. Draft is a downsampled full render. These are correctness features, not performance optimizations.
+- Full-canvas layer surfaces trade memory for simple correct composition. A surface budget rejects oversized scenes. Dirty-tile caches and region-aware kernels are later work.
+- An external agent can supply natural-language planning and visual critique through MCP; the engine does not call a particular model provider.
+
+References: [native Canvas/Skia binding](https://github.com/Brooooooklyn/canvas), [Zod validation](https://zod.dev/basics), [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).