# Agent Pitch Map

> AI-navigable pitch map for notes, scales, chords, sound, and tab across piano and standard guitar.

This public agent-readable pitch map helps humans and AI agents inspect how a musical pitch maps across piano keys, standard 6-string guitar frets, scale/chord membership, sound playback, and simple tab placement.

## Start Here

- Human UI: https://www.agentpitchmap.com/
- Agent guide: https://www.agentpitchmap.com/agent
- OpenAPI: https://www.agentpitchmap.com/openapi.json
- Capabilities JSON: https://www.agentpitchmap.com/api/capabilities
- Example map query: https://www.agentpitchmap.com/api/map?note=D4&root=C&scale=major&piano=49-key
- Example voicing query: https://www.agentpitchmap.com/api/voicings?root=C&chord=major
- Example composer query: https://www.agentpitchmap.com/api/composer?note=G2&root=C&scale=major
- Example chord-scale query: https://www.agentpitchmap.com/api/chord-scale?root=G&chord=dominant7&contextRoot=C
- Example containing-scales query: https://www.agentpitchmap.com/api/scales/containing?notes=C,E,G,Bb
- Example tab recipe query: https://www.agentpitchmap.com/api/recipes/tab?key=D&scale=naturalMinor&style=beginner-riff

## Agent Instructions

- Prefer `/api/map` for exact music reasoning instead of scraping the visual UI.
- Use query parameters: `note`, `midi`, `root`, `layer`, `scale`, `chord`, and `piano`.
- Treat exact pitch, same note name across octaves, theory membership, and interval function as separate concepts.
- Use `/api/voicings` for playable guitar chord shapes.
- Use `/api/composer` for circle-of-fifths neighbors, common-tone pivots, guide-tone moves, and guitar anchor notes.
- Use `/api/scales`, `/api/scale-map`, `/api/chord-scale`, and `/api/scales/containing` for scale reasoning instead of treating scales as a flat list.
- Use `/api/recipes/tab` when an explanation needs a quick live example; return its `appUrl` for the playable workbench and `asciiTab` for plain text.
- Use `/api/project` for portable project JSON and `/api/tab/export` for derived ASCII tab from encoded project state.
- Treat `project.overlays` as semantic teaching annotations. Roles and selectors are durable; UI colors are presentation.
- Browser agents can use stable attributes such as `data-testid="piano-key-D4"`, `data-testid="fret-S2-F3"`, `data-note`, `data-midi`, and `data-agent-role`.
- All public endpoints in this version are read-only and have no side effects.

## Example Prompts

- Show D4 on standard guitar and explain every other D across octaves.
- Is B3 inside C major, and where does it appear on guitar?
- Give me the exact fret positions for C4 and same-note-name positions for every other C.
- Explain the difference between exact pitch and same note name using the current map.
- Find playable C major guitar voicings and identify each interval.
- Suggest composition moves from G2 in C major and show common tones on guitar.
- Suggest scale choices for G7 in a C major context.
- Find scales containing C, E, G, and Bb.
- Generate a beginner D natural minor tab and show the live annotated workbench URL.
- Export the current tab/project state as JSON, then derive ASCII tab from it.

## Boundaries

- Tuning: standard 6-string guitar, frets 0-24.
- Pitch model: 12-tone equal temperament, MIDI 0-127.
- Current theory layers: modal, pentatonic, blues, jazz, symmetric, synthetic, major/minor/diminished/dominant7/major7/minor7 chords.
- Current composer bridge: circle neighbors, common tones, guide-tone pivots, chromatic mediants, and standard-guitar anchors.
- Current scale atlas: scale catalog, scale maps, chord-scale advisor, and containing-scale search.
- Current agent project model: selected pitch, theory layer, mapping preferences, transport state, tuning, structured tab events, and semantic overlay marks.
- No write-capable agent task execution is exposed yet.