@call-me-sensei/toonlab 0.4.20 → 0.4.22

package/NPM-LIBRARY.md

@@ -1,7 +1,7 @@
 # ToonLab npm library guide
 
 This guide is included in `@call-me-sensei/toonlab`. It is the package-first
-reference for version 0.4.20 and does not require access to the source
+reference for version 0.4.22 and does not require access to the source
 repository.
 
 ## Install
@@ -45,7 +45,7 @@ them:
 - `@call-me-sensei/toonlab/styles` for portable bundles, strict labels,
   auditing, and coordinated application;
 - `@call-me-sensei/toonlab/assetlib`, `/asset-policy`, and
-  `/official-catalog` for policy-aware Library and Gallery discovery;
+  `/official-catalog` for policy-aware local/released-catalog integration;
 - `@call-me-sensei/toonlab/character` and `/loaders` for supported preview and
   host-model integration;
 - `@call-me-sensei/toonlab/runtime`, `/renderer`, `/lighting`, and
@@ -76,7 +76,9 @@ The npm artifact contains four supported layers:
 It does not contain the ToonLab website, Lab application UIs, examples,
 screenshots, models, textures, or other binary media. Optional public fixtures
 are identified by immutable `https://assets.toonlab.io` metadata rather than
-being bundled.
+being bundled. Authored tree recipes are assets too: the reviewed public tree
+collection remains in the Gallery and is discovered through MCP instead of
+being hard-coded into the JavaScript runtime.
 
 ## Use a focused runtime
 
@@ -122,6 +124,55 @@ The host application still owns renderer creation, geometry and XZ layout,
 cameras, controls, gameplay, dynamic physics, navigation, persistence, and the
 frame loop. ToonLab does not turn a prompt into a finished world.
 
+## Load Nature Reference Rocks
+
+Version 0.4.22 understands both the original `rock-0001`–`rock-0480`
+identities and the `rock-c8-*` Nature Reference Rocks. Acquiring an asset
+directly returns its realistic PBR GLB. The one-call placement path additionally
+loads that asset's reviewed geology maps and `call_me_sensei` material settings
+before applying the selected style bundle.
+
+```js
+import {
+  createOfficialCatalogAssetRuntime,
+  createOfficialCatalogProvider,
+  createOfficialCatalogRockEditorDescriptor,
+  loadOfficialCatalogAsset,
+} from '@call-me-sensei/toonlab/official-catalog';
+import { CALL_ME_SENSEI_STYLE_BUNDLE } from '@call-me-sensei/toonlab/styles';
+
+const provider = createOfficialCatalogProvider({
+  baseUrl: 'https://toonlab.io/',
+  transport: 'public-rock',
+});
+const assets = createOfficialCatalogAssetRuntime({ provider, renderer });
+
+// Raw acquisition keeps the realistic PBR model.
+const realistic = await assets.acquireAsset('rock-c8-arch-sandstone');
+scene.add(realistic.root);
+
+// Placement loads the same rock's geology maps and applies Call Me Sensei.
+const stylized = await loadOfficialCatalogAsset({
+  assetId: 'rock-c8-arch-sandstone',
+  assetRuntime: assets,
+  parent: scene,
+  styleBundle: CALL_ME_SENSEI_STYLE_BUNDLE,
+});
+
+// Rock Lab/editor integrations receive the non-destructive authoring contract.
+const rockPackage = await assets.getRockPackage('rock-c8-arch-sandstone');
+const editorSource = createOfficialCatalogRockEditorDescriptor(
+  rockPackage.asset,
+  rockPackage,
+);
+```
+
+`editorSource` exposes `control.glb`, retained high detail, LOD0–LOD4,
+collision, recipe, material configuration, and the required post-sculpt
+reprojection/rebake/rebuild flags. These are immutable R2 URLs; the package
+does not embed any rock media. Release acquired handles and dispose the runtime
+when their scene lifetime ends.
+
 ## Install the agent guidance
 
 Everything in this section is present in the installed npm package.
@@ -167,7 +218,7 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
       "command": "npx",
       "args": [
         "-y",
-        "@call-me-sensei/toonlab@0.4.20",
+        "@call-me-sensei/toonlab@0.4.22",
         "--workspace",
         "/absolute/path/to/your-game/.toonlab"
       ],
@@ -181,8 +232,11 @@ it uses the disk workspace passed through `--workspace`; no account is needed.
 
 This server provides the anime-game profile, runtime guide, live-Lab
 contracts, deterministic document creation and mutation, policy validation,
-public asset discovery, local Library operations, and optional provider-backed
-generation when the developer supplies server-side provider keys.
+public Gallery search/retrieval, local Library operations, and optional
+provider-backed generation when the developer supplies server-side provider
+keys. Authored tree recipes are not bundled. Call `search_public_gallery` with
+`{ query: "tree", type: "tree-recipe" }`, then use
+`get_public_gallery_asset` to retrieve the reviewed portable recipe.
 
 ### ToonLab Pro MCP
 

package/README.md

@@ -19,7 +19,7 @@ Use ToonLab as a focused runtime library (`@call-me-sensei/toonlab` on npm), as
 an asset/preset authoring workspace, or as an asset-discovery service—not as a
 one-shot world generator.
 
-## Versioned expectation: 0.4.20
+## Versioned expectation: 0.4.22
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual
@@ -277,8 +277,9 @@ Catalog data therefore does **not** use a separate downloadable “current
 seed,” and new datasets are **not** schema migrations. Keeping every released
 batch in the repository gives fresh and upgraded installations the same final
 catalog while preserving a simple, auditable upgrade path. The checked-in
-catalog currently contains 8,163 official assets: 480 first-party ToonLab
-rocks plus 7,683 verified open assets.
+catalog includes the original 480 first-party Stylized rocks, the 100-item
+Nature Reference Rocks by ToonLab collection, and the verified open-asset
+release. The two ToonLab rock collections keep distinct searchable identities.
 
 Applied filenames and SHA-256 digests are recorded in `schema_migrations` and
 `catalog_seed_batches`. Never edit, rename, or replace a released migration or
@@ -310,10 +311,13 @@ npm run dev
 # In an MCP client, use the command/config shown at /settings/.
 ```
 
-The local server can search the built-in procedural catalog and public CC0
-sources, read your saved presets and exported files, generate seeded recipes,
-and import assets into the project. It uses stdio, requires no account or
-OAuth, and keeps work local. See [Local MCP and workspace](https://github.com/call-me-sensei/toonlab/blob/main/docs/mcp.md) and
+The local server can search your workspace, the public ToonLab Gallery, the
+released official catalog, and public CC0 sources; read saved presets and
+exported files; generate approved seeded recipes; and import assets into the
+project. Authored Gallery recipes are fetched with their public license and
+provenance instead of being copied into the npm package. The server uses stdio,
+requires no account or OAuth for public discovery, and keeps local work local.
+See [Local MCP and workspace](https://github.com/call-me-sensei/toonlab/blob/main/docs/mcp.md) and
 [Local database and public asset releases](https://github.com/call-me-sensei/toonlab/blob/main/docs/local-database-and-public-assets.md).
 
 ## The labs
@@ -375,7 +379,7 @@ camera behavior, and game feel remain host-owned or pre-beta.
 | Toon character shading | `@call-me-sensei/toonlab/toon` | Modern anime character shader: cel bands with art-directed face lighting, skin-tone shadow management, shadow-color HSV control, scene/self/contact shadows, average-shadow smoothing, rim light (fresnel or screen-space depth), stylized + anisotropic hair highlights, eye catchlights, role-aware specular, source map routing (normal/AO/emissive/MatCap/ramp/detail), inverted-hull outlines, glitter, stickers, perspective removal, shell fur, dither fades — 23 settings groups, all preset-serializable. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/toon-shading.md) |
 | Environment shading | `@call-me-sensei/toonlab/environment` | Modern anime-style scene shader for texture packs, standard glTF, and untextured scenes: material-role classification, wrapped lighting, packed-map hints, window cutouts, sun/lamp rigs, time-of-day, six-direction ambient probe, planar floor reflections, BVH vertex-AO baking, height fog, cloud shadows. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/environment.md) |
 | Water | `@call-me-sensei/toonlab/water` | Focused water treatment for a host-authored water footprint, continuous shore, and closed seabed: Gerstner waves, absorption color, refraction/caustics/foam, ripples, splashes, wakes, kelp, underwater treatment, and CPU buoyancy sampling. It does not design the coast or underwater habitat. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/water.md) |
-| Vegetation | `@call-me-sensei/toonlab/vegetation` | Instanced grass and flower fields; the 12 named pre-species legacy trees; and a focused procedural broadleaf `BranchTree` with deterministic branching, five leaf silhouettes, caller-supplied leaf/bark textures, and a portable recipe. Package-generated Call Me Sensei trees preserve authored bark first and otherwise select a registered deterministic bark surface instead of a bare trunk. The 165-species research roster remains repository-only experimental work. Independent Tree, Grass, and Flower shader profiles share one semantic-role renderer family. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/vegetation-sky.md) |
+| Vegetation | `@call-me-sensei/toonlab/vegetation` | Tree/grass/flower construction and shader runtimes, including the focused procedural broadleaf `BranchTree` with deterministic branching, five leaf silhouettes, caller-supplied leaf/bark textures, and a portable recipe. No authored tree asset collection is bundled or exported: reviewed tree recipes remain searchable Gallery assets delivered through MCP with their CC0 metadata. Package-generated trees preserve authored bark first and otherwise select a registered deterministic bark surface instead of a bare trunk. The experimental species roster remains repository-only. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/vegetation-sky.md) |
 | Rock shader | `@call-me-sensei/toonlab/rock-shader` | Detailed, versioned rock-material profiles with projected detail, distance tint, normal fading, striping, moss and optional top layers, plus explicit source-albedo and vertex-color/AO integration. Call Me Sensei is the default. Geometry generation remains separate in `rockgen`. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/rock-shader.md) |
 | Ground shader | `@call-me-sensei/toonlab/ground-shader` | Splat-weighted anime terrain with slope/cliff detail, shoreline and weather response, HDR sun/shade controls, safe shadow defaults, and flat-albedo ground-field output for vegetation adoption. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/ground-shader.md) |
 | Sky | `@call-me-sensei/toonlab/sky` | Reusable atmosphere, palette, sun, moon, stars, and god-ray settings authored by Sky Lab and Sky & Cloud Lab. Your application coordinates final lighting and scene state. [Docs](https://github.com/call-me-sensei/toonlab/blob/main/docs/sky.md) |
@@ -460,21 +464,21 @@ profile parameters for other authored styles. Its recipe-v3 LOD0/1/2 topology
 uses 40/14/6 primary blades and compensates retained stroke width so zooming
 does not make the underlying terrain appear to change color.
 
-The supported tree set is intentionally the proven pre-species surface.
-Use a named legacy silhouette directly:
+ToonLab does not ship predefined tree assets in npm. Search reviewed public
+tree recipes through MCP, then pass the retrieved portable recipe options to
+the runtime:
 
 ```js
-import {
-  LEGACY_TREE_IDS,
-  createLegacyTree,
-} from '@call-me-sensei/toonlab/vegetation';
+import { StylizedTree } from '@call-me-sensei/toonlab/vegetation';
 
-console.log(LEGACY_TREE_IDS); // straight, leaning, see-through, ...
-const legacyTree = createLegacyTree('golden-gingko', {
+// treeRecipe is the document returned by get_public_gallery_asset after
+// search_public_gallery({ query: 'tree', type: 'tree-recipe' }).
+const tree = new StylizedTree({
+  ...treeRecipe.options,
   trunkMap: barkTexture,
   vegetationShader: { preset: 'call_me_sensei' },
 });
-scene.add(legacyTree);
+scene.add(tree);
 ```
 
 For a configurable recursive branch-type broadleaf, use the focused wrapper:
@@ -495,7 +499,8 @@ scene.add(tree);
 shapes. Botanical species generation is not a public package claim.
 
 Water, sky, flowers, trees, grass, and splashes keep procedural defaults, while
-legacy trees and BranchTree may use caller-owned leaf and bark textures. The
+Gallery tree recipes, `StylizedTree`, and `BranchTree` may use caller-owned
+leaf and bark textures. The
 Call Me Sensei tree path resolves bark in this order: explicit
 `trunkSurfaceProfile`, authored `trunkMap`, then the registered
 `call-me-sensei-bark-v1` fallback. Use `getTreeSurfaceProfileOptions()` when a
@@ -698,9 +703,11 @@ Ready-to-paste supported prompts are included in
 Two servers, and they compose:
 
 **Local (free, no account).** The stdio server included in this package
-searches the built-in procedural catalog and public CC0 sources, reads your
-saved presets and lab exports, generates seeded recipes, and imports assets
-into a disk-backed `.toonlab/` workspace:
+searches local/project content, reviewed public Gallery recipes, the released
+official catalog, and public CC0 sources; reads saved presets and Lab exports;
+generates approved seeded recipes; and imports assets into a disk-backed
+`.toonlab/` workspace. Use `search_public_gallery` for authored assets such as
+the public tree collection—those recipes are not npm built-ins:
 
 ```json
 {

package/agents/PROMPTS.md

@@ -1,7 +1,7 @@
 # ToonLab agent prompts
 
 These prompts are included with the npm package. They use only the supported
-0.4.20 runtime, agent skills, and MCP workflows.
+0.4.22 runtime, agent skills, and MCP workflows.
 
 ## Existing-scene integration
 
@@ -55,11 +55,15 @@ document.
 
 ```text
 Using the ToonLab vegetation-sky skill, create the requested tree, shrub,
-grass, or groundcover with the public vegetation runtime. Keep species/recipe,
-seed, geometry, palette, and placement separate from the Tree/Grass/Flower
-shader profile. Emit stable modeled-part and material-role labels, preserve
-the recipe for regeneration, and verify LOD and shadow behavior. Do not use the
-repository-only experimental species engine.
+grass, or groundcover. For an existing authored tree, search the public Gallery
+through MCP first and retrieve its portable recipe; the npm package contains
+tree construction/shader capability but no predefined tree asset collection.
+Author a new `StylizedTree` or `BranchTree` only when requested or when accepted
+discovery does not close the role. Keep recipe, seed, geometry, palette, and
+placement separate from the Tree/Grass/Flower shader profile. Emit stable
+modeled-part and material-role labels, preserve the recipe for regeneration,
+and verify LOD and shadow behavior. Do not use the repository-only experimental
+species engine.
 ```
 
 ## Rock generation and shader separation

package/agents/codex/AGENTS.md

@@ -82,10 +82,12 @@ or environment with ToonLab's runtime library in their own Three.js app.
   system preset with embedded shader controls. Sky, Cloud, and Sky & Cloud are
   live focused authoring surfaces. Vegetation is one shared
   implementation family with separate Tree, Grass, and Flower shader profiles;
-  their Generation Labs own geometry/material data. The stable public package
-  trees are the 12 named pre-species legacy presets plus the generic
-  `BranchTree`; repository species work is experimental and must not be
-  presented as supported. Ground is a separate shader domain. Scene weather,
+  their Generation Labs own geometry/material data. The public package ships
+  tree construction and shader capability, not predefined tree assets. Search
+  reviewed authored tree recipes through MCP; use `StylizedTree` or
+  `BranchTree` to instantiate or deliberately author them. Repository species
+  work is experimental and must not be presented as supported. Ground is a
+  separate shader domain. Scene weather,
   lighting, camera, interactions, and complete Sky/Cloud composition stay
   host-owned or experimental.
 - For style-bundle, multi-shader, or arbitrary-asset work, read

package/agents/references/mcp-asset-discovery.md

@@ -10,11 +10,12 @@ Inspect the connected server's tool names before calling anything. Do not
 assume the developer has ToonLab Pro, and do not assume a local OSS checkout.
 
 - **ToonLab OSS local MCP** exposes `get_workspace_info`,
-  `search_cc0_assets`, `get_cc0_asset`, and `import_cc0_asset`. Its
-  `search_assets` searches built-in procedural entries, the complete official
-  R2-backed Gallery catalog, and the disk-backed project/library/workspace.
-  Use `source: 'official'` for released assets and follow `nextOffset` until
-  null.
+  `search_public_gallery`, `get_public_gallery_asset`, `search_cc0_assets`,
+  `get_cc0_asset`, and `import_cc0_asset`. Its `search_assets` searches
+  approved built-in generator/settings entries, the local released official
+  catalog, and the disk-backed project/library/workspace. Authored assets such
+  as reviewed tree recipes are searched through `search_public_gallery` rather
+  than copied into npm.
 - **ToonLab Pro remote MCP** exposes `get_runtime_guide`,
   `search_public_gallery`, and `get_toonlab_asset`. Its `search_assets`
   searches indexed external open assets; first-party rocks/trees and community
@@ -41,10 +42,12 @@ the surface the developer actually has and report which surface was used.
 1. Call `list_my_creations` with the task's text and exact tag filters, then
    `search_assets` with `source: 'library'`,
    `'workspace'`, `'workspace-storage'`, or `'builtin'` as appropriate. If no
-   accepted local entry closes the role, call it with `source: 'official'` to
-   search the released Gallery through the local database. Follow
-   `nextOffset` until null so all matching official assets remain reachable.
-2. Call local `get_asset` for the complete recipe/file descriptor.
+   accepted local entry closes the role, call `search_public_gallery` for
+   authored public assets and follow `nextOffset` until null. Use
+   `type: 'tree-recipe'` for reviewed trees. Use `search_assets` with
+   `source: 'official'` only for the installed released catalog.
+2. Call local `get_public_gallery_asset` for a selected Gallery document or
+   `get_asset` for a local/released-catalog record.
 3. When policy permits external CC0, call `search_cc0_assets`, then
    `get_cc0_asset`; call `import_cc0_asset` only after selection to download
    bytes plus their provenance manifest into `.toonlab/imports/`.

package/agents/skills/claude/asset-sourcing/SKILL.md

@@ -50,9 +50,11 @@ scene-kit role.
 2. **Reuse what exists.** In OSS, earlier imports, saved presets, and exports
    live in `.toonlab/`; call local `list_my_creations` and `search_assets` with
    `source: 'workspace'`, `'workspace-storage'`, `'library'`, or `'builtin'`.
-   If those do not close the role, use local `search_assets` with
-   `source: 'official'` for the complete released Gallery catalog and follow
-   `nextOffset` until null.
+   If those do not close the role, use local `search_public_gallery` and follow
+   `nextOffset` until null; use `type: 'tree-recipe'` for authored trees and
+   retrieve a finalist with `get_public_gallery_asset`. Use local
+   `search_assets({ source: 'official' })` only for the installed released
+   catalog.
    In Pro, call cloud `list_my_creations`, then `search_public_gallery`; use
    `source: 'toonlab'` plus the appropriate catalog for first-party assets and
    follow `nextOffset`. For rocks on either surface, shortlist from positive
@@ -195,9 +197,10 @@ table, as the source of truth):
 
 - Seamless PBR material sets (brick, wood, ground …) → ambientCG.
 - Photoscanned props, HDRIs, high-end texture sets → Poly Haven.
-- Stylized/toon-ready models, vegetation, buildings → the built-in
-  procedural catalog first only for families that passed the base-set
-  reliability gate; otherwise compare curated external candidates.
+- Authored stylized/toon-ready models and vegetation → the public Gallery
+  first; retrieve their portable document and provenance through MCP. Use a
+  built-in procedural family only when it passed the base-set reliability gate
+  and the task calls for new generation rather than an existing asset.
 - Stylized *seamless textures* → `@call-me-sensei/toonlab/texgen` in code
   (60+ presets); the catalog has no texture entries, so this route is a
   package import, not an MCP call.

package/agents/skills/claude/vegetation-sky/SKILL.md

@@ -80,8 +80,11 @@ User guidance:
   create the pass after all writer meshes exist, call its `update()` every frame before grass, require
   `writerCount > 0` and `ready`, and call `invalidate()` after repainting a
   writer without a transform change.
-- In the public package, use `LEGACY_TREE_PRESETS` and `createLegacyTree()` for the 12
-  supported pre-species silhouettes. Use `BranchTree` when the developer wants
+- The public package contains tree construction and shader capability, not a
+  predefined tree asset collection. For an authored tree, use the connected
+  MCP's `search_public_gallery` and `get_public_gallery_asset` tools, then
+  instantiate its portable recipe with `StylizedTree`. Use `BranchTree` when
+  the developer explicitly wants
   recursive branching, five broadleaf silhouettes, leaf color/texture plus a
   portable lit/shadow/crown palette, independent leaf `coverageScale`, bark
   color/texture, authored trunk bend/twist/taper, roots, portable documents,
@@ -108,11 +111,11 @@ User guidance:
   `GRASS_SHADER_PROFILE`, and `FLOWER_SHADER_PROFILE` through the bundle's
   `treeShader`, `grassShader`, and `flowerShader` slots. They share a renderer
   family and semantic material contract, but serialize and apply independently.
-  Keep asset albedo and legacy/BranchTree geometry/material inputs separate from all
+  Keep asset albedo and Gallery-recipe/BranchTree geometry/material inputs separate from all
   three shader treatments.
 - Grass palettes update base, tip, and shadow tint together; they do not change
   shadow strength, wind, or current weather.
-- Use the public versioned Grass, vegetation-shader, legacy/BranchTree/flower recipe, and Sky
+- Use the public versioned Grass, vegetation-shader, BranchTree/flower recipe, and Sky
   preset document APIs for portable data; do not copy lab-local validators.
 - Treat Sky as one integrated World System, not a separate Shader Lab. Its
   shader, sun, clouds, stars, and procedural motion form one system preset with

package/agents/skills/codex/asset-sourcing/SKILL.md

@@ -50,9 +50,11 @@ scene-kit role.
 2. **Reuse what exists.** In OSS, earlier imports, saved presets, and exports
    live in `.toonlab/`; call local `list_my_creations` and `search_assets` with
    `source: 'workspace'`, `'workspace-storage'`, `'library'`, or `'builtin'`.
-   If those do not close the role, use local `search_assets` with
-   `source: 'official'` for the complete released Gallery catalog and follow
-   `nextOffset` until null.
+   If those do not close the role, use local `search_public_gallery` and follow
+   `nextOffset` until null; use `type: 'tree-recipe'` for authored trees and
+   retrieve a finalist with `get_public_gallery_asset`. Use local
+   `search_assets({ source: 'official' })` only for the installed released
+   catalog.
    In Pro, call cloud `list_my_creations`, then `search_public_gallery`; use
    `source: 'toonlab'` plus the appropriate catalog for first-party assets and
    follow `nextOffset`. For rocks on either surface, shortlist from positive
@@ -195,9 +197,10 @@ table, as the source of truth):
 
 - Seamless PBR material sets (brick, wood, ground …) → ambientCG.
 - Photoscanned props, HDRIs, high-end texture sets → Poly Haven.
-- Stylized/toon-ready models, vegetation, buildings → the built-in
-  procedural catalog first only for families that passed the base-set
-  reliability gate; otherwise compare curated external candidates.
+- Authored stylized/toon-ready models and vegetation → the public Gallery
+  first; retrieve their portable document and provenance through MCP. Use a
+  built-in procedural family only when it passed the base-set reliability gate
+  and the task calls for new generation rather than an existing asset.
 - Stylized *seamless textures* → `@call-me-sensei/toonlab/texgen` in code
   (60+ presets); the catalog has no texture entries, so this route is a
   package import, not an MCP call.

package/agents/skills/codex/vegetation-sky/SKILL.md

@@ -80,8 +80,11 @@ User guidance:
   create the pass after all writer meshes exist, call its `update()` every frame before grass, require
   `writerCount > 0` and `ready`, and call `invalidate()` after repainting a
   writer without a transform change.
-- In the public package, use `LEGACY_TREE_PRESETS` and `createLegacyTree()` for the 12
-  supported pre-species silhouettes. Use `BranchTree` when the developer wants
+- The public package contains tree construction and shader capability, not a
+  predefined tree asset collection. For an authored tree, use the connected
+  MCP's `search_public_gallery` and `get_public_gallery_asset` tools, then
+  instantiate its portable recipe with `StylizedTree`. Use `BranchTree` when
+  the developer explicitly wants
   recursive branching, five broadleaf silhouettes, leaf color/texture plus a
   portable lit/shadow/crown palette, independent leaf `coverageScale`, bark
   color/texture, authored trunk bend/twist/taper, roots, portable documents,
@@ -108,11 +111,11 @@ User guidance:
   `GRASS_SHADER_PROFILE`, and `FLOWER_SHADER_PROFILE` through the bundle's
   `treeShader`, `grassShader`, and `flowerShader` slots. They share a renderer
   family and semantic material contract, but serialize and apply independently.
-  Keep asset albedo and legacy/BranchTree geometry/material inputs separate from all
+  Keep asset albedo and Gallery-recipe/BranchTree geometry/material inputs separate from all
   three shader treatments.
 - Grass palettes update base, tip, and shadow tint together; they do not change
   shadow strength, wind, or current weather.
-- Use the public versioned Grass, vegetation-shader, legacy/BranchTree/flower recipe, and Sky
+- Use the public versioned Grass, vegetation-shader, BranchTree/flower recipe, and Sky
   preset document APIs for portable data; do not copy lab-local validators.
 - Treat Sky as one integrated World System, not a separate Shader Lab. Its
   shader, sun, clouds, stars, and procedural motion form one system preset with

package/database/apply-one-catalog-seed.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { closeDatabase, getPool, withTransaction } from './client.mjs';
+
+const fileArgument = process.argv[2];
+if (!fileArgument) throw new Error('Usage: node database/apply-one-catalog-seed.mjs database/seeds/catalog/NNNN_release.sql');
+const file = path.resolve(fileArgument);
+const catalogSeedRoot = `${path.resolve('database/seeds/catalog')}${path.sep}`;
+if (!file.startsWith(catalogSeedRoot) || !/^\d{4}_[a-z0-9._-]+\.sql$/iu.test(path.basename(file))) {
+  throw new Error('Only one numbered catalog seed below database/seeds/catalog may be applied.');
+}
+
+const sql = await readFile(file, 'utf8');
+const hash = createHash('sha256').update(sql).digest('hex');
+const name = path.basename(file);
+const release = sql.match(/^-- Release: ([a-z0-9._-]+)$/im)?.[1];
+const assetCount = Number(sql.match(/^-- Asset count: (\d+)$/m)?.[1]);
+if (!release || !Number.isSafeInteger(assetCount) || assetCount < 0) {
+  throw new Error(`${name}: missing generated release metadata.`);
+}
+
+try {
+  const pool = await getPool();
+  await pool.query(
+    `create table if not exists catalog_seed_batches (
+      name text primary key,
+      sha256 text not null,
+      release text,
+      asset_count integer not null default 0,
+      applied_at timestamptz not null default now()
+    )`,
+  );
+  const result = await withTransaction(async (client) => {
+    await client.query('select pg_advisory_xact_lock(hashtext($1))', ['toonlab:catalog_seed_batches']);
+    const existing = await client.query('select sha256 from catalog_seed_batches where name = $1', [name]);
+    if (existing.rowCount) {
+      if (existing.rows[0].sha256 !== hash) throw new Error(`${name} changed after it was applied`);
+      return { status: 'unchanged' };
+    }
+    await client.query(sql);
+    await client.query(
+      `insert into catalog_seed_batches (name, sha256, release, asset_count)
+       values ($1, $2, $3, $4)`,
+      [name, hash, release, assetCount],
+    );
+    const published = await client.query(
+      `select count(*)::int as count from catalog_assets
+       where release = $1 and availability_status = 'active'`,
+      [release],
+    );
+    if (Number(published.rows[0].count) !== assetCount) {
+      throw new Error(`${release}: expected ${assetCount} active assets after seed.`);
+    }
+    return { published: Number(published.rows[0].count), status: 'applied' };
+  });
+  process.stdout.write(`${JSON.stringify({ assetCount, hash, name, release, ...result }, null, 2)}\n`);
+} finally {
+  await closeDatabase();
+}