docs: README Overhaul + GIF Demos + Documentation Structure

[ElBeh]

Description

The README was written for v0.8 and has grown into a feature-catalog that repeats
PROJECT.md. It needs a structural overhaul — not just updated screenshots, but a
rethought information architecture that serves two audiences:

1. New visitors — "What is this? Does it solve my problem? How do I start?"
2. Returning users / contributors — detailed guides, setup, workflows.

Goals

• README becomes a concise landing page (hero, 2-3 GIFs, quick start, done)
• Detailed documentation moves to docs/guides/
• Static screenshots replaced by short GIF demos showing real workflows
• Feature list collapsed into <details> — visible but not overwhelming

README Structure (new)

Section	Content	~Lines
Hero	Title + one-liner + live link + badges	5
GIF: Core Workflow	Song → Waveform → Sections → Loop → Tempo	—
Key Features	5-6 bullet points, one sentence each	12
GIF: Guitar Pro	GP file → Notation renders → Cursor follows audio	—
Quick Start	Solo dev + Band Sync setup (incl. how sync works)	20
GIF: Band Sync	Host starts → Viewer connects → Notation syncs	—
Tech Stack	Table (keep current)	15
<details> Full Feature List	Condensed version of current list	collapsed
<details> More Screenshots	Static screenshots for reference	collapsed
License	CC BY-NC-SA 4.0	2

Roadmap section removed — tracked in Issues instead.

GIF Demos

On README (max 3)

#	GIF	Shows
1	Core Practice Workflow	Load song → waveform appears → add section markers → loop a section → adjust tempo
2	Guitar Pro Integration	Load GP file → notation renders → play audio → cursor follows → switch tracks
3	Band Sync	Host starts session → viewer opens URL → notation syncs on both screens

In docs/guides/ (detailed how-tos)

Guide	GIF shows
Setlists	Create setlist → drag & drop reorder → add pause entry → export
GP Marker Import	Open dialog → preview marks → Replace/Merge/Cancel
MIDI Setup	Open MIDI settings → MIDI Learn → press footswitch → mapping saved
Remote Controller	Viewer requests control → host approves → viewer controls transport
Sync Offset Editor	Nudge offset → adjust BPM correction → notation re-aligns
Count-In & Metronome	Enable count-in → configure beats → enable metronome → adjust volume

Documentation Structure

docs/
├── gifs/                      # All GIF files
├── screenshots/               # Static screenshots (existing, pruned)
└── guides/
    ├── getting-started.md     # Expanded Quick Start
    ├── sections-and-loops.md  # Markers, section loop, A/B loop
    ├── guitar-pro.md          # GP rendering, sync offset, marker import
    ├── band-sync.md           # Setup, roles, auto-advance
    ├── setlists.md            # Builder, export/import, URL import
    ├── midi-setup.md          # MIDI Learn, mappings, footswitch
    └── count-in-metronome.md  # Count-in, metronome config

Tasks

README Overhaul

• Write new README with collapsed structure (see table above)
• Remove standalone Roadmap section
• Fix typo "Controll" → "Control" in existing screenshots section
• Remove TODO comment from Sync Offset Editor screenshot

GIF Recording

• Record GIF 1: Core Practice Workflow
• Record GIF 2: Guitar Pro Integration
• Record GIF 3: Band Sync
• Record guide GIFs (can be done incrementally per guide)

Documentation

• Create docs/guides/ folder structure
• Write getting-started.md
• Write sections-and-loops.md
• Write guitar-pro.md
• Write band-sync.md
• Write setlists.md
• Write midi-setup.md
• Write count-in-metronome.md
• Add docs/README.md as index page

Cleanup

• Remove outdated screenshots from docs/screenshots/
• Verify all GIF/image links work after restructure