@aethervtt/shard-project 0.0.1

package/dist/docs.js

@@ -0,0 +1,1336 @@
+import {
+  allAssetSchemas,
+  allDataTypes,
+  allImporters
+} from "@aethervtt/shard-assets";
+import { allComponents } from "@aethervtt/shard-core";
+import { allGenerators } from "@aethervtt/shard-procgen";
+import { saveJsonSchema } from "@aethervtt/shard-save";
+import { prefabJsonSchema, sceneJsonSchema } from "@aethervtt/shard-scene";
+import { BUILTIN_PLUGINS, manifestJsonSchema } from "./manifest.js";
+const GENERATED_START = "<!-- shard:generated -->";
+const GENERATED_END = "<!-- /shard:generated -->";
+function fieldRow(name, schema) {
+  const type = describeType(schema);
+  const def = schema.default === void 0 ? "" : `\`${JSON.stringify(schema.default)}\``;
+  const range = [
+    schema.minimum !== void 0 ? `\u2265 ${schema.minimum}` : "",
+    schema.maximum !== void 0 ? `\u2264 ${schema.maximum}` : "",
+    schema["x-unit"] ? `${schema["x-unit"]}` : ""
+  ].filter(Boolean).join(", ");
+  const presets = schema["x-presets"] ? ` Presets: ${Object.keys(schema["x-presets"]).join(", ")}.` : "";
+  const description = `${schema.description ?? ""}${presets}`.replace(
+    /\|/g,
+    "\\|"
+  );
+  return `| \`${name}\` | ${type} | ${def} | ${range} | ${description} |`;
+}
+function describeType(schema) {
+  if (schema.anyOf) return schema.anyOf.map(describeType).join(" or ");
+  if (schema.enum) return schema.enum.map((v) => `\`"${v}"\``).join(" \\| ");
+  if (schema.type === "array") {
+    const n = schema.minItems === schema.maxItems && schema.minItems !== void 0 ? `${schema.minItems}` : "";
+    return `${describeType(schema.items ?? {})}[${n}]`;
+  }
+  if (schema.type === "object" && schema.properties && schema.properties.guid)
+    return schema["x-asset-type"] ? `${schema["x-asset-type"]} ref` : "asset ref";
+  return schema.type ?? "any";
+}
+function renderComponentCatalog(defs = allComponents()) {
+  const visible = defs.filter((d) => !d.name.startsWith("test/"));
+  const lines = [
+    "# Components",
+    "",
+    "Generated by `shard docs` from the registry. Use these names as keys under `components` in scene files.",
+    ""
+  ];
+  for (const def of visible) {
+    lines.push(`## \`${def.name}\``, "");
+    if (def.description) lines.push(def.description, "");
+    if (!def.serializable) lines.push("_Computed by the engine; never written in scene files._", "");
+    if (def.requires.length > 0)
+      lines.push(`Brings along: ${def.requires.map((r) => `\`${r.name}\``).join(", ")}.`, "");
+    const props = def.jsonSchema().properties ?? {};
+    if (Object.keys(props).length === 0) {
+      lines.push("Tag (no fields).", "");
+      continue;
+    }
+    lines.push("| Field | Type | Default | Range | Description |", "|---|---|---|---|---|");
+    for (const [name, schema] of Object.entries(props)) lines.push(fieldRow(name, schema));
+    if (def.name === "core/Transform") {
+      lines.push(
+        "| `rotationEuler` | number[3] | | degrees | Scene files only: rotation as X, then Y, then Z degrees. |"
+      );
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function renderErrorCatalog(codes) {
+  const lines = [
+    "# Error codes",
+    "",
+    "Every engine error is a `ShardError` with one of these codes.",
+    ""
+  ];
+  lines.push("| Code | Source | Hint |", "|---|---|---|");
+  for (const c of [...codes].sort((a, b) => a.code.localeCompare(b.code))) {
+    lines.push(`| \`${c.code}\` | ${c.source} | ${(c.hint ?? "").replace(/\|/g, "\\|")} |`);
+  }
+  return `${lines.join("\n")}
+`;
+}
+function renderAssetCatalog(importers = allImporters(), dataTypes = []) {
+  const projectImporters = new Set(dataTypes.map((d) => d.importer.name));
+  const visible = importers.filter(
+    (i) => !i.name.startsWith("test") && !projectImporters.has(i.name)
+  );
+  const lines = [
+    "# Assets",
+    "",
+    "Generated by `shard docs`. Files under the asset roots (`assetRoots` in shard.json) are imported",
+    "by extension. Each gets a `.meta` next to it with its guid and import settings; commit both.",
+    'Reference assets in scenes by path: `{ "path": "materials/hull.material.json" }`, or a',
+    'sub-asset with `#`: `{ "path": "assets/ship.glb#Mesh/Hull" }`.',
+    ""
+  ];
+  for (const importer of visible) {
+    lines.push(`## \`${importer.name}\``, "");
+    lines.push(`Files: ${importer.extensions.map((e) => `\`*${e}\``).join(", ")}`, "");
+    const props = importer.settings.jsonSchema().properties ?? {};
+    if (Object.keys(props).length === 0) {
+      lines.push("No import settings.", "");
+      continue;
+    }
+    lines.push("| Setting | Type | Default | Range | Description |", "|---|---|---|---|---|");
+    for (const [name, schema] of Object.entries(props)) lines.push(fieldRow(name, schema));
+    lines.push("");
+  }
+  if (dataTypes.length > 0) {
+    lines.push(
+      "# Project data types",
+      "",
+      "Defined in `scripts/` with `project.dataAsset`. Write one JSON file per value, anywhere under an",
+      "asset root (by convention `data/<kind>/`). A file can start from another of the same type with",
+      '`"$extends": { "path": "..." }` and override fields. Reference them from components and other',
+      "data types with `t.handle('<type>')`; read them with `world.resource(Type.store).get(ref)`.",
+      ""
+    );
+    for (const type of dataTypes) {
+      lines.push(`## \`${type.name}\``, "");
+      if (type.description) lines.push(type.description, "");
+      lines.push(
+        `Files: \`*.${type.extension}.json\` (e.g. \`data/${type.extension}s/<name>.${type.extension}.json\`). Schema: \`.shard/schemas/${type.extension}.schema.json\`.`,
+        ""
+      );
+      const props = type.jsonSchema().properties ?? {};
+      if (Object.keys(props).length === 0) {
+        lines.push("No fields.", "");
+        continue;
+      }
+      lines.push("| Field | Type | Default | Range | Description |", "|---|---|---|---|---|");
+      for (const [name, schema] of Object.entries(props)) lines.push(fieldRow(name, schema));
+      lines.push("");
+    }
+  }
+  return `${lines.join("\n")}
+`;
+}
+function renderGeneratorCatalog(gens = allGenerators()) {
+  const visible = gens.filter((g) => !g.name.startsWith("test/"));
+  const lines = [
+    "# Generators",
+    "",
+    "Generated by `shard docs`. A generator is `(seed, params) \u2192 output`, cached by the hash of its",
+    "inputs (name, version, code, params, seed, loaded assets). Use an output as:",
+    "",
+    "- a file, `generators/<name>.gen.json` (schema `.shard/schemas/gen.schema.json`), usable anywhere a",
+    '  handle of the output type is: `{ "path": "generators/boulder.gen.json" }`',
+    '- a ref, `{ "path": "procedural:<generator>?radius=2&seed=3" }` (numbers, bools, asset paths)',
+    '- entities: `procgen/GeneratorInstance { "generator": { "path": "<generator>" }, "seed": 3, "params": {} }`',
+    "- at runtime: `await generate(world, Gen, params, seed)`",
+    "",
+    'Tune one with MCP `preview_generator { "generator": "<name>", "seeds": "1-9" }` (a contact sheet)',
+    "and `run_generator` (counts, bounds, cache key). See `.agents/skills/make-a-generator.md`.",
+    ""
+  ];
+  if (visible.length === 0) lines.push("No generators yet.", "");
+  for (const gen of visible) {
+    lines.push(`## \`${gen.name}\``, "");
+    if (gen.description) lines.push(gen.description, "");
+    lines.push(
+      `Output: \`${gen.outputType}\`${gen.output === "mesh" ? " (sub-assets `#LOD1`, \u2026 when it makes levels of detail)" : ""}. Version ${gen.version}.`,
+      ""
+    );
+    const props = gen.params.jsonSchema().properties ?? {};
+    if (Object.keys(props).length === 0) lines.push("No params.", "");
+    else {
+      lines.push("| Param | Type | Default | Range | Description |", "|---|---|---|---|---|");
+      for (const [name, schema] of Object.entries(props)) lines.push(fieldRow(name, schema));
+      lines.push("");
+    }
+    const example = {
+      $schema: "../.shard/schemas/gen.schema.json",
+      generator: gen.name,
+      seed: 1,
+      params: {}
+    };
+    lines.push("```json", JSON.stringify(example), "```", "");
+  }
+  return `${lines.join("\n")}
+`;
+}
+const SKILLS = {
+  "build-a-scene.md": `# Build or change a scene
+
+1. Read \`.agents/components.md\` for component names and fields.
+2. Edit \`scenes/*.scene.json\`. Name every entity; nest with \`children\`. Materials go in \`assets\`
+   (\`{ "type": "Material", "value": {...} }\`), meshes can be procedural
+   (\`{ "path": "procedural:sphere?radius=2" }\`).
+3. Validate: \`shard validate --json\` (or the MCP \`validate_scene\` tool). Fix every error by its \`path\`.
+4. Look at it: \`shard screenshot scenes/main.scene.json --out shot.png\` (or MCP \`screenshot\`).
+`,
+  "add-a-component.md": `# Add a component
+
+In \`scripts/\`, define it on the project so it gets the project namespace:
+
+\`\`\`ts
+export const Fuel = project.component('Fuel', {
+  liters: t.f32({ default: 100, min: 0, unit: 'L', description: 'Fuel left.' }),
+})
+\`\`\`
+
+Write a description for every field: it ends up in \`.agents/components.md\`. Run \`shard docs\` after.
+`,
+  "write-a-system.md": `# Write a system
+
+\`\`\`ts
+const burn = defineSystem({
+  name: '<project>/burn',
+  setup: (world) => ({ q: world.query({ with: [Fuel] }) }),
+  run: ({ q }, world) => {
+    const dt = world.resource(FixedTime).step
+    for (const table of q.tables) {
+      const liters = table.column(Fuel, 'liters')
+      for (let i = 0; i < table.count; i++) liters[i] = Math.max(0, liters[i]! - dt)
+      table.markChanged(Fuel)
+    }
+  },
+})
+\`\`\`
+
+Register it in the project's \`build(app)\`: \`app.addSystems(FixedUpdate, burn)\`. Hot loops must not
+allocate: walk \`q.tables\` and use columns.
+`,
+  "write-a-gameplay-test.md": `# Write a gameplay test
+
+\`\`\`ts
+import { expect, test } from '@aethervtt/shard-testing'
+
+test('thrust moves the ship', async ({ game }) => {
+  await game.load('scenes/main.scene.json')
+  game.input.hold('<project>/Controls.thrust')
+  await game.step(120)
+  expect(game.get('ship', 'core/Transform').translation[2]).toBeLessThan(0)
+})
+\`\`\`
+
+Run with \`shard test --json\`. Tests are headless, seeded, and fixed-timestep: they pass or fail the
+same way every run.
+`,
+  "iterate-on-a-system.md": `# Change game code and see it run
+
+1. Edit a system or component in \`scripts/\`. The running game (MCP server, \`shard dev\` page)
+   rebuilds and hot reloads on save, keeping every entity and resource.
+2. Check it took: MCP \`project_status\` (or the note in \`step\`'s result). A failed build or reload
+   reports \`source\` as \`scripts/<file>.ts:line:col\`, and the previous code keeps running.
+3. \`step\` some frames and \`screenshot\` or \`get_entity\` to see the effect.
+4. Run \`typecheck\` (\`shard check --json\`): reloads don't wait for type errors.
+5. Changing a component's fields migrates live data: new fields take their defaults, removed ones
+   are dropped. To rename a field, bump the component's \`version\` and move the value in \`migrate\`.
+`,
+  "use-assets.md": `# Use asset files
+
+1. Put files under an asset root (\`assets/\`, \`materials/\`, \`data/\`). \`.agents/assets.md\` lists
+   what each extension imports as and its settings.
+2. Import: \`shard import --json\` (MCP \`reimport_asset\` with no "asset"). Fix failures by their \`path\`.
+3. Reference by path in scenes: \`"material": { "path": "materials/hull.material.json" }\`.
+4. Inspect with MCP \`get_asset\` (sub-assets, bounds, dependents, errors); change import settings
+   with \`reimport_asset\` and \`{ "settings": {...} }\`.
+5. Move or rename with \`shard mv <from> <to>\` (MCP \`move_asset\`), never by hand: it keeps the
+   \`.meta\` with the file and rewrites references.
+6. Look before you place: MCP \`preview_asset\` renders a texture, a material, or a model.
+
+Models: place a .glb/.gltf with \`"scene/SceneInstance": { "scene": { "path": "assets/ship.glb#Scene" } }\`;
+its nodes become children you can address by path (\`ship/Hull\`), changed per placement with
+\`overrides\` (see make-a-prefab.md). Reusable entity trees are prefabs (\`prefabs/*.prefab.json\`).
+
+Textures: a texture's \`usage\` setting says what it holds: \`color\` (albedo, emissive; sRGB),
+\`data\` (roughness, metallic, occlusion; linear), \`normal\` (tangent-space normal map), \`hdr\`.
+New files get a usage from their name (\`*_normal*\`, \`*rough*\`, \`*_orm*\`, \`*.hdr\`). Materials
+use textures through slots: \`"baseColorTexture": { "texture": { "path": "assets/rock.png" } }\`
+(also metallicRoughnessTexture, normalTexture, occlusionTexture, emissiveTexture).
+`,
+  "write-a-material.md": `# Write a material
+
+A material type is a schema plus a shader that overrides hooks. Lighting, shadows, and post effects
+keep working because the shader only changes the surface.
+
+1. Define it in \`scripts/\`:
+
+   \`\`\`ts
+   export const Lava = project.material('Lava', {
+     fields: {
+       crackColor: t.color({ default: [1, 0.3, 0.05, 1] }),
+       crackLuminance: t.f32({ default: 20000, unit: 'cd/m\xB2' }),
+       flow: t.vec2({ default: [0.02, 0], description: 'UV scroll per second.' }),
+       cracks: t.handle('Texture', { description: 'Crack mask (R).' }),
+     },
+     shader: 'project::lava',
+   })
+   \`\`\`
+
+2. Write \`shaders/lava.wesl\`. The generated module \`material::lava\` has the uniform (\`Lava\`)
+   and one texture and sampler per texture field (\`Lava_cracks\`, \`Lava_cracks_sampler\`):
+
+   \`\`\`wesl
+   import shard::pbr::types::{ VertexOutput, PbrInput };
+   import shard::pbr::standard::standard_input;
+   import shard::globals::globals;
+   import material::lava::{ Lava, Lava_cracks, Lava_cracks_sampler };
+
+   override fn pbr_input(in: VertexOutput) -> PbrInput {
+     var p = standard_input(in);
+     let uv = in.uv + Lava.flow * globals.time;
+     let crack = textureSample(Lava_cracks, Lava_cracks_sampler, uv).r;
+     p.emissive += Lava.crackColor.rgb * Lava.crackLuminance * crack;
+     return p;
+   }
+   \`\`\`
+
+   Hooks: \`vertex_position(position, normal, uv) -> vec3f\` (object-space displacement, applied in
+   every pass, shadows included), \`pbr_input(in) -> PbrInput\` (the surface), and
+   \`fragment_output(color) -> vec4f\` (pre-exposed HDR, before tonemapping). With
+   \`extends: 'none'\`, override \`shade(in) -> vec4f\` instead: it returns radiance in cd/m\xB2 and
+   alpha, and no lighting runs. \`noise: { detail: 'assets/noise/rock.noise.json' }\` in the
+   definition adds \`noise_detail(p: vec3f, seed: u32) -> f32\` to \`material::lava\` (see
+   make-a-noise-graph.md). In \`vertex_position\`, \`shard::mesh\` also gives the vertex's
+   \`vertex_uv1()\` and \`vertex_tangent()\`, \`vertex_world(p)\` (object to world), and
+   \`vertex_instance_data()\`: the two numbers of the entity's \`render/InstanceData\` (a fade,
+   flags). \`arrays: ['layers']\` binds a texture field as \`texture_2d_array\` (a
+   \`*.texarray.json\`).
+
+3. Use it in a material file: \`{ "type": "<project>/Lava", "crackLuminance": 30000,
+   "cracks": { "path": "assets/cracks.png" } }\`. Leaving out \`"type"\` means the standard material.
+4. Check it: \`shard validate --json\` (bad fields are reported by path), then MCP \`preview_asset\`
+   on the material file. Shader errors appear in \`recent_errors\` as \`shaders/lava.wesl:line:col\`,
+   and the last shader that compiled keeps running.
+`,
+  "make-2d.md": `# Make 2D: sprites, animation, tilemaps
+
+Add \`"sprite"\` to \`plugins\` in \`shard.json\`. 2D uses the same renderer as 3D (HDR, post effects).
+
+1. An atlas. Either drop images in a folder and add \`assets/sprites/hero.atlas-pack.json\`
+   (\`{}\` packs \`assets/sprites/hero/*.png\`; regions are the file names), or write
+   \`hero.atlas.json\`: \`{ "texture": { "path": "assets/sheet.png" }, "grid": { "columns": 8,
+   "rows": 4, "cellWidth": 16, "cellHeight": 16 } }\` (regions \`cell0\`, \`cell1\`, \u2026) and/or
+   \`"regions": [{ "name": "idle_0", "rect": [x, y, w, h] }]\`.
+2. A sprite: \`"sprite/Sprite": { "atlas": { "path": "assets/sprites/hero.atlas-pack.json" },
+   "region": "idle_0", "layer": 1 }\`. No \`size\`: pixels \xF7 \`Sprite2dSettings.pixelsPerUnit\` (100).
+   Higher \`layer\` draws on top; within a layer, higher z does. \`"space": "screen"\` makes an
+   overlay positioned in pixels.
+3. Animation: \`walk.clip.json\` = \`{ "atlas": {...}, "frames": [{ "region": "walk_0",
+   "duration": 0.1 }, ...], "loop": "loop", "events": [{ "frame": 2, "name": "step" }] }\`, then
+   \`"sprite/SpriteAnimation": { "clip": { "path": "assets/walk.clip.json" } }\`. Read events with
+   \`world.reader(SpriteAnimationEvent)\`.
+4. Tilemaps: \`level.tilemap.json\` layers are base64 u16 tiles (atlas region + 1, 0 empty), and
+   \`"sprite/Tilemap": { "atlas": ..., "data": ..., "tileSize": [1, 1] }\`. Edit at runtime with
+   \`setTile(world, map, x, y, tile)\`; only that chunk re-uploads.
+5. Pixel art: \`"render/PixelPerfect": { "pixelsPerUnit": 16 }\` on an orthographic camera.
+6. Check: \`shard validate\`, MCP \`preview_asset\` on the atlas (regions outlined and numbered) or
+   the clip, and \`render.describe\` \u2192 \`sprites\` (draw calls, sprites per layer, tilemap chunks).
+7. Lights and shadows: see \`light-2d.md\`.
+`,
+  "light-2d.md": `# Light 2D: lights, normal maps, shadows
+
+Sprites are unlit until their camera has \`"sprite/Lighting2d": { "ambient": [0.08, 0.08, 0.1, 1] }\`.
+Then each lit sprite shows \`albedo \xD7 (ambient + \u03A3 lights) + albedo \xD7 emissive\`: a light of
+intensity 1 at its center shows the sprite at its texture color. For a bright scene where lights
+only add, use \`"ambient": [1, 1, 1, 1]\`.
+
+1. Lights: \`"sprite/PointLight2d": { "color": [1, 0.7, 0.4, 1], "intensity": 1.5, "radius": 6 }\`.
+   \`"sprite/SpotLight2d"\` adds \`innerAngle\` / \`outerAngle\` (degrees) and points along the
+   entity's +X: rotate the entity (or parent it to a hand) to aim it. \`falloff\` tightens the
+   edge; \`height\` is how high above the sprites it sits (low grazes normal maps).
+2. Shadows: \`"shadows": true\` on the light (at most \`Lighting2d.maxShadowed\`, 64, per view; the
+   nearest win) and \`"sprite/LightOccluder2d"\` on what blocks it: \`"shape": "box"\` with \`size\`,
+   \`"circle"\` (\`size[0]\` is the radius), \`"polygon"\` with \`points\`, \`"sprite"\` (the sprite's
+   outline), or \`"collider"\` (its physics Collider). \`softness\` on the light widens penumbras
+   (0: hard). Tile walls: set \`"occludes": true\` on the layer in \`*.tilemap.json\`.
+3. Normal maps: name them \`hero_n.png\` next to \`hero.png\` in an atlas-pack folder and they pack
+   into a matching page (\`"normalMap": "directx"\` in the pack file flips green). Plain texture
+   sprites: \`"sprite/SpriteLighting": { "normal": { "path": "assets/rock_n.png" } }\`. Add
+   \`"outlines": true\` to the pack file for \`shape: 'sprite'\` occluders that follow the alpha.
+4. Glow and exceptions: \`SpriteLighting.emissive\` for eyes and screens; \`"lit": false\` on a Sprite
+   (flames, UI, particles that shine on their own). \`layers\` on lights and occluders masks which
+   layer bands they touch (bit k covers layers k\xD764 \u2212 1024 \u2026).
+5. Check: \`render.describe\` \u2192 \`sprites.lighting\` (lights lit, culled, dropped over budget,
+   shadowed and demoted, occluder segments, tiles at the 64-light cap, GPU ms), the \`lights2d\`
+   overlay in a screenshot (radii, cones, each shadow row as a ring, occluder segments), and the log
+   for \`sprite/invalid-occluder\`, \`sprite/too-many-lights\`, \`sprite/too-many-shadowed-lights\`.
+`,
+  "show-text.md": `# Show text
+
+Add \`"text"\` to \`plugins\` in \`shard.json\` and put a \`.ttf\` or \`.otf\` under \`assets/\` (import
+settings: \`charset\`, \`size\`, \`range\`, \`fallback\` fonts for missing characters).
+
+- In the world: \`"text/Text": { "value": "Scanner 7", "font": { "path": "assets/fonts/Inter.ttf" },
+  "size": 0.5, "billboard": true }\`. \`size\` is the em height in meters.
+- On screen: \`"text/ScreenText": { "value": "Fuel 82%", "font": ..., "size": 24, "corner":
+  "top-right", "position": [-16, 16] }\` (pixels from the corner, y down).
+- Style: \`outline: { width: 0.03, color }\`, \`shadow: { offset: [0.05, -0.05], softness: 0.3, color }\`
+  (offset 0 with softness is a glow), \`weight\`. Wrap with \`maxWidth\`; \`align\` and \`anchor\` place it.
+- Size before placing: MCP \`measure_text\` returns width, height, and lines. \`preview_asset\` on the
+  font shows a specimen. Missing characters: \`render.describe\` \u2192 \`text.missing\`.
+`,
+  "add-physics.md": `# Add physics
+
+Add \`"physics3d"\` (or \`"physics2d"\` for a 2D game, never both) to \`plugins\` in \`shard.json\`.
+Bodies and colliders are components, so scenes, prefabs, and \`patch_entity\` create and change them:
+
+\`\`\`json
+{ "name": "crate", "components": {
+  "core/Transform": { "translation": [0, 3, 0] },
+  "physics/RigidBody": { "kind": "dynamic" },
+  "physics/Collider": { "shape": "cuboid", "halfExtents": [0.5, 0.5, 0.5], "restitution": 0.2 } } }
+\`\`\`
+
+- Kinds: \`dynamic\` (forces and contacts move it), \`fixed\`, \`kinematic-position\` (follows its
+  Transform), \`kinematic-velocity\` (moves by \`physics/Velocity\`). A \`Collider\` without a body is fixed.
+- Shapes: ball (\`radius\`), cuboid (\`halfExtents\`), capsule, cylinder, cone (\`radius\`, \`halfHeight\`
+  along Y), convex and trimesh (\`mesh\`: a Mesh asset, or \`points\`), heightfield, segment, polyline.
+  Scale in the Transform scales the shape. Colliders on children without their own body attach to
+  the nearest ancestor body (one compound body).
+- Move bodies with \`physics/Velocity\`, \`physics/ExternalForce\` (every step), or
+  \`physics/ExternalImpulse\` (once). Writing a dynamic body's Transform teleports it.
+- Layers: \`layers\` and \`mask\` are 16-bit masks; two colliders touch when each one's mask has the
+  other's layer. Planets: \`physics/GravitySource\` on the planet, and \`physics/Config\` gravity \`[0, 0, 0]\`.
+- Events: set \`events: true\` on a collider (sensors too) and read \`physics/CollisionEvent\`
+  (\`started\` / \`stopped\`, the two collider entities and their bodies).
+- Queries in code: \`world.resource(Physics).raycast(origin, dir, { mask }, hit)\`. From tools:
+  \`physics_raycast\`, \`physics_overlap\`, \`physics_describe\`. See shapes with
+  \`screenshot\` \`"overlays": ["colliders"]\`.
+
+Check a fall with a gameplay test:
+
+\`\`\`ts
+test('the crate lands', async ({ game }) => {
+  await game.load('scenes/main.scene.json')
+  await game.step(120)
+  expect(game.get('crate', 'core/Transform').translation[1]).toBeCloseTo(0.5, 1)
+})
+\`\`\`
+
+## Characters
+
+A walking player or NPC is \`physics/CharacterController\` with no RigidBody or Collider: it makes
+its own kinematic capsule (centered on the entity), climbs steps and slopes, snaps to the ground,
+pushes dynamic bodies, and rides kinematic platforms.
+
+\`\`\`json
+{ "name": "player", "components": {
+  "core/Transform": { "translation": [0, 1, 0] },
+  "physics/CharacterController": { "height": 1.8, "radius": 0.35, "up": "gravity" } } }
+\`\`\`
+
+- Write \`physics/CharacterIntent\`: \`move\` in m/s in the character's frame (x right, -z forward;
+  2D: x), and \`jump: true\` to jump once at the next grounded step.
+- Read \`physics/CharacterState\` (\`grounded\`, \`groundEntity\`, \`velocity\`, \`up\`, \`airTime\`) and
+  \`physics/CharacterGroundEvent\` (landed or left the ground). \`physics_describe\` lists characters.
+- \`up: "gravity"\` follows the strongest \`physics/GravitySource\` (walk around planets) and turns the
+  entity to match; \`"fixed"\` uses \`fixedUp\` and \`gravity\`. Turn it by writing its rotation;
+  writing its translation teleports it.
+
+\`\`\`ts
+test('the player walks and lands', async ({ game }) => {
+  await game.load('scenes/main.scene.json')
+  await game.step(30)
+  await game.patch('player', { 'physics/CharacterIntent': { move: [0, 0, -3] } })
+  await game.step(60)
+  expect(game.get('player', 'physics/CharacterState').grounded).toBe(true)
+  expect(game.get('player', 'core/Transform').translation[2]).toBeLessThan(-2.5)
+})
+\`\`\`
+`,
+  "animate.md": `# Animate a model or a property
+
+Add \`"animation"\` to \`plugins\` in \`shard.json\`. A \`.glb\` with animations imports each as an
+\`AnimationClip\` sub-asset (\`assets/ships/walker.glb#Animation/Walk\`; MCP \`get_asset\` lists its
+channels and duration). Skinned meshes and morph targets import tagged (\`render/SkinnedMesh\`,
+\`render/MorphWeights\`) and deform on their own; the player moves the joints.
+
+\`\`\`json
+{ "name": "walker", "components": {
+  "core/Transform": {},
+  "scene/SceneInstance": { "scene": { "path": "assets/walker.glb#Scene" } },
+  "animation/AnimationPlayer": { "layers": [
+    { "clip": { "path": "assets/walker.glb#Animation/Walk" } },
+    { "clip": { "path": "assets/walker.glb#Animation/Wave" }, "weight": 1,
+      "mask": { "path": "assets/masks/upper-body.mask.json" } } ] } } }
+\`\`\`
+
+- Put the player on the model root (the SceneInstance entity). Channels bind joints by path under
+  it; \`animation_describe\` lists channels that found no target.
+- Layers blend in order: \`override\` lerps toward its pose by \`weight\`; \`additive\` adds its change
+  since the clip's first frame. \`loop\`: \`loop\`, \`once\` (holds the end, sends
+  \`animation/AnimationFinished\`), \`ping-pong\`. Seek with \`time\`, pause with \`playing: false\`.
+- A mask is \`{ "joints": { "Armature/Hips/Spine": 1, "Armature/Hips/Spine/Neck": 0 } }\` in a
+  \`*.mask.json\`: a path covers its subtree, the longest match wins, uncovered joints get 0.
+- In code: \`crossfade(world, entity, clipRef, 0.3, { loop: 'once' })\` fades in a layer and fades
+  the others out; \`animationLayer(clipRef, { weight: 0.5 })\` builds a full layer.
+- To pick clips from state (idle, walk, run, jump, land), use a graph: see
+  \`animate-a-character.md\`.
+- Root motion: \`"rootMotion": "character"\` on an entity with \`physics/CharacterController\` turns
+  the clip's root travel into \`CharacterIntent.move\` (walking collides); \`"transform"\` moves the
+  entity directly. The root joint stays in place; \`animation/RootMotion\` has this frame's delta.
+- See joints with \`screenshot\` \`"overlays": ["skeleton"]\`; \`preview_asset\` on a glTF clip shows
+  its model at 5 times.
+- Feet on uneven ground, heads that look at things, weapons in hands, or clips from another rig:
+  see \`rig-a-character.md\`.
+
+Property clips animate any numeric field by path (\`""\` is the player's entity):
+
+\`\`\`json
+{ "duration": 2,
+  "tracks": [
+    { "path": "radar/dish", "component": "core/Transform", "field": "rotation",
+      "keys": [[0, [0, 0, 0, 1]], [2, [0, 1, 0, 0]]] },
+    { "path": "", "component": "render/PointLight", "field": "intensity",
+      "keys": [[0, 800], [0.1, 0], [0.2, 800]], "interpolation": "step" } ],
+  "events": [{ "time": 1, "name": "ping" }] }
+\`\`\`
+
+Save it as \`assets/anims/radar.anim.json\`. Events arrive as \`animation/AnimationEvent\`
+(\`name\`, \`layer\`, \`time\`). Unknown components or fields fail import with a pointer.
+`,
+  "animate-a-character.md": `# Animate a character with a graph
+
+A graph (\`*.animgraph.json\`) picks the character's clips from parameters: states, transitions
+with conditions, blend spaces, and masked layers. It writes the \`animation/AnimationPlayer\`
+layers each frame, so everything the player does (masks, root motion, events) still works.
+
+1. Import the model (\`assets/hero.glb\`); \`get_asset\` lists its \`#Animation/...\` clips.
+2. Write \`data/hero.animgraph.json\` (schema \`.shard/schemas/animgraph.schema.json\`):
+
+\`\`\`json
+{ "parameters": {
+    "speed": { "type": "float", "bind": { "component": "physics/CharacterState", "field": "velocity", "op": "horizontal" } },
+    "grounded": { "type": "bool", "bind": { "component": "physics/CharacterState", "field": "grounded" } },
+    "attack": { "type": "trigger" } },
+  "layers": [
+    { "name": "base", "entry": "locomotion",
+      "states": {
+        "locomotion": { "blend1d": { "parameter": "speed", "clips": [[0, "#idle"], [1.5, "#walk"], [5, "#run"]] } },
+        "fall": { "clip": "#fall" },
+        "land": { "clip": "#land", "loop": "once" } },
+      "transitions": [
+        { "from": "locomotion", "to": "fall", "when": "!grounded", "duration": 0.15 },
+        { "from": "fall", "to": "land", "when": "grounded", "duration": 0.05 },
+        { "from": "land", "to": "locomotion", "exitTime": 0.8, "duration": 0.2 } ] },
+    { "name": "upper", "mask": { "path": "data/masks/upper-body.mask.json" },
+      "states": { "none": {}, "swing": { "clip": "#swing", "loop": "once" } },
+      "transitions": [
+        { "from": "none", "to": "swing", "when": "attack", "duration": 0.1 },
+        { "from": "swing", "to": "none", "exitTime": 1, "duration": 0.2 } ] } ],
+  "clips": {
+    "idle": { "path": "assets/hero.glb#Animation/Idle" }, "walk": { "path": "assets/hero.glb#Animation/Walk" },
+    "run": { "path": "assets/hero.glb#Animation/Run" }, "fall": { "path": "assets/hero.glb#Animation/Fall" },
+    "land": { "path": "assets/hero.glb#Animation/Land" }, "swing": { "path": "assets/hero.glb#Animation/Swing" } } }
+\`\`\`
+
+3. Put \`"animation/Animator": { "graph": { "path": "data/hero.animgraph.json" } }\` on the model
+   root (next to its AnimationPlayer). Bound parameters read the component on that entity or its
+   nearest ancestor, so a model under a \`physics/CharacterController\` entity finds its state.
+4. \`shard validate --json\`: unknown states, clips, or parameters and conditions that don't parse
+   are errors with a pointer (conditions give the column); unreachable states are warnings.
+
+- Conditions: parameter names, numbers, \`true\`/\`false\`, \`!\`, \`&&\`, \`||\`, \`< <= > >= == !=\`,
+  parentheses. Transitions are checked in order, first match wins; \`"from": "*"\` is any state.
+  \`exitTime\` waits for the source state's normalized time (1 = its end); \`duration\` crossfades.
+- Triggers stay true until a transition that reads them is taken. Set parameters in code with
+  \`setAnimParam(world, entity, 'attack', true)\`, or patch \`animation/AnimatorParams.values\`.
+- \`{}\` states play nothing: the layers below show through. \`blend1d\` syncs its clips' normalized
+  times; \`blend2d\` (\`"x"\`, \`"y"\`, \`"clips": [[x, y, "#clip"], ...]\`) weights the three nearest
+  samples. Bind ops: \`value\`, \`length\`, \`horizontal\` (xz), \`x\`, \`y\`, \`z\`, \`not\`.
+- \`animation/AnimatorStateEntered\` (\`entity\`, \`layer\`, \`state\`, \`from\`) fires on each entry, for
+  "landed" or "swing hit". \`animation_describe\` shows each layer's state, transition progress,
+  time in state, blend weights, and the parameters.
+
+\`\`\`ts
+test('the hero falls, lands, and walks', async ({ game }) => {
+  await game.load('scenes/main.scene.json')
+  const layer = async () =>
+    (await game.call<any>('animation.describe', { entity: 'hero/model' })).animator.layers[0]
+  await game.step(30)
+  expect((await layer()).state).toBe('locomotion')
+  await game.patch('hero', { 'core/Transform': { translation: [0, 5, 0] } })
+  await game.step(10)
+  expect((await layer()).state).toBe('fall')
+  await game.patch('hero', { 'physics/CharacterIntent': { move: [0, 0, -3] } })
+  await game.step(120) // lands, then walks at 3 m/s: between walk (1.5) and run (5)
+  const base = await layer()
+  expect(base.state).toBe('locomotion')
+  expect(base.active.at(-1).motions.find((m: any) => m.name === 'Walk').weight).toBeGreaterThan(0.5)
+})
+\`\`\`
+`,
+  "rig-a-character.md": `# IK, sockets, and retargeting
+
+IK runs on the animated pose each frame (after the clips, before rendering). Joint fields are
+**paths** under the IK entity or its nearest ancestor that has them, like animation channels, so
+put IK on the model root (or on an entity under it, one per leg). Targets and poles are entities.
+
+\`\`\`json
+{ "name": "hero", "components": {
+    "scene/SceneInstance": { "scene": { "path": "assets/hero.glb#Scene" },
+      "overrides": { "Armature/Hips/Spine/Chest/Shoulder_R/UpperArm_R/LowerArm_R/Hand_R": {
+        "animation/BoneSocket": { "name": "hand_r", "offset": [0, -0.07, 0] } } } },
+    "animation/AnimationPlayer": { "layers": [{ "clip": { "path": "assets/hero.glb#Animation/Walk" } }] },
+    "animation/FootPlacement": { "hips": "Armature/Hips", "maxStep": 0.4, "feet": [
+      { "ik": "hero/leg-l", "footJoint": "Armature/Hips/UpLeg_L/Leg_L/Foot_L", "offset": 0.08 },
+      { "ik": "hero/leg-r", "footJoint": "Armature/Hips/UpLeg_R/Leg_R/Foot_R", "offset": 0.08 } ] },
+    "animation/LookAtIk": { "joint": "Armature/Hips/Spine/Chest/Neck/Head", "target": "player",
+      "maxAngle": 70, "chain": [{ "joint": "Armature/Hips/Spine/Chest", "share": 0.2 }] } },
+  "children": [
+    { "name": "leg-l", "components": { "animation/TwoBoneIk": {
+        "root": "Armature/Hips/UpLeg_L", "mid": "Armature/Hips/UpLeg_L/Leg_L",
+        "tip": "Armature/Hips/UpLeg_L/Leg_L/Foot_L", "target": "hero/foot-l", "pole": "hero/knee-l",
+        "tipRotation": 1 } } },
+    { "name": "foot-l", "components": { "core/Transform": {} } },
+    { "name": "knee-l", "components": { "core/Transform": { "translation": [-0.1, 0.5, -1] } } } ] }
+\`\`\`
+
+(and the same for the right leg). Add a sword with
+\`"animation/Attach": { "owner": "hero", "socket": "hand_r" }\`: it rides the hand, and comes back
+to it when the model reloads.
+
+- \`TwoBoneIk\`: legs and arms; bends toward \`pole\`. \`ChainIk\`: FABRIK for tails and tentacles.
+  \`LookAtIk\`: \`axis\` is the joint's own forward (-Z by default), clamped to \`maxAngle\` degrees.
+- \`FootPlacement\` needs \`"physics"\` in plugins. It casts down from each foot along the entity's
+  up, lowers the hips (never raises), and moves each leg's target onto the ground, turned to its
+  normal. Put the entity level with the soles; \`offset\` is the ankle height.
+- \`weight\` (0 to 1) blends every solver with the animation: fade it for cutscenes or ragdolls.
+- Retarget clips made for another skeleton: \`"animation/Retarget": { "source": { "path":
+  "assets/mixamo.glb#Skin/Skin0" }, "mode": "rotation-and-root" }\` on the player. Names match after
+  normalizing (\`mixamorig:LeftUpLeg\` = \`UpLeg_L\`); others go in a \`*.jointmap.json\`
+  (\`{ "joints": { "Spine1": "Chest" } }\`, the \`map\` field).
+- \`animation_describe\` on the model: \`ik\` (distance left to each target, foot hits, hips drop,
+  problems like \`ik/unknown-joint\`) and \`retarget\` (hip ratio, unmapped joints). Screenshot with
+  \`"overlays": ["ik", "skeleton"]\` to see targets, poles, and foot rays.
+`,
+  "make-a-data-asset.md": `# Make a data asset
+
+Tuning data that isn't an entity (weapon stats, items, loot tables, wave schedules) is a project
+data type: fields in \`scripts/\`, one JSON file per value.
+
+1. **Define the type** with component-schema fields:
+
+   \`\`\`ts
+   export const Weapon = project.dataAsset('Weapon', {
+     damage: t.f32({ default: 10, min: 0, unit: 'hp', description: 'Damage per hit.' }),
+     fireRate: t.f32({ default: 4, unit: 'shots/s' }),
+     projectile: t.handle('Prefab', { description: 'Spawned per shot.' }),
+     upgradesTo: t.handle('<project>/Weapon'),
+   }, { extension: 'weapon', description: 'A ship weapon.' })
+   \`\`\`
+
+   Run \`shard docs\`: the type shows up in \`.agents/assets.md\` and its schema is written to
+   \`.shard/schemas/weapon.schema.json\`.
+2. **Write files**: \`data/weapons/laser.weapon.json\`. Missing fields take their defaults.
+
+   \`\`\`json
+   { "$schema": "../../.shard/schemas/weapon.schema.json", "damage": 12,
+     "projectile": { "path": "prefabs/bolt.prefab.json" } }
+   \`\`\`
+3. **Make a variant** that starts from another file and overrides fields (struct fields merge field
+   by field, lists and handles replace):
+
+   \`\`\`json
+   { "$extends": { "path": "data/weapons/laser.weapon.json" }, "damage": 18 }
+   \`\`\`
+
+   Editing the base re-imports its variants. MCP \`get_asset\` on a variant shows its value, its
+   \`extends\` chain, and which file set each field (\`info.setBy\`).
+4. **Reference it** from a component: \`project.component('Armed', { weapon: t.handle('<project>/Weapon') })\`,
+   and in a scene \`"<project>/Armed": { "weapon": { "path": "data/weapons/laser.weapon.json" } }\`.
+   The weapon loads with the scene.
+5. **Read it** in a system: \`world.resource(Weapon.store).get(armed.weapon)\` is one map lookup,
+   no allocation. Every weapon at once: \`await loadAll(world, Weapon)\` (from \`@aethervtt/shard-assets\`).
+6. **Check**: \`shard import --json\` then \`shard validate --json\`. Errors point into the file;
+   a handle to the wrong type is \`schema/asset-type-mismatch\`, a loop of variants \`data/extends-cycle\`.
+
+Saving a data file or changing the type's fields while the game runs reloads the values in place.
+`,
+  "make-a-prefab.md": `# Make a prefab
+
+A prefab is a reusable entity tree: \`prefabs/<name>.prefab.json\`, validated against
+\`.shard/schemas/prefab.schema.json\`. It has one \`root\` entity, written like a scene entity:
+
+\`\`\`json
+{ "$schema": "../.shard/schemas/prefab.schema.json", "version": 1,
+  "assets": { "hull": { "type": "Material", "value": { "baseColor": "#8a93a6" } } },
+  "root": { "name": "ship",
+    "components": { "core/Transform": {}, "<project>/Health": { "max": 100 } },
+    "children": [
+      { "name": "Hull", "components": { "scene/SceneInstance": { "scene": { "path": "assets/ship.glb#Scene" } } } },
+      { "name": "Exhaust", "components": { "particles/ParticleSystem": { "effect": { "path": "assets/fx/exhaust.particles.json" } } } }
+    ] } }
+\`\`\`
+
+1. **Extract**: move an entity and its children out of a scene into \`root\`. Entity fields inside
+   the prefab use paths from the root (\`"Hull"\`, \`"Hull/Cockpit"\`; \`"."\` is the root).
+   \`shard import\` then \`shard validate --json\`: errors point into the file.
+2. **Place** it in a scene. The instance entity *is* the root: the prefab's root components merge
+   into it, and fields the entity sets win. Its children are generated, at \`player-ship/Exhaust\`:
+
+   \`\`\`json
+   { "name": "player-ship", "components": {
+     "core/Transform": { "translation": [0, 5, 0] },
+     "scene/PrefabInstance": { "prefab": { "path": "prefabs/ship.prefab.json" },
+       "overrides": {
+         "Exhaust": { "particles/ParticleSystem": { "timeScale": 2 } },
+         "Hull/Cockpit": { "render/MeshMaterial": { "material": { "path": "materials/red.material.json" } } },
+         "Hull/Antenna": null,
+         "Exhaust/particles/ParticleEmitterOverrides": null } } } }
+   \`\`\`
+
+   Override keys are paths from the instance and reach into models inside it (\`Hull/Cockpit\`).
+   A patch sets fields (adding the component if missing), \`null\` removes the entity, and a path
+   ending in a component name set to \`null\` removes that component. Authored \`children\` of the
+   instance sit next to the generated ones (names can't clash). \`scene/SceneInstance\` takes the same
+   \`overrides\` for a model placed directly.
+3. **Override live**: \`patch_entity\` on \`player-ship/Exhaust\`, check \`prefab_overrides\`, then
+   \`save_scene\` with \`"write": true\`: the change is written into \`overrides\`, nothing else.
+   \`prefab.apply\` (protocol) moves an instance's overrides into the prefab file instead.
+4. **Variant**: a prefab that extends another. Editing the base updates every variant.
+
+   \`\`\`json
+   { "version": 1, "extends": { "path": "prefabs/ship.prefab.json" },
+     "rootComponents": { "<project>/Health": { "max": 250 } },
+     "overrides": { "Hull/Antenna": null },
+     "children": [{ "name": "Turret", "components": { "core/Transform": {} } }] }
+   \`\`\`
+5. **Spawn from code**: load once, then spawning copies a compiled template (cheap enough for
+   bullets). In a system, pass \`ctx.commands\` to spawn when the commands apply:
+
+   \`\`\`ts
+   import { loadPrefab, spawnPrefab } from '@aethervtt/shard-scene'
+   await loadPrefab(world, 'prefabs/ship.prefab.json') // e.g. in the plugin's setup
+   const ship = spawnPrefab(ctx.commands, 'prefabs/ship.prefab.json', {
+     transform: { translation: [0, 5, 0] },
+     overrides: { Exhaust: { 'particles/ParticleSystem': { timeScale: 2 } } },
+   })
+   \`\`\`
+
+   Unloaded prefabs throw \`prefab/not-loaded\`. MCP \`spawn_prefab\` does the same from tools.
+
+Saving a prefab file updates every running instance and keeps each one's overrides; an override
+whose path no longer exists is kept in the file and logged as \`prefab/stale-override\`.
+\`get_asset\` on a prefab shows its entity tree, and on a variant its base chain.
+`,
+  "add-sound.md": `# Add sound
+
+Add \`"audio"\` to \`plugins\` in \`shard.json\`. Drop \`.ogg\`, \`.mp3\`, \`.wav\`, or \`.flac\` files under
+\`assets/\` and run \`shard import\`: each is an \`AudioClip\` (MCP \`get_asset\` shows duration, channels,
+sample rate, codec). Files stay compressed. Clips under \`music/\` stream; set \`"mode": "stream"\` in
+the \`.meta\` for other long files, and \`loopStart\`/\`loopEnd\` (seconds) for loop points.
+
+\`\`\`json
+{ "name": "camera", "components": { "core/Transform": {}, "render/Camera3d": {},
+    "audio/AudioListener": {} } },
+{ "name": "reactor", "components": { "core/Transform": { "translation": [4, 0, -10] },
+    "audio/AudioSource": { "clip": { "path": "assets/sfx/hum.ogg" }, "loop": true,
+      "rolloff": "linear", "maxDistance": 30 } } },
+{ "name": "music", "components": { "core/Transform": {},
+    "audio/AudioSource": { "clip": { "path": "assets/music/theme.ogg" }, "bus": "music",
+      "loop": true, "spatial": false, "volume": 0.6 } } }
+\`\`\`
+
+- Sources autoplay; set \`playing\` to start or stop one. A clip that doesn't loop clears
+  \`playing\` at its end and sends \`audio/AudioFinished\`. Spatial sources follow their transform;
+  the listener is the first \`audio/AudioListener\` (put it on the camera).
+- \`rolloff\`: \`inverse\` (default, natural), \`linear\` (silent at \`maxDistance\`; past it the source
+  goes virtual and holds no voice), \`exponential\`. \`panning\`: \`equal-power\` or \`hrtf\`.
+- One-shots from code: \`playSound(world, weapon.sound, { position: muzzle, bus: 'sfx' })\` from
+  \`@aethervtt/shard-audio\` returns a voice id for \`stopSound\`. A handle field
+  (\`t.handle('AudioClip')\`) on a data asset keeps sounds in data.
+- Buses are data (\`audio/Buses\`: master, music, sfx, ui, voice). Add one in a scene's
+  \`"resources": { "audio/Buses": { "engines": { "volume": 0.7, "parent": "sfx" } } }\`; change them
+  with \`setBus(world, 'sfx', { muted: true })\`. \`duck(world, 'music', { by: 0.7, release: 0.5 })\`
+  lowers music while a voice-bus line plays.
+- Over 64 voices (8 per clip) the lowest \`priority\`, then the quietest, lose theirs.
+- Check it: \`audio_describe\` lists every voice with gain and pan (-1 left, +1 right); gameplay tests
+  read \`await game.audioLog()\`:
+
+\`\`\`ts
+expect(await game.audioLog()).toContainEqual(
+  expect.objectContaining({ event: 'start', clip: 'assets/sfx/laser.ogg', position: [0, 0, 0] }),
+)
+\`\`\`
+
+Browsers start audio after the first click or key press; until then \`audio_describe\` says
+\`"context": "suspended"\` and voices wait. Headless runs record voices without sound.
+`,
+  "make-a-hud.md": `# Make a HUD
+
+Add \`"ui"\` to \`plugins\` in \`shard.json\`. UI is entities: a \`ui/UiRoot\` fills the screen, and
+\`ui/UiNode\` children lay out by flexbox (\`direction\`, \`justify\`, \`alignItems\`, \`grow\`, \`gap\`,
+\`padding\` and \`margin\` as top, right, bottom, left). Sizes are pixels, \`"50%"\`, or \`"auto"\`.
+Make the HUD a prefab, \`prefabs/hud.prefab.json\`, and place it in the scene with
+\`scene/PrefabInstance\`:
+
+\`\`\`json
+{ "version": 1, "root": { "name": "hud", "components": {
+    "ui/UiRoot": { "scale": "fit-height", "referenceSize": [1920, 1080],
+      "theme": { "path": "ui/hud.theme.json" } },
+    "ui/UiNode": { "padding": [24, 24, 24, 24], "justify": "space-between" } },
+  "children": [
+    { "name": "fuel", "components": { "ui/UiNode": { "style": "panel", "width": 260 } },
+      "children": [{ "name": "label", "components": { "ui/UiText": { "text": "Fuel 100%" } } }] },
+    { "name": "scan", "components": { "ui/UiNode": { "style": "button", "padding": [8, 16, 8, 16] },
+        "ui/UiButton": {} },
+      "children": [{ "name": "label", "components": { "ui/UiText": { "text": "Scan" } } }] }
+  ] } }
+\`\`\`
+
+- Looks: \`ui/UiStyle\` (background, borderColor, borderWidth, radius, opacity), \`ui/UiText\`
+  (text, size, color, font, align, wrap), \`ui/UiImage\` (texture or atlas region, \`slice\` for
+  nine-slice, \`fit\`). A \`*.theme.json\` names styles; nodes pick one with \`UiNode.style\`, and
+  \`"button:hovered"\` (on, focused, hovered, pressed, disabled) overrides a state. Fields a node sets
+  win over its theme. Saving the theme restyles the running game.
+- Text needs a font: \`UiText.font\`, the theme's \`font\`, or the \`ui/UiDefaults\` resource.
+- Widgets: \`ui/UiButton\`, \`ui/UiToggle\` (\`on\`), \`ui/UiSlider\` (\`value\`, \`min\`, \`max\`, \`step\`),
+  \`ui/UiTextInput\` (\`value\`, shown through its UiText). Systems read \`ui/UiClick\` and
+  \`ui/UiChanged\` events. A click on UI never reaches gameplay actions or world picking.
+- Bind text from a system: \`world.set(label, UiText, { text: \\\`Fuel \\\${pct}%\\\` })\`. Setting the
+  same text again costs nothing.
+- Markers over planets: a node with \`ui/UiAnchor\` (\`target\` entity path, \`clamp\`, \`hideBehind\`,
+  \`scaleDistance\`) and an optional \`ui/UiAnchorArrow\` child that points at an off-screen target.
+- Keyboard and gamepad: Tab moves focus; arrows and the D-pad move it; Enter, Space, or south
+  presses. Focus a menu's first button with \`ui_focus\` or \`focusUi(world, entity)\`.
+
+Check it as data, not pixels: \`ui_describe\` gives each node's rect, text, and state, and
+\`ui_click\` presses a button by path. In gameplay tests:
+
+\`\`\`ts
+await game.ui.click('hud/scan')
+await game.step(1)
+expect(await game.ui.node('fuel/label')).toMatchObject({ text: 'Fuel 100%', visible: true })
+\`\`\`
+
+Turn on the \`ui-layout\` overlay (\`debug_overlays\`) to see node rects, padding, and margins.
+`,
+  "save-and-settings.md": `# Save the game, and remember settings
+
+Saves are on in every project (no plugin to add). A save holds only what changed: per loaded
+scene, the fields that differ from the scene file and the entities despawned; entities spawned at
+runtime (prefab instances as the prefab plus overrides); resources defined with \`persist\`; named
+RNG streams; and time. Loading reloads each scene from its current file, so scene edits made after
+a save show up, and the player's changes stay.
+
+\`\`\`ts
+import { loadGame, saveGame } from '@aethervtt/shard-save'
+
+await saveGame(world, 'slot1', { meta: { label: 'Crash site' } })
+await loadGame(world, 'slot1') // between frames: from a UI click handler, ready(), or a tool
+\`\`\`
+
+- What's saved: components that serialize, unless defined with \`save: false\`. Tag an entity
+  \`save/NoSave\` to leave it out (and keep it as it is through a load).
+- Resources: \`project.resource('Inventory', { schema, persist: true, init })\`, where \`schema\` is a
+  \`defineSchema\` of its fields. Only resources with \`persist\` go in saves.
+- Loot that matches after a load: draw from \`world.resource(GlobalRng).stream('<project>/loot')\`
+  (a named stream); saves record every stream's state.
+- A component whose fields change gets \`version\` and \`migrate\`; old saves migrate on load.
+  Migrations see only the saved fields, so handle missing ones.
+- Saves go to platform storage: \`.shard/user/saves/<slot>.json\` for \`shard serve\` and
+  \`shard mcp\` (tests and \`shard run\` keep them in memory), IndexedDB in the browser.
+
+Test fixtures: \`save_game\`, then \`save.read\` gives the JSON (schema
+\`.shard/schemas/save.schema.json\`). Edit a value and load it with \`load_game { json }\`:
+
+\`\`\`ts
+const save = await game.saves.read()
+save.scenes['scenes/main.scene.json'].changed.ship = { '<project>/Ship': { fuel: 10 } }
+await game.saves.load(save)
+\`\`\`
+
+\`load_game\` returns warnings (\`save/stale-entity\`) for saved changes whose entity is no longer in
+the scene file.
+
+## Settings
+
+\`\`\`ts
+export const Settings = project.settings({
+  invertY: t.bool(),
+  difficulty: t.enum(['normal', 'easy', 'hard']),
+})
+\`\`\`
+
+Settings load before Startup: project defaults from \`settings/*.json\`
+(\`{ "<project>/Settings": { "difficulty": "easy" } }\`), then the player's \`settings.json\`. Read them
+like any resource; plain writes persist within half a second. \`setSettings(world, Settings, {...})\`
+validates and applies at once. \`engine/Settings\` is built in: \`volumes\` (bus \u2192 volume), \`quality\`
+(shadow map sizes), \`locale\`, and \`bindings\`, which \`rebindAction(world, '<map>.<action>',
+['Key:KeyJ'])\` fills in. Agents use \`settings.get\` and \`settings.set\`.
+`,
+  "localize.md": `# Localize text
+
+String tables are \`locales/<locale>.strings.json\` (schema \`.shard/schemas/strings.schema.json\`),
+one per locale, named by BCP 47 tag:
+
+\`\`\`json
+{ "hud.fuel": "Fuel: {amount}%", "items.count": { "one": "{n} item", "other": "{n} items" } }
+\`\`\`
+
+- Give text a key instead of (or besides) its text: \`"ui/UiText": { "key": "hud.fuel", "params":
+  { "amount": 100 } }\`. \`text/Text\` and \`text/ScreenText\` take \`key\` and \`params\` too. The
+  translated string shows, and follows locale switches on the next frame. \`text\` shows until the
+  key resolves.
+- Update a parameter from a system: \`world.set(label, UiText, { params: { amount: pct } })\`.
+- Code: \`tr(world, 'items.count', { n: 3 })\`. Plural forms (zero, one, two, few, many, other) are
+  picked by \`n\` (or \`count\`) with \`Intl.PluralRules\`; numbers format with \`Intl.NumberFormat\`.
+- Switch: \`setLocale(world, 'pt-BR')\`, or \`locale.set\` from a tool. \`pt-BR\` falls back to \`pt\`,
+  then \`text/Locale\`'s \`fallback\` (\`en\`). The choice persists in \`engine/Settings\`.
+
+Check it: \`shard validate\` reports keys a locale lacks, \`{params}\` that differ between locales,
+and keys scenes and prefabs use that no table defines. At runtime, \`locale.missing\` lists what
+didn't resolve, and \`ui_describe\` shows each node's \`key\` and translated \`text\`.
+`,
+  "make-it-navigate.md": `# Make it navigate
+
+Add \`"nav"\` to \`plugins\` in \`shard.json\` (\`"nav/grid"\` for grid-only 2D games: no WASM).
+
+**3D: a navmesh.** Tag level geometry with \`nav/NavSource\`: its \`physics/Collider\` (or, without one,
+its \`render/Mesh3d\`) and those of children bake. One \`nav/NavMesh\` entity holds the settings:
+
+\`\`\`json
+{ "name": "navmesh", "components": { "nav/NavMesh": { "agentRadius": 0.4, "agentHeight": 1.8,
+    "maxClimb": 0.3, "maxSlope": 45 } } },
+{ "name": "ground", "components": { "core/Transform": {},
+    "physics/Collider": { "shape": "cuboid", "halfExtents": [20, 0.5, 20] }, "nav/NavSource": {} } },
+{ "name": "swamp", "components": { "core/Transform": { "translation": [6, 0, 0] },
+    "physics/Collider": { "shape": "cuboid", "halfExtents": [3, 0.5, 3] },
+    "nav/NavSource": { "area": 1 } } }
+\`\`\`
+
+- Area costs are the \`nav/Areas\` resource: \`"resources": { "nav/Areas": { "1": 4 } }\` makes area 1
+  four times as costly (0 excludes it). Slopes steeper than \`maxSlope\` and gaps narrower than the
+  agent don't bake.
+- Jumps and ladders: \`nav/OffMeshLink\` on an entity at one end, \`to\` the entity at the other.
+- Bake: \`shard bake nav\` (or the \`nav_bake\` tool) writes the tiles to \`.shard/cache/nav\`; loading
+  then skips Recast. Moving a source at runtime rebuilds only the tiles it touches.
+
+**2D: a grid.** A \`nav/NavGrid\` with \`source: "tilemap"\` on a \`sprite/Tilemap\` entity makes a cell
+per tile, blocked where the \`layer\` has a tile (or only \`blockingTiles\`). \`source: "colliders"\`
+rasterizes fixed 2D colliders; \`source: "data"\` reads a \`*.navgrid.json\`. \`diagonal\`:
+\`no-corners\`, \`never\`, or \`always\`. Editing tiles with \`setTile\` updates the grid.
+
+**Agents.** \`nav/NavAgent\` walks to \`destination\` or follows \`target\` (an entity path), repathing when
+it moves. \`drive: "character"\` writes \`physics/CharacterIntent\` (slopes, steps, collisions), \`"velocity"\`
+the body's \`physics/Velocity\`, \`"transform"\` moves it directly. \`nav/NavAgentState\` has \`status\`
+(idle, moving, arrived, unreachable) and \`remaining\`; systems read \`nav/NavArrived\` and
+\`nav/NavUnreachable\` events. From code: \`findPath(world, from, to, { out })\`, \`nearestPoint\`,
+\`navRaycast\` from \`@aethervtt/shard-nav\`.
+
+Check it as data: \`nav_path\` says whether two points connect, \`nav_describe\` lists tiles, skipped
+sources, and each agent's route. In gameplay tests:
+
+\`\`\`ts
+expect((await game.nav.path([0, 0, 10], [6, 3, -12])).status).toBe('complete')
+await game.step(600)
+expect(await game.nav.agent('enemy')).toMatchObject({ status: 'arrived' })
+\`\`\`
+
+Turn on the \`navmesh\` overlay (\`debug_overlays\`) to see polygons by area, links, and paths.
+`,
+  "make-a-noise-graph.md": `# Make a noise graph
+
+Terrain heights, biome masks, rock displacement, and cloud textures all start as a noise graph:
+\`assets/noise/<name>.noise.json\`, validated against \`.shard/schemas/noise.schema.json\` (errors point
+into the file). One file gives the CPU (gameplay, headless tests) and the GPU (materials, compute)
+the same function.
+
+\`\`\`json
+{ "output": "height",
+  "nodes": {
+    "continents": { "fbm": { "source": "simplex", "octaves": 5, "frequency": 0.8, "seed": 1 } },
+    "mountains":  { "ridged": { "source": "simplex", "octaves": 6, "frequency": 3.2, "seed": 2 } },
+    "mask":       { "remap": { "input": "continents", "from": [0.1, 0.4], "to": [0, 1], "clamp": true } },
+    "warped":     { "warp": { "input": "mountains", "by": "continents", "amount": 0.15 } },
+    "height":     { "add": ["continents", { "multiply": ["warped", "mask"] }] } } }
+\`\`\`
+
+- An input is a node name, an inline node, or a number. Sources (value, perlin, simplex, cellular)
+  and fractals (fbm, ridged, billow) take \`seed\` and \`frequency\` (features per unit). Operators:
+  add, multiply, min, max, lerp, select, remap, clamp, curve, terrace, abs, power, constant; domain:
+  warp, scale, translate. The schema lists every parameter with its range.
+- Layer, don't hand-tune one node: a low-frequency fbm for continents, ridged for mountains, a
+  \`remap\` of the continents (clamped to [0, 1]) as a mask so mountains only rise on land, and a
+  small \`warp\` so ridges bend. Change one layer's \`seed\` to reroll only that layer.
+- Frequencies are per unit of the domain. For a planet of radius R, continents are around 1/R to 4/R.
+  Set \`"extent"\` to the radius and the importer rejects octaves too fine to address that far out.
+- Check it numerically, not by eye: MCP \`noise_stats\` with \`{ "graph": "assets/noise/planet.noise.json",
+  "domain": "sphere", "thresholds": [0] }\` says what fraction of the surface is below 0 (under water).
+  \`sample_noise\` gives exact values at points; pass \`"graph"\` as JSON to try an edit before saving.
+- Look at it: \`preview_noise\` (or \`preview_asset\` with \`options\`) renders it in grayscale, on a plane or a
+  sphere; \`"node": "mask"\` shows one intermediate node on its own.
+- In code: \`sampleNoise\` (near the origin), \`sampleOffset\` (any distance: an f64 origin plus small
+  offsets), \`sampleSpherePatch\` / \`sampleGrid2d\`, and \`...Async\` versions on the worker pool.
+- In a material: \`project.material('Rock', { shader: 'project::rock', noise: { detail:
+  'assets/noise/rock.noise.json' } })\` makes \`noise_detail(p: vec3f, seed: u32) -> f32\` available
+  to \`import material::rock::noise_detail;\`. Saving the graph re-renders the material.
+`,
+  "make-a-generator.md": `# Make a generator
+
+Don't place 10 000 rocks: write the rule for one rock and let seeds make the rest. A generator is a
+pure function \`(seed, params) \u2192 output\` (a mesh, a texture, a data value, or entities), cached by the
+hash of its inputs, so the same seed gives the same bytes on every host.
+
+1. Define it in \`scripts/\` (any module the entry imports):
+
+\`\`\`ts
+export const Rock = project.generator('Rock', {
+  params: {
+    radius: t.f32({ default: 1, min: 0.05, unit: 'm' }),
+    roughness: t.f32({ default: 0.3, min: 0, max: 1 }),
+    detail: t.u8({ default: 3, min: 0, max: 6 }),
+    shape: t.handle('NoiseGraph', { description: 'Displacement noise.' }),
+  },
+  output: 'mesh',
+  run(ctx, p) {
+    const mesh = ctx.mesh.icosphere(p.detail)
+    const shape = ctx.load<NoiseGraph>(p.shape) // only handles in params; editing it regenerates
+    const n = new Float32Array(mesh.positions.length / 3)
+    ctx.noise.sample(shape, ctx.seed, mesh.positions, n)
+    for (let i = 0; i < n.length; i++) {
+      const s = p.radius * (1 + p.roughness * n[i]!)
+      for (let k = 0; k < 3; k++) mesh.positions[i * 3 + k]! *= s
+    }
+    return ctx.mesh.finish(mesh, { normals: true, tangents: true, lods: [0.5, 0.2] })
+  },
+})
+\`\`\`
+
+   \`output\` is \`'mesh'\`, \`'texture'\` (\`{ width, height, mips: [rgba8] }\`), \`'data'\` or a data type
+   (\`project.dataAsset\`), or \`'entities'\` (a prefab-shaped entity \`{ name, components, children }\`,
+   or a list of them). A generator can use another: \`await ctx.generate(Planet, params, ctx.childSeed(i))\`
+   returns a ref to put in its output; each is cached on its own.
+2. Keep it pure. Randomness is \`ctx.rng\` (seeded from the seed and the generator's name), per-part
+   seeds \`ctx.childSeed(label)\`. \`Math.random\`, \`Date.now\`, and \`performance.now\` throw
+   \`procgen/nondeterministic\` (and \`shard check\` flags them). Prefer \`+ * sqrt\` over trig for
+   geometry that must match across browsers.
+3. Look at it: MCP \`preview_generator { "generator": "<project>/Rock", "seeds": "1-9", "params": { "roughness": 0.6 } }\`
+   (or \`shard gen scripts:Rock --seeds 1-9 --out sheet.png\`) renders a labelled contact sheet. Change
+   one param, preview again, compare. \`run_generator\` reports vertex and triangle counts, bounds,
+   the cache key, and whether it was a cache hit.
+4. Place it:
+   - a file \`generators/boulder.gen.json\` (schema \`.shard/schemas/gen.schema.json\`):
+     \`{ "generator": "<project>/Rock", "seed": 3, "params": { "radius": 2, "shape": { "path": "assets/noise/rock.noise.json" } } }\`,
+     then \`"mesh": { "path": "generators/boulder.gen.json" }\` in a prefab (\`#LOD1\` for a level of detail)
+   - a ref: \`"mesh": { "path": "procedural:<project>/Rock?seed=3&radius=2" }\`
+   - entities: \`"procgen/GeneratorInstance": { "generator": { "path": "<project>/StarSystem" }, "seed": 7 }\`
+     spawns the fragment as children; patching \`seed\` regenerates and keeps the ids of unchanged paths
+   - at runtime: \`const mesh = await generate(world, Rock, { radius: 2 }, seed)\`
+5. \`shard validate\` checks every \`*.gen.json\` against its generator (\`procgen/bad-params\` with a pointer).
+   Editing the generator's code (or a helper it imports) regenerates its outputs on hot reload; the
+   reload report lists them under \`procgen.regenerated\`.
+`,
+  "make-particles.md": `# Make a particle effect
+
+Add \`"particles"\` to \`plugins\` in \`shard.json\`. An effect is \`assets/fx/<name>.particles.json\`,
+validated against \`.shard/schemas/particle-effect.schema.json\` (errors point into the file):
+
+\`\`\`json
+{ "emitters": [{ "name": "exhaust", "capacity": 20000, "spawn": { "rate": 4000 },
+  "shape": { "type": "cone", "angle": 8, "radius": 0.2 },
+  "init": { "lifetime": [0.3, 0.6], "speed": [18, 25], "size": [0.2, 0.35], "color": "#9ad4ff" },
+  "update": [{ "module": "drag", "coefficient": 1.5 }, { "module": "curl-noise", "strength": 2 },
+    { "module": "color-over-life", "gradient": [[0, "#e9f6ff", 1], [1, "#1a3a7a", 0]] }],
+  "render": { "blend": "additive", "emissive": 4000 } }] }
+\`\`\`
+
+- Values: a number or \`[min, max]\`; curves \`[[t, v], \u2026]\`; gradients \`[[t, color, alpha], \u2026]\`.
+- Modules: gravity, drag, velocity-over-life, curl-noise, attractor, rotation, color-over-life,
+  size-over-life, collision (bounces off what the camera sees).
+- Use it: \`"particles/ParticleSystem": { "effect": { "path": "assets/fx/exhaust.particles.json" } }\`;
+  \`space: "local"\` keeps particles attached. Drive it from gameplay with
+  \`particles/ParticleEmitterOverrides\` (\`spawnScale\`). Saving the file updates the running effect.
+- Look: MCP \`preview_asset\` on the file shows it after one second; \`render.describe\` \u2192
+  \`particles\` gives alive counts.
+`,
+  "large-worlds.md": `# Build a large world: grids and the floating origin
+
+Positions are f32. Past about 10 km from the origin they lose millimetres, and past 1 000 km they
+visibly jitter. For anything bigger (a star system, a planet you can land on), put entities in a
+\`transform/Grid\` and mark the camera \`transform/FloatingOrigin\`. A small level doesn't need any of this.
+
+A position in a grid is \`GridCell.cell \xD7 Grid.cellSize + Transform.translation\`. The cell is an exact
+integer and the translation stays under half a cell, so everything near the camera is precise.
+\`GlobalTransform\` is relative to the origin's cell, so it stays small too.
+
+\`\`\`json
+{ "name": "system", "components": { "transform/Grid": { "cellSize": 2000 } }, "children": [
+  { "name": "planet", "components": {
+      "transform/Grid": { "cellSize": 2000 },
+      "transform/GridCell": { "cell": [75000000, 0, 0] },
+      "core/Transform": { "rotationEuler": [0, 20, 0] } } },
+  { "name": "ship", "components": {
+      "transform/GridCell": { "cell": [74996000, 0, 0] },
+      "core/Transform": { "translation": [120, 0, -40] } },
+    "children": [ { "name": "camera", "components": {
+      "render/Camera3d": {}, "transform/FloatingOrigin": {} } } ] } ] }
+\`\`\`
+
+| Grid | Suggested cell | Reach (\xB12\xB3\xB9 cells) | f32 offset precision |
+|---|---|---|---|
+| Galaxy | 10\xB9\xB2 m | 2\xD710\xB2\xB9 m | ~60 km, fine for stars |
+| Star system | 2 000 m | 4\xD710\xB9\xB2 m (~30 AU) | ~0.1 mm |
+| Planet | 2 000 m | far beyond any planet | ~0.1 mm |
+
+- Only direct children of a grid carry \`GridCell\`. Deeper descendants use their parent's transform as
+  usual. A nested grid (a planet) is a \`Grid\` with a \`GridCell\` in its parent grid; spin it with its
+  own \`Transform\` rotation and everything on its surface turns with it.
+- Moving things: write the translation as usual. \`transform/recenter\` moves an entity into the next
+  cell once it goes \`cellSize / 2 + hysteresis\` past the centre. Don't write a far position into
+  \`translation\`: \`shard validate\` reports \`transform/translation-outside-cell\`.
+- One \`FloatingOrigin\` per world (\`transform/multiple-origins\`), usually on the camera. When it
+  changes cells, \`transform/OriginShift\` fires with the offset: code that caches \`GlobalTransform\`
+  positions across frames adds \`offset\` to them.
+- From tools: \`patch_entity\` with \`{ "position64": [3.8e8, 0, 0], "grid": "system" }\` places an entity
+  exactly and splits the cell for you. \`get_entity\` returns \`worldPosition64\` (relative to the origin
+  cell), and \`app.describe\` lists the grids and where the origin is.
+- In code (cold paths, f64): \`worldPosition64(world, e, out, frame?)\`, \`distance64(world, a, b)\`,
+  \`placeInGrid(world, e, grid, position)\`, and \`reparentToGrid(world, ship, planetGrid)\` to move a
+  ship into a rotating planet grid without a jump.
+- Physics runs in the origin's frame, so bodies near the camera are precise; saves store cells, so a
+  save 10\xB9\xB2 m out loads to the millimetre.
+`,
+  "make-a-planet.md": `# Make a planet you can land on
+
+A planet is an entity with \`terrain/Planet\` (it brings \`transform/Grid\`) and the \`terrain\` plugin in
+\`shard.json\` (with \`render/forward\` to draw it and \`physics3d\` to stand on it). Heights come from a
+noise graph (make-a-noise-graph.md); chunks are generated on the GPU as the camera moves, from six at
+orbit down to 0.4 m vertex spacing on the ground. Put the camera in the planet's grid with
+\`transform/FloatingOrigin\` (large-worlds.md).
+
+\`\`\`json
+{ "name": "planet", "components": {
+    "transform/Grid": { "cellSize": 2000 },
+    "terrain/Planet": { "radius": 600000, "heightScale": 3000, "seed": 7,
+      "height": { "path": "assets/noise/planet.noise.json" },
+      "climate": { "path": "assets/noise/climate.noise.json" },
+      "biomes": { "path": "assets/biomes/planet.biomes.json" }, "ocean": true, "seaLevel": 0 },
+    "physics/GravitySource": { "strength": 9.81, "radius": 600000 } } }
+\`\`\`
+
+- Height: the graph's output (about \u22121 to 1) \xD7 \`heightScale\` metres above \`radius\`. The graph is
+  sampled at points on the sphere in metres, so frequency 1e-5 is 100 km features. Keep \`radius\` under
+  50 000 km (\`terrain/radius-too-large\`).
+- Climate: a graph with \`temperature\` and \`moisture\` nodes (\u22121 to 1). Latitude and altitude cool it
+  (\`latitudeBias\`, \`snowLine\` in the BiomeSet).
+- Biomes: \`*.biome.json\` files (ranges of temperature, moisture, height, slope; a tint; up to four
+  texture layers by slope) listed in a \`*.biomes.json\` with \`albedo\`, \`normal\`, and \`orm\`
+  \`*.texarray.json\` texture arrays (\`{ "layers": ["grass.png", "rock.png"], "size": 1024 }\`).
+- Standing on it: characters, dynamic bodies, and \`terrain/TerrainAnchor\` entities get collider chunks
+  within \`colliderRadius\`, built from the same CPU noise as \`planetHeightAt(world, planet, dir)\`, and
+  those chunks render their own vertices. Use \`CharacterController\` with \`up: "gravity"\`.
+- Walking agents: add \`terrain/PlanetNav\` to the planet; a navmesh follows the \`NavAgent\`s.
+- Check it: MCP \`terrain_map\` (\`{ "mode": "biomes" }\`) shows continents, sea, and poles in one image;
+  \`sample_terrain\` gives height, water depth, slope, and biome at \`[lat, lon]\` points;
+  \`describe_terrain\` lists chunks per depth, generation, and colliders. Overlays \`terrain-lod\`,
+  \`terrain-biomes\`, and \`terrain-colliders\` show them in a screenshot.
+- Edit the height graph while \`shard dev\` runs: visible chunks regenerate together, colliders too.
+  \`terrain/Budget\` caps chunks per frame and GPU time.
+- Frame time: \`vertexPixels\` (4) stops chunks splitting once vertices are that many pixels apart
+  (normal tiles keep the finer relief in the shading), and \`terrain/Budget.triangles\` (2M) coarsens
+  a planet a little at a time when it draws more, so frame time holds at any resolution.
+  \`describe_terrain\` shows \`detail.lodBias\` above 1 while it's coarsening.
+- Give it air: \`"render/Atmosphere": {}\` on the planet entity takes the planet's radius, draws
+  the sky from the ground to orbit, and hazes distant terrain (tune-an-atmosphere.md).
+`,
+  "tune-an-atmosphere.md": `# Tune an alien sky
+
+\`render/Atmosphere\` on a planet entity (the \`terrain/Planet\`, or any entity: it's centered on
+its origin) gives it a sky you can see from the surface, from a ship, and from orbit as a glowing
+limb. It also hazes distant terrain and dims and reddens the sun near the horizon, for lighting too.
+\`bottomRadius: 0\` takes the Planet's radius. Units are physical: metres and 1/m.
+
+\`\`\`json
+"render/Atmosphere": { "thickness": 60000, "rayleighScattering": [5.8e-6, 13.6e-6, 33.1e-6] }
+\`\`\`
+
+Presets (\`AtmospherePresets\` in code; copy the values into a scene): \`earth\` (the defaults),
+\`mars\`, \`thin\`, \`thick-haze\`, \`alien-violet\`, \`gas-giant\`.
+
+Which knob does what:
+
+- **Sky color and sunset color: \`rayleighScattering\`.** The sky takes the color that scatters most;
+  sunsets get what's left after the long path. Blue above red gives a blue sky with orange sunsets.
+  Reverse it for a red sky with blue sunsets; raise red and blue for violet. Scale all three
+  together to thicken or thin the air.
+- **Haze and the glow around the sun: \`mieScattering\`** (4e-6 very clear, 1e-4 hazy) with
+  \`mieScale\` (how high the haze reaches) and \`mieG\` (how tight the halo is). \`mieAbsorption\` makes
+  the haze dirtier and darker. \`mieGOffset\` gives different colors different halos: Mars' blue
+  sunset is blue scattered more forward, \`[-0.15, 0, 0.2]\`.
+- **Twilight and tinted air: \`absorption\`**, a layer at \`absorptionCenter\` \`absorptionWidth\` wide.
+  Earth's ozone keeps twilight blue; at center 0 and a wide layer it's dust (Mars' butterscotch) or
+  methane (Neptune's blue: absorb red).
+- **How far you see: all of the above.** Distant terrain turns the sky's color; 20 km on Earth is
+  noticeably blue, a few km in \`thick-haze\`.
+- **Ground below the horizon:** \`groundAlbedo\`, where no terrain is drawn (from high up, or before
+  chunks load).
+- **Gas giants:** \`bottomRadius\` is the cloud top and \`deckDepth\` the haze below it that thickens to
+  opaque cloud as a ship dives.
+
+Check it without screenshots: MCP \`sample_atmosphere\` (\`{ "direction": [0, 1, 0] }\`) gives sky
+radiance and transmittance from the camera; with \`position\` 40 km up the sky should be near black.
+\`render.describe\`'s \`atmosphere\` section lists each camera's primary atmosphere, the sunlight
+reaching the camera (\`illuminanceAtCamera\`), and GPU time. In code, \`sunTransmittanceAt(world,
+planet, position)\` is how much sunlight gets through, for gameplay (solar panels, heat).
+
+- The sun's \`DirectionalLight.illuminance\` is above the air (direct-sun 100 000). Its
+  \`angularDiameter\` (0.53\xB0) sizes the disk; the two brightest lights both draw one.
+- \`render/AtmosphereSettings\` on a camera: \`aerialPerspective: false\` for only the sky; the froxel
+  range \`maxDistance\` (32 km) beyond which haze is marched per pixel.
+- \`render/Fog\` is for flat scenes: inside an atmosphere it's ignored (\`render/fog-with-atmosphere\`)
+  unless \`mode: "add"\`, for ground fog on top.
+- \`render/ProceduralSky\` is an Earth atmosphere pinned 10 m under the camera: fine for a level, but
+  you can't fly out of it.
+`,
+  "inspect-a-scene.md": `# Find what's wrong in a scene
+
+When a screenshot looks wrong, connect the pixels to entities:
+
+1. \`screenshot\` with \`"overlays": ["bounds", "labels"]\`: every mesh gets its outline and its scene
+   path. Add \`"filter": "ship/"\` to label one subtree. Other overlays: lights, cameras, cascades,
+   normals, axes.
+2. \`pick\` a pixel that looks wrong (same coordinates as the screenshot): its path, position, and
+   normal. Or \`raycast\` from a point, e.g. straight down to find the ground.
+3. \`get_entity\` on that path, \`patch_entity\` the fix, and screenshot again with the same overlays.
+
+In your own systems, draw with gizmos (they last one frame, or \`duration\` seconds):
+
+\`\`\`ts
+const g = world.resource(Gizmos)
+g.line(from, to, [1, 0.2, 0.2, 1])
+g.arrow(position, target, [1, 1, 0, 1], { width: 2 })
+g.sphere(center, radius, [0, 1, 1, 1], { depthTest: false })
+g.label(position, 'target', [1, 1, 1, 1])
+\`\`\`
+
+\`list_gizmos\` shows what was drawn as data. \`pick(world, camera, x, y)\` and
+\`raycast(world, origin, direction)\` from \`@aethervtt/shard-render\` do the same in code.
+`,
+  "debug-with-screenshots.md": `# Look at the game
+
+- \`shard screenshot <scene> --out shot.png --frames 60\` renders headless (no window needed).
+- With the MCP server: \`screenshot\` returns the image; \`step\` advances frames; \`press\`/\`hold\`
+  drive input; \`query_entities\` / \`get_entity\` read state; \`recent_errors\` shows what failed.
+`
+};
+function agentsBlock(manifest) {
+  return `${GENERATED_START}
+# ${manifest.name}
+
+A [Shard](https://github.com/) project. The engine is data-first: scenes are JSON validated against
+component schemas, game code is ECS (components, systems) in \`scripts/\`.
+
+## Commands
+
+\`\`\`sh
+shard validate --json     # manifest, assets, scenes: every error with a path
+shard import --json       # import new and changed asset files
+shard mv <from> <to>      # move an asset and rewrite references to it
+shard run --frames 600    # headless run
+shard screenshot ${manifest.startScene} --out shot.png
+shard test --json         # gameplay tests in tests/
+shard check --json        # type-check scripts: file, line, column
+shard gen <generator> --seeds 1-9 --out sheet.png   # preview a generator's outputs
+shard dev                 # play it in a browser; saves hot reload in place
+shard docs                # regenerate this block, .agents/, and .shard/schemas/
+shard mcp                 # MCP server for this project (see .mcp.json)
+\`\`\`
+
+## Where things are
+
+- \`shard.json\`: manifest (start scene: \`${manifest.startScene}\`, seed ${manifest.seed}, plugins: ${manifest.plugins.join(", ")})
+- \`scripts/main.ts\`: the project plugin; project types are named \`${manifest.name}/<Name>\`
+- \`scenes/\`: scene files; \`tests/\`: gameplay tests; \`shaders/\`: \`project::\` shader modules
+- \`generators/\`: \`*.gen.json\` generator outputs; \`.agents/generators.md\`: every generator and its params
+- \`${manifest.assetRoots.join("/`, `")}/\`: asset files, each with a \`.meta\` (guid, import settings)
+- \`.agents/components.md\`: every component and field; \`.agents/assets.md\`: importers and
+  project data types;
+  \`.agents/errors.md\`: error codes
+- \`.agents/skills/\`: recipes for common tasks
+
+Engine plugins available: ${Object.entries(BUILTIN_PLUGINS).map(([n, d]) => `\`${n}\` (${d})`).join("; ")}.
+${GENERATED_END}`;
+}
+function mergeAgentsMd(existing, manifest) {
+  const block = agentsBlock(manifest);
+  if (!existing)
+    return `${block}
+
+## Notes
+
+Project-specific notes for agents go here; \`shard docs\` keeps them.
+`;
+  const start = existing.indexOf(GENERATED_START);
+  const end = existing.indexOf(GENERATED_END);
+  if (start === -1 || end === -1) return `${block}
+
+${existing}`;
+  return `${existing.slice(0, start)}${block}${existing.slice(end + GENERATED_END.length)}`;
+}
+function generateDocs(manifest, errors) {
+  const files = {
+    ".agents/components.md": renderComponentCatalog(),
+    ".agents/errors.md": renderErrorCatalog(errors),
+    ".agents/generators.md": renderGeneratorCatalog(),
+    ".agents/assets.md": renderAssetCatalog(
+      allImporters(),
+      allDataTypes().filter((d) => d.name.startsWith(`${manifest.name}/`))
+    ),
+    ".shard/schemas/shard.schema.json": `${JSON.stringify(manifestJsonSchema(), null, 2)}
+`,
+    ".shard/schemas/scene.schema.json": `${JSON.stringify(sceneJsonSchema(), null, 2)}
+`,
+    ".shard/schemas/prefab.schema.json": `${JSON.stringify(prefabJsonSchema(), null, 2)}
+`,
+    ".shard/schemas/save.schema.json": `${JSON.stringify(saveJsonSchema(), null, 2)}
+`
+  };
+  for (const [name, content] of Object.entries(SKILLS))
+    files[`.agents/skills/${name}`] = content.replaceAll("<project>", manifest.name);
+  for (const [file, schema] of allAssetSchemas()) {
+    files[`.shard/schemas/${file}`] = `${JSON.stringify(schema(), null, 2)}
+`;
+  }
+  for (const def of allComponents()) {
+    if (def.name.startsWith("test/")) continue;
+    files[`.shard/schemas/components/${def.name.replace("/", ".")}.json`] = `${JSON.stringify(def.jsonSchema(), null, 2)}
+`;
+  }
+  return files;
+}
+export {
+  GENERATED_END,
+  GENERATED_START,
+  generateDocs,
+  mergeAgentsMd,
+  renderAssetCatalog,
+  renderComponentCatalog,
+  renderErrorCatalog,
+  renderGeneratorCatalog
+};