feat(workspace): name the next rehearsal action from help

AGENTS.md

@@ -2,6 +2,7 @@
 
 ## Project overview
 - 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.
+- Rehearsal help must name the next action: choose a local song, start analysis, wait, retry after failure, or open tonight's map. Stem playback and a licensed demo remain later work.
 - 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.

ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ARCHITECTURE.md
 
-Last updated: 2026-03-11
+Last updated: 2026-08-21
 
 ## Brand source
 
@@ -86,6 +86,7 @@ Last updated: 2026-03-11
   - 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
+  - a rehearsal-help surface that names the next local-first action (choose a song, start analysis, wait, retry, or open the map) without claiming stem playback or a licensed demo
 
 ## Confidence, edits, and provenance
 

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- Rehearsal help now names the next action: choose a local song, start analysis, wait while analysis runs, retry after a failure, or open tonight's map.
 - Name tonight's first playable range on the ready rehearsal map and tell the player to check that span on their instrument before the section.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.

CLAUDE.md

@@ -51,7 +51,7 @@ BandScope is a local-first desktop app for rehearsal prep: it turns a song into
 
 Three layers, decoupled through shared contracts:
 
-- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings). The ready workspace names tonight's first playable range and the next instrument check. `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
+- `apps/desktop` — Tauri 2 + Vite + React 19 shell (Tailwind 4, Base UI, Storybook). Feature screens live in `src/features/` (home, workspace, chords, ranges, player, settings, help). The help control names tonight's next local-first action instead of a coming-soon label. The ready workspace also names tonight's first playable range and the next instrument check. `src/lib/analysis.ts` and `src/lib/job_runner.ts` call typed Tauri IPC commands, with a browser fallback that serves demo data when not running inside Tauri.
 - `apps/desktop/src-tauri/src/main.rs` — the Rust orchestration boundary. Tauri commands (`start_analysis_job`, `get_analysis_job_status`, `select_local_audio_source`, `import_youtube_url`) validate untrusted input (project IDs, file paths, URLs) and spawn the Python engine as a subprocess. There is no loopback HTTP listener and no network path for local analysis.
 - `services/analysis-engine` — Python package `bandscope_analysis` (librosa/numpy). Entry point `cli.py` reads a JSON job request on stdin and prints a structured job-status JSON envelope on stdout (`--progress-jsonl` streams progress lines). `api.py` orchestrates the pipeline across the `separation`, `sections`, `roles`, `chords`, `ranges`, `temporal`, `transcription`, and `youtube` modules.
 

apps/desktop/src/App.rehearsalHelpFailure.integration.test.tsx

@@ -0,0 +1,335 @@
+import { createDemoRehearsalSong } from "@bandscope/shared-types";
+import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { App } from "./App";
+
+const analysisMocks = vi.hoisted(() => ({
+  getAnalysisJobStatus: vi.fn(),
+  importYoutubeUrl: vi.fn(),
+  isSupportedYoutubeUrl: vi.fn(),
+  loadProject: vi.fn(),
+  saveProject: vi.fn(),
+  selectLocalAudioSource: vi.fn(),
+  startAnalysisJob: vi.fn(),
+  subscribeToAnalysisJobUpdates: vi.fn(async () => () => undefined),
+}));
+
+vi.mock("./lib/analysis", () => ({
+  createDefaultAnalysisRequest: () => ({
+    sourceKind: "demo",
+    sourceLabel: "Late Night Set",
+    roleFocus: ["bass-guitar", "keys-right", "lead-vocal"],
+  }),
+  getAnalysisJobStatus: analysisMocks.getAnalysisJobStatus,
+  importYoutubeUrl: analysisMocks.importYoutubeUrl,
+  isSupportedYoutubeUrl: analysisMocks.isSupportedYoutubeUrl,
+  loadProject: analysisMocks.loadProject,
+  MAX_YOUTUBE_URL_LENGTH: 2048,
+  saveProject: analysisMocks.saveProject,
+  selectLocalAudioSource: analysisMocks.selectLocalAudioSource,
+  startAnalysisJob: analysisMocks.startAnalysisJob,
+  subscribeToAnalysisJobUpdates: analysisMocks.subscribeToAnalysisJobUpdates,
+}));
+
+vi.mock("./features/score/ScoreView", () => ({
+  ScoreView: () => <div data-testid="score-view">Score view</div>,
+}));
+
+function bootstrap(projectId: string, fileName: string) {
+  return {
+    projectId,
+    sourceMode: "reference",
+    projectRoot: `/tmp/bandscope/projects/${projectId}`,
+    cacheRoot: `/tmp/bandscope/cache/${projectId}`,
+    tempRoot: `/tmp/bandscope/temp/${projectId}`,
+    source: {
+      sourcePath: `/Users/test/Music/${fileName}`,
+      fileName,
+      extension: "wav",
+      fileSizeBytes: 1024000,
+    },
+  };
+}
+
+/**
+ * Security Notes:
+ * - Local paths in this suite are synthetic test fixtures and are never rendered in customer-facing copy.
+ * - The suite mocks the existing picker and analysis boundaries; it adds no network access or IPC permission.
+ */
+describe("App rehearsal-help failure recovery", () => {
+  beforeEach(() => {
+    for (const mock of Object.values(analysisMocks)) {
+      mock.mockReset();
+    }
+    analysisMocks.isSupportedYoutubeUrl.mockReturnValue(false);
+    analysisMocks.subscribeToAnalysisJobUpdates.mockResolvedValue(() => undefined);
+  });
+
+  it("gives compact rehearsal help a distinct accessible name", () => {
+    render(<App />);
+
+    const compactNav = screen.getByRole("navigation", { name: /compact rehearsal views/i });
+    const compactHelp = within(compactNav).getByRole("button", {
+      name: /^open rehearsal help compact view$/i,
+    });
+
+    expect(screen.getByRole("button", { name: /^open rehearsal help$/i })).toBeTruthy();
+    fireEvent.click(compactHelp);
+    expect(screen.getByTestId("rehearsal-help-dialog")).toBeTruthy();
+  });
+
+  it("does not describe a project-load error as an analysis failure", async () => {
+    analysisMocks.loadProject.mockRejectedValueOnce(new Error("Broken project fixture"));
+
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /open project/i }));
+    await waitFor(() => expect(screen.getByRole("alert")).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: "Open rehearsal help" }));
+    const helpDialog = screen.getByTestId("rehearsal-help-dialog");
+    expect(within(helpDialog).getByTestId("rehearsal-help-next-action").textContent).toMatch(
+      /choose a local song first/i,
+    );
+    expect(within(helpDialog).getByTestId("rehearsal-help-next-action").textContent).not.toMatch(
+      /analysis did not finish/i,
+    );
+  });
+
+  it("advances from retry to start analysis after a different local song is selected", async () => {
+    analysisMocks.selectLocalAudioSource
+      .mockResolvedValueOnce({ ok: true, bootstrap: bootstrap("project-a", "failed-song.wav") })
+      .mockResolvedValueOnce({ ok: true, bootstrap: bootstrap("project-b", "fresh-song.wav") });
+    analysisMocks.startAnalysisJob.mockResolvedValueOnce({
+      jobId: "job-help-failed",
+      state: "failed",
+      requestedAt: "2026-08-21T05:00:00.000Z",
+      updatedAt: "2026-08-21T05:00:01.000Z",
+      error: {
+        code: "engine_unavailable",
+        message: "Analysis engine is unavailable.",
+      },
+    });
+
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/failed-song\.wav/i)).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: /^start analysis$/i }));
+    await waitFor(() => {
+      expect(screen.getByRole("alert").textContent).toMatch(/analysis engine is unavailable/i);
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Open rehearsal help" }));
+    let helpDialog = screen.getByTestId("rehearsal-help-dialog");
+    expect(within(helpDialog).getByTestId("rehearsal-help-next-action").textContent).toMatch(
+      /choose another local song and try again/i,
+    );
+    fireEvent.click(within(helpDialog).getByRole("button", { name: /choose another song/i }));
+
+    await waitFor(() => expect(screen.getByText(/fresh-song\.wav/i)).toBeTruthy());
+    fireEvent.click(screen.getByRole("button", { name: "Open rehearsal help" }));
+    helpDialog = screen.getByTestId("rehearsal-help-dialog");
+
+    expect(within(helpDialog).getByTestId("rehearsal-help-next-action").textContent).toMatch(
+      /start analysis to get tonight's first cues/i,
+    );
+    expect(within(helpDialog).queryByRole("button", { name: /choose another song/i })).toBeNull();
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  it("forgets the previous analyzed song when a different local source is selected", async () => {
+    analysisMocks.selectLocalAudioSource
+      .mockResolvedValueOnce({ ok: true, bootstrap: bootstrap("project-a", "analyzed-song.wav") })
+      .mockResolvedValueOnce({ ok: true, bootstrap: bootstrap("project-b", "fresh-song.wav") });
+    analysisMocks.startAnalysisJob.mockResolvedValueOnce({
+      jobId: "job-help-succeeded",
+      state: "succeeded",
+      requestedAt: "2026-08-21T05:10:00.000Z",
+      updatedAt: "2026-08-21T05:10:01.000Z",
+      progressLabel: "Analysis ready",
+      progressStage: "ready",
+      progressPercent: 100,
+      cacheStatus: "disabled",
+      result: createDemoRehearsalSong(),
+    });
+
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/analyzed-song\.wav/i)).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: /^start analysis$/i }));
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /save project/i }).getAttribute("aria-disabled")).toBeNull();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/fresh-song\.wav/i)).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: "Open rehearsal help" }));
+    const helpDialog = screen.getByTestId("rehearsal-help-dialog");
+    expect(within(helpDialog).getByTestId("rehearsal-help-next-action").textContent).toMatch(
+      /start analysis to get tonight's first cues/i,
+    );
+    expect(within(helpDialog).queryByRole("button", { name: /show the rehearsal map/i })).toBeNull();
+  });
+
+  it("clears a stale save failure when a different local source is selected", async () => {
+    analysisMocks.selectLocalAudioSource
+      .mockResolvedValueOnce({ ok: true, bootstrap: bootstrap("project-save-a", "save-failed-song.wav") })
+      .mockResolvedValueOnce({ ok: true, bootstrap: bootstrap("project-save-b", "fresh-song.wav") });
+    analysisMocks.startAnalysisJob.mockResolvedValueOnce({
+      jobId: "job-help-save-failure",
+      state: "succeeded",
+      requestedAt: "2026-08-22T06:00:00.000Z",
+      updatedAt: "2026-08-22T06:00:01.000Z",
+      progressLabel: "Analysis ready",
+      progressStage: "ready",
+      progressPercent: 100,
+      cacheStatus: "disabled",
+      result: createDemoRehearsalSong(),
+    });
+    analysisMocks.saveProject.mockRejectedValueOnce(new Error("Disk unavailable"));
+
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/save-failed-song\.wav/i)).toBeTruthy());
+    fireEvent.click(screen.getByRole("button", { name: /^start analysis$/i }));
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /save project/i }).getAttribute("aria-disabled")).toBeNull();
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: /save project/i }));
+    await waitFor(() => expect(screen.getByRole("alert").textContent).toMatch(/disk unavailable/i));
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/fresh-song\.wav/i)).toBeTruthy());
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  it("forgets the previous analyzed song when a YouTube source is imported", async () => {
+    analysisMocks.isSupportedYoutubeUrl.mockReturnValue(true);
+    analysisMocks.selectLocalAudioSource.mockResolvedValueOnce({
+      ok: true,
+      bootstrap: bootstrap("project-local", "analyzed-song.wav"),
+    });
+    analysisMocks.startAnalysisJob.mockResolvedValueOnce({
+      jobId: "job-help-youtube-reset",
+      state: "succeeded",
+      requestedAt: "2026-08-21T05:15:00.000Z",
+      updatedAt: "2026-08-21T05:15:01.000Z",
+      progressLabel: "Analysis ready",
+      progressStage: "ready",
+      progressPercent: 100,
+      cacheStatus: "disabled",
+      result: createDemoRehearsalSong(),
+    });
+    analysisMocks.importYoutubeUrl.mockResolvedValueOnce({
+      ok: true,
+      bootstrap: bootstrap("project-youtube", "imported-song.m4a"),
+    });
+
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/analyzed-song\.wav/i)).toBeTruthy());
+    fireEvent.click(screen.getByRole("button", { name: /^start analysis$/i }));
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /save project/i }).getAttribute("aria-disabled")).toBeNull();
+    });
+
+    fireEvent.change(screen.getByRole("textbox", { name: /youtube url/i }), {
+      target: { value: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /import youtube/i }));
+    await waitFor(() => expect(screen.getByText(/imported-song\.m4a/i)).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: "Open rehearsal help" }));
+    const helpDialog = screen.getByTestId("rehearsal-help-dialog");
+    expect(within(helpDialog).getByTestId("rehearsal-help-next-action").textContent).toMatch(
+      /start analysis to get tonight's first cues/i,
+    );
+    expect(within(helpDialog).queryByRole("button", { name: /show the rehearsal map/i })).toBeNull();
+  });
+
+  it("shows a wait-only help state while a YouTube import is in flight", async () => {
+    let resolveImport: ((value: unknown) => void) | undefined;
+    analysisMocks.isSupportedYoutubeUrl.mockReturnValue(true);
+    analysisMocks.selectLocalAudioSource.mockResolvedValueOnce({
+      ok: true,
+      bootstrap: bootstrap("project-local", "local-song.wav"),
+    });
+    analysisMocks.importYoutubeUrl.mockImplementationOnce(
+      () =>
+        new Promise((resolve) => {
+          resolveImport = resolve;
+        }),
+    );
+
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/local-song\.wav/i)).toBeTruthy());
+
+    fireEvent.change(screen.getByRole("textbox", { name: /youtube url/i }), {
+      target: { value: "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /import youtube/i }));
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /import youtube/i }).textContent).toMatch(/importing/i);
+    });
+
+    fireEvent.click(screen.getByRole("button", { name: "Open rehearsal help" }));
+    const helpDialog = screen.getByTestId("rehearsal-help-dialog");
+
+    expect(within(helpDialog).getByTestId("rehearsal-help-next-action").textContent).toMatch(
+      /wait for this step to finish/i,
+    );
+    expect(within(helpDialog).queryByRole("button", { name: /^start analysis$/i })).toBeNull();
+    expect(analysisMocks.startAnalysisJob).not.toHaveBeenCalled();
+
+    resolveImport?.({ ok: true, bootstrap: bootstrap("project-youtube", "imported-song.m4a") });
+    await waitFor(() => expect(screen.getByText(/imported-song\.m4a/i)).toBeTruthy());
+  });
+
+  it("switches from score back to the workspace before showing the rehearsal map", async () => {
+    analysisMocks.selectLocalAudioSource.mockResolvedValueOnce({
+      ok: true,
+      bootstrap: bootstrap("project-map", "map-song.wav"),
+    });
+    analysisMocks.startAnalysisJob.mockResolvedValueOnce({
+      jobId: "job-help-map",
+      state: "succeeded",
+      requestedAt: "2026-08-21T05:20:00.000Z",
+      updatedAt: "2026-08-21T05:20:01.000Z",
+      progressLabel: "Analysis ready",
+      progressStage: "ready",
+      progressPercent: 100,
+      cacheStatus: "disabled",
+      result: createDemoRehearsalSong(),
+    });
+
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
+    await waitFor(() => expect(screen.getByText(/map-song\.wav/i)).toBeTruthy());
+    fireEvent.click(screen.getByRole("button", { name: /^start analysis$/i }));
+    await waitFor(() => {
+      expect(screen.getByRole("button", { name: /save project/i }).getAttribute("aria-disabled")).toBeNull();
+    });
+
+    fireEvent.click(screen.getAllByRole("button", { name: /^score$/i })[0]!);
+    await waitFor(() => expect(screen.getByTestId("score-view")).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: "Open rehearsal help" }));
+    const helpDialog = screen.getByTestId("rehearsal-help-dialog");
+    fireEvent.click(within(helpDialog).getByRole("button", { name: /show the rehearsal map/i }));
+
+    await waitFor(() => expect(screen.queryByTestId("score-view")).toBeNull());
+    await waitFor(() => expect(screen.queryByTestId("rehearsal-help-dialog")).toBeNull());
+    expect(document.activeElement?.id).toBe("main-content");
+  });
+});