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

# Design principles

> The deliberate constraints behind clickwheel.

A few constraints shape everything clickwheel does. They're intentional.

## Single-tenant

clickwheel runs on **your** machine and works with **your** library and iPod in
place. There's no cloud service holding your data. The catalog is built from
your local files; the iPod is a USB-mounted volume the tool writes directly.

This is why "multi-user clickwheel" isn't a thing a hosted service could
provide: each person's library and iPod are physically bound to their own Mac.
Even the [remote/mobile MCP access](/guides/remote-mcp) keeps the Mac as the
source of truth and simply exposes the existing local server through a tunnel.

## Read-only library

Indexing (`scan`) only reads tags and writes to SQLite. The one command that
touches your files is [`fix`](/guides/fix-metadata), and it edits tags, art, and
genres **in place**, never moving or renaming them (other tools like Plex read
the same library and rely on stable paths).

## FLAC is skipped

Stock classic-iPod firmware doesn't play FLAC, so clickwheel skips FLAC when
loading the device rather than silently transcoding. Your library keeps its
FLACs; they just don't go on the iPod.

## No auto-scan over MCP

The MCP server never auto-scans: chat tool calls always serve cached catalog
data, so a conversation never blocks on a multi-minute library walk. You refresh
by running `clickwheel scan` when you've added music. (The interactive CLI
commands *do* auto-scan, via a cheap probe plus a fallback timer.)