# Migrating v0.2.1 → v0.2.2

**Purely additive.** Existing callsites keep working — no imports to move, no config fields to rename, no CSS variables to rebind. The three sections below are optional adoptions that let you take advantage of what v0.2.2 shipped.

If you're upgrading from an earlier version, chain via [v0.2.1 migrating](../../v0.2.1/dddk/migrating.md) first — the notes below assume you already run v0.2.1.

## Optional: adopt `dddk.prompts` to centralise LLM prompts

If you currently pass `webAgent.systemPrompt`, `InlineAgentConfig.systemPrompt`, `VoiceConfig.cleanupPrompt`, or `DwellConfig.systemPrompt` to replace the SDK defaults, you can leave those in place — they still win over the registry (as before). But if you want to override PER-LOCALE (English + Japanese + Traditional Chinese versions of the same prompt), the config fields only accept one string; the registry does.

Before (single locale, per-subsystem):

```ts
new DotDotDuck({
  webAgent: { systemPrompt: MY_JAPANESE_NARRATOR },
  llm: ...,
});
```

After (per-locale, single API):

```ts
const dddk = new DotDotDuck({ llm: ... });

dddk.prompts.override('webagent-narrator.system', 'ja', () => MY_JAPANESE_NARRATOR);
dddk.prompts.override('webagent-narrator.system', 'zh-TW', () => MY_TRADITIONAL_CHINESE_NARRATOR);
// English keeps the SDK default.
```

Live locale switch works too — the registry is process-wide and read at message-assembly time, so the next agent turn picks up the current locale's prompt without a re-mount.

Full guide: [prompts.md](./prompts.md).

## Optional: swap `new DotDotDuck({...})` for `autoInstall(...)`

If your existing app already wires every config field explicitly, don't bother — you'll just be moving code around. `autoInstall()` is aimed at:

- **New apps** wanting to see the SDK working before choosing what to configure.
- **Landing pages / marketing sites** where the palette + Dwell + mascot are enough without an LLM.
- **`<script src>` embeds** on static sites where full config is overkill.

Before:

```ts
const dddk = new DotDotDuck({
  llm: myProvider,
  locale: navigator.language.startsWith('zh') ? 'zh-TW' : 'en',
  // ... 20 more fields explicitly ...
});
```

After (skip the boilerplate, override only what matters):

```ts
const dddk = autoInstall({
  llm: myProvider,
  paletteCommands: myCommands,
});
// Locale, duck sprites, and 20 other fields default to sensible values.
```

If you want the OLD behaviour (silent no-op when `llm` is absent, matching raw `new DotDotDuck({})`), set `demoLLM: false`:

```ts
const dddk = autoInstall({ demoLLM: false });
```

Full guide: [auto-install.md](./auto-install.md).

## Optional: drop your duck sprite files

Before v0.2.2 the SDK expected the host to serve mascot sprite PNGs at whatever paths `--dddk-*-url` pointed to (plus a hard-coded `/duck/swim-cycle.png` for the Dwell overlay). v0.2.2 ships **seven** sprites as build-time-bundled assets inside `dist/duck/`, referenced by `tokens.css` defaults — including the new WebAgent `cursor.png` (a duck riding a paper airplane) that replaces the SVG pointer glyph.

Before:

```css
/* your app.css */
:root {
  --dddk-avatar-url: url('/duck/neutral.png');
  --dddk-swim-url: url('/duck/swim-side.png');
  --dddk-hero-url: url('/duck/hero-greet.png');
  --dddk-chill-url: url('/duck/chill-shades.png');
}
```

```
static/duck/
  neutral.png
  swim-side.png
  hero-greet.png
  chill-shades.png
```

After (SDK ships them, remove your copies):

```css
/* your app.css — nothing here for sprites unless you want to swap them */
```

**Sub-path caveat** — if your app is served from a subdirectory like `/tools/`, keep the `:root` overrides pointing at root-absolute paths. See the "Sub-path caveat" section in the [v0.2.2 release notes](./release-notes.md) for why.

## Removed / deprecated

Nothing. Every field, function, and CSS variable that existed in v0.2.1 still works in v0.2.2 unchanged.

## New surface summary

| API | Where |
|---|---|
| `dddk.prompts` | on every `DotDotDuck` instance |
| `PromptRegistry`, `PROMPT_IDS`, `promptRegistry` | `@perhapxin/dddk` root export |
| `autoInstall(opts?)`, `AutoInstallOptions` | `@perhapxin/dddk` root export |
| `dddk.mobile.showHeroGreeting(text, opts?)` | on `dddk.mobile` (existed in v0.2.1 as an experiment, promoted to stable) |
| 8 mascot animation duration tokens | CSS variables — declare on `:root` to override |
| 6 duck sprite URLs | CSS variables — SDK defaults ship; declare to override |