> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ngram.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Design a shell

> Give the same Entity a different model, voice, movement vocabulary, and spatial behavior.

A shell is a directory containing `shell.yaml` and its assets. The file describes presentation. The canonical Entity keeps identity, relationships, and memory.

## Start with an included body

The shipped Rook shell uses included FBX assets. This example uses its existing paths:

```yaml theme={null}
name: Rook
description: A curious spatial collaborator.
model: models/ybot/ybot.fbx
scale: 0.01

animationPack:
  idle: models/ybot/idle.fbx
  talking: models/ybot/talking.fbx
  waving: models/ybot/waving.fbx
  walking: models/ybot/walking.fbx

behaviorPack:
  - look-at-user
  - idle-breathe
  - anchor-to-surface
  - proximity-greet
  - gesture-respond

voice:
  provider: edge
  voice: en-US-GuyNeural

toolSurfaces:
  - floating-card

binding:
  type: ngram_entity
  options: {}
  system: |
    Use spatial actions when they add meaning.
    Keep identity and memory in the running Entity.
```

Paths resolve relative to the shell directory. If you copy only this YAML into an empty folder, copy or provide the referenced model and animation assets too.

## Model and scale

Use a model format supported by the shell loader and check the resulting size in a real preview. The included Rook model uses `scale: 0.01`; that value is asset-specific, not a universal conversion for every avatar.

Inspect feet, floor contact, eye height, and the user's comfortable viewing distance. A model that loads successfully can still be the wrong scale or orientation.

## Animation vocabulary

The agent requests semantic gestures. The shell chooses the corresponding animation. A schema may accept a gesture even when your custom shell lacks an appropriate clip.

Start with idle, talking, waving, and walking. Add expressive gestures after verifying retargeting and transitions on the actual rig. Keep animation filenames and aliases aligned with the shell's animation pack.

## Behavior packs

Behavior packs add continuous presentation such as gaze, breathing, surface anchoring, proximity responses, and gesture reactions. They should support the agent's intent without moving personality into the renderer.

## Credentials and pairing

Keep bridge URLs and credentials in local environment files generated by setup. Do not embed provider keys in `shell.yaml`, model metadata, browser code, or publicly served assets.

The shell's `binding.system` adds spatial guidance. It should not duplicate the Entity's biography or claim capabilities that the current surface cannot provide.

## Asset review

Before sharing a shell, confirm the asset license permits redistribution, retain required notices, and inspect exported files for personal filesystem paths and authoring metadata. Test both the model and its animation pack from a clean checkout.