---
name: icoustic
description: >
  Guide for using Icoustic (personal music library on Mac/iPad/iPhone)
  and its local Mac MCP server. Use when the user asks about Spaces,
  libraries, playback, playlists, metadata, MCP setup, or wants help
  searching / auditing / proposing library changes via Icoustic tools.
compatibility: >
  Requires Icoustic on Mac with MCP enabled for tool use; product guidance
  works without MCP.
---

# Icoustic

Icoustic is a **personal music system for files you own** — MP3, FLAC, and M4A/AAC. No streaming catalog. No account required to listen. Mac, iPad, and iPhone form a **Space** so any device can hold a library, play sound, or control another.

## Working style

1. **Prefer Icoustic MCP tools** when connected (Mac, Icoustic open, MCP enabled). Query the live local index instead of guessing about the user’s collection.
2. **Without MCP**, answer from product knowledge in this skill and point users at in-app Settings / docs. Do not invent cloud APIs, accounts, or remote catalog access.
3. **Never invent product features that don’t exist.** Especially: no Icoustic cloud sync, no required Icoustic account to play or share, no synchronized multi-room audio (same song in every room at once). Sharing is local-network Spaces only.
4. **Mutations are review-gated.** Librarian `propose_*` tools stage changes. The user approves in the sidebar **MCP Actions**. Do **not** call `apply_proposal` unless the user explicitly wants AI apply **and** **Allow AI to apply proposals** is on (default off). Prefer telling them to Approve in-app.
5. Be concise. Prefer tool results and concrete next steps over long lectures.

## Route for detail

- Product UI, Spaces, library folders, playback, playlists → read `references/product-map.md`
- Analyst vs Librarian, proposal etiquette, privacy → read `references/mcp-workflows.md`
- Tool names and when to use them → read `references/tool-cheatsheet.md`

## Example asks (good MCP prompts)

- How many tracks / albums are in my library?
- Which tracks are missing year or genre?
- Find likely duplicate albums or tracks (confirm before any remove proposal).
- Audit messy genre labels.
- Build a running mix from 4-star tracks (propose a playlist; user Approves).
- What’s in my Sources? Any iCloud placeholders still needing download?

## Quick constraints

- **Formats:** DRM-free MP3, FLAC, M4A/AAC only.
- **MCP:** Mac only, Full unlock (or Full trial), loopback `127.0.0.1`, Icoustic must stay open.
- **Files as truth:** Tag edits write into files; the local index mirrors them.
- **Duplicates:** Heuristic candidates only (no content hash yet). `propose_duplicate_resolution` removes from the **index**, not the trash — files stay on disk.
- **Artwork via MCP:** ArtworkStore keys only — does not write embedded APIC/covr.