rtistree 0.5.1 → 0.6.0

package/docs/releasing.md

@@ -1,60 +1,116 @@
 # Release process
 
-The repository is `Coly010/rtistree`, the npm package is `rtistree`, and the website's
-canonical origin is `https://rtistree.dev`. The package is MIT licensed to Colum Ferry.
-
-## Validate a release
-
-1. Update `package.json`, its lockfile and `CHANGELOG.md` together. Keep the website version
-   label and package instructions aligned with the release.
-2. Run `npm ci`, `npm run check`, `npm run format:check` and `npm run package:check`.
-3. Run `npm ci --prefix website` and `npm run build --prefix website`.
-4. Review the tarball inventory, documentation commands and example sources. The package
-   intentionally includes only the small hello example; larger trials are repository assets.
-5. Commit the validated source and tag the matching version, for example `v0.5.0`.
-
-## First npm publication
+Rtistree uses Release Please to prepare version and changelog updates, and npm trusted
+publishing to publish from GitHub Actions. The repository is `Coly010/rtistree`, the npm
+package is `rtistree`, and the website is `https://rtistree.dev`.
+
+## Everyday releases
+
+1. Merge changes into `main` using Conventional Commit messages. For squash merges, use
+   a conventional PR title; that title becomes the commit message.
+2. The **Release** workflow opens or updates a release PR with the next version,
+   `CHANGELOG.md`, both package lockfiles, and the README and website version labels.
+3. Review the generated notes and the **Graphics engine** and **Documentation website**
+   checks on that PR. Release PRs stay open until a maintainer decides to ship.
+4. Merge the release PR. The same workflow creates the `vX.Y.Z` tag and GitHub release,
+   validates the tagged source and packaged installation, then publishes the tested
+   tarball to npm with provenance. It also attaches that tarball to the GitHub release.
+
+There is no npm token or personal access token in this flow. GitHub supplies a short-lived
+OIDC identity that npm checks against the configured repository and workflow.
+
+### Commit messages and versions
+
+| Commit                            | Example                                            | Version change                          |
+| --------------------------------- | -------------------------------------------------- | --------------------------------------- |
+| `fix:`                            | `fix: preserve layer opacity when undoing an edit` | Patch: 0.5.1 → 0.5.2                    |
+| `feat:`                           | `feat: add palette extraction`                     | Minor: 0.5.1 → 0.6.0                    |
+| Breaking change (`!`)             | `feat!: replace the scene coordinate format`       | Minor before 1.0; major from 1.0 onward |
+| `docs:`, `ci:`, `chore:`, `test:` | `docs: explain sprite export`                      | No release on their own                 |
+
+Use a `BREAKING CHANGE:` footer to explain migration steps for breaking changes.
+The largest applicable change determines the release version. Do not edit versions by hand
+for a routine release. Releases continue to use normal `0.x.y` versions on npm's `latest`
+tag while the project is a public alpha; this does not claim a stable 1.0 API.
+
+The manifest starts at the already-published 0.5.1. `bootstrap-sha` bounds the initial
+history scan at that tag. Older non-conventional commit messages are not automatically
+converted into changelog entries. Once the first automated release is merged, normal
+release history takes over.
+
+## Trusted publisher setup
+
+The npm package owner configures this once in the package's settings:
+
+- Provider: GitHub Actions
+- Repository owner: `Coly010`
+- Repository: `rtistree`
+- Workflow filename: `release.yml`
+- Environment: leave blank (the workflow does not use a GitHub environment)
+- Permission: publish
 
-The owner must authenticate with `npm login` and complete any npm 2FA challenge.
-Confirm `npm whoami` is the intended owner. Build and inspect the package before publishing:
+Alternatively, with an authenticated npm owner account and 2FA:
 
 ```sh
-npm pack
-npm publish rtistree-0.5.0.tgz --access public
+npx --yes npm@11.19.1 trust list rtistree
+npx --yes npm@11.19.1 trust github rtistree --repository Coly010/rtistree --file release.yml --allow-publish --yes
 ```
 
-Do not republish a version number. If a command's outcome is uncertain, check the npm
-registry before retrying. Never commit npm tokens or configure long-lived tokens in workflows.
+The workflow uses Node.js 24, npm 11.19.1, a GitHub-hosted runner and `id-token: write`.
+No `NPM_TOKEN`, `NODE_AUTH_TOKEN`, or enablement variable is required. A trust mismatch
+fails publication visibly rather than silently skipping it.
 
-## Subsequent releases with trusted publishing
+In GitHub **Settings → Actions → General → Workflow permissions**, enable **Allow GitHub
+Actions to create and approve pull requests**. GitHub bundles creation and approval in
+one setting; this workflow creates release PRs but does not approve or merge them.
+The repository's default workflow permission can remain read-only.
 
-In the npm package settings, configure a GitHub Actions trusted publisher:
+Bot-created PRs and releases do not trigger ordinary workflows when using `GITHUB_TOKEN`.
+The Release workflow explicitly dispatches both validation workflows on the release PR
+branch and publishes in a dependent job when a release is created. This avoids needing a
+long-lived GitHub token just to trigger CI.
 
-- Owner: `Coly010`
-- Repository: `rtistree`
-- Workflow filename: `release.yml`
+See the [npm trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/)
+and [Release Please documentation](https://github.com/googleapis/release-please-action).
 
-After configuring the npm trusted publisher, set the GitHub repository Actions variable
-`NPM_TRUSTED_PUBLISHING_ENABLED` to `true`. Without it, release validation runs but npm
-publication is skipped. This permits the initial GitHub tarball release before npm sign-in.
+## Recovering a failed release
 
-The release workflow checks the tag against the package version, validates the engine,
-website and packaged installation, then publishes the same checked tarball with provenance.
-It runs on publication of a GitHub release. Configure trust before publishing the next release.
-For the bootstrap release, publish npm first and let the workflow skip an already-published version.
+A GitHub release can exist while npm publication is still running or has failed. Check the
+**Release** workflow before announcing availability. Correct the account/trust problem, then
+use **Actions → Release → Run workflow**, select `main`, and enter the existing tag in the
+`tag` input. Leave the tag blank to refresh the release PR instead.
 
-See https://docs.npmjs.com/trusted-publishers/ for current npm account requirements.
+The retry checks that the tag matches the package, has a published GitHub release and belongs
+to `main`. It rebuilds and tests the tarball. If npm already has that version, the workflow
+only skips publication when its integrity matches the checked tarball; a mismatch or registry
+error fails. Never delete/reuse a published version to fix package contents: ship a new version.
+A failed publish can also be retried by rerunning failed jobs from its original workflow run.
 
-## Website
+## Local validation
 
-The website is an Astro/Starlight static build in `website/`. `docs/` is the source of truth;
-the content sync script generates Starlight pages, remaps repository links and copies curated
-assets. Generated files are ignored by Git but included when preparing a standalone Sites source snapshot.
+```sh
+npm ci
+npm run check
+npm run format:check
+npm run docs:check
+npm run package:check
+npm ci --prefix website
+npm run build --prefix website
+```
+
+The package check installs the actual tarball in a temporary project and exercises the CLI,
+starter, rendering, SDK and MCP guide. It retains the checked archive for the publish job.
+Large trial assets stay in the repository; only the small hello example ships in the package.
 
-`npm run build --prefix website` produces `website/dist`. This is portable static output.
-The Sites project ID is in `website/.openai/hosting.json`; never replace it on redeployment.
-Use the Sites publishing flow to save and deploy the validated source and static archive.
-The `website.yml` workflow validates and uploads a deployable static artifact for each change.
+## Website deployment
 
-Custom-domain DNS must use the exact records returned by the hosting provider. Do not infer
-an apex A record from a preview hostname. Confirm domain and TLS status after the DNS change.
+The website is an Astro/Starlight static build in `website/`. `docs/` is the source of truth;
+the content sync script publishes an explicit list of current user guides plus the changelog,
+remaps repository links and copies curated assets. Maintainer procedures and historical proposals/
+decisions remain in the repository. Removed generated routes and raw source copies are deleted
+during synchronization. Generated files are ignored by Git but included in a standalone Sites source snapshot.
+
+`npm run build --prefix website` produces `website/dist`. The `website.yml` workflow validates
+and uploads that static artifact. **npm releases do not deploy the live website.** Publish the
+validated website through the Sites flow when documentation or the displayed version changes.
+Keep the existing project ID in `website/.openai/hosting.json` when redeploying.

package/docs/scene-format.md

@@ -1,21 +1,26 @@
 # Scene format v1
 
-The examples in this document are the implemented format. The original proposal is exploratory; unsupported fields are rejected, not silently interpreted. Generate machine-readable schemas with `npm run schema` or `rtistree schema`.
+The examples in this document are the implemented format. The original proposal is exploratory; unsupported fields are rejected, not silently interpreted. The package ships schemas in `node_modules/rtistree/schemas/`. Use `authoring.schema.json`
+for source scenes with includes/components and `fragment.schema.json` for included files.
+`npx rtistree schema --kind scene` prints the resolved scene schema; `--kind command` prints
+a single-command schema. A transaction uses `patch.schema.json`. Repository contributors
+can regenerate all schemas with `npm run schema`.
 
-The [production guide](production.md) describes v0.3 physical documents, exports, affine and perspective transforms, extended masks, adjustments, path commands and typography.
+The [production guide](production.md) describes physical documents, exports, affine and perspective transforms, extended masks, adjustments, path commands and typography.
 
-The [studio guide](studio.md) describes v0.4 programmable assets and dense editing. Assets may carry a `recipe: {source, hash}` reference to a frozen program manifest. Promoted regions accept `composite: replace|over` (default replacement). Programs are executed explicitly and baked; scenes never execute referenced recipes while rendering.
+The [studio guide](studio.md) describes programmable assets and dense editing. Assets may carry a `recipe: {source, hash}` reference to a frozen program manifest. Promoted regions accept `composite: replace|over` (default replacement). Programs are executed explicitly and baked; scenes never execute referenced recipes while rendering.
 
 ## Files and assets
 
-Root documents contain `version: 1`, `canvas`, `layers` and/or `include`, optional `assets`, `metadata`, and `verification: {rules: [...]}`. Fragments contain `include`, `assets`, `fonts`, `components` and `layers`. JSON and YAML can be mixed. There can be at most 128 included documents and 256 total layers.
+Root documents contain `version: 1`, `canvas`, optional `layers` and/or `include`, optional `assets`, `metadata`, and `verification: {rules: [...]}`. Fragments contain `include`, `assets`, `fonts`, `components` and `layers`. JSON and YAML can be mixed. Root scenes can also declare `fonts`, `components`, `document` and `paragraph_styles`.
+The loader permits at most 128 document reads including the root, and 256 total layers after expansion.
 
 ```yaml
 assets:
   portrait:
     type: image # or generated-image; provenance category only
     source: ./assets/portrait.png
-    hash: sha256:... # optional on input; checked when supplied
+    # hash is optional; when supplied, use sha256: followed by the file’s 64 hex digest characters
 ```
 
 PNG, JPEG, WebP and TIFF assets are supported. ICC-tagged input is normalised to sRGB. The separate `import-svg` command converts a closed static geometry subset into scene layers. No URL loading or external resource resolution is permitted. Asset paths must resolve inside the root scene directory, including after symlink resolution. File size is limited to 64 MiB and decoded dimensions to 32 megapixels. Large rasters belong in binary image files, not YAML arrays.
@@ -66,7 +71,7 @@ Shapes are `rectangle` (optional radius), `ellipse`, or `path` with SVG path dat
 
 Text is retained as semantic content. It wraps at whitespace and respects explicit newlines. `style` supports `font: inter|display`, `size`, `weight: regular|bold`, `colour`, `line_height` as a multiplier, and `align: left|center|right`. `display` uses DM Serif Display regular; its bold variant is not supplied. Text is clipped to its box, and the verifier reports overflow. Bundled Latin fonts provide reproducible typography; a custom font can be registered in the scene fonts map and selected by its ID.
 
-Generators: `solid` (`colour`); `gradient` (`from`, `to`, `angle`, with 0° horizontal and 90° vertical); `noise` (`seed`, `amount`, optional base `colour`). Every random generator requires an integer seed. Noise is sampled in a stable row-major order.
+Generators: `solid` (`colour`); `gradient` (`from`, `to`, `angle`, with 0° horizontal and 90° vertical); `noise` (`seed`, `amount`, optional base `colour`). Every noise generator requires an explicit integer seed. Noise is sampled in a stable row-major order.
 
 Blend modes: normal, multiply, screen, overlay, darken, lighten, difference, soft-light, hard-light. Compositing and colour adjustments use Skia's sRGB path; this is not a linear-light color grading engine.
 
@@ -115,12 +120,44 @@ Tiles have canvas bounds, a single-character palette, and rows of keys. Rows mus
 
 `replaceTile` replaces a tile with exactly matching bounds or appends a new one. Transparent tile pixels composite over underlying layer content. Palette tiles remain compact grids. Separately, `promoteRegion`, `updateRegion` and `demoteRegion` manage patches with 1–4× resolution and optional external raster sources; see [evolution](evolution.md).
 
+For a complete pixel-art and sprite workflow, see [Pixel art, sprites and
+spritesheets](sprites.md). An optional pixel-art scene contract makes integer
+coordinates, palette use and nearest-neighbour delivery explicit:
+
+```yaml
+pixel_art:
+  scale: 1 # authored tile pixel → scene-pixel multiplier
+  palette: ['#00000000', '#f2be81', '#b75c40']
+  strict: true # reject transforms/blur and invalid tile geometry
+```
+
+The optional `sprites` manifest selects integer canvas rectangles and records
+their game-facing pivot, duration and tags. Animations list frame IDs and a
+loop flag. Atlas settings support padding, edge extrusion, power-of-two output
+and a maximum width:
+
+```yaml
+sprites:
+  frames:
+    walk_0: { bounds: [0, 0, 16, 16], pivot: [8, 14], duration: 120, tags: [walk, right] }
+  animations:
+    walk_right: { frames: [walk_0], loop: true }
+  atlas: { padding: 1, extrusion: 1, power_of_two: true, max_width: 2048 }
+```
+
+`rtistree sprites scene.json -o atlas.png --manifest atlas.json` renders the
+declared frame rectangles and writes an engine-neutral, deterministic atlas
+manifest. Frames are not trimmed; exported records retain both atlas and source
+rectangles. Use `rtistree schema --kind scene` for the complete scene contract
+and `rtistree schema --kind sprites` for export options in the installed version.
+
 ## Commands and verification
 
 `apply` accepts `{reason, expected_hash?, commands: [...]}`. Commands include add/remove/move/resize layer, set opacity/blend/text/style, group siblings, align/distribute siblings, apply effect, apply raster operation, and replace tile. See `rtistree schema --kind command` for exact fields. Removing referenced mask or verification targets is rejected unless the resulting scene is valid. Grouping can change compositing with interleaved siblings; it is an explicit structural edit without a locality promise.
 
 Verification always checks rendered text overflow. Optional rules cover safe-area, text-overflow, text-equals, required-role, contrast, no-overlap and region-luma. Luma is a mean weighted sRGB channel value in [0,1], not perceptual luminance. `contrast` uses declared foreground and explicit background colours. `pixel-contrast` and `visible-area` use counterfactual rendered samples through `verifyRendered` / `Project.verify`. Geometry checks use transformed bounding boxes, not exact silhouettes. A heatmap marks issue bounds. All reports state these limitations.
 
-`render-region` requires an integer rectangle fully inside the canvas and equals an exact crop of the full render. `draft` halves both output dimensions after rendering; preview and final currently use the same full-quality pipeline. PNG output includes renderer evidence in a sidecar. Canonical scene hashes omit timestamps; history includes timestamps for audit purposes without influencing pixel output.
+`render-region` requires an integer rectangle fully inside the canvas and equals an exact crop of the full render. `draft` halves both output dimensions after rendering; preview and final currently use the same full-quality pipeline. PNG output includes renderer evidence in a sidecar. Scene hashes cover the resolved scene, including authored metadata. Journal timestamps are outside
+that scene hash and do not influence pixel output; a timestamp you put in scene metadata does change the hash.
 
 The [evolution guide](evolution.md) documents the expanded command surface, coordinates, components, fonts, adaptive regions, critiques, rebase, compaction, and agent trials.

package/docs/sprites.md

@@ -0,0 +1,166 @@
+# Pixel art, sprites and spritesheets
+
+Rtistree can author small raster assets and package them as a sprite set. The
+sprite workflow is deliberately split into two jobs:
+
+1. draw and inspect each frame as an ordinary Rtistree scene or studio asset;
+2. describe the frames, pivots and animation timing in a `sprites` manifest and
+   export a deterministic atlas for the game or other runtime to consume.
+
+This keeps the artwork editable and reviewable while making the delivery format
+boring and portable. Rtistree is an asset authoring and verification tool here;
+it is not a game engine, a runtime animation system or an automatic animation
+critic.
+
+## Choose the pixel-art contract
+
+Use the optional `pixel_art` scene contract when the image is meant to be read
+as pixels rather than as a smoothly sampled illustration. A pixel-art scene
+should declare its palette policy and grid scale, then keep the following
+invariants visible to the agent and reviewer:
+
+- coordinates and frame dimensions are integer pixels;
+- colour choices come from the declared palette, including transparency;
+- `scale` is an integer multiplier from a tile's authored grid to its
+  scene-pixel bounds;
+- atlas sampling uses nearest-neighbour filtering;
+- frame canvases and pivots are stable across an animation;
+- strict mode rejects transforms, rotation and blur on the scene's pixel-art
+  layers and checks tile geometry and declared palette membership.
+
+The contract does not make a weak drawing good. It makes common production
+mistakes detectable and makes an intentional one-pixel edit auditable. Keep
+the intended game display size in the brief and inspect the result at that size
+as well as zoomed in.
+
+For small, deliberately indexed marks, palette tiles are the compact scene
+primitive:
+
+```yaml
+- id: lantern
+  type: raster
+  tiles:
+    - bounds: [8, 8, 10, 6]
+      palette:
+        .: '#00000000'
+        a: '#f2be81'
+        b: '#b75c40'
+      pixels:
+        - '....aa....'
+        - '...abba...'
+        - '..abbbba..'
+        - '..abbbba..'
+        - '...abba...'
+        - '....aa....'
+```
+
+Rows must be equal in width and every key must exist in the palette. Palette
+tiles are limited to 256 × 256 and are scaled with nearest-neighbour sampling.
+Use `replaceTile` for an auditable tile-sized revision. For dense or generated
+frames, use the studio's `art.raster`, `art.pixels` and `art.put` APIs instead;
+those bake ordinary PNG assets with a replayable recipe.
+
+The complete scene and command shapes are in [scene format](scene-format.md).
+Run `rtistree schema --kind scene` or `rtistree schema --kind command` against
+the installed version rather than copying a stale schema from a blog post.
+
+## Build a sprite set
+
+Start with one representative character frame and one representative prop.
+Record the intended facing, ground line, display scale, palette, silhouette and
+pivot before multiplying the set. A useful frame brief says what must remain
+stable (for example, the foot contact point) and what changes (for example,
+the lifted leg).
+
+The scene's `sprites` manifest is the delivery description for a set. Each
+`frames[id].bounds` is a canvas rectangle selecting source pixels. The exporter
+writes a JSON manifest in which each output `frames[id]` records:
+
+- the frame rectangle in the atlas;
+- the original canvas `source` rectangle;
+- the pixel pivot or origin used by the game;
+- optional duration and tags such as `idle`, `contact` or `recovery`;
+- animation order and loop behaviour; use tags to carry labels such as facing.
+
+Atlas placement is deterministic. The same frame inputs and atlas settings
+produce the same packed image and metadata on the same pinned runtime. Keep
+the atlas image and its metadata together; the metadata is part of the asset,
+not an optional comment for the viewer.
+
+Export the set with the installed command:
+
+```sh
+npx rtistree sprites scene.json -o output/sprites.png --manifest output/sprites.json
+```
+
+The command accepts a scene or configured project containing the sprite
+manifest. Use `npx rtistree sprites --help` and the installed schema/help
+output for the exact options in the release you are using. The PNG path must
+end in `.png` and the manifest path in `.json`. The export produces an atlas
+image plus machine-readable frame and animation metadata. Frames are not
+trimmed or rotated. `padding`, `extrusion`, `power_of_two` and `max_width`
+control packing; edge extrusion copies the frame's edge pixels and the
+remaining padding stays transparent.
+
+The same export is available through the SDK as `exportSpriteSheet(project,
+output, options)` and through the MCP `exportSprites` tool. SDK callers should
+retain the returned atlas and metadata as release artifacts; MCP callers should
+expose the result to the agent so it can inspect the actual image and not only
+the JSON. The MCP tool writes `<name>.png` and `<name>.json` into the configured
+project output directory.
+
+## Review an animation before shipping it
+
+Technical validity and animation quality are separate gates. For each set,
+check the following in order:
+
+1. Render every frame and inspect a contact sheet at the intended display size.
+2. Confirm frame dimensions, alpha margins, palette use, atlas rectangles and
+   pivots against the manifest.
+3. Play a complete loop against a ground marker. Inspect contact, passing and
+   recovery frames, then inspect the loop boundary.
+4. Check that the subject's silhouette, weight, facing and prop ownership read
+   consistently. For walking, planted feet should remain coherent against the
+   ground while lifted feet recover in the travel direction.
+5. Record technical, functional and visual results separately. A set can have
+   reproducible PNGs and valid metadata while still being rejected for weak
+   posing, muddy silhouettes or a broken loop.
+
+`rtistree verify` can check declared technical constraints and scoped changes;
+it cannot watch a loop, judge a silhouette or prove that a reviewer looked at
+the image. Keep the rendered frames, contact sheet, atlas, manifest and any
+rejected revision together so a later agent can compare against the actual
+parent rather than trusting a summary.
+
+## Existing example
+
+The [Verdigris Watch asset trial](https://github.com/Coly010/rtistree/tree/main/examples/warden-asset-trial)
+is the reference end-to-end example. It draws 17 transparent sprites, bakes an
+eight-frame walk cycle, records fixed pivots and 8 fps playback metadata, packs
+an atlas, and provides a small viewer for stepping through the loop. Its
+`render.mjs` and `verify.mjs` intentionally keep atlas assembly and motion
+checks visible, so the example also documents what the first-class export is
+meant to make less bespoke.
+
+The trial is evidence of a reproducible workflow, not a claim that every image
+is production-quality. Read its review and inspect the actual frames before
+using it as a visual reference.
+
+For the smallest strict-pixel example, see
+[`examples/pixel-sprite-lab`](https://github.com/Coly010/rtistree/tree/main/examples/pixel-sprite-lab).
+It uses four 16 × 16 palette-tile frames, a fixed `[8, 14]` pivot, 120 ms
+durations, a `walk_right` animation, one-pixel padding and one-pixel edge
+extrusion. Its verifier checks source-to-atlas pixels, palette use, fixed
+pivots and deterministic cold export.
+
+## Scope and limits
+
+The sprite workflow is a neutral asset format. It does not add a dependency on
+Godot, Unity, Phaser or another game engine, and it does not promise a native
+timeline, inverse kinematics, automatic retargeting, palette optimisation or
+automatic visual approval. A renderer or game project can consume the atlas and
+metadata through its own adapter.
+
+For a broader view of the agent protocol, read [art direction for agents](agent-art-workflow.md),
+then [programmable digital art](studio.md) for seeded frame generation and
+[production](production.md) for general image export.

package/docs/studio.md

@@ -1,14 +1,26 @@
-# Programmable digital art in v0.4
+# Programmable digital art
 
 The studio is the escape hatch below scene abstractions. An agent can build an image using paths and gradients, paint pressure-sensitive strokes, calculate pixel colours, sample textures, or write a custom image-processing algorithm. No image-generation model is used by these tools.
 
 Scene layers still describe composition. Programs produce ordinary pinned PNG assets and can replace the source of a raster/image layer. Their exact source, seed, parameters, input snapshots and output hash are saved as a recipe. Rendering, inspecting and opening a scene never runs a program. Re-execution is explicit, and existing edits remain undoable.
 
+This is also the frame-generation path for sprites: keep the frame construction
+function pure and parameterise its pose or animation phase, then bake one asset
+per frame. A `sprites` manifest can reference those frames and the sprite
+exporter can pack them into an atlas with pivots, durations and animation tags.
+See [pixel art, sprites and spritesheets](sprites.md) for the review and delivery
+workflow.
+
 ## First painting
 
+Run these commands from a directory where `npm install rtistree` has already completed.
+`project new` creates a scene project; unlike `init`, it does not create a package.json
+or install Rtistree. The custom size `100x100` is in millimetres and gives this example
+a 400 × 400 design canvas.
+
 ```sh
-rtistree project new study --size 100x100
-rtistree studio-help
+npx rtistree project new study --size 100x100
+npx rtistree studio-help
 ```
 
 Save this as `study/programs/rubber.js`:
@@ -41,9 +53,9 @@ Save a request as `study/paint.json`:
 ```
 
 ```sh
-rtistree program study study/paint.json
-rtistree render study -o study/output/rubber.png
-rtistree program-replay study rubberPaint
+npx rtistree program study study/paint.json
+npx rtistree render study -o study/output/rubber.png
+npx rtistree program-replay study rubberPaint
 ```
 
 Supply exactly one of `source` (a project-local JavaScript file) or `code` (an inline function body). A program receives `art` and `parameters`, runs synchronously and returns one Canvas with the declared dimensions. It cannot import modules through the public API. A new `target` creates a raster layer; an existing target must accept an image source. Omit `target` to register an asset for subsequent mask, region or layer operations. The runner captures the starting scene hash and rejects a concurrent edit before committing.
@@ -72,7 +84,8 @@ Height-field lighting is an artistic 2.5D calculation, with the viewer along pos
 
 ## Dense regional edits
 
-`readRasterRegion` / `rtistree raster-read PROJECT request.json` read a PNG crop of the composite or an isolated layer. The request contains integer canvas-space `bounds` and an optional `target`. The result includes the scene hash and an asset descriptor ready for `registerAsset`.
+`readRasterRegion` / `rtistree raster-read PROJECT request.json` read a PNG crop of the composite or an isolated layer. The request contains integer canvas-space `bounds` and an optional `target`. The result includes the scene hash and an asset descriptor (`source` and `hash`). Wrap
+that descriptor in a `registerAsset` command with an `id` before using it as a program input.
 
 `writeRasterRegion` / `rtistree raster-write PROJECT request.json` consumes:
 
@@ -89,7 +102,8 @@ Height-field lighting is an artistic 2.5D calculation, with the viewer along pos
 }
 ```
 
-The source must be a project-local PNG matching the region's exact dimensions. `replace` clears/replaces the region, including alpha; `over` composites it onto the previous pixels. The command creates or updates a named promoted region at scale 1 and stores an immutable copy of the PNG. `space: layer` captures reference dimensions, so the patch follows later transforms and resizing. `space: canvas` stays at canvas coordinates. Existing layer masks/effects still apply; locality validation rejects changes leaking outside the declared region. Undo/redo restores the prior image.
+The source must be a project-local PNG matching the region's exact dimensions. `replace` clears/replaces the region, including alpha; `over` composites it onto the previous pixels. The command creates or updates a named promoted region at scale 1 and stores an immutable copy of the PNG. `space: layer` captures reference dimensions, so the patch follows later transforms and resizing. `space: canvas` stays at canvas coordinates. The patch is composited after the target layer’s effects and ordinary operations, but
+before its mask and opacity. Ancestor effects can still change its appearance; locality validation rejects changes leaking outside the declared region. Undo/redo restores the prior image.
 
 For a custom filter, register the descriptor returned by the read, pass that asset to `runProgram.inputs`, calculate the new pixels, and write the returned PNG into a region. Use the latest scene hash returned by each mutation. Canvas-space reads cannot automatically become local-space reads of a rotated object; use canvas-space patch coordinates for a direct read/edit/write round trip.
 
@@ -101,8 +115,9 @@ Programs execute only when explicitly requested and must be trusted code. A work
 
 The runner checks a 16-megapixel output limit, 16 input images, an 8,192-pixel edge, 256 KiB source, 64 KiB parameters, and up to 30 seconds of execution. The parent watchdog allows two additional seconds for worker setup. Studio helper allocations are capped at 32 cumulative megapixels including inputs; V8's heap limit is 256 MiB. Native Canvas buffers and arbitrary allocations made through exposed native objects are outside the V8 accounting, so these limits are not an OS memory quota. Scene rendering retains its separate surface budget.
 
-The studio has no live dependency graph. Changing program code, parameters or an input does not automatically rebake dependent assets. Explicit execution replaces a target source through the existing transaction/history mechanism. If execution or commit fails, the scene is unchanged; a late failed commit can leave unreferenced content-addressed artifacts.
+Programs do not rebake automatically. The [pipeline API](atelier.md) provides an explicit
+dependency graph with caching; run it when you want to rebuild changed nodes. Changing program code, parameters or an input does not automatically rebake dependent assets. Explicit execution replaces a target source through the existing transaction/history mechanism. If execution or commit fails, the scene is unchanged; a late failed commit can leave unreferenced content-addressed artifacts.
 
 ## Trial
 
-The [manual wheel trial](../examples/manual-wheel-trial/README.md) used no model-generated or downloaded imagery. Its eight layers were painted with code, geometry, material fields, text and brushes. Source, recipes, initial/refined images, critiques and replay checks are retained. The result demonstrates a reproducible digital illustration; its visual evaluation explicitly leaves photographic realism unachieved.
+The [manual wheel trial](https://github.com/Coly010/rtistree/blob/main/examples/manual-wheel-trial/README.md) used no model-generated or downloaded imagery. Its eight layers were painted with code, geometry, material fields, text and brushes. Source, recipes, initial/refined images, critiques and replay checks are retained. The result demonstrates a reproducible digital illustration; its visual evaluation explicitly leaves photographic realism unachieved.

package/examples/hello/README.md

@@ -1,5 +1,9 @@
 # Your first Rtistree project
 
+Run these commands inside a project created by `npx rtistree@latest init my-art`.
+If you are reading this in the repository’s `examples/hello` directory, create a project
+first: these are template files, and `init` supplies the package.json and npm scripts.
+
 ```sh
 npm install
 npm run render

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rtistree",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Deterministic, agent-operable raster graphics engine",
   "main": "./dist/index.js",
   "scripts": {
@@ -11,12 +11,13 @@
     "graphics": "node --import tsx src/cli.ts",
     "demo": "node --import tsx scripts/demo.ts",
     "schema": "node --import tsx scripts/schema.ts",
-    "format": "prettier --write src tests scripts docs examples schemas README.md package.json tsconfig.json .github .prettierrc.json",
-    "format:check": "prettier --check src tests scripts docs examples schemas README.md package.json tsconfig.json .github .prettierrc.json",
+    "format": "prettier --write src tests scripts docs examples schemas README.md package.json tsconfig.json .github .prettierrc.json release-please-config.json .release-please-manifest.json CONTRIBUTING.md",
+    "format:check": "prettier --check src tests scripts docs examples schemas README.md package.json tsconfig.json .github .prettierrc.json release-please-config.json .release-please-manifest.json CONTRIBUTING.md",
     "performance": "node --import tsx scripts/performance.ts",
     "prepack": "npm run build",
     "package:check": "node scripts/package-smoke.mjs",
-    "rtistree": "node --import tsx src/cli.ts"
+    "rtistree": "node --import tsx src/cli.ts",
+    "docs:check": "npm run build && node scripts/docs-smoke.mjs"
   },
   "keywords": [
     "graphics",
@@ -68,7 +69,9 @@
     "CHANGELOG.md",
     "THIRD_PARTY_NOTICES.md",
     "licenses",
-    "examples/hello"
+    "examples/hello",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
   ],
   "license": "MIT",
   "author": "Colum Ferry",