@call-me-sensei/toonlab 0.3.1 → 0.4.20

package/agents/PROMPTS.md

@@ -0,0 +1,87 @@
+# 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.
+
+## Existing-scene integration
+
+```text
+Using the ToonLab game-dev skill, integrate @call-me-sensei/toonlab into this
+existing Three.js scene. Inventory every renderable root and material. Assign
+stable ToonLab target ids, rendering domains, material ids, and semantic roles.
+Apply the Call Me Sensei bundle in strict mode through the documented focused
+runtimes for the domains actually present. Preserve the scene's geometry, XZ
+layout, cameras, gameplay, dynamic physics, navigation, and frame loop. Run the
+app's typecheck, tests, build, and visual smoke check. Finish only when the
+style audit is ready or report each remaining blocker with a concrete fix.
+```
+
+## Character or manufactured-material before/after
+
+```text
+Using the ToonLab toon-shading or environment skill as appropriate, create a
+true before/after comparison for the supplied model. The before side must use
+its normal Three.js PBR material and the same camera, pose, lights, exposure,
+background, and source textures as the after side. The after side may change
+only the selected ToonLab shader/profile. Do not flatten, unlight, or otherwise
+degrade the before side. Verify that the comparison demonstrates the shader's
+effect rather than a scene-lighting difference.
+```
+
+## Policy-aware asset discovery
+
+```text
+Using the ToonLab asset-sourcing skill and whichever ToonLab MCP servers are
+connected, load get_anime_game_profile and confirm the project's sourcing
+policy. Search project/local Library first, then ToonLab Gallery, then allowed
+external open sources. Validate provenance, license, anime-style support, and
+policy decision before selection. Generate only after the searches fail and a
+custom asset gap has been recorded and approved. Report the selected stable id,
+source, license, dimensions, semantic domain, and material-role readiness.
+```
+
+## Author a portable Lab document
+
+```text
+Use ToonLab MCP to call list_live_labs, choose the named public Lab, and call
+get_lab_features before editing. Create a schema-valid starter with
+create_lab_document, make only requested semantic changes, and validate the
+result. Save it to my Library only if I asked for persistence. Keep preview
+camera, stage, lighting, playback, and comparison state out of the portable
+document.
+```
+
+## Tree or grass generation
+
+```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.
+```
+
+## Rock generation and shader separation
+
+```text
+Using the ToonLab rockgen and rock-ground-shaders skills, create or edit the
+requested rock asset with @call-me-sensei/toonlab/rockgen and style it with
+@call-me-sensei/toonlab/rock-shader. Keep geometry identity, seed, LOD,
+collision, and baked channels in the rock document; keep reusable appearance in
+the rock shader profile. Validate the portable documents and verify the result
+from multiple useful views. Do not deep-import repository compilers or test
+fixtures.
+```
+
+## Apply a Style Bundle
+
+```text
+Using the ToonLab scene-style-application skill, load the selected portable
+Style Bundle. Inventory and explicitly label only the domains present in this
+scene, audit in strict mode, and stop before mutation if any target, material
+role, required mask, or adapter is missing. Apply the accepted plan atomically,
+preserve asset identity and current scene conditions, then verify that every
+populated slot has an owning runtime and that teardown restores the source
+materials.
+```

package/agents/README.md

@@ -0,0 +1,54 @@
+# ToonLab Agent Resources
+
+These are downloadable AI coding agent resources for developers using ToonLab
+runtime features in their own apps. They are not maintenance instructions for
+this repository.
+
+The recommended agent workflow starts from an existing scene: apply the
+focused character, manufactured, ground, rock, vegetation, water, sky, cloud,
+lighting, and post runtimes; find assets through Gallery or MCP; and author
+bounded portable outputs. The package does not promise reliable one-shot scene
+construction.
+
+Layout:
+
+- `codex/AGENTS.md` — shared Codex-style runtime usage guide.
+- `claude/CLAUDE.md` — Claude Code wrapper for the shared guide.
+- `cursor/toonlab.mdc` — Cursor rule file; copy it to `.cursor/rules/` in a
+  project if desired.
+- `skills/codex/` — Codex-oriented feature skills.
+- `skills/claude/` — Claude-oriented feature skills.
+- `references/` — public anime art direction, style routing, MCP discovery,
+  runtime-boundary, sourcing-policy, and custom-gap contracts used by every
+  agent integration.
+
+Recommended feature skills (start with `game-dev` for existing-scene
+integration and `asset-sourcing` for Gallery/MCP work):
+
+- `asset-sourcing`
+- `environment`
+- `game-dev`
+- `post-processing`
+- `rock-ground-shaders`
+- `rockgen`
+- `style-presets`
+- `toon-shading`
+- `vegetation-sky`
+- `visual-verification`
+- `water`
+
+Experimental and host-owned skills are intentionally omitted from the npm
+artifact. This includes whole-world construction, natural cliff formation,
+Weather/Climate composition, camera behavior, game feel, and gameplay VFX.
+
+These text-only resources ship with the npm package beside the runtime source.
+The package does not include ToonLab lab applications, examples, review
+fixtures, models, textures, or other redistributed visual/media assets.
+First-party grass geometry and materials are generated by runtime code; the
+optional CC0 mannequin resolves from immutable public R2 rather than npm.
+
+All integrations share one non-optional authored-asset rule: every renderable
+root needs a stable target ID/domain, and every material slot needs a stable
+material ID plus semantic role in the versioned ToonLab material contract.
+Root-only labels do not make multi-material assets bundle-ready. Strict mode
+blocks incomplete assets; advisory mode must report them as incomplete.

package/agents/claude/CLAUDE.md

@@ -0,0 +1,8 @@
+@node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md
+
+## Claude Code
+
+- Use `agents/skills/claude/` as the user-facing usage guides for ToonLab
+  runtime features.
+- Keep this file short; shared guidance belongs in `agents/codex/AGENTS.md`.
+- Keep these downloadable resources focused on runtime usage.

package/agents/codex/AGENTS.md

@@ -0,0 +1,159 @@
+# ToonLab Agent Guide
+
+Use this file when helping a developer build an anime-style game, character,
+or environment with ToonLab's runtime library in their own Three.js app.
+
+## Anime-Game Product Contract
+
+- ToonLab is specifically an anime-game toolkit, not a generic stylization
+  library. Read `agents/references/anime-art-direction.md` before making
+  visual, shader, material, or asset decisions.
+- Load the selected bundle's `artDirection` and treat it as authoritative.
+  Call Me Sensei is the first-party coordinated reference.
+- Never accept unintended photorealism, generic low-poly styling, undirected
+  cartoon rendering, or untreated PBR materials as a finished ToonLab result.
+- If supported shaders or approved assets are insufficient, document the
+  customization and why your project needs it.
+
+## Runtime Boundary
+
+- `@call-me-sensei/toonlab` is primarily a runtime library for applying
+  Three.js shaders, stylized materials, focused vegetation/water, settings,
+  and preset documents to supplied scene content.
+- Prefer public package imports such as `@call-me-sensei/toonlab/toon`,
+  `@call-me-sensei/toonlab/environment`, `@call-me-sensei/toonlab/water`,
+  `@call-me-sensei/toonlab/vegetation`, `@call-me-sensei/toonlab/post`,
+  `@call-me-sensei/toonlab/styles`,
+  `@call-me-sensei/toonlab/texgen`, and `@call-me-sensei/toonlab/rockgen`.
+- Use `@call-me-sensei/toonlab/sky` and `/cloud` for the live Sky, Cloud, and
+  Sky & Cloud Lab contracts. Weather, Climate, ambient effects, and fauna are
+  not public package entry points in this release.
+- Use `@call-me-sensei/toonlab/vegetation-shaders` and
+  `@call-me-sensei/toonlab/grass-palettes` when a consumer needs only those
+  focused contracts. They are the same bindings exposed by the vegetation and
+  root barrels.
+- Keep root imports lightweight in examples. Import only the feature subpath a
+  developer needs.
+- Public export status and product maturity are different. Toon,
+  Environment/Ground/Rock, Tree/Grass/Flower, Water on a host-authored
+  footprint/shore/bed, Post, Gallery/MCP asset workflows, loaders, portable
+  settings, Sky/Cloud, and qualified focused generators are the recommended
+  path. Whole terrain/biome/coast/cliff construction,
+  automatic set dressing, and cross-system world assembly are experimental.
+- ToonLab's labs, sample assets, local manifests, screenshots, captures, and
+  app routes are examples. Do not treat them as part of the runtime API or copy
+  their local asset assumptions into user apps.
+- The host app owns scene layout and major geometry, asset placement, cameras,
+  collision, asset loading, decoder hosting, storage, routing, persistence,
+  collaboration, and final art direction. Renderer construction stays
+  host-owned, while the public renderer helper and scene style runtime apply
+  reversible Call Me Sensei renderer, lighting, probe, and shadow settings.
+- VFX, camera, game-feel, and renderer selection are not style-bundle domains.
+  Treat project-local implementations as custom adapters and record a gap when
+  they affect the selected look. Lighting is a supported bundle domain.
+
+## Usage Rules
+
+- Use the README and docs pages first; feature skills in `agents/skills/codex/`
+  are short usage guides for public runtime APIs.
+- For existing-scene or multi-system integration, start with the `game-dev`
+  skill (boundary, frame-loop contract, task→skill routing). When sourcing or generating
+  assets, use the `asset-sourcing` skill. Feature-detect the connected ToonLab
+  OSS local and/or ToonLab Pro remote MCP surface before calling tools; their
+  overlapping tool names have different discovery roles and schemas.
+  First-party rock search must shortlist from meter dimensions and taxonomy;
+  do not load or render catalog GLBs merely to determine their size.
+- Whole-world and natural-cliff construction skills are not shipped in the npm
+  package. Prefer bounded work on an existing terrain, asset family,
+  vegetation field, or water body.
+- For any style-aware construction, use `style-presets` to record the intended
+  selector and distinguish neutral defaults from domains that already default
+  to Call Me Sensei. Before visual approval or reporting a package gap, use
+  `visual-verification` for readiness, isolation, multi-view, measurement, and
+  outlier checks. These routes apply to every agent integration, not only Codex
+  or Claude.
+- ToonLab materials are TSL/NodeMaterial-first for Three.js WebGPU with WebGL2
+  fallback through the same TSL path. Do not guide developers toward raw GLSL,
+  `ShaderMaterial`, or classic WebGL-only forks for ToonLab features.
+- Keep developer examples focused on documented settings, preset documents,
+  public constructors/helpers, and app-owned Three.js objects.
+- Keep artifact scope explicit: Shader Labs author IP profiles, Asset Labs
+  author geometry/material data, and Water Lab authors a focused runtime
+  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,
+  lighting, camera, interactions, and complete Sky/Cloud composition stay
+  host-owned or experimental.
+- For style-bundle, multi-shader, or arbitrary-asset work, read
+  `agents/references/style-bundles.md` first. A bundle selects coordinated treatments;
+  explicit asset labels select rendering destinations; scene state selects
+  current conditions. Inventory and label every renderable root and material.
+  Every newly modeled, generated, or imported material slot requires a stable
+  ID and valid semantic role in the versioned material contract. A root domain
+  label is not sufficient for a multi-material asset; missing roles and mixed
+  atlases without a split or ID mask block strict handoff.
+  Character anatomy, clothing, held weapons, and worn hero accessories
+  normally route to toon; manufactured props, vegetation, rocks/debris,
+  water/sky, and VFX retain their owning runtimes. For an imported manufactured
+  prop, call `proposeManufacturedStyleTargetLabel()` first, review every issue,
+  provide explicit `materialOverrides` for unresolved slots, then call
+  `applyManufacturedStyleTargetLabelProposal()`. Never collapse assisted
+  results into the automatic success rate.
+- Report unknown domains and material roles, mixed atlases without masks,
+  unsupported transparency, and custom-renderer exemptions. Never silently
+  infer a production-safe route from names, texture colors, or scene
+  parenting. Preserve asset identity and runtime conditions when changing
+  style.
+- Local style bundle creation, validation, serialization, parsing, and
+  resolution are OSS `/styles` APIs and require no database. Hosted storage
+  and `fetchStyleBundle` are optional. Scene discovery remains explicit;
+  manufactured assets have a conservative proposal/review/apply labeling path,
+  and strict bundle application reconciles declared roles against live slots
+  before the first mutation.
+- New bundles use `treeShader`, `grassShader`, `flowerShader`, and
+  `groundShader`. V1 `vegetationShader`, `tree`, `grass`, and `flowers`
+  selections are migration inputs only and never serialize into v2. Do not
+  serialize asset recipes, tree geometry, scatter, or live wind/weather
+  into shader slots.
+- Treat `call_me_sensei` as the first-party reference bundle. Optimize the
+  canonical domain implementations for the best coordinated result and apply
+  the completion gate in `agents/references/style-bundles.md`. Assigning the same
+  style id to every slot is not completion, and compatibility flattening for
+  incomplete assets must not define the signature look.
+- For sourcing or generation, read
+  `agents/references/mcp-asset-discovery.md` and
+  `agents/references/asset-sourcing-policy.md`. Reuse an
+  accepted asset first. If a procedural family has an approved stylized base
+  set and passed the reliability gate, generate directly and skip gallery
+  search. Otherwise use curated CC0, then properly attributed CC-BY; reserve
+  image-to-3D for a named remaining gap. Preserve base-set version, recipe,
+  seed, domain/material labels, license provenance, and the Call Me Sensei
+  verification result. Pro may author/review base sets; OSS consumes portable
+  artifacts without a database.
+- For Sky/Cloud and Water work, `.settings` is the portable authored baseline and
+  `.renderedSettings` is the current composition. Give Lighting, Weather, and
+  other transient owners unique `setSceneOverrideLayer` ids and clear only the
+  same id; never export composed scene state.
+- In a composed-world test, use the public Lighting bundle slot and scene style
+  runtime for the coordinated sun, sky probe, and shared shadow contract. Keep
+  host-owned Weather and any custom local-light adapters coordinated with Sky,
+  Water, and vegetation scene inputs.
+- Sky documents contain exactly 46 portable art fields. Radius and compile-time
+  quality are not portable: named tiers use 2/3/4 cloud octaves, custom quality
+  accepts `{ cloudOctaves: 1..5 }`, and `sky.setQuality()` rebuilds the material.
+  Water quality is chosen when constructing/replacing `WaterSurface`, not via
+  `applySettings()`.
+- Do not depend on ToonLab sample assets, generated manifests, or lab-only
+  model/environment discovery.
+- Keep these downloadable resources focused on runtime usage.
+
+## Developer Verification
+
+- For consumer apps, run that app's normal typecheck, test, build, and visual
+  smoke checks.
+- For generated rock assets, use a fixed seed and compare the output your app
+  expects.

package/agents/cursor/toonlab.mdc

@@ -0,0 +1,37 @@
+---
+description: ToonLab developer guidance for Cursor agents
+globs: "**/*"
+alwaysApply: true
+---
+
+# ToonLab
+
+- Treat `node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md` as the
+  shared developer guide.
+- Help developers stylize and populate supplied scenes with ToonLab runtime,
+  Gallery, and MCP workflows. Do not promise one-shot world construction.
+- Prefer package subpath imports such as `@call-me-sensei/toonlab/toon`,
+  `@call-me-sensei/toonlab/water`,
+  `@call-me-sensei/toonlab/vegetation-shaders`,
+  `@call-me-sensei/toonlab/grass-palettes`, and
+  `@call-me-sensei/toonlab/rockgen`;
+  keep root imports lightweight.
+- Use TSL/NodeMaterial patterns. Do not guide developers toward raw GLSL,
+  `ShaderMaterial`, or classic WebGL-only forks for ToonLab features.
+- Treat ToonLab labs, sample assets, screenshots, captures, and generated
+  manifests as examples, not runtime API.
+- Use `agents/skills/` as reference material for feature-specific workflows.
+- Material metadata is a blocking modeling deliverable. Every modeled,
+  generated, converted, or imported renderable needs a stable target ID and
+  domain; every material slot needs a stable material ID and semantic role in
+  the versioned ToonLab material contract. A root-only label is incomplete for
+  a multi-material asset. Split incompatible atlas regions or supply an ID
+  mask. Strict mode blocks handoff; advisory mode reports the gap and must not
+  describe incomplete material coverage as bundle-ready.
+- Treat Sky and Cloud as supported focused authoring/runtime systems. Whole
+  terrain/biome/coast/cliff formation remains outside the npm boundary.
+- Before style-aware construction, read the matching `style-presets` skill.
+  Before approving screenshots or reporting a package gap use
+  `visual-verification`. The Claude and Codex copies are byte-identical, so
+  either directory is authoritative.
+- Verify with the consumer app's normal checks.

package/agents/references/anime-art-direction.md

@@ -0,0 +1,24 @@
+# ToonLab Anime-Game Art Direction
+
+ToonLab is for anime-style games, characters, and environments. Do not treat
+"stylized" as permission to drift toward generic low-poly, western cartoon,
+pixel-art, or untreated photoreal rendering.
+
+The selected style bundle is the visual authority. Its `artDirection` must
+declare `family: "anime-game"`, `rendering: "cel-shaded"`, and both character
+and environment subjects.
+
+Evaluate every scene at gameplay camera distance:
+
+- Group values into intentional light and shadow shapes.
+- Preserve readable silhouettes and important material boundaries.
+- Reduce high-frequency texture detail deliberately; do not merely blur it.
+- Coordinate shadow color, atmosphere, sky, water, and post-processing.
+- Use material-aware graphic highlights for skin, hair, cloth, metal, leaves,
+  rock, ground, and water rather than one universal specular response.
+- Keep imported PBR maps as useful source information, then route the asset
+  through its owning ToonLab shader.
+
+If an asset or renderer cannot meet this direction with a supported shader,
+record a custom integration note instead of silently accepting a visually inconsistent
+fallback.

package/agents/references/asset-sourcing-policy.md

@@ -0,0 +1,23 @@
+# Asset-Sourcing Policy
+
+Import from `@call-me-sensei/toonlab/asset-policy`.
+
+Policies use one of three modes:
+
+- `strict`: a candidate is usable only when its domain rule explicitly lists
+  the candidate's source class.
+- `advisory`: preferred sources are ranked first; other registered sources
+  remain usable with a warning.
+- `open`: every registered source class is allowed, with provenance retained.
+
+Registered source classes are `project-library`, `toonlab-library`,
+`toonlab-gallery`, `external-cc0`, `procedural`, and `custom`.
+
+No policy means “ask, then advisory.” It never means strict and it never gives
+an agent permission to claim that a sourcing requirement was satisfied.
+
+The strict Call Me Sensei acceptance fixture allows rocks only from the
+project library, ToonLab library, or ToonLab gallery. Trees may also use the
+package's supported procedural legacy set or `BranchTree`. Other custom trees must be
+reviewed and admitted to one of the approved libraries before that fixture can
+use them.

package/agents/references/custom-gap-report.md

@@ -0,0 +1,16 @@
+# Custom integration records
+
+Custom work should be traceable instead of becoming an invisible fallback. Before adding it, use
+`record_asset_gap` or `createAssetGapRecord()` and record:
+
+- Target and rendering domain.
+- Relevant style-bundle slot.
+- MCP searches, queries, candidate IDs, and rejection reasons.
+- Why permitted library, gallery, external, or procedural routes failed.
+- What custom model, texture, shader, or adapter was introduced.
+- Provenance, license, generator/recipe/seed where relevant, and the decision owner.
+- Why the customization exists and what your team may want to revisit later.
+
+The MCP server maintains `.toonlab/reports/style-asset-gaps.json` and the
+project-level `TOONLAB_ASSET_GAPS.md`. Keep both with your project whenever it
+uses custom rendering or content outside the supported library.

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

@@ -0,0 +1,104 @@
+# MCP Asset Discovery
+
+Use MCP for discovery, provenance, shared workspace state, and policy-aware
+imports. Use runtime package APIs for shader application and deterministic
+runtime construction.
+
+## Detect the available ToonLab surface
+
+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.
+- **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
+  work are searched through `search_public_gallery`.
+- **Both connected** is valid. Qualify calls by MCP server name because common
+  names such as `search_assets`, `get_asset`, `list_my_creations`, and
+  `validate_asset_candidate` have surface-specific schemas. Search the local
+  project/library first, then the Pro gallery and cloud library.
+
+The absence of a surface-specific tool is not an asset failure. Continue with
+the surface the developer actually has and report which surface was used.
+
+## Shared start
+
+1. Call the available server's `get_anime_game_profile` and load the selected
+   style bundle.
+2. Locate the project's asset-sourcing policy. If it is absent, ask the
+   developer. Until answered, continue library-first in advisory mode and
+   record that the decision is unresolved.
+3. Reuse accepted project/library content before public or generated content.
+
+## ToonLab OSS local sequence
+
+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.
+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/`.
+4. Validate with local schema:
+   `validate_asset_candidate({ policy, candidate: { domain, sourceClass } })`.
+5. Local `generate_asset` creates deterministic procedural recipes. With local
+   provider keys configured, `generate_ai_asset` exposes image generation,
+   Meshy 7 image/multiview-to-3D, and Text → selected image model → Meshy 7.
+   Call `get_generation_capabilities` first, then poll with
+   `get_generation_job(s)` and persist a succeeded model with
+   `save_generated_asset`. This uses the developer's keys and no ToonLab credits.
+
+## ToonLab Pro remote sequence
+
+1. Call Pro `list_my_creations` with `query`, `tags`, and/or `types` for the
+   signed-in cloud library, following `nextOffset` until null.
+2. Call `search_public_gallery` with its unified default. For first-party
+   rocks/trees, use `source: 'toonlab'`, `catalog: 'rock' | 'tree'`, and keep
+   following `nextOffset`.
+3. Use Pro `search_assets` only for indexed external open assets, followed by
+   Pro `get_asset`. Pro has no `search_cc0_assets` or `import_cc0_asset`; the
+   selected download URL and provenance are returned by `get_asset`.
+4. Validate with Pro schema:
+   `validate_asset_candidate({ stable_id, source_class, asset_kind, domain,
+   license, provenance, policy })`.
+5. Managed generation requires an approved policy, exhausted discovery,
+   `record_asset_gap`, and `get_generation_capabilities` before any
+   consequential credit-spending call.
+
+Follow `nextOffset` until null on both OSS and Pro catalog searches; never
+interpret one response page as the complete candidate set.
+
+## Common completion rules
+
+- Treat a saved Library object as a reusable asset, not an invisible draft.
+  When saving, assign up to ten stable lowercase slug tags covering semantic
+  role, material/asset family, location or biome, project, and lifecycle state.
+  Do not stuff prose into tags, and do not rely on a filename as the only
+  discovery key.
+
+- For first-party rocks on either surface, shortlist from search metadata
+  before loading binaries. Require positive `dimensionsMeters.width`,
+  `.height`, and `.depth`, then compare family/profile, scale class, category,
+  subcategory, geology, and surface. Call `get_asset` (OSS) or
+  `get_toonlab_asset` (Pro) only for finalists that need the full recipe,
+  lineage, and immutable file list. Never render a GLB merely to discover its
+  catalog size.
+- Inspect provenance, license, semantic suitability, `animeStyleSupport`, and
+  the policy decision before selection. A strict denial means the candidate
+  must not be selected, imported, or generated.
+- Search results may show denied candidates so the user can see what was
+  considered; visibility is not approval.
+- Use generation only when the policy permits it and discovery did not close
+  the named gap.
+- Record a custom integration note before introducing custom models, textures, shaders, or
+  adapters. The OSS and Pro `record_asset_gap` argument names differ, so use
+  the schema advertised by the connected server.