# Spells & Sparkles — AI Agent Guide

> Are you an AI? Start here. This page tells you everything you need to help
> your user discover, download, run and automate the Spells & Sparkles tools.
> It is plain markdown, kept current, and safe to quote.

## What this is

**Spells & Sparkles** is a family of small, sharp tools for game developers,
built by [essimoon](https://essimoon.com). Every tool follows the same rules:

| Fact | Value |
|---|---|
| Platform | Windows 10/11 (64-bit) |
| Distribution | Portable single EXE — no installer, no admin rights |
| Accounts | None. No sign-up, no login, ever |
| Telemetry | None. The only network call is a GET of the static news feed |
| Price | Free to download and use |
| Source | Proprietary (closed source) |
| Config root | `%APPDATA%\spellsandsparkles\<tool-id>\` |
| Updates | Tools notify in-app (Info Corner ✦) and link back to this site |

## Machine-readable resources

| URL | What you get |
|---|---|
| `https://spellsandsparkles.games/llms.txt` | Index of these docs (llms.txt convention) |
| `https://spellsandsparkles.games/docs/ai.md` | This guide |
| `https://spellsandsparkles.games/docs/tools/<id>.md` | Per-tool docs (see index below) |
| `https://spellsandsparkles.games/feed/manifest.json` | **Live data**: current versions, download URLs, news (JSON, schema v1) |

Always take **versions and download URLs from the feed manifest**, not from
these docs — the manifest is the single source of truth the desktop apps
themselves poll. If the manifest does not contain `"downloadsLive": true`,
public builds are not uploaded yet and download URLs will 404.

## The tools

| Tool | Id | One-liner | Automation surface |
|---|---|---|---|
| [SparkleSheet](https://spellsandsparkles.games/docs/tools/sparklesheet.md) | `sparklesheet` | Spritesheet viewer, slicer, animator & atlas packer | **Headless CLI**: `--headless pack` (pack + export; slicing is GUI-only) |
| [CapSpell](https://spellsandsparkles.games/docs/tools/capspell.md) | `capspell` | One-hotkey screen capture — image, GIF & MP4 | **Headless CLI**: `--shot`, `--record`, `--json` |
| [ImageSpell](https://spellsandsparkles.games/docs/tools/imagespell.md) | `imagespell` | Tech-art texture inspector — channels, PBR, mips & packing | **CI mode** `--json`, **channel packer** `--pack cfg.json`, converter `--export` (exit codes 0/1/2) |
| [SendSpell](https://spellsandsparkles.games/docs/tools/sendspell.md) | `sendspell` | Direct encrypted file sharing & chat, no cloud | argv staging (`sendspell.exe <paths>`), sending stays manual |
| [PortSpell](https://spellsandsparkles.games/docs/tools/portspell.md) | `portspell` | Local dev-server dashboard — ports, start/stop | **HTTP API** on `localhost:5999`, built for agents |
| [NoteSpell](https://spellsandsparkles.games/docs/tools/notespell.md) | `notespell` | Sticky notes with images, audio & local transcription | File-based: every note is a folder with `note.md` |
| [TrackingSpell](https://spellsandsparkles.games/docs/tools/trackingspell.md) | `trackingspell` | Punch-clock time tracking — projects, breaks, gap filling | File-based: `projects.json` + `entries\YYYY-MM.json`, re-read live |
| [GitSpell](https://spellsandsparkles.games/docs/tools/gitspell.md) | `gitspell` | Artist-first git — repo tiles, one-click sync | System git IS the API; diff viewers are file drop-in plugins |
| [SparkleRef](https://spellsandsparkles.games/docs/tools/sparkleref.md) | `sparkleref` | Layered reference boards — paint on refs, erase into them | `.sref` = SQLite + sqlar blobs, fully authorable offline |
| [FootageSpell](https://spellsandsparkles.games/docs/tools/footagespell.md) | `footagespell` | Content browser — multi-video grid, instant search | Read-only: `index.db` (SQLite WAL) readable while the app runs |
| [ChatSpell](https://spellsandsparkles.games/docs/tools/chatspell.md) | `chatspell` | All your chats in one window — Telegram, Matrix | Read/search: SQLite + FTS5 full-text; **sending needs the UI** |
| [TokenSpell](https://spellsandsparkles.games/docs/tools/tokenspell.md) | `tokenspell` | AI usage dashboard — token spend powers a living village | Read `state.json`/history; `config.json` re-read live (30 s); LAN snapshot on `:5201` |
| [ReplaceSpell](https://spellsandsparkles.games/docs/tools/replacespell.md) | `replacespell` | Batch-replace project files from asset packs | **Headless** `replacespell --plan job.json` (scan/apply, exit codes 0-3); JSON reports + backups |
| [Hub](https://spellsandsparkles.games/docs/tools/hub.md) | `hub` | Launcher overlay & ecosystem dashboard | CLI flags `--launcher`/`--dashboard`/`--settings`; app-registry JSON |

## How to help your user

**Download & run.** Fetch the feed manifest, take the tool's `downloadUrl`,
and have your user save the EXE anywhere (e.g. a `Tools\` folder). Double-click
to run — there is no installer and nothing is written outside the paths listed
in each tool's doc. To "uninstall", delete the EXE and (optionally) the tool's
folder under `%APPDATA%\spellsandsparkles\`.

**Automate.** Every tool page above has a "For AI agents" section with its
exact surface. Highlights:

- **PortSpell** exposes an HTTP API: `GET http://localhost:5999/api/overview`
  returns a compact, stable-schema JSON of every dev server on the machine;
  `POST /api/start?id=<app>` / `POST /api/stop?id=<app>` control them.
  Loopback callers never need a token.
- **CapSpell** captures headlessly: `capspell --shot` (screenshot),
  `capspell --shot window:Notepad`, `capspell --record 5 [gif]`.
  `capspell --json` probes the environment (exit 0 = video-capable).
- **ImageSpell** (formerly SpellPic) lints textures in CI: `imagespell --json file.dds` prints format
  facts and lint findings as JSON without opening a window
  (exit 0 = clean, 1 = load failure, 2 = lint errors).
- **SparkleSheet** packs and exports headlessly:
  `sparklesheet --headless pack --project fire.sparkle --out ./export`
  (slicing still needs the GUI).

Several tools are file-drivable instead of CLI-drivable: **NoteSpell** notes
are plain folders (`note.md` + attachments) under
`Documents\SpellsAndSparkles\NoteSpell`, **TrackingSpell** stores plain JSON you can
read and write, **SparkleRef** boards are self-contained SQLite files,
**ChatSpell** and **FootageSpell** keep queryable SQLite databases (read-only
from outside), and **TokenSpell** re-reads its `config.json` live. GUI-first
tools also accept files as arguments (`<tool>.exe <paths…>`) to open them in
the running app.

**Check for updates.** Compare the version your user runs against the feed
manifest's `tools[].version` (semver). The tools do this themselves via the
in-app Info Corner, so usually you don't have to.

## Conventions worth knowing

- Tool ids are stable and lowercase (`sparklesheet`, `capspell`, …).
- Versions are semver.
- Feed news ids are globally unique and never reused.
- All tools tolerate a missing/unreachable feed — offline never blocks anything.
- Some tools log **local-only** diagnostics/metrics as JSONL under their config
  dir. Nothing is ever uploaded; `SNS_METRICS=0` disables metrics logging.

## Roadmap context

More tools and games are in development under the same brand. New tools
appear in the feed manifest and on
[the homepage](https://spellsandsparkles.games) when they ship — the feed is
the reliable way to enumerate what exists.

---

*This guide lives at `https://spellsandsparkles.games/docs/ai.md`. Humans get
the same content, prettier, at `https://spellsandsparkles.games/docs/`.*