# Agent Rules

These files are the canonical package-owned rules for `mbt-3d`.

## Rule Map

- `.ai/agent-rules/README.md` - normative usage rules for exported components and hooks.
- `.ai/agent-rules/maintenance.md` - required rule for keeping package docs in sync with public changes.

## Usage Rules

- Prefer higher-level exported components before using lower-level hooks directly.
- Use `Scene3D` as the normal scene container for package consumers.
- Use `Model` for static models, `AnimatedModel` for animation-capable models, and `MorphableModel` when morph targets are required.
- Use `BoneAttachment` only as a child of `AnimatedModel`.
- Pass ready-to-use asset URLs into package components; asset downloading, path resolution, and cache orchestration are consumer concerns.
- Prefer stable props and memoized configuration objects when scenes become configuration-heavy.
- Use advanced hooks only when the consumer truly needs lower-level control.
- Use `pnpm` as the package manager for this repo and keep a single lockfile.

## Boundaries

- This package owns scene and model behavior.
- Consumer apps own where assets come from, how remote URLs are resolved, and when app-specific preload flows run.
- Do not put app-owned IPC, CDN, asset-server, or resolver workflow rules into package docs.

## Scene Guidance

- `Scene3D` supports mixed lighting through `lights` and `environment` together.
- `Scene3D` preserves camera state between model changes inside the same mounted scene.
- Keep `renderer`, `lights`, and `controls` props stable when a consumer already memoizes or stores them outside render.
- Prefer explicit camera and control configuration in examples instead of relying on implicit defaults when teaching usage.

## Model Guidance

- Resolve model and texture URLs before rendering a component when the asset source is external or dynamic.
- Use `Model.preload()` or `preloadModel()` only when the consumer already has a real preload step.
- Use `preloadTextures()` only when the consumer already has a preload stage and texture URLs are known before render.
- For texture-driven materials, resolve model and texture data together before render to avoid mixed old/new asset states.

## Animation Guidance

- If `AnimatedModel.defaultAnimation` is omitted, the library falls back to the first available animation.
- `playAnimation(name)` uses name matching that tolerates partial or case-insensitive matches when possible.
- Prefer explicit animation names in consumer code even though partial matching exists.

## Bone Guidance

- Match bone names to the actual model data; do not guess names.
- Common families include custom names like `hand_r`, Mixamo-style names like `RightHand`, and Rigify-style names like `DEF-handR`.
