# Ally Implementation Guide

## 1. Asset model

Each Ally has one approved canonical revision and one asset per supported state.

Recommended production masters:

- Format: lossless PNG or high-quality WebP
- Canvas: square
- Master: 2048 × 2048 px
- Standard exports: 512, 256, 128, 64, 40, and 32 px
- Color profile: sRGB
- Crop: circular medallion centered inside the square canvas
- Safe area: keep identity-defining details inside the central 86% of the canvas

The current example cards are landscape review artifacts, not production avatar files.

## 2. Naming convention

```text
ally-{ally_id}-r{revision}-{state}-{size}.{format}
```

Examples:

```text
ally-a17f2-r1-open-512.webp
ally-a17f2-r1-engaged-128.webp
ally-a17f2-r1-focused-40.webp
ally-a17f2-r1-dreaming-2048.png
```

Use stable opaque Ally IDs in public asset names. Do not place a Source’s legal name, email, phone number, or other private identifier in filenames or public URLs.

## 3. Suggested data shape

```json
{
  "ally_id": "a17f2",
  "canonical_revision": 1,
  "display_name": "Source-approved display name",
  "current_state": "open",
  "state_origin": "source",
  "assets": {
    "open": "/allies/a17f2/r1/open/",
    "engaged": "/allies/a17f2/r1/engaged/",
    "focused": "/allies/a17f2/r1/focused/",
    "dreaming": "/allies/a17f2/r1/dreaming/"
  },
  "approved_at": "ISO-8601 timestamp"
}
```

Keep private Source records and generation references outside this public presentation object.

Allowed state values:

```text
open | engaged | focused | dreaming
```

Suggested `state_origin` values:

```text
source | product | default
```

An explicit Source selection should override a product-selected state.

## 4. Rendering behavior

- Default to `open` when state is absent, stale, or unsupported.
- Render the appropriate pre-generated asset; do not generate a new portrait during routine UI rendering.
- Keep the same crop and dimensions across all states to prevent layout movement.
- Crossfade between states in 150–250 ms when motion is allowed.
- Do not pulse, bounce, rotate, or continuously animate the avatar.
- Preserve the prior state during brief network interruptions rather than flashing to a placeholder.
- Use a stable monogram or abstract celestial medallion while assets load or when a Source opts out of likeness.

## 5. Status semantics

The avatar state may mirror an explicit mode in the product, but it is not a universal presence protocol.

- `open`: default or explicitly available
- `engaged`: participating in an active Kiduna exchange
- `focused`: inside a clearly initiated work or review mode
- `dreaming`: inside a clearly labeled ideation, reflection, or incubation mode

Do not use these states to expose private activity. Avoid converting arbitrary telemetry into a public state. A product should document which actions can change state and who can see it.

## 6. UI usage

- Profile and member lists: use OPEN unless a meaningful, permitted state is active.
- Conversations: ENGAGED may appear while the Source is participating.
- Studios and workspaces: FOCUSED may appear during an explicit focus session.
- Ideation and incubation surfaces: DREAMING may appear during a named generative mode.
- Audit logs, legal records, permissions, and identity verification: use the canonical OPEN image or a neutral identity token. Do not use an expressive state as evidence of intent.

Labels such as “Focused” belong in accessible UI or status text, not inside the avatar bitmap.

## 7. Quality checks

Before accepting a new Ally revision:

- compare all states side by side at 256 px
- compare all states at 40 px
- confirm face, hair, age, skin tone, and signature adornments are stable
- confirm every cheek sigil matches its state
- confirm both eyes remain visible when practical
- confirm no unapproved symbols or cultural markers were introduced
- confirm the circular rim is clean and centered
- confirm no text, logo, or watermark appears in production assets
- obtain Source approval
- record canonical revision and generation provenance

## 8. Versioning

- State-expression corrections that preserve identity may replace an asset within a draft revision.
- Any approved change to face, hair, age presentation, signature adornments, clothing silhouette, or caricature intensity creates a new canonical revision.
- Keep old revisions available for rollback according to product retention policy.
- Never silently regenerate an Ally in place.
