docs: align TRD with rehearsal domain model

AGENTS.md

@@ -1,8 +1,8 @@
 # AGENTS.md
 
 ## Project overview
-- BandScope is a local-first desktop app for chord, stem, and range analysis.
-- Authoritative delivery rules live in `docs/ARCHITECTURE.md`, `docs/plans/`, and the root verification scripts.
+- BandScope is a local-first desktop app for rehearsal prep: a practical song view with likely harmony by section and by instrument or vocal role, form and groove cues, stems, playable ranges, simplification guidance, transposition or setup cues, part-overlap cues, visible confidence, and rehearsal priorities.
+- Authoritative delivery rules live in `ARCHITECTURE.md`, `docs/plans/`, and the root verification scripts.
 - Brand, tone, UX copy, and prioritization rules live in `docs/brand-story.md` and must be applied to PRDs, TRDs, UI copy, onboarding, empty states, and error messages.
 - App security rules live in `docs/security/app-security.md` and must be applied to file handling, URL intake, subprocesses, IPC, WebView usage, model loading, updates, logging, cache handling, and export behavior.
 - Dependency, SBOM, and supply-chain rules live in `docs/security/dependency-policy.md` and must be applied to dependency additions, GitHub Actions, releases, bundled binaries, and model artifacts.
@@ -58,6 +58,7 @@
 - Keep UI and analysis engine decoupled through shared contracts.
 - Prefer minimal, test-first changes for production code.
 - Prefer practical, friendly, rehearsal-first wording over academic or authority-heavy language.
+- Do not reduce the product to a chord analyzer when form, timing, player coordination, simplification, and setup cues are the real rehearsal blockers.
 - Do not frame usability as a reason to accept weak analysis quality; BandScope should aim for both easy use and high accuracy.
 
 ## Safety

ARCHITECTURE.md

@@ -45,6 +45,36 @@ Last updated: 2026-03-10
 - `scripts/harness` - fail-fast repo verification
 - `scripts/checks` - small doc and structure checks
 
+## Product capability scope
+
+- BandScope is not only a shell around chord labels, stems, and ranges.
+- The technical scope includes rehearsal-facing outputs for harmony, section roadmap, groove cues, role entry and dropout cues, simplification guidance, transposition or setup guidance, confidence flags, and rehearsal priority.
+- These outputs must stay aligned with `docs/brand-story.md` rather than drifting back to a song-summary-only analyzer.
+
+## Analysis target model
+
+- The analysis target is a `song -> section -> role` hierarchy, not a single song-wide chord track.
+- A `role` can represent an instrument, a vocal function, or a hand-specific subdivision when the arrangement exposes it clearly.
+- Typical roles include bass, guitar, keyboard players, keyboard left hand, keyboard right hand, lead vocal, backing vocal, horns, strings, and other arrangement-carrying parts.
+- Shared contracts should be able to carry different harmonic guidance for simultaneous roles in the same section.
+
+## Rehearsal outputs
+
+- Core rehearsal artifacts should include:
+  - likely harmony by section and by role
+  - section roadmap with entries, dropouts, pickups, stops, tags, and handoffs
+  - groove and timing cues relevant to locking the band together
+  - playable ranges and density or overlap warnings
+  - simplification, transposition, capo, tuning, or setup cues where applicable
+  - role-specific rehearsal priorities and confidence flags
+  - cue-sheet or chart-style exports that summarize the analysis in rehearsal-friendly form
+
+## Confidence, edits, and provenance
+
+- Confidence must be representable at the section and role level.
+- Automatic analysis should remain editable without losing provenance of what was model-generated versus user-confirmed.
+- Future shared contracts should preserve manual overrides, confidence markers, and export-safe summaries of those states.
+
 ## Harness decisions
 
 - The harness uses `npm` workspaces for JavaScript/TypeScript and `uv` for Python.
@@ -58,6 +88,7 @@ Last updated: 2026-03-10
 - Cross-platform Windows and macOS build coverage is part of the bootstrap security architecture.
 - GitHub-facing setup is staged: no-git -> local-git -> GitHub-connected -> protected-branches with required checks.
 - Shared contracts live in `packages/shared-types` so the UI can evolve without importing Python internals.
+- Shared contracts should ultimately model section, role, cue, confidence, and export artifacts explicitly enough that desktop UI and analysis outputs do not invent their own parallel schemas.
 - Product and UX decisions should prefer rehearsal-first simplicity while still maintaining high analytical accuracy.
 - Security decisions should prefer allowlisted narrow capabilities over generic convenience APIs.
 

README.md

@@ -1,6 +1,8 @@
 # BandScope
 
-BandScope is a public GitHub project for a local-first desktop app that gives amateur band members fast chord, stem, and range analysis without DAW complexity.
+BandScope is a public GitHub project for a local-first desktop app that turns a song into a practical rehearsal view: likely harmony by section and by instrument or vocal role, section roadmap, tempo and groove cues, separated stems, playable ranges, simplification hints, transposition or capo guidance, overlap cues, visible confidence, and rehearsal priorities without DAW complexity.
+
+It does not promise notation-grade full arrangement transcription or DAW-style production editing.
 
 Brand and product voice source of truth: `docs/brand-story.md`
 App security source of truth: `docs/security/app-security.md`
@@ -80,6 +82,7 @@ BANDSCOPE_ENABLE_RUST_CHECK=1 ./scripts/harness/quickcheck.sh
 
 - make the repository bootstrappable on a clean machine
 - keep frontend and Python engine contracts explicit
+- keep rehearsal-domain outputs explicit across sections, roles, cues, confidence, and exports
 - enforce mechanical checks early
 - keep docs visible to future agents
 - keep brand, product voice, and UX tone consistent through repo docs

docs/architecture/overview.md

@@ -4,6 +4,28 @@
 
 BandScope is a local-first desktop app with a React + Tauri shell, shared TypeScript contracts, and a Python analysis service.
 
+It is technically defined as a rehearsal-analysis product, not a single-output chord detector.
+
+## Core rehearsal artifacts
+
+- likely harmony by section and by role
+- section roadmap with entries, dropouts, pickups, stops, and handoffs
+- groove and timing cues
+- role ranges, overlap warnings, and simplification guidance
+- transposition, capo, tuning, or setup cues where relevant
+- role-specific confidence and rehearsal priority
+
+## Shared domain contracts
+
+- Shared contracts must support a `song -> section -> role` model.
+- Roles can include instruments, vocal roles, or hand-specific subdivisions when the arrangement exposes them clearly.
+- Contracts should preserve user edits, provenance, and confidence so UI and exports stay aligned with the same domain model.
+
+## Exported rehearsal deliverables
+
+- BandScope should support cue-sheet or chart-style outputs derived from the same section and role model.
+- Exported artifacts should stay compact and rehearsal-friendly rather than becoming DAW sessions or engraved scores.
+
 ## Delivery flow
 
 GitHub is the source of truth for repository governance, PR review, CI/CD, Code Security, dependency review, SBOM retention, and release distribution.

docs/architecture/rehearsal-domain-model.md

@@ -0,0 +1,54 @@
+# BandScope Rehearsal Domain Model
+
+## Role taxonomy and extraction targets
+
+BandScope models a song as rehearsal-facing roles, not only as a single global harmonic summary.
+
+- A `role` can be an instrument role, a vocal role, or a hand-specific subdivision when the arrangement exposes it clearly.
+- Example roles include bass guitar, guitar, Keyboard 1 left hand, Keyboard 1 right hand, Keyboard 2 left hand, Keyboard 2 right hand, lead vocal, backing vocal harmony, horns, and strings.
+- The technical goal is not unlimited score transcription. The goal is enough role separation to make rehearsal decisions per player or role.
+
+## Harmony by section and role
+
+- Harmony should be modeled per section and per role.
+- Different roles may carry different voicings or harmonic functions at the same moment.
+- The shared contract must not collapse those differences into one global chord answer when the arrangement clearly separates them.
+
+## Keyboard hands and vocal modeling
+
+- Keyboard hands should be modeled separately when left-hand and right-hand material diverge enough to affect rehearsal.
+- Lead vocals and backing vocals should be modeled separately when melody, harmony stack, or entry timing differ.
+- Vocal-specific outputs should support lyric-linked cue anchors, range pressure, and harmony-entry timing.
+
+## Form, roadmap, and cue anchors
+
+- A section model should support intro, verse, pre-chorus, chorus, bridge, outro, tags, pickups, stops, and handoffs.
+- A rehearsal roadmap should expose who enters, who drops out, and where the band must re-enter together.
+- Cue anchors should support lyric phrases, count-based entries, or section-transition markers.
+
+## Groove cues and rhythmic feel
+
+- Groove guidance should include practical rehearsal cues such as straight versus swing feel, stop-time moments, sustained versus choppy roles, and shared hits.
+- The purpose is rehearsal coordination, not notation-level rhythm engraving.
+
+## Transposition, capo, tuning, and simplification guidance
+
+- A role output may include concert-key versus player-key transposition, capo suggestions, likely tuning or setup notes, and rehearsal-safe simplifications.
+- Simplification guidance should separate must-play material from optional color tones or tonight-safe reductions.
+
+## Confidence, provenance, and manual edits
+
+- Confidence must be available per section and per role.
+- Manual corrections should preserve provenance so BandScope can distinguish model guesses from user-confirmed edits.
+- Rehearsal prioritization should be able to use low-confidence areas as one source of urgency.
+
+## Cue sheet and chart exports
+
+- Exports should be compact rehearsal artifacts rather than DAW sessions or engraved notation.
+- Acceptable examples include cue sheets, section roadmaps, role notes, lyric-linked anchors, and chart-style summaries.
+- Export formats must stay aligned with `docs/security/app-security.md` export safety rules.
+
+## Rehearsal prioritization
+
+- The system should be able to rank what matters first by role and by section.
+- Typical priority drivers include difficult entries, dense overlap, low-confidence harmony, setup changes, and likely train-wreck sections.

docs/brand-story.md

@@ -2,7 +2,8 @@
 
 ## One-line definition
 
-BandScope is an easy band mate that turns complex music analysis into something people can use right away for practice, copying, and rehearsal prep after work, while still aiming for high analysis accuracy.
+BandScope is an easy band mate that turns complex rehearsal analysis into something people can use right away for practice, copying, and rehearsal prep after work, while still aiming for high analysis accuracy.
+It should help with what to play, when to enter, how the section moves, what to simplify, and what each player needs to lock in before rehearsal.
 
 ## Brand story
 
@@ -13,12 +14,18 @@ Its starting point is not studio prestige or advanced theory.
 Its starting point is the time people lose before they can actually play.
 
 Band hobbyists with day jobs often face the same problem.
-They want to understand the original song before rehearsal, but separating parts, figuring out chords, and checking vocal or instrument range takes too long.
+They want to understand the original song before rehearsal, but separating parts, understanding the harmonic flow for each instrument, and checking vocal or instrument range takes too long.
 As a result, rehearsal time gets spent on confusion instead of music.
 
 BandScope exists to reduce that waste.
 
-Users should be able to drop in a YouTube link or audio file, look at the chord progression, listen to separated parts, understand each part's range, and spot where parts clash.
+Users should be able to drop in a YouTube link or audio file, see a practical rehearsal view of the song, inspect likely harmony by section and by playing role, listen to separated parts, understand each part's range, and spot where parts clash or need simplification.
+They should also be able to follow the form quickly, understand tempo and groove cues, see who enters or drops out, and identify which sections need attention first.
+
+That means BandScope cannot treat `the chord` as one flat answer for the whole arrangement.
+Different keyboard players, each left hand, each right hand, the bass guitar, guitars, horns, strings, lead vocals, backing vocals, or other arrangement-carrying roles can hold different note choices or harmonic functions at the same moment.
+BandScope should treat those roles as separate extraction targets.
+If the arrangement exposes separate left/right hands, multiple keyboard players, bass movement, lead-vocal melody, or backing-vocal harmony, the product should aim to extract and present them separately enough that rehearsal decisions can be made per player and per role, not only at the song-summary level.
 
 BandScope does not try to replace musical judgment.
 It helps people understand songs faster and rehearse better.
@@ -47,23 +54,33 @@ One-line promise:
 
 Turn first-listen uncertainty into understandable information.
 
-- `아, 이 곡은 이런 코드구나`
-- `여기서는 보컬이 이 음역이네`
+- `아, 이 곡은 악기마다 이렇게 잡아야 하는구나`
+- `여기서는 리드 보컬이 이 음역이네`
+- `이 코러스는 백보컬 화성이 이렇게 쌓이네`
 - `여기 기타랑 키보드가 겹치네`
 
 ### 2. Save rehearsal time
 
 Reduce ear-only copying time and help users spend more time actually playing.
+That includes fast transposition choices, capo or tuning-aware playability hints, lyric or count-based cue anchors, and a clear view of what each player needs to fix before the room starts.
+
+### 3. Show the form and feel, not just the harmony
+
+Help players see where the song changes, how sections connect, where hits or stops matter, what kind of rhythmic feel they need to lock together, and where entries, dropouts, pickups, and handoffs happen.
 
-### 3. Prioritize action over theory, not over accuracy
+### 4. Prioritize action over theory, not over accuracy
 
 Show results that help practice now before offering deeper explanation, but do not simplify the product in ways that make the analysis meaningfully less accurate.
 
-### 4. Help like a peer, not a judge
+### 5. Help like a peer, not a judge
 
 Be smart, but never show off.
 Be kind, clear, and useful.
 
+### 6. Tell each player what matters first
+
+Make it obvious which role carries the hook, which part can simplify, which cue matters, which section is most likely to waste rehearsal time, and what each player should learn first versus confirm in the room.
+
 ## Brand personality
 
 ### Keep
@@ -109,6 +126,7 @@ Frame analysis as recommendation or estimation.
 Good:
 - `자동으로 추정한 코드입니다.`
 - `가장 가능성이 높은 파트 분류입니다.`
+- `이 구간은 확신이 낮으니 귀로 한 번 더 확인해 보세요.`
 
 ### 4. Sound like a band mate
 
@@ -126,12 +144,15 @@ Tie feature explanations back to practice, copying, rehearsal prep, or quick und
 - hide complex options behind reasonable defaults without lowering result quality
 - keep automatic analysis editable
 - avoid making users feel like they are learning a DAW
-- keep practice-first tasks in front: chord view, part/range view, loop playback
+- keep practice-first tasks in front: harmonic view by section and playing role, section roadmap, tempo/groove cues, vocal and instrument range view, loop playback, overlap/clash cues, simplification cues, transposition and capo/tuning guidance, confidence flags, and role-specific editing
 - make sharing results easy
 
 ## Decision rules for future docs and copy
 
 - If one option is more powerful but more complex, prefer the one that helps practice sooner without reducing the accuracy users need for rehearsal decisions.
+- Do not collapse arrangement-specific harmony into one global chord label when the real rehearsal problem is instrument-, hand-, vocal-, or role-specific voicing or function.
+- Do not collapse rehearsal prep into chord display when structure, timing, transposition, or player coordination are the real blockers.
+- If a player needs a practical output like a cue sheet, compact chart, or lyric-linked rehearsal anchor, prefer that over deeper analysis that still leaves them guessing when to come in.
 - If one sentence sounds more professional but colder, prefer the one that sounds practical and kind.
 - If one screen shows more information but feels heavier, prefer the simpler default mode as long as it does not hide or weaken important accurate feedback.
 - Never present uncertain output like a final answer.
@@ -143,6 +164,7 @@ Tie feature explanations back to practice, copying, rehearsal prep, or quick und
 - fast results should still be reliable enough for real rehearsal prep
 - product simplification should remove friction, not lower analytical correctness
 - if there is a trade-off, aim to keep both: low learning cost and high confidence in the result
+- uncertainty should be visible at the section and role level when it can change rehearsal decisions
 
 ## Required application areas
 
@@ -161,13 +183,18 @@ Apply this brand story in:
 - empty states
 - export labels and guidance
 - user guides
+- rehearsal cue sheets and chart-style exports
 
 ## Copy patterns
 
 ### Good examples
 
 - `이 구간은 보컬과 키보드가 같은 음역에 몰려 있어 답답하게 들릴 수 있습니다.`
-- `자동으로 추정한 코드 진행입니다. 필요하면 직접 고칠 수 있습니다.`
+- `자동으로 추정한 악기별·보컬별 코드와 화성 흐름입니다. 필요하면 직접 고칠 수 있습니다.`
+- `이 구간은 드럼과 베이스가 같이 잠깐 멈추는 타이밍이 중요합니다.`
+- `오늘 합주 기준으로는 이 보이싱을 단순하게 줄여도 됩니다.`
+- `이 파트는 2절에서만 들어오고, 코러스 직전 가사 뒤에서 다시 잡으면 됩니다.`
+- `기타는 카포 2 기준으로 보면 오늘 합주 준비가 더 쉽습니다.`
 - `어려운 구간만 반복해서 들으면서 코드를 확인해 보세요.`
 
 ### Bad examples
@@ -180,6 +207,6 @@ Apply this brand story in:
 
 BandScope is:
 
-`퇴근 후 합주하는 사람들을 위해, 복잡한 음악 분석을 쉽고 정확하게 정리해 바로 연습에 쓸 수 있게 돕는 밴드 메이트`
+`퇴근 후 합주하는 사람들을 위해, 악기와 보컬 역할별 코드·폼·리듬·음역·충돌·준비 우선순위를 한눈에 정리해 바로 연습에 쓸 수 있게 돕는 밴드 메이트`
 
 Use this line as the default tie-breaker for future product, UX, and copy decisions.