@call-me-sensei/toonlab 0.4.19 → 0.4.20

package/NPM-LIBRARY.md

@@ -0,0 +1,225 @@
+# 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
+repository.
+
+## Install
+
+```bash
+npm install @call-me-sensei/toonlab three
+```
+
+ToonLab requires Node.js 18 or newer for its command-line and local MCP tools.
+The rendering library targets the Three.js TSL/NodeMaterial stack and is
+WebGPU-first with a WebGL2 fallback through the same public materials.
+
+## Supported product surface
+
+The public package follows the 15 Labs currently shown in ToonLab Pro. Several
+Labs share one runtime because they author different scopes of the same
+portable document.
+
+| ToonLab Pro Lab | npm runtime |
+| --- | --- |
+| Character & Creature Shader | `@call-me-sensei/toonlab/toon` |
+| Tree Shader | `@call-me-sensei/toonlab/vegetation-shaders` |
+| Grass Shader | `@call-me-sensei/toonlab/vegetation-shaders` |
+| Flower Shader | `@call-me-sensei/toonlab/vegetation-shaders` |
+| Rock & Geology Shader | `@call-me-sensei/toonlab/rock-shader` |
+| Terrain & Ground Shader | `@call-me-sensei/toonlab/ground-shader` |
+| Manufactured Surface Shader | `@call-me-sensei/toonlab/environment` |
+| Water & Liquid Shader | `@call-me-sensei/toonlab/water` |
+| Sky Shader | `@call-me-sensei/toonlab/sky` |
+| Cloud Shader | `@call-me-sensei/toonlab/cloud` |
+| Sky & Cloud | `@call-me-sensei/toonlab/sky` and `/cloud` |
+| Rock & Cliff Generation | `@call-me-sensei/toonlab/rockgen` |
+| Tree & Shrub Generation | `@call-me-sensei/toonlab/vegetation` |
+| Grass & Groundcover Generation | `@call-me-sensei/toonlab/vegetation` |
+| Texture & Material Map Generation | `@call-me-sensei/toonlab/texgen` |
+
+These stable support entry points are also public because the visible Labs,
+Library, Gallery, style-bundle workflow, or integration examples depend on
+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;
+- `@call-me-sensei/toonlab/character` and `/loaders` for supported preview and
+  host-model integration;
+- `@call-me-sensei/toonlab/runtime`, `/renderer`, `/lighting`, and
+  `/world-collision` for the shared scene contract used by the documented
+  integration examples;
+- `@call-me-sensei/toonlab/post` for the coordinated optional post pipeline;
+- focused aliases such as `/toon-settings`, `/water-settings`, `/grass`,
+  `/grass-palettes`, `/post-processing`, and `/vegetation-shaders` when a
+  consumer does not want a larger barrel.
+
+The package deliberately does not export Weather, Climate, Biome, Landscape,
+path/building/village generation, debris generation, fauna, ambient effects,
+game feel, camera behavior, soundscape, or gameplay VFX. Those areas may exist
+as repository experiments or host examples, but they are not npm APIs in this
+release. A one-asset Node rock annotation compiler is also repository-only.
+
+## What the package contains
+
+The npm artifact contains four supported layers:
+
+1. The JavaScript runtime and TypeScript declarations for the public imports.
+2. Text-only agent guides, prompts, references, and paired Codex/Claude skills
+   under `agents/`.
+3. The `toonlab` manifest audit CLI and `toonlab-mcp` local stdio MCP server.
+4. The local MCP database/catalog support required for Library and asset
+   discovery workflows.
+
+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.
+
+## Use a focused runtime
+
+```js
+import {
+  applyToonShader,
+  createToonSettings,
+} from '@call-me-sensei/toonlab/toon';
+
+const settings = createToonSettings({
+  rimLight: { intensity: 0.35, mode: 'depth' },
+  outline: { thickness: 1.6 },
+  skinTone: { skinShadowBrightness: 0.94 },
+});
+
+applyToonShader(characterRoot, { settings });
+```
+
+For a multi-domain scene, label roots and materials before applying a bundle.
+Strict mode preflights the complete plan and stops before mutation when a
+target, material role, or adapter is missing.
+
+```js
+import {
+  CALL_ME_SENSEI_STYLE_BUNDLE,
+  createSceneStyleRuntime,
+} from '@call-me-sensei/toonlab/styles';
+
+const look = createSceneStyleRuntime({ renderer, scene, sky, water, post });
+await look.apply(CALL_ME_SENSEI_STYLE_BUNDLE, {
+  discovery: 'scene-labels',
+  mode: 'strict',
+});
+
+renderer.setAnimationLoop(() => {
+  const delta = clock.getDelta();
+  look.update(delta, camera);
+  renderer.render(scene, camera);
+});
+```
+
+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.
+
+## Install the agent guidance
+
+Everything in this section is present in the installed npm package.
+
+### Codex
+
+```bash
+cp node_modules/@call-me-sensei/toonlab/agents/codex/AGENTS.md ./AGENTS.md
+mkdir -p .agents/skills
+cp -R node_modules/@call-me-sensei/toonlab/agents/skills/codex/* .agents/skills/
+```
+
+### Claude Code
+
+```bash
+cp node_modules/@call-me-sensei/toonlab/agents/claude/CLAUDE.md ./CLAUDE.md
+mkdir -p .claude/skills
+cp -R node_modules/@call-me-sensei/toonlab/agents/skills/claude/* .claude/skills/
+```
+
+### Cursor
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/@call-me-sensei/toonlab/agents/cursor/toonlab.mdc .cursor/rules/
+```
+
+Use `agents/PROMPTS.md` for ready-to-paste prompts. Begin with `game-dev` for
+an existing scene and add `asset-sourcing` when Library, Gallery, or MCP asset
+discovery is involved.
+
+## Connect MCP
+
+### Local npm MCP
+
+The package executable runs as a local stdio server. With no `DATABASE_URL`,
+it uses the disk workspace passed through `--workspace`; no account is needed.
+
+```json
+{
+  "mcpServers": {
+    "toonlab-local": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@call-me-sensei/toonlab@0.4.20",
+        "--workspace",
+        "/absolute/path/to/your-game/.toonlab"
+      ],
+      "env": {
+        "TOONLAB_LEGACY_WORKSPACE": "1"
+      }
+    }
+  }
+}
+```
+
+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.
+
+### ToonLab Pro MCP
+
+Add `https://toonlab.io/mcp` as a remote MCP server and authorize in the
+browser. The hosted server adds the signed-in Pro Library, published Gallery,
+stored characters, and managed generation. Local and remote servers may be
+connected at the same time; inspect the tool description before choosing one
+when names overlap.
+
+Full live setup and tool documentation is available at
+<https://toonlab.io/docs/mcp>.
+
+## CLI
+
+The `toonlab` executable audits JSON scene manifests without starting a
+renderer:
+
+```bash
+npx toonlab audit --input scene.json --bundle call-me-sensei --mode strict --pretty
+```
+
+Supported operations are `inspect`, `audit`, `plan`, `apply`, and `verify`.
+Use `--out` to write a report. `apply --write-manifest` is the only operation
+that replaces the input file and should be used only after reviewing the plan.
+
+## Documentation without the source repository
+
+- This installed guide is the complete npm boundary and setup reference.
+- `README.md` provides the longer runtime tour.
+- `agents/README.md` explains the packaged agent resource layout.
+- `agents/PROMPTS.md` contains supported prompts.
+- `agents/references/` contains the machine-readable runtime, style, sourcing,
+  and MCP contracts used by the skills.
+- <https://toonlab.io/docs> provides hosted user documentation.
+- <https://toonlab.io/docs/labs> documents all 15 public Labs.
+- <https://toonlab.io/docs/reference> and
+  <https://toonlab.io/docs/reference.md> provide the settings reference.
+
+GitHub access is not required for npm installation, agent setup, MCP setup, or
+the supported runtime workflows above.

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.19
+## Versioned expectation: 0.4.20
 
 For a correctly constructed and semantically labeled scene, one strict Call Me
 Sensei bundle application is expected to establish the supported visual
@@ -34,12 +34,11 @@ and reversible per-domain inspection.
 
 The host still authors the level, geometry, asset selection and placement,
 material labels, cameras, gameplay, dynamic physics, and navigation. Labeled
-solid objects receive conservative static collision by default. Arbitrary imported assets are
-not guaranteed to route automatically; strict mode blocks uncertain contracts
-instead of guessing. See [What ToonLab 0.4.19 can and cannot
-do](https://github.com/call-me-sensei/toonlab/blob/main/docs/capability-status.md)
-for the complete public contract, measured imported-asset readiness, and the
-required verification sequence.
+solid objects receive conservative static collision by default. Arbitrary
+imported assets are not guaranteed to route automatically; strict mode blocks
+uncertain contracts instead of guessing. The installed
+[npm library guide](./NPM-LIBRARY.md) defines the complete shipped surface,
+exclusions, agent setup, MCP setup, and package-first documentation paths.
 
 ## Recommended scope today
 
@@ -61,9 +60,8 @@ The recommended production workflow is:
 
 Whole-world generation, terrain/biome/coast/cliff formation, automatic set
 dressing, Weather/Climate composition, gameplay systems, and autonomous scene
-classification belong under experimentation. See
-[What ToonLab is ready for today](https://github.com/call-me-sensei/toonlab/blob/main/docs/capability-status.md)
-for the exact boundary and a recommended agent brief.
+classification belong under experimentation. The exact supported boundary and
+a recommended agent brief ship in `NPM-LIBRARY.md` and `agents/PROMPTS.md`.
 
 ## Quickstart
 
@@ -86,6 +84,19 @@ permissive signatures only where inference cannot produce a valid public type.
 Package verification compiles a clean packed consumer with `strict: true` and
 `skipLibCheck: false`.
 
+The npm artifact is self-documenting when the source repository is unavailable:
+
+- `NPM-LIBRARY.md` is the versioned install, runtime, agent, MCP, and support
+  boundary guide.
+- `agents/PROMPTS.md` contains ready-to-paste supported prompts.
+- The Codex, Claude Code, and Cursor guidance files are included under
+  `agents/` alongside their paired feature skills.
+- Live user documentation remains available at
+  [toonlab.io/docs](https://toonlab.io/docs), including the
+  [15 public Labs](https://toonlab.io/docs/labs),
+  [MCP setup](https://toonlab.io/docs/mcp), and
+  [settings reference](https://toonlab.io/docs/reference).
+
 ```ts
 import {
   CALL_ME_SENSEI_STYLE_BUNDLE,
@@ -159,6 +170,7 @@ TRIPO_API_KEY=
 MESHY_API_KEY=
 MESHY_API_KEYS=
 GEMINI_API_KEY=
+FAL_KEY=
 OPENAI_API_KEY=
 ARK_API_KEY=
 POLYPIZZA_API_KEY=
@@ -178,6 +190,9 @@ safe to run again.
 
 The local MCP server exposes the same configured image/3D providers through
 `generate_ai_asset`, `get_generation_job(s)`, and `save_generated_asset`.
+With `FAL_KEY`, `kind: "material"` creates a seamless Fal Patina preview and a
+durable grouped PBR bundle (basecolor, normal, roughness, metalness, and height)
+at 1K–8K instead of flattening the maps into unrelated image jobs.
 Meshy text mode first generates a concept with the selected `image_model`,
 then submits that PNG/JPEG to Meshy 7 as one trackable MCP job. The existing
 `generate_asset` tool remains the deterministic procedural-recipe contract.
@@ -220,6 +235,18 @@ opaque objects under `.toonlab/objects`; Postgres stores their metadata and
 generation history. Saved generated assets appear in `/library/` with preview,
 Open, asset-download, JSON-export, and delete actions.
 
+Every meaningful Library save also creates an immutable local revision. Open a
+creation in `/library/` to browse or download earlier documents, give important
+versions a unique name, add version-only tags and notes, pin milestones, or
+restore an earlier snapshot. Identical saves are deduplicated, and restore
+always creates a new head revision instead of rewriting history. This revision
+number is Library history; a document's own `version` field remains its portable
+schema version. Style-bundle revisions also record the exact revisions of saved
+documents referenced by their slots. Local runtimes can request the locked,
+self-contained bundle with
+`fetchStyleBundle('/api/toonlab/library/<bundle-id>/resolved')`; a missing lock
+fails explicitly instead of substituting a newer dependency.
+
 ### Updating an existing installation
 
 Use the same update sequence for every ToonLab release, whether it contains
@@ -249,7 +276,9 @@ seed batches in order. Existing installations apply only newer batches.
 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.
+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.
 
 Applied filenames and SHA-256 digests are recorded in `schema_migrations` and
 `catalog_seed_batches`. Never edit, rename, or replace a released migration or
@@ -497,6 +526,10 @@ separators; maximum 10 tags and 32 characters each) and are
 stored independently from the portable document so they remain searchable
 after reload and edits.
 
+Revision history is unlimited in the local workspace. Creation tags above are
+separate from version tags: creation tags remain discovery metadata, while
+version tags describe a particular immutable snapshot.
+
 Start by loading one style bundle, explicitly labeling the scene targets, and
 preflighting the complete routing plan. Strict mode is atomic: if any target
 is unlabeled, unsupported, or missing an adapter, nothing is mutated.
@@ -637,9 +670,8 @@ visual assets.
 The skills teach the agent the runtime boundary, asset-discovery order,
 frame-loop contract, and each focused subsystem API. Start with `game-dev` for
 integration into an existing scene and `asset-sourcing` for Gallery/MCP work.
-`outdoor-world`, `karst-cliff-construction`, and current Sky/Cloud guidance are
-experimental research aids: use them to qualify a bounded experiment or record
-a gap, not as a promise that an agent can build a polished world in one pass.
+Experimental whole-world, natural-cliff, Weather/Climate, camera, game-feel,
+and gameplay-VFX skills are intentionally not included in the npm artifact.
 
 ```bash
 # Claude Code — feature skills + project guidance
@@ -658,6 +690,8 @@ cp node_modules/@call-me-sensei/toonlab/agents/cursor/toonlab.mdc .cursor/rules/
 ```
 
 See [`agents/README.md`](agents/README.md) for the full layout.
+Ready-to-paste supported prompts are included in
+[`agents/PROMPTS.md`](agents/PROMPTS.md).
 
 ### 2. Connect MCP for asset discovery
 
@@ -673,15 +707,17 @@ into a disk-backed `.toonlab/` workspace:
   "mcpServers": {
     "toonlab-local": {
       "command": "npx",
-      "args": ["-y", "@call-me-sensei/toonlab@latest", "--workspace", "/absolute/path/to/your-game/.toonlab"]
+      "args": ["-y", "@call-me-sensei/toonlab@latest", "--workspace", "/absolute/path/to/your-game/.toonlab"],
+      "env": { "TOONLAB_LEGACY_WORKSPACE": "1" }
     }
   }
 }
 ```
 
-If you run the labs from a checkout (`npm run dev`), open
-`http://localhost:5175/settings/` for a ready-made config instead. See
-[Local MCP and workspace](https://github.com/call-me-sensei/toonlab/blob/main/docs/mcp.md).
+The npm server defaults to this disk workspace when `DATABASE_URL` is absent.
+See [the installed npm guide](./NPM-LIBRARY.md) and
+[live MCP documentation](https://toonlab.io/docs/mcp) for the complete local
+and hosted setup.
 
 **ToonLab Pro (remote, OAuth).** [toonlab.io](https://toonlab.io) hosts a
 remote MCP server that adds an indexed CC0 asset search with ToonLab-styled

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

@@ -4,11 +4,11 @@ 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 focused
-shaders/vegetation/water/post, find assets through Gallery or MCP, and author
-bounded portable outputs. `outdoor-world`, `karst-cliff-construction`, and
-current Sky/Cloud guidance are experimental research/qualification resources,
-not a promise of reliable one-shot scene construction.
+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:
 
@@ -33,18 +33,13 @@ integration and `asset-sourcing` for Gallery/MCP work):
 - `rockgen`
 - `style-presets`
 - `toon-shading`
-- `vegetation-sky` (vegetation path; its Sky/Cloud path is experimental)
+- `vegetation-sky`
 - `visual-verification`
 - `water`
 
-Experimental or host-owned boundary skills:
-
-- `camera`
-- `game-feel`
-- `karst-cliff-construction`
-- `lighting`
-- `outdoor-world`
-- `weather`
+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

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.