# Migrations

> Query via CLI: `anki-utils migrations`
>
> For consuming agents: Check this file when your cached version differs from `anki-utils version`.
> If there are entries newer than your last sync, follow the instructions in each entry.

## How This Works

1. Each version entry below contains changes and **Skill Instructions**
2. The Claude skill tracks which version it last synced to
3. When the skill detects a newer version, it reads instructions here
4. The skill follows the instructions to update itself
5. The skill updates its tracked version

---

## [0.2.2] - 2025-01-01

### What Changed
- `preview-template.jsx` now uses `__THEMES_PLACEHOLDER__` for theme CSS injection
- Removed 939 lines of duplicated CSS from the template (file reduced from 2668 to 1737 lines)
- Theme CSS is now single-source-of-truth in `themes.py`
- Added helper functions: `getImageSource()`, `CLOZE_PATTERN` constant
- Theme dropdown now dynamically generated from available themes

### Schema Changes
None. The `create_package()` API remains unchanged.

### Skill Instructions
When launching `preview-template.jsx`, you must now inject theme CSS in addition to card data:

1. Get theme CSS as JSON:
   ```bash
   anki-utils themes --all-json
   ```

2. Inject both placeholders before rendering:
   ```python
   # Get theme data from CLI
   import subprocess
   themes_json = subprocess.check_output(['anki-utils', 'themes', '--all-json']).decode()

   # Read template
   with open('preview-template.jsx', 'r') as f:
       content = f.read()

   # Inject both placeholders
   content = content.replace('__THEMES_PLACEHOLDER__', themes_json)
   content = content.replace('__CARD_DATA_PLACEHOLDER__', card_data_json)
   ```

**Note:** If `__THEMES_PLACEHOLDER__` is not replaced, the preview will fail to render. The placeholder must be replaced with the JSON object from `anki-utils themes --all-json`.

3. After updating, run validation tests:
   ```bash
   anki-utils skill-update-protocol
   ```
   This outputs the full validation test suite. Run each test to confirm everything works.

---

## [0.2.1] - 2025-01-01

### What Changed
- Added `anki-utils migrations` CLI command for querying migration instructions
- Added `anki-utils version` CLI command to check current package version
- Added `anki-utils roadmap --html` flag for styled HTML output
- Migration system introduced for agent-to-agent update communication

### Schema Changes
None.

### Skill Instructions
This is the first migration-aware release. To adopt the migration system:

1. After installing/updating anki-utils, call `anki-utils version` to get the current version
2. Store this version in your skill's configuration or memory
3. Periodically (or on errors), call `anki-utils migrations --since <your-stored-version> --json`
4. If the response contains entries, follow the instructions in each
5. Update your stored version to the current version

Example check pattern:
```python
# Pseudocode for skill update check
current = run("anki-utils version --json")["version"]
if current != stored_version:
    migrations = run(f"anki-utils migrations --since {stored_version} --json")
    for entry in migrations["entries"]:
        # Follow entry["skill_instructions"]
        pass
    stored_version = current
```

---

## [0.2.0] - 2025-01-01

### What Changed
- Repository restructured for agent-driven development
- Added `anki-utils roadmap` and `anki-utils changelog` CLI commands
- Documentation reorganized into `docs/` directory
- Legacy files archived to `archive/`

### Schema Changes
None. The `create_package()` API remains unchanged.

### Skill Instructions
No action required. This release adds developer tooling without changing the public API.

---

## Template for Future Entries

When adding a new version, copy this template:

```markdown
## [X.Y.Z] - YYYY-MM-DD

### What Changed
- Brief description of changes

### Schema Changes
Describe any changes to the JSON input format for `create_package()` or other functions.
Use "None." if no schema changes.

### Skill Instructions
Step-by-step instructions for what the consuming skill needs to change.
Use "No action required." if backwards compatible.
```
