guitar-tui 0.1.0__tar.gz

guitar_tui-0.1.0/.claude/claudify

@@ -0,0 +1 @@
+blueprint: python-tui

guitar_tui-0.1.0/.claude/claudify.md

@@ -0,0 +1,31 @@
+<!-- This project uses claudify — a Claude Code configuration kit.
+     Commands: /continue, /save, /log, /prep, /pulse
+     To update kit files: /claudify update
+     Learn more: https://github.com/konoerik/claudify -->
+
+## Context Loading
+
+Read on every session:
+- `docs/CONTEXT.md` — current focus, last decisions, next action
+
+Read when the user mentions tasks, features, bugs, or current work:
+- `docs/PLAN.md` — `## Active` section only
+
+Read when writing or editing code:
+- `docs/CONVENTIONS.md` — canonical style reference; pattern-match before writing
+
+Read when touching code structure, architecture, or making structural decisions:
+- `docs/ARCHITECTURE.md` — `## Quick Reference` first; full file only if needed
+
+Load only when explicitly asked about goals or priorities:
+- `docs/ROADMAP.md`
+
+Never auto-load:
+- `.claude/archive/`
+
+## Behavior Rules
+- Prefer editing existing files over creating new ones
+- Do not create `BACKLOG.md`, `TASKS.md`, `TODO.md`, or similar — use `PLAN.md`
+- When making an architectural decision, record it with `/log` before ending the session
+- Keep `PLAN.md ## Active` short — if it exceeds 10 items, triage before adding more
+- Never commit or push without explicit instruction — `/save` and `/prep` are the checkpoints before that happens

guitar_tui-0.1.0/.claude/commands/continue.md

@@ -0,0 +1,10 @@
+Read docs/CONTEXT.md and the ## Active section of docs/PLAN.md.
+
+Summarize:
+1. Current focus and next action from docs/CONTEXT.md
+2. Active tasks as a numbered list with their status
+3. Any blockers that need attention
+
+Then ask: "What do you want to work on?"
+
+Do not load docs/PLAN.md ## Backlog or docs/ROADMAP.md unless I ask about priorities.

guitar_tui-0.1.0/.claude/commands/log.md

@@ -0,0 +1,20 @@
+Record an architectural decision in docs/ARCHITECTURE.md under ## Decisions (ADRs).
+
+First, read docs/ARCHITECTURE.md to find the next ADR number.
+
+Then ask me:
+1. What is the decision? (title)
+2. What was the context or problem?
+3. What alternatives were considered?
+4. What are the consequences or trade-offs?
+
+Append to docs/ARCHITECTURE.md ## Decisions using this format:
+
+### ADR-N: <Title>
+**Date:** YYYY-MM-DD
+**Context:** <Why this decision was needed>
+**Decision:** <What was decided>
+**Alternatives considered:** <What else was evaluated>
+**Consequences:** <Trade-offs, follow-up work, or constraints introduced>
+
+Also update docs/CONTEXT.md **Last session** to mention the decision was recorded.

guitar_tui-0.1.0/.claude/commands/prep.md

@@ -0,0 +1,19 @@
+Run a pre-ship checklist before I open a PR or push a release.
+
+Work through each item and report pass/fail/skip with a brief reason:
+
+**Code**
+- [ ] All tests pass
+- [ ] No leftover debug logs, commented-out code, or TODOs in changed files
+- [ ] No hardcoded secrets or environment-specific values
+
+**Docs**
+- [ ] docs/PLAN.md ## Active updated — completed items moved to ## Done
+- [ ] If an architectural decision was made, it's recorded in docs/ARCHITECTURE.md
+- [ ] docs/CONTEXT.md reflects the current state
+
+**Review**
+- [ ] Changes are scoped to what was planned — no unrelated modifications
+- [ ] Any new dependencies are intentional and noted in docs/ARCHITECTURE.md ## Quick Reference
+
+If any item fails, surface it clearly and ask whether to fix it now or proceed anyway.

guitar_tui-0.1.0/.claude/commands/pulse.md

@@ -0,0 +1,21 @@
+Take stock of where the project is and whether it's still pointed at the right thing.
+
+1. Read docs/CONTEXT.md, docs/PLAN.md (## Active and ## Done), and the ## Quick Reference section of docs/ARCHITECTURE.md.
+
+2. In 2–3 sentences, summarize: what the project set out to do, and what it has actually been doing lately. Be factual, not evaluative.
+
+3. Then ask these three questions together — don't wait for answers one at a time:
+
+   - **Right problem?** Is what we're building still solving the problem we originally set out to solve?
+   - **Off track?** Is there anything we've spent real time on that, in hindsight, wasn't the point?
+   - **Avoiding something?** Is there something we keep not doing that is probably the actual next thing?
+
+4. After I respond, do one of the following based on what I say:
+
+   - **If the direction has shifted unintentionally:** Help me refocus. Update docs/PLAN.md ## Active to reflect the real next thing, and update docs/CONTEXT.md **Next action** to match.
+
+   - **If the direction has shifted intentionally (a pivot):** Treat it as a decision. Run /log to record it as an ADR, then update docs/CONTEXT.md to reflect the new direction.
+
+   - **If we're on track:** Say so clearly, in one sentence. No need to change anything.
+
+Keep the tone curious, not corrective. This is a gut-check, not a postmortem.

guitar_tui-0.1.0/.claude/commands/save.md

@@ -0,0 +1,20 @@
+Wrap up this session by updating docs/CONTEXT.md and docs/PLAN.md.
+
+1. Read docs/CONTEXT.md and docs/PLAN.md ## Active (if not already in context).
+
+2. Based on what we did this session, rewrite docs/CONTEXT.md with:
+   - **Current focus:** what is still actively in progress (not done yet)
+   - **Last session:** one concise sentence — what was accomplished and any decisions made
+   - **Blocking:** anything unresolved, waiting on input, or unclear
+   - **Next action:** the single most important thing to do next session
+
+   Keep the whole file under 8 lines. Add a hidden sentinel on the last line:
+   `<!-- wrapped: YYYY-MM-DD -->`
+   (use today's actual date)
+
+3. Review docs/PLAN.md ## Active. For any tasks completed this session, move them to ## Done.
+   Do not add new tasks unless I explicitly ask.
+
+4. Confirm what was updated. Do not summarize the whole session — just state:
+   - What changed in docs/CONTEXT.md
+   - How many tasks moved to Done (if any)

guitar_tui-0.1.0/.claude/hooks/pre-tool-use/guard-naming.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Hook: pre-tool-use/guard-naming.sh
+# Fires before file edits/writes. Blocks creation of non-canonical doc files.
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || true)
+
+if [[ "$TOOL_NAME" != "Write" && "$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null || true)
+BASENAME=$(basename "$FILE_PATH")
+
+DISALLOWED=("BACKLOG.md" "TASKS.md" "TODO.md" "TODOS.md" "TASK.md")
+
+for name in "${DISALLOWED[@]}"; do
+  if [[ "$BASENAME" == "$name" ]]; then
+    echo "Blocked: '$BASENAME' is not a canonical filename. Use PLAN.md with ## Active and ## Backlog sections instead." >&2
+    exit 1
+  fi
+done

guitar_tui-0.1.0/.claude/hooks/stop/session-wrap.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# Hook: stop/session-wrap.sh
+# Fires at the end of every Claude Code session.
+# 1. Archives completed tasks from docs/PLAN.md ## Done to .claude/archive/YYYY-MM.md
+# 2. Warns if docs/PLAN.md ## Active is getting long
+# 3. Flags docs/CONTEXT.md as stale if /save was not run this session
+
+set -euo pipefail
+
+PLAN="docs/PLAN.md"
+ARCHIVE_DIR=".claude/archive"
+ARCHIVE_FILE="$ARCHIVE_DIR/$(date +%Y-%m).md"
+
+# --- Archive completed tasks ---
+
+if [[ ! -f "$PLAN" ]]; then
+  exit 0
+fi
+
+DONE_CONTENT=$(awk '/^## Done/{found=1; next} found && /^## /{exit} found{print}' "$PLAN")
+DONE_CONTENT=$(echo "$DONE_CONTENT" | sed '/./,$!d' | sed -e :a -e '/^\s*$/{ $d; N; ba }')
+
+if [[ -n "$DONE_CONTENT" ]]; then
+  mkdir -p "$ARCHIVE_DIR"
+  {
+    echo ""
+    echo "## Archived $(date +%Y-%m-%d)"
+    echo "$DONE_CONTENT"
+  } >> "$ARCHIVE_FILE"
+
+  awk '
+    /^## Done/ { print; in_done=1; next }
+    in_done && /^## / { in_done=0 }
+    !in_done { print }
+  ' "$PLAN" > "$PLAN.tmp" && mv "$PLAN.tmp" "$PLAN"
+
+  echo "[session-wrap] Archived $(echo "$DONE_CONTENT" | grep -c '^\- \[x\]' || true) completed task(s) to $ARCHIVE_FILE"
+fi
+
+# --- Warn if Active section is long ---
+
+ACTIVE_COUNT=$(awk '/^## Active/{found=1; next} found && /^## /{exit} found && /^\- /{print}' "$PLAN" | wc -l | tr -d ' ')
+
+if [[ "$ACTIVE_COUNT" -gt 10 ]]; then
+  echo "[session-wrap] Warning: docs/PLAN.md ## Active has $ACTIVE_COUNT items. Consider moving lower-priority items to ## Backlog."
+fi
+
+# --- Check if CONTEXT.md was updated this session ---
+
+CONTEXT="docs/CONTEXT.md"
+TODAY=$(date +%Y-%m-%d)
+
+if [[ -f "$CONTEXT" ]]; then
+  if ! grep -q "wrapped: $TODAY" "$CONTEXT" 2>/dev/null; then
+    echo "[session-wrap] docs/CONTEXT.md was not updated this session. Run /save before your next session to keep context fresh."
+  fi
+fi

guitar_tui-0.1.0/.claude/settings.local.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(~/.local/bin/uv run:*)",
+      "Bash(git:*)",
+      "Bash(~/.local/bin/uv sync:*)",
+      "Bash(grep -hv \"^$\" /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/07-natural-minor/minor_scale_chords.md /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/08-major-scale/major_scale_chords.md /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/08-major-scale/diatonic_progressions.md)",
+      "Bash(grep -hv \"^$\" /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/01-orientation/the_fretboard.md /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/01-orientation/tuning_your_guitar.md /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/01-orientation/reading_scale_diagrams.md)",
+      "Bash(grep -B2 -A2 -E \"[A-G]\\(#|b\\)?\\(m|maj7|m7|7|dim\\)?\\( ?[–-] ?[A-G]\\(#|b\\)?\\(m|maj7|m7|dim|7\\)?\\){2,}|major scale of|key of [A-G]|= [A-G] \")",
+      "Bash(grep -hv \"^$\" /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/05-barre-chords/e_shape_major.md /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/05-barre-chords/a_shape_major.md)",
+      "Bash(grep -hv \"^$\" /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/06-pentatonic-scale/pentatonic_major_vs_minor.md)",
+      "Bash(grep -hv \"^$\" /Users/erik/Sandbox/guitar-tui/guitar_tui/content/lessons/01-orientation/reading_chord_diagrams.md)",
+      "Bash(~/.local/bin/uv build *)",
+      "Bash(python3 -c ' *)"
+    ]
+  }
+}

guitar_tui-0.1.0/.env.example

@@ -0,0 +1,7 @@
+# Copy this file to .env and fill in your values. .env is gitignored — never commit it.
+
+# PyPI API token for publishing (create at https://pypi.org/manage/account/token/)
+# Usage:   set -x UV_PUBLISH_TOKEN (grep '^UV_PUBLISH_TOKEN' .env | cut -d= -f2)   # fish
+#          export $(grep -v '^#' .env | xargs)                                     # bash/zsh
+# then:    uv publish
+UV_PUBLISH_TOKEN=pypi-REPLACE_ME

guitar_tui-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,27 @@
+---
+name: Bug report
+about: Something isn't working correctly
+labels: bug
+---
+
+**Describe the bug**
+A clear description of what happened and what you expected instead.
+
+**To reproduce**
+Steps to reproduce the behaviour:
+1.
+2.
+3.
+
+**Environment**
+- OS and version (e.g. macOS 14.4, Ubuntu 24.04):
+- Terminal emulator (e.g. iTerm2, Kitty, Windows Terminal):
+- Python version (`python --version`):
+- Install method (uv tool install / pip install / cloned repo):
+- App version (`guitar-tui --version` if available):
+
+**If a diagram rendered incorrectly**
+Paste the relevant `diagram` YAML block from the lesson file, and describe what was wrong with the output.
+
+**Additional context**
+Any other information that might help — screenshots, error messages, relevant lesson slug.

guitar_tui-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest an idea or improvement
+labels: enhancement
+---
+
+**What problem does this solve, or what would it enable?**
+A clear description of the gap or use case.
+
+**Proposed solution**
+What you'd like to see. Be as specific or as rough as you like — a sketch is fine.
+
+**Alternatives considered**
+Any other approaches you thought about and why they didn't fit.
+
+**Additional context**
+Anything else — related lessons, relevant music theory, similar tools that do this well.

guitar_tui-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.Python
+
+# Virtual environment (uv)
+.venv/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Textual devtools
+.textual/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+.claude/archive/
+
+# Secrets — never commit; see .env.example
+.env

guitar_tui-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

guitar_tui-0.1.0/CLAUDE.md

@@ -0,0 +1,77 @@
+# Guitar TUI — Claude Context
+
+## Project
+
+Guitar TUI is a Python terminal application built with Textual that teaches guitar music theory interactively. It presents chord diagrams, scale patterns, fretboard visualizations, and structured lessons entirely within the terminal. The application is designed for guitarists who prefer keyboard-driven tools and want a fast, distraction-free reference for theory concepts.
+
+## Architecture
+
+Four-layer model, built bottom-up:
+
+```
+Data Layer      guitar_tui/data/        YAML chord/scale data, tunings
+Engine Layer    guitar_tui/engine/      DiagramSpec renderers (music-agnostic)
+Content Layer   guitar_tui/loaders/     Lesson parser, diagram block dispatcher
+TUI Layer       guitar_tui/ui/          Screens, widgets, stylesheet
+```
+
+**Critical rule**: the engine is music-agnostic. It renders DiagramSpec objects — it does not know chord names or scale theory. Music knowledge lives exclusively in the data layer and lesson content.
+
+**Data validation**: the data loader validates all YAML files against Pydantic schemas on startup. Invalid data is a hard error, not a warning.
+
+**Schema contract**: `schemas/` defines the interface between the Developer and Instructor personas. Both must agree on schema changes before acting.
+
+**Diagram taxonomy**: `schemas/diagram_taxonomy.md` — full catalog of all diagram types (Groups A–F) identified during planning, with M2 scope vs. deferred notes. Read before implementing any new renderer.
+
+## Personas
+
+Three distinct roles share this codebase. See [PERSONAS.md](docs/PERSONAS.md) for full details.
+
+- **Developer** — owns engine, loaders, UI, schemas, tooling
+- **Instructor** — owns `guitar_tui/data/` and `guitar_tui/content/`; [CURRICULUM.md](docs/CURRICULUM.md) is the Instructor's primary planning document — read it before adding any lesson or reference content
+- **Reviewer** — external perspective; periodic assessments live in `docs/reviews/`
+
+## Key Commands
+
+Prefer `make` targets — they wrap `uv run` and are the canonical interface:
+
+```bash
+make setup    # uv sync — install / refresh dependencies
+make run      # launch the application
+make dev      # launch with Textual devtools (live reload + inspector)
+make test     # run the test suite
+make check    # verify the package is importable
+make clean    # remove .venv, caches, build artifacts
+make build    # build distribution packages (future)
+```
+
+Raw `uv run` equivalents if needed:
+```bash
+uv run guitar-tui
+uv run pytest
+uv run textual run --dev guitar_tui/app.py
+```
+
+## Conventions
+
+- **Python**: type hints on all functions, Pydantic models for all data schemas
+- **Data files**: YAML for music data (`guitar_tui/data/`), Markdown+YAML frontmatter for lessons (`guitar_tui/content/lessons/`)
+- **Naming**: `snake_case` for files and identifiers; diagram types use lowercase strings (`"chord"`, `"scale"`, `"tab"`, `"fretboard"`)
+- **Diagram directives**: fenced code blocks with type `diagram` in lesson Markdown; YAML body per `schemas/diagram_spec.md`
+- **Tests**: all engine renderers require tests; use `pytest-asyncio` for Textual widget tests
+
+## Session Resumption
+
+1. Read `docs/CONTEXT.md` — current focus and next action
+2. Read `docs/PLAN.md` — find the highest-priority unchecked item in Active
+3. Read `docs/ROADMAP.md` — review the current phase's goals if needed
+4. Check `schemas/` if working on content or engine boundary code
+5. Check `docs/ARCHITECTURE.md` § Decisions before questioning an established pattern — the trade-offs were considered during planning
+
+## Critical Rules
+
+- Engine renders DiagramSpec objects only — never raw chord/scale data
+- Data layer validates on startup; startup failure is acceptable, silent corruption is not
+- `schemas/` is the dev-instructor contract; no unilateral changes
+- Instructor does not modify engine or UI code
+- Developer does not curate lesson content or decide music theory accuracy

guitar_tui-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in this project a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+The project maintainer is responsible for clarifying and enforcing standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior deemed inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces — GitHub issues, pull requests, and any other project communication channels.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening a GitHub issue or contacting the maintainer directly via GitHub. All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

guitar_tui-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to Guitar TUI
+
+Thank you for your interest in contributing. This is a small, focused project — contributions are welcome, but please read this first so your effort isn't wasted.
+
+## What kind of contributions are welcome
+
+- **Bug reports** — something renders incorrectly, crashes, or behaves unexpectedly
+- **Content corrections** — a chord voicing is wrong, a scale position has an error, lesson prose is inaccurate
+- **Small fixes** — typos, broken links, off-by-one errors in diagrams
+- **Feature proposals** — open an issue before writing code; the roadmap is deliberate and not everything fits
+
+## What is out of scope
+
+- Copyrighted note sequences or transcriptions
+- Audio playback (deferred by design — see architecture notes)
+- User-configurable content paths or plugin systems
+- Python < 3.12 support
+
+## Reporting a bug
+
+Open a GitHub issue and include:
+
+- OS and terminal emulator (e.g. macOS 14, iTerm2)
+- Python version (`python --version`)
+- How you installed the app (`uv tool install`, `pip install`, cloned repo)
+- What you expected vs. what happened
+- If a diagram rendered incorrectly, paste the diagram YAML from the lesson file
+
+## Suggesting content changes
+
+Content lives in `guitar_tui/content/` (lessons, exercises, licks) and `guitar_tui/data/` (YAML chord/scale data). The schema contract is in `schemas/`. If you spot an error in a chord voicing or scale pattern, open an issue with the correct value and a reference — a reputable source, a published book, or a clear theoretical derivation.
+
+## Submitting a pull request
+
+1. Fork the repository and create a branch from `main`
+2. Install dependencies: `uv sync`
+3. Make your changes
+4. Run the test suite: `uv run pytest` — all tests must pass
+5. Open a PR with a clear description of what changed and why
+
+For anything beyond a small fix, open an issue first so we can discuss whether it fits before you invest the time.
+
+## Development setup
+
+```bash
+git clone https://github.com/konoerik/guitar-tui
+cd guitar-tui
+uv sync
+uv run guitar-tui          # run the app
+uv run pytest              # run tests
+uv run textual run --dev guitar_tui/app.py   # run with Textual devtools
+```

guitar_tui-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Erikton Konomi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

guitar_tui-0.1.0/Makefile

@@ -0,0 +1,70 @@
+.DEFAULT_GOAL := help
+
+UV := uv
+
+# ── Help ──────────────────────────────────────────────────────────────────────
+
+.PHONY: help
+help:
+	@echo "Guitar TUI — available targets"
+	@echo ""
+	@echo "  Setup"
+	@echo "    setup        Install all dependencies (runs uv sync)"
+	@echo ""
+	@echo "  Run"
+	@echo "    run          Launch the application"
+	@echo "    dev          Launch with Textual devtools (live reload + inspector)"
+	@echo ""
+	@echo "  Test & verify"
+	@echo "    test         Run the test suite"
+	@echo "    check        Verify the package is importable"
+	@echo ""
+	@echo "  Clean"
+	@echo "    clean        Remove venv, caches, and build artifacts"
+	@echo "    clean-pyc    Remove compiled Python files only"
+	@echo ""
+	@echo "  Package (future)"
+	@echo "    build        Build distribution packages"
+
+# ── Setup ─────────────────────────────────────────────────────────────────────
+
+.PHONY: setup
+setup:
+	$(UV) sync
+
+# ── Run ───────────────────────────────────────────────────────────────────────
+
+.PHONY: run
+run:
+	$(UV) run guitar-tui
+
+.PHONY: dev
+dev:
+	$(UV) run textual run --dev guitar_tui/app.py
+
+# ── Test & verify ─────────────────────────────────────────────────────────────
+
+.PHONY: test
+test:
+	$(UV) run pytest
+
+.PHONY: check
+check:
+	$(UV) run python -c "import guitar_tui; print('OK:', guitar_tui.__version__)"
+
+# ── Clean ─────────────────────────────────────────────────────────────────────
+
+.PHONY: clean
+clean: clean-pyc
+	rm -rf .venv .pytest_cache dist
+
+.PHONY: clean-pyc
+clean-pyc:
+	find . -path './.venv' -prune -o -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -path './.venv' -prune -o -type f -name '*.pyc'     -delete 2>/dev/null || true
+
+# ── Package (future) ──────────────────────────────────────────────────────────
+
+.PHONY: build
+build:
+	$(UV) build