rtistree 0.5.0 → 0.6.0

package/dist/sprites.d.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import type { Project } from './project.js';
+/** Controls the two portable artifacts written by exportSpriteSheet. */
+export declare const spriteSheetOptionsSchema: z.ZodObject<{
+    manifest: z.ZodOptional<z.ZodString>;
+    atlas: z.ZodOptional<z.ZodObject<{
+        padding: z.ZodDefault<z.ZodNumber>;
+        extrusion: z.ZodDefault<z.ZodNumber>;
+        power_of_two: z.ZodDefault<z.ZodBoolean>;
+        max_width: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SpriteSheetOptions = z.infer<typeof spriteSheetOptionsSchema>;
+/**
+ * Render declared canvas-frame sprites once and pack their exact RGBA pixels
+ * into a deterministic, engine-neutral PNG atlas and JSON manifest. Frames are
+ * intentionally not trimmed: their declared bounds and pivots remain stable.
+ */
+export declare function exportSpriteSheet(project: Project, output: string, raw?: unknown): Promise<{
+    image: string;
+    manifest: string;
+    width: number;
+    height: number;
+    frames: number;
+    animations: number;
+    evidence: {
+        scene_hash: string;
+        source_png_hash: string;
+        atlas_png_hash: string;
+    };
+}>;

package/dist/sprites.js

@@ -0,0 +1,142 @@
+import { extname, basename, resolve } from 'node:path';
+import { z } from 'zod';
+import { createCanvas } from './native.js';
+import { writeArtifact } from './artifacts.js';
+import { sceneHash, sha256 } from './assets.js';
+import { spriteAtlasSchema } from './schema.js';
+/** Controls the two portable artifacts written by exportSpriteSheet. */
+export const spriteSheetOptionsSchema = z.strictObject({
+    manifest: z.string().min(1).max(2048).optional(),
+    atlas: spriteAtlasSchema.optional(),
+});
+function nextPowerOfTwo(value) {
+    let result = 1;
+    while (result < value)
+        result *= 2;
+    return result;
+}
+function packFrames(sprites, atlas) {
+    const margin = atlas.padding + atlas.extrusion;
+    const frames = Object.entries(sprites.frames)
+        .map(([id, frame]) => ({
+        id,
+        width: frame.bounds[2] + margin * 2,
+        height: frame.bounds[3] + margin * 2,
+    }))
+        // The explicit sort means authored object ordering cannot change the atlas.
+        .sort((a, b) => b.height - a.height || b.width - a.width || a.id.localeCompare(b.id));
+    const widest = Math.max(...frames.map((frame) => frame.width));
+    // POT sheets start at the narrowest possible valid power of two. This can
+    // fit tall sparse sets that a square-root estimate would wrongly reject.
+    const minimum = atlas.power_of_two
+        ? widest
+        : Math.max(widest, Math.ceil(Math.sqrt(frames.reduce((sum, frame) => sum + frame.width * frame.height, 0))));
+    if (minimum > atlas.max_width)
+        throw new Error('Sprite atlas frames exceed max_width');
+    let width = atlas.power_of_two ? nextPowerOfTwo(minimum) : minimum;
+    if (width > atlas.max_width)
+        throw new Error('Sprite atlas power-of-two width exceeds max_width');
+    while (true) {
+        let x = 0, y = 0, rowHeight = 0, usedWidth = 0;
+        const placements = [];
+        for (const frame of frames) {
+            if (x && x + frame.width > width) {
+                y += rowHeight;
+                x = 0;
+                rowHeight = 0;
+            }
+            if (y + frame.height > 8192)
+                break;
+            placements.push({ ...frame, x, y });
+            x += frame.width;
+            rowHeight = Math.max(rowHeight, frame.height);
+            usedWidth = Math.max(usedWidth, x);
+        }
+        if (placements.length === frames.length) {
+            const usedHeight = y + rowHeight;
+            const outputWidth = atlas.power_of_two ? width : usedWidth;
+            const outputHeight = atlas.power_of_two ? nextPowerOfTwo(usedHeight) : usedHeight;
+            if (outputWidth > 8192 || outputHeight > 8192)
+                throw new Error('Sprite atlas exceeds 8192 pixels');
+            return { placements, width: outputWidth, height: outputHeight };
+        }
+        const next = atlas.power_of_two
+            ? width * 2
+            : Math.min(atlas.max_width, Math.max(width + 1, Math.ceil(width * 1.5)));
+        if (next > atlas.max_width || next === width)
+            throw new Error('Sprite atlas cannot fit within max_width and 8192-pixel height');
+        width = next;
+    }
+}
+function copyPixel(target, targetWidth, targetX, targetY, source, sourceWidth, sourceX, sourceY) {
+    const to = (targetY * targetWidth + targetX) * 4, from = (sourceY * sourceWidth + sourceX) * 4;
+    target.set(source.subarray(from, from + 4), to);
+}
+/**
+ * Render declared canvas-frame sprites once and pack their exact RGBA pixels
+ * into a deterministic, engine-neutral PNG atlas and JSON manifest. Frames are
+ * intentionally not trimmed: their declared bounds and pivots remain stable.
+ */
+export async function exportSpriteSheet(project, output, raw = {}) {
+    const options = spriteSheetOptionsSchema.parse(raw);
+    if (extname(output).toLowerCase() !== '.png')
+        throw new Error('Sprite atlas output must end in .png');
+    const image = resolve(output), manifest = resolve(options.manifest ?? output.replace(/\.png$/i, '.json'));
+    if (image === manifest)
+        throw new Error('Sprite atlas image and manifest must have different paths');
+    if (extname(manifest).toLowerCase() !== '.json')
+        throw new Error('Sprite atlas manifest must end in .json');
+    const scene = await project.scene(), sprites = scene.sprites;
+    if (!sprites)
+        throw new Error('Scene has no sprites manifest');
+    const atlas = spriteAtlasSchema.parse({ ...sprites.atlas, ...options.atlas }), packing = packFrames(sprites, atlas), render = await project.render({ quality: 'final', cache: false }), canvas = createCanvas(packing.width, packing.height), context = canvas.getContext('2d'), pixels = context.createImageData(packing.width, packing.height), records = {};
+    const placements = new Map(packing.placements.map((placement) => [placement.id, placement]));
+    for (const [id, frame] of Object.entries(sprites.frames)) {
+        const placement = placements.get(id);
+        const [sourceX, sourceY, width, height] = frame.bounds;
+        const x = placement.x + atlas.padding + atlas.extrusion, y = placement.y + atlas.padding + atlas.extrusion;
+        for (let py = 0; py < height; py++)
+            for (let px = 0; px < width; px++)
+                copyPixel(pixels.data, packing.width, x + px, y + py, render.pixels, render.width, sourceX + px, sourceY + py);
+        // Copy edge pixels into the extrusion ring. Padding outside this ring stays transparent.
+        for (let py = -atlas.extrusion; py < height + atlas.extrusion; py++)
+            for (let px = -atlas.extrusion; px < width + atlas.extrusion; px++) {
+                if (px >= 0 && py >= 0 && px < width && py < height)
+                    continue;
+                copyPixel(pixels.data, packing.width, x + px, y + py, render.pixels, render.width, sourceX + Math.max(0, Math.min(width - 1, px)), sourceY + Math.max(0, Math.min(height - 1, py)));
+            }
+        records[id] = {
+            frame: [x, y, width, height],
+            source: frame.bounds,
+            pivot: frame.pivot,
+            duration: frame.duration,
+            tags: frame.tags,
+        };
+    }
+    context.putImageData(pixels, 0, 0);
+    const png = await canvas.encode('png'), pngHash = sha256(png), document = {
+        format: 'rtistree-sprites@1',
+        image: basename(image),
+        size: [packing.width, packing.height],
+        frames: records,
+        animations: sprites.animations,
+        atlas: { ...atlas, packing: 'shelf-v1', trimmed: false, sampling: 'nearest' },
+        evidence: {
+            scene_hash: sceneHash(scene),
+            source_png_hash: render.evidence.render.png_hash,
+            atlas_png_hash: pngHash,
+        },
+    };
+    await writeArtifact(image, png);
+    await writeArtifact(manifest, JSON.stringify(document, null, 2) + '\n');
+    return {
+        image,
+        manifest,
+        width: packing.width,
+        height: packing.height,
+        frames: Object.keys(records).length,
+        animations: Object.keys(sprites.animations).length,
+        evidence: document.evidence,
+    };
+}
+//# sourceMappingURL=sprites.js.map

package/dist/sprites.js.map

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

package/dist/starter.d.ts

@@ -0,0 +1,7 @@
+/** Create a starter in a new directory. Existing paths are never overwritten. */
+export declare function createStarter(directory: string): Promise<{
+    directory: string;
+    files: string[];
+    next: string[];
+    output: string;
+}>;

package/dist/starter.js

@@ -0,0 +1,38 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+/** Create a starter in a new directory. Existing paths are never overwritten. */
+export async function createStarter(directory) {
+    const destination = resolve(directory);
+    const names = ['scene.json', 'refine.json', 'render.mjs', 'README.md'];
+    const templates = await Promise.all(names.map(async (name) => [name, await readFile(new URL(`../examples/hello/${name}`, import.meta.url))]));
+    const { version } = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+    const manifest = {
+        name: 'rtistree-artwork',
+        private: true,
+        type: 'module',
+        scripts: { render: 'rtistree render scene.json -o hello.png', 'render:sdk': 'node render.mjs' },
+        dependencies: { rtistree: version },
+    };
+    // mkdir is exclusive: reject files, directories and symlinks, even empty directories.
+    try {
+        await mkdir(destination);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new Error(`Destination already exists: ${destination}. Choose a new directory.`);
+        throw error;
+    }
+    for (const [name, contents] of templates)
+        await writeFile(join(destination, name), contents, { flag: 'wx' });
+    await writeFile(join(destination, 'package.json'), JSON.stringify(manifest, null, 2) + '\n', {
+        flag: 'wx',
+    });
+    await writeFile(join(destination, '.gitignore'), 'node_modules/\nhistory/\n*.png\n*.evidence.json\n', { flag: 'wx' });
+    return {
+        directory: destination,
+        files: [...names, 'package.json', '.gitignore'],
+        next: ['Change into the created directory', 'npm install', 'npm run render'],
+        output: 'hello.png',
+    };
+}
+//# sourceMappingURL=starter.js.map

package/dist/starter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"starter.js","sourceRoot":"","sources":["../src/starter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,iFAAiF;AACjF,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,SAAiB;IACnD,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,CAAC,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;IACvE,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,GAAG,CACjC,KAAK,CAAC,GAAG,CACP,KAAK,EAAE,IAAI,EAAE,EAAE,CACb,CAAC,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,qBAAqB,IAAI,EAAE,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAU,CACzF,CACF,CAAC;IACF,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK,CAC5B,MAAM,QAAQ,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAC7C,CAAC;IACzB,MAAM,QAAQ,GAAG;QACf,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,EAAE,MAAM,EAAE,yCAAyC,EAAE,YAAY,EAAE,iBAAiB,EAAE;QAC/F,YAAY,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE;KACpC,CAAC;IACF,sFAAsF;IACtF,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;YACpD,MAAM,IAAI,KAAK,CAAC,+BAA+B,WAAW,2BAA2B,CAAC,CAAC;QACzF,MAAM,KAAK,CAAC;IACd,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,SAAS;QACtC,MAAM,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACrE,MAAM,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE;QAC3F,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IACH,MAAM,SAAS,CACb,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC,EAC/B,mDAAmD,EACnD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACF,OAAO;QACL,SAAS,EAAE,WAAW;QACtB,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,cAAc,EAAE,YAAY,CAAC;QAC/C,IAAI,EAAE,CAAC,mCAAmC,EAAE,aAAa,EAAE,gBAAgB,CAAC;QAC5E,MAAM,EAAE,WAAW;KACpB,CAAC;AACJ,CAAC"}

package/dist/studio-reference.js

@@ -34,6 +34,6 @@ export const studioReference = {
         lighting: 'art.normal(heightFn,x,y,strength=1,step=1) → surface normal from central differences. art.light(normal,[r,g,b,a],{light:[x,y,z]?,ambient?,diffuse?,specular?,shininess?}) → RGBA using Lambert diffuse and Blinn–Phong specular, viewer along +Z. Artistic 2.5D shading, not ray tracing.',
     },
     example: 'return art.raster((x,y) => { const n=art.fbm(x/35,y/35); return [35+n*40,40+n*35,45+n*30,255]; });',
-    edits: 'readRasterRegion reads exact canvas-space PNG pixels and a scene hash. writeRasterRegion consumes an exact-size project-local PNG and that expected_hash, with replace/over semantics and canvas/layer coordinates. Layer-space patches capture reference dimensions and follow transforms. Layer effects/masks can change patch appearance; locality guards reject outward leakage.',
+    edits: 'readRasterRegion reads exact canvas-space PNG pixels and a scene hash. writeRasterRegion consumes an exact-size project-local PNG and that expected_hash, with replace/over semantics and canvas/layer coordinates. Layer-space patches capture reference dimensions and follow transforms. Patches follow target effects/operations and precede its mask/opacity; ancestor effects can change appearance; locality guards reject outward leakage.',
 };
 //# sourceMappingURL=studio-reference.js.map

package/dist/studio-reference.js.map

@@ -1 +1 @@
-{"version":3,"file":"studio-reference.js","sourceRoot":"","sources":["../src/studio-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,mBAAmB;IAC5B,UAAU,EAAE,gBAAgB;IAC5B,aAAa,EAAE,iBAAiB;IAChC,UAAU,EACR,8YAA8Y;IAChZ,QAAQ,EACN,sWAAsW;IACxW,SAAS,EACP,wPAAwP;IAC1P,MAAM,EAAE;QACN,iBAAiB,EAAE,EAAE;QACrB,MAAM,EAAE,EAAE;QACV,4BAA4B,EAAE,EAAE;QAChC,IAAI,EAAE,IAAI;QACV,UAAU,EAAE,GAAG;QACf,cAAc,EAAE,EAAE;QAClB,UAAU,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC;QACvB,WAAW,EAAE,GAAG;KACjB;IACD,GAAG,EAAE;QACH,MAAM,EACJ,gbAAgb;QAClb,MAAM,EACJ,uRAAuR;QACzR,MAAM,EACJ,iJAAiJ;QACnJ,MAAM,EACJ,sLAAsL;QACxL,KAAK,EACH,oGAAoG;QACtG,KAAK,EACH,0OAA0O;QAC5O,KAAK,EACH,qKAAqK;QACvK,WAAW,EACT,+IAA+I;QACjJ,MAAM,EACJ,qIAAqI;QACvI,IAAI,EAAE,kKAAkK;QACxK,QAAQ,EACN,0HAA0H;QAC5H,IAAI,EAAE,2EAA2E;QACjF,QAAQ,EACN,2RAA2R;KAC9R;IACD,OAAO,EACL,oGAAoG;IACtG,KAAK,EACH,sXAAsX;CACzX,CAAC"}
+{"version":3,"file":"studio-reference.js","sourceRoot":"","sources":["../src/studio-reference.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,mFAAmF;AACnF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,OAAO,EAAE,mBAAmB;IAC5B,UAAU,EAAE,gBAAgB;IAC5B,aAAa,EAAE,iBAAiB;IAChC,UAAU,EACR,8YAA8Y;IAChZ,QAAQ,EACN,sWAAsW;IACxW,SAAS,EACP,wPAAwP;IAC1P,MAAM,EAAE;QACN,iBAAiB,EAAE,EAAE;QACrB,MAAM,EAAE,EAAE;QACV,4BAA4B,EAAE,EAAE;QAChC,IAAI,EAAE,IAAI;QACV,UAAU,EAAE,GAAG;QACf,cAAc,EAAE,EAAE;QAClB,UAAU,EAAE,CAAC,EAAE,EAAE,KAAK,CAAC;QACvB,WAAW,EAAE,GAAG;KACjB;IACD,GAAG,EAAE;QACH,MAAM,EACJ,gbAAgb;QAClb,MAAM,EACJ,uRAAuR;QACzR,MAAM,EACJ,iJAAiJ;QACnJ,MAAM,EACJ,sLAAsL;QACxL,KAAK,EACH,oGAAoG;QACtG,KAAK,EACH,0OAA0O;QAC5O,KAAK,EACH,qKAAqK;QACvK,WAAW,EACT,+IAA+I;QACjJ,MAAM,EACJ,qIAAqI;QACvI,IAAI,EAAE,kKAAkK;QACxK,QAAQ,EACN,0HAA0H;QAC5H,IAAI,EAAE,2EAA2E;QACjF,QAAQ,EACN,2RAA2R;KAC9R;IACD,OAAO,EACL,oGAAoG;IACtG,KAAK,EACH,obAAob;CACvb,CAAC"}

package/docs/agent-art-workflow.md

@@ -1,7 +1,7 @@
 # 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`
+protocol is returned by `rtistree art-guide`, included in `rtistree studio-help`
 and MCP `studioHelp`, and exported as `artDirectionGuide` by the SDK.
 
 MCP connections receive the core rules in the server's initialization
@@ -10,7 +10,7 @@ MCP connections receive the core rules in the server's initialization
 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
+CLI hosts should read `rtistree 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.
 
@@ -59,6 +59,16 @@ 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.
 
+**Pixel art:** declare the intended display size, palette and transparency policy.
+Keep coordinates, frame dimensions and pivots on integer pixels, use
+nearest-neighbour scaling, and inspect at the actual game size. A declared
+pixel-art contract can catch palette overruns, invalid tile geometry and
+disallowed transforms or blur; the sprite exporter preserves exact RGBA frame
+pixels. It cannot decide whether a one-pixel choice is artistically good.
+Use palette tiles for compact indexed marks and seeded studio programs for dense
+or generated frames. Pack a set only after the individual frames and their
+contact sheet have been inspected.
+
 **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.

package/docs/agent-setup.md

@@ -1,5 +1,8 @@
 # Connect an agent
 
+New to Rtistree? Read [Core concepts: an agent is the interface](core-concepts.md)
+for how you, your agent and the engine work together.
+
 Rtistree provides a CLI, an MCP server and a TypeScript SDK. The engine renders locally;
 your host supplies the model and any vision capability.
 
@@ -41,17 +44,19 @@ Example task:
 > 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.
+critiques, program execution, pipelines, sprite-atlas export and staged production. The
+`exportSprites` tool writes an engine-neutral PNG atlas plus JSON frame/animation metadata for
+a scene with a `sprites` manifest. 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
+npx rtistree art-guide
+npx rtistree inspect scene.json
+npx rtistree render scene.json -o review.png
+npx rtistree studio-help
 ```
 
 Read the JSON guide, open the rendered image, then choose a focused edit. Do not substitute a

package/docs/atelier.md

@@ -2,7 +2,7 @@
 
 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.
+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 `rtistree studio-help` for the synchronous painting API and technique catalogue.
 
 ## Working sequence
 
@@ -17,6 +17,13 @@ CLI actions also have SDK equivalents (`buildPipeline`, `production`) and MCP to
 
 ## Editable dependency graph
 
+These examples assume an installed package and an existing scene project; see
+[the first painting](studio.md#first-painting). Save the graph as `pipeline.json`,
+create `programs/ground.js` inside the artwork project, and make that program return
+a Canvas of the requested dimensions. For a minimal ground program, use
+`return art.raster(() => [38, 62, 69, 255]);`. Source paths inside the graph resolve
+from the artwork project root; the CLI request filename resolves from your shell directory.
+
 ```json
 {
   "version": 1,
@@ -44,15 +51,19 @@ CLI actions also have SDK equivalents (`buildPipeline`, `production`) and MCP to
 }
 ```
 
-`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.
+`rtistree 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.
+All node artifacts are baked before one scene transaction. The CLI takes the graph
+as the request file directly. To pass a previously inspected `expected_hash`, use
+the SDK third argument or MCP’s separate `expected_hash` field. 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.
+It does not copy production sessions, rejected candidates, reviews or edit history; retain
+the original project if you need those records.
 
 ## Production requests
 
-Create a plan with `graphics production my-project plan.json`:
+Create a plan with `rtistree production my-project plan.json`:
 
 ```json
 {

package/docs/cli-reference.md

@@ -1,34 +1,54 @@
 # 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.
+Installing Rtistree exposes `rtistree` and the compatibility alias `graphics`. In a local npm project, use `npx rtistree`.
+Run `rtistree --help` for the complete installed-version reference. Structured results go to
+stdout as JSON; errors go to stderr. Failed verification/preflight and non-identical recipe replay exit 2; input/runtime errors exit 1.
+
+## Create a starter
+
+```sh
+npx rtistree@latest init my-art
+cd my-art
+npm install
+npm run render
+```
+
+The destination must be a new directory. The starter includes a scene, sample patch, SDK example
+and npm render scripts. `init` writes starter files without installing dependencies or executing painting programs.
 
 ## 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
+npx rtistree inspect scene.json
+npx rtistree inspect scene.json --layer title
+npx rtistree inspect-region scene.json 0 0 100 100
+npx rtistree render scene.json -o image.png
+npx rtistree render-region scene.json 0 0 100 100 -o crop.png
+npx rtistree sprites scene.json -o output/sprites.png --manifest output/sprites.json
+npx rtistree apply scene.json patch.json
+npx rtistree undo scene.json
+npx rtistree redo scene.json
+npx rtistree 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.
 
+`sprites` reads a scene or configured project with a sprite manifest and writes a
+deterministically packed atlas plus frame/animation metadata. The atlas output
+must end in `.png`; the optional `--manifest` path must end in `.json`. Pixel-art
+projects can opt into integer, palette and nearest-neighbour guardrails. Use
+`npx rtistree sprites --help` for the exact options supported by the installed
+version.
+
 ## 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
+npx rtistree verify scene.json -o report.json --heatmap heatmap.png
+npx rtistree critique scene.json critique.json
+npx rtistree export scene.json -o portable/scene.json
+npx rtistree export scene.json --format png -o image.png
 ```
 
 Verification measures configured technical constraints. Critiques are authored after inspecting
@@ -38,12 +58,12 @@ 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
+npx rtistree art-guide
+npx rtistree studio-help
+npx rtistree program scene.json program.json
+npx rtistree program-replay scene.json asset-id
+npx rtistree pipeline scene.json pipeline.json
+npx rtistree production scene.json request.json
 ```
 
 Read [studio](studio.md) for program requests and [staged production](atelier.md) for plans,
@@ -52,10 +72,53 @@ candidate captures, reviews and selection. Program execution is for trusted code
 ## 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
+npx rtistree project new artwork --size A3 --orientation landscape --ppi 300 --bleed 3mm
+npx rtistree schema --kind scene
+npx rtistree schema --kind command
+npx rtistree serve /absolute/path/to/scene.json
 ```
 
 The MCP server uses stdio. See [agent setup](agent-setup.md).
+
+## Additional commands
+
+| Command                                                     | Purpose                                                                             |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `npx rtistree rebase scene.json`                            | Merge manual source changes into journaled state; conflicts fail without committing |
+| `npx rtistree compact scene.json`                           | Compress history while retaining undo and redo                                      |
+| `npx rtistree raster-read scene.json read.json`             | Write an exact crop plus evidence and return an asset descriptor                    |
+| `npx rtistree raster-write scene.json write.json`           | Commit an exact-size PNG patch with a required current hash                         |
+| `npx rtistree sprites scene.json -o output/sprites.png`     | Pack declared sprite frames into an atlas and write animation metadata              |
+| `npx rtistree import-svg drawing.svg -o drawing.scene.json` | Import the supported static SVG subset                                              |
+| `npx rtistree preflight artwork --preset screen`            | Check physical document/export settings and save a report                           |
+| `npx rtistree proof artwork --preset print -o proof.png`    | Make a CMYK round-trip proof; requires a configured ICC profile                     |
+| `npx rtistree benchmark scene.json brief.json before`       | Capture a benchmark checkpoint after recording a current critique                   |
+| `npx rtistree benchmark scene.json brief.json finish`       | Finish after at least two inspected checkpoints                                     |
+
+Dense request shapes are in [studio](studio.md). Source rebasing, critiques and benchmark
+requirements are in [editing workflows](evolution.md). Names such as `patch.json`, `read.json`
+and `critique.json` are request files you author, not files created by `init`.
+
+## Options, paths and output
+
+- `--output` / `-o` chooses an artifact path. Explicit paths and request filenames resolve
+  from the shell's working directory. Asset/program paths inside requests resolve from the
+  artwork project root. Without `-o`, configured projects use `output_dir`; bare scene files
+  use a `renders/` directory alongside the scene.
+- `render --quality draft|preview|final` controls PNG rendering. Draft halves dimensions
+  after rendering; preview and final share the full-quality path. `--layer ID` renders an
+  isolated layer on a full-size transparent canvas. `render-region` requires an integer crop
+  entirely inside the canvas; default/final quality is an exact full-render crop.
+- `inspect-region` also writes `inspection.png` and its evidence unless you supply `-o`.
+- Artwork `export` and full `render` accept `--format`, `--preset` and `--ppi`. Known output
+  extensions are inferred. Print exports additionally accept `--profile` (project-relative
+  ICC file; implies CMYK), `--colour-space srgb|cmyk` and `--crop-marks`. Use `export` for
+  print options; a plain PNG `render` with only `--profile` does not select the export path.
+- `schema --kind scene` describes a resolved scene. Source scenes with includes/components
+  use the packaged `authoring.schema.json`; a patch uses `patch.schema.json`.
+
+JSON is the structured result format; help is plain text and `serve` writes MCP protocol
+messages. The npm/npx launcher can print its own installation notices. `verify` and
+`preflight` failures, and non-identical `program-replay` results, exit 2. Input/runtime/export
+errors exit 1. Warnings alone do not make preflight fail. Program or pipeline build success
+only means execution succeeded; it does not establish visual quality.

package/docs/core-concepts.md

@@ -0,0 +1,95 @@
+# Core concepts: an agent is the interface
+
+Rtistree is designed to be operated through an agent. You describe what you want,
+set constraints and give feedback. The agent uses Rtistree to construct artwork,
+inspect renders and make focused revisions.
+
+The CLI, MCP server and TypeScript SDK are the agent's controls. They are also
+available for direct human use, but learning every command is not the intended
+starting point for someone who wants to make art.
+
+## Three roles
+
+| Role      | Responsibility                                                                                     |
+| --------- | -------------------------------------------------------------------------------------------------- |
+| You       | Set the brief, references, constraints and intended use; judge whether the result meets your needs |
+| The agent | Plan the work, call tools, inspect images, identify defects and revise the artwork                 |
+| Rtistree  | Store the editable scene, render it, apply typed edits, track history and export files             |
+
+Rtistree does not contain a model. Your agent host supplies the model, its context,
+image-viewing capability and tool access. An agent that cannot inspect images can
+still operate the tools, but cannot credibly judge their visual quality.
+
+You can connect an MCP-capable host, give an agent access to the CLI, or integrate
+the SDK into your own application. [Agent setup](agent-setup.md) explains each path.
+The host decides which tools require confirmation and what files the agent can access.
+
+## A conversation becomes an editable scene
+
+A useful starting brief might be:
+
+> Create a square event poster with a bold title, a quiet landscape and room for
+> a date. Keep the title and illustration independently editable. Show me a
+> composition before adding detail.
+
+The agent creates a scene with named layers rather than treating the final PNG as
+its only state. Text, geometry, image assets, masks and adjustments can retain
+separate identities. For painted detail, trusted JavaScript programs can produce
+baked raster assets with saved source, parameters and seeds.
+
+After inspecting the render, you might say:
+
+> The title works. Reduce the contrast behind it and move the sun farther right.
+
+The agent can inspect the relevant layers, change those parts and render again.
+It should preserve the parts you approved and check that the requested revision
+actually helps. Scoped raster edits have an enforced pixel-locality check;
+arbitrary structural edits do not automatically promise that every other pixel
+will remain unchanged.
+
+A painted image is only as editable as its construction. If an agent bakes every
+part into one asset, Rtistree cannot recover meaningful objects from those pixels.
+Ask for independent layers or program parameters for the parts you expect to revise.
+
+## The working loop
+
+1. **Direct:** establish the brief, references, intended size and acceptance criteria.
+2. **Construct:** make a representative composition or asset with useful editable structure.
+3. **Inspect:** open the actual render, including silhouettes, crops or animation frames as relevant.
+4. **Refine:** identify a specific defect, make a focused change and compare the result.
+5. **Deliver:** export the accepted state and keep the source needed for future edits.
+
+This loop is deliberate. A successful command, valid file or reproducible image
+is not proof that the artwork is good. The agent brings drawing and observation
+skills; Rtistree provides tools and records. A stronger agent may use the same
+toolkit better, but the toolkit does not guarantee artistic success.
+
+## Guidance travels with the tool
+
+The package includes art-direction guidance based on recorded trials: connected
+construction, coherent prop perspective, ground contact, representative samples,
+and separate technical, functional and visual assessment.
+
+- MCP supplies compact instructions during connection and exposes the full guide
+  through `studioHelp` and the `rtistree://guides/art-direction` resource.
+- CLI agents can read it with `rtistree art-guide`.
+- SDK hosts can provide `rtistreeAgentInstructions` and `artDirectionGuide` to their agent.
+
+Availability is not automatic compliance: some hosts do not pass server instructions
+to their model. Ask the agent to read the guide before authoring. The
+[art-direction workflow](agent-art-workflow.md) explains the process and optional
+production gates in detail.
+
+## Local work and explicit execution
+
+Ordinary scene loading and rendering use local assets and do not execute painting
+recipes. Program execution, pipeline builds and recipe replay are explicit actions
+for trusted code; the JavaScript VM is not a security sandbox. The agent host's
+model calls may use a remote service even though Rtistree renders locally.
+
+Edits are journaled and can be undone. Portable export saves the current artwork,
+assets and recipes as a new baseline; it does not copy the complete edit history
+or production reviews. Keep the original project when those records matter.
+
+Start by [connecting your agent](agent-setup.md). To understand the mechanics
+first, [make your first image](getting-started.md) with the small CLI walkthrough.

package/docs/decisions/004-print-production-and-projects.md

@@ -16,4 +16,4 @@ Hybrid PDF preserves supported text, vectors, gradients and isolation-free group
 
 The print trial revealed two defects that were fixed during implementation: metadata configuration could overwrite the requested CMYK conversion, and mask inversion after erosion expanded the selected foreground instead of shrinking it. Actual-file tests and visual proof inspection cover these cases. The original engine regression suite remains in place, alongside production and editing tests.
 
-See [the production guide](../production.md) for capabilities and operational limits, [the A3 evidence](../previews/a3-production.json), and [the generated-asset print trial](../../examples/print-trial/README.md).
+See [the production guide](../production.md) for capabilities and operational limits, [the A3 evidence](../previews/a3-production.json), and [the generated-asset print trial](https://github.com/Coly010/rtistree/blob/main/examples/print-trial/README.md).