feat(workspace): start analysis from the first-run card

AGENTS.md

@@ -83,6 +83,7 @@ This section applies to any agent (Claude, Codex, Cursor, opencode, ...) working
 - 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.
+- After a song is selected, customer-facing copy must enable the next rehearsal action (pick tonight's part and analyze). Do not leave a selected source on the empty-file prompt.
 - 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.
 

ARCHITECTURE.md

@@ -6,6 +6,7 @@ Last updated: 2026-03-11
 
 - Product identity, UX tone, copy rules, and prioritization tie-breakers live in `docs/brand-story.md`.
 - Future PRDs, TRDs, onboarding copy, empty states, error messages, and marketing copy should use that document as the single brand source of truth.
+- After local or YouTube source admission, the workspace first-run card names analyze as the next action and records an explicit role focus before the job starts.
 
 ## Security source
 

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- After a local song or admitted YouTube source is chosen, the workspace names Analyze this song as the next action and lets the player pick tonight's part before analysis starts.
 - Display the analyzed song tempo (BPM) as a badge in the rehearsal workspace.
 - 각 합주 역할(Role)별 개인 연습 진행도를 0~100% 범위로 기록 및 시각화할 수 있는 연습 진척도(`practiceProgress`) 트래커 기능 추가. UI 컨트롤(슬라이더 및 +/- 버튼)과 한/영 다국어 지원 포함.
 

CLAUDE.md

@@ -6,6 +6,8 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 `AGENTS.md` is the canonical agent operating guide — read and follow it before making changes. It defines the security workflow (`Security Notes`), supply-chain workflow, cross-platform build rules, GitHub bootstrap rules, code style, and safety guardrails. This file complements it with commands and architecture; when in doubt, `AGENTS.md` and the docs it references win.
 
+After a local or YouTube source is selected, the workspace must show a first-run card that starts analysis for the chosen part rather than repeating the empty-file prompt.
+
 Agent execution and delegation rules live in `docs/agents/README.md`. PR canonicalization rules live in `docs/workflow/pr-continuity.md`.
 
 ## Common commands

apps/desktop/src/App.test.tsx

@@ -402,7 +402,7 @@
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
 
     await waitFor(() => {
       expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy();
     });
 
@@ -479,7 +479,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => {
       expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy();
     });
 
@@ -519,7 +519,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => {
       expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy();
     });
 
@@ -553,7 +553,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy());
 
     fireEvent.click(screen.getByRole("button", { name: /start analysis/i }));
 
@@ -586,7 +586,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy());
 
     fireEvent.click(screen.getByRole("button", { name: /start analysis/i }));
     await waitFor(() => {
@@ -623,7 +623,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy());
 
     fireEvent.click(screen.getByRole("button", { name: /start analysis/i }));
     await waitFor(() => {
@@ -660,7 +660,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy());
 
     fireEvent.click(screen.getByRole("button", { name: /start analysis/i }));
     await waitFor(() => {
@@ -715,7 +715,7 @@
     const { unmount } = render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy());
 
     fireEvent.click(screen.getByRole("button", { name: /start analysis/i }));
     await waitFor(() => {
@@ -750,7 +750,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy());
 
     fireEvent.click(screen.getByRole("button", { name: /start analysis/i }));
 
@@ -775,7 +775,7 @@
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
     await waitFor(() => expect(screen.getByText(/late-night-set\.wav/i)).toBeTruthy());
 
     fireEvent.click(screen.getByRole("button", { name: /start analysis/i }));
     await waitFor(() => expect(tauriInvoke).toHaveBeenCalledTimes(3));
@@ -1616,4 +1616,98 @@
     expect(await screen.findByRole("heading", { name: /Score · Late Night Set/i })).toBeInTheDocument();
     expect(screen.queryByText(/Song Timeline/i)).toBeNull();
   });
+
+  it("turns a selected local song into a first-run analyze card", async () => {
+    tauriInvoke.mockResolvedValueOnce(bootstrapResponse());
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /^Choose local audio$/i }));
+
+    expect(await screen.findByRole("heading", { name: "Tonight's song is ready" })).toBeTruthy();
+    expect(screen.getByRole("button", { name: "Analyze this song" })).toBeTruthy();
+    expect(screen.getByRole("radio", { name: "Whole band" })).toHaveAttribute("aria-checked", "true");
+    expect(screen.queryByText("/Users/test/Music/late-night-set.wav")).toBeNull();
+    expect(screen.queryByRole("heading", { name: "Ready to Analyze" })).toBeNull();
+  });
+
+  it("starts analysis from the first-run card with the chosen part", async () => {
+    tauriInvoke
+      .mockResolvedValueOnce(bootstrapResponse())
+      .mockResolvedValueOnce(jobStatusResponse({
+        jobId: "job-first-run",
+        state: "queued",
+        progressLabel: "Queued for analysis"
+      }));
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /^Choose local audio$/i }));
+    expect(await screen.findByRole("heading", { name: "Tonight's song is ready" })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("radio", { name: "Lead vocal" }));
+    fireEvent.click(screen.getByRole("button", { name: "Analyze this song" }));
+
+    await waitFor(() => {
+      expect(tauriInvoke).toHaveBeenNthCalledWith(2, "start_analysis_job", {
+        request: {
+          sourceKind: "local_audio",
+          projectId: "project-1",
+          sourceLabel: "late-night-set.wav",
+          roleFocus: ["lead-vocal"]
+        }
+      });
+    });
+  });
+
+  it("lets the first-run card choose a different local file", async () => {
+    tauriInvoke
+      .mockResolvedValueOnce(bootstrapResponse())
+      .mockResolvedValueOnce(bootstrapResponse({
+        projectId: "project-2",
+        source: {
+          sourcePath: "/Users/test/Music/next-song.wav",
+          fileName: "next-song.wav",
+          extension: "wav",
+          fileSizeBytes: 2048000
+        }
+      }));
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /^Choose local audio$/i }));
+    expect(await screen.findByRole("heading", { name: "Tonight's song is ready" })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: "Choose a different file" }));
+
+    await waitFor(() => {
+      expect(screen.getByText(/next-song\.wav/i)).toBeTruthy();
+    });
+    expect(screen.getByRole("heading", { name: "Tonight's song is ready" })).toBeTruthy();
+    expect(screen.queryByText("/Users/test/Music/next-song.wav")).toBeNull();
+  });
+
+  it("keeps header start-analysis on the whole-band role until a part is chosen", async () => {
+    tauriInvoke
+      .mockResolvedValueOnce(bootstrapResponse())
+      .mockResolvedValueOnce(jobStatusResponse({
+        jobId: "job-header-role",
+        state: "queued",
+        progressLabel: "Queued for analysis"
+      }));
+    render(<App />);
+
+    fireEvent.click(screen.getByRole("button", { name: /^Choose local audio$/i }));
+    expect(await screen.findByRole("heading", { name: "Tonight's song is ready" })).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: /^Start analysis$/i }));
+
+    await waitFor(() => {
+      expect(tauriInvoke).toHaveBeenNthCalledWith(2, "start_analysis_job", {
+        request: {
+          sourceKind: "local_audio",
+          projectId: "project-1",
+          sourceLabel: "late-night-set.wav",
+          roleFocus: ["bass-guitar", "keys-right", "lead-vocal"]
+        }
+      });
+    });
+  });
 });

apps/desktop/src/App.tsx

@@ -46,7 +46,8 @@ import {
 import { createTranslator, detectPreferredLocale, type TranslationKey } from "./i18n";
 import { ScoreView } from "./features/score/ScoreView";
 import { Workspace } from "./features/workspace/Workspace";
-import { EmptyState, ErrorState, LoadingState } from "./features/workspace/WorkspaceStates";
+import { EmptyState, ErrorState, FirstRunState, LoadingState } from "./features/workspace/WorkspaceStates";
+import { roleFocusForFirstRun, type FirstRunRoleId } from "./features/workspace/firstRunRoles";
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Progress } from "@/components/ui/progress";
@@ -258,6 +259,7 @@ export function App() {
   const [renderedProgressPercent, setRenderedProgressPercent] = useState<number | undefined>(undefined);
   const [isStarting, setIsStarting] = useState(false);
   const [selectedBootstrap, setSelectedBootstrap] = useState<ProjectBootstrapSummary | null>(null);
+  const [firstRunRoleId, setFirstRunRoleId] = useState<FirstRunRoleId>("whole-band");
   const [activeAnalysisBootstrap, setActiveAnalysisBootstrap] = useState<ProjectBootstrapSummary | null>(null);
   const [selectionError, setSelectionError] = useState<string | null>(null);
   const [selectionErrorSource, setSelectionErrorSource] = useState<"local" | "youtube" | null>(null);
@@ -273,7 +275,7 @@ export function App() {
         sourceKind: "local_audio",
         projectId: selectedBootstrap.projectId,
         sourceLabel: selectedBootstrap.source.fileName,
-        roleFocus: defaultRequest.roleFocus
+        roleFocus: roleFocusForFirstRun(firstRunRoleId)
       }
     : defaultRequest;
 
@@ -420,6 +422,7 @@ export function App() {
     const selection = await selectLocalAudioSource();
     if (selection.ok) {
       setSelectedBootstrap(selection.bootstrap);
+      setFirstRunRoleId("whole-band");
       return;
     }
 
@@ -451,6 +454,7 @@ export function App() {
       const selection = await importYoutubeUrl(normalizedUrl);
       if (selection.ok) {
         setSelectedBootstrap(selection.bootstrap);
+        setFirstRunRoleId("whole-band");
         setYoutubeUrl("");
       } else {
         setSelectionError(safeErrorDetail(selection.error.message, t("youtubeImportFailed")));
@@ -514,6 +518,22 @@ export function App() {
     if (jobResult) {
       return <Workspace song={jobResult} sourceBootstrap={jobResultBootstrap} onSongUpdate={handleSongUpdate} />;
     }
+    if (selectedBootstrap) {
+      return (
+        <FirstRunState
+          fileName={selectedBootstrap.source.fileName}
+          selectedRoleId={firstRunRoleId}
+          onSelectRole={setFirstRunRoleId}
+          onStartAnalysis={() => {
+            void handleStartAnalysis();
+          }}
+          onChooseDifferentFile={() => {
+            void handleChooseLocalAudio();
+          }}
+          analysisDisabled={analysisInFlight || isStarting || isImporting}
+        />
+      );
+    }
     return <EmptyState />;
   };
 

apps/desktop/src/features/workspace/WorkspaceStates.test.tsx

@@ -0,0 +1,113 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { EmptyState, FirstRunState, LoadingState } from "./WorkspaceStates";
+
+const originalLanguage = window.navigator.language;
+
+function setNavigatorLanguage(language: string) {
+  Object.defineProperty(window.navigator, "language", {
+    configurable: true,
+    value: language
+  });
+}
+
+describe("WorkspaceStates first-run card", () => {
+  afterEach(() => {
+    setNavigatorLanguage(originalLanguage);
+  });
+
+  it("keeps the empty card text-only until a song is selected", () => {
+    render(<EmptyState />);
+    expect(screen.getByRole("heading", { name: "Ready to Analyze" })).toBeTruthy();
+    expect(screen.queryByRole("button", { name: "Analyze this song" })).toBeNull();
+  });
+
+  it("names analyze as the next action after a song is selected", () => {
+    const onSelectRole = vi.fn();
+    const onStartAnalysis = vi.fn();
+    const onChooseDifferentFile = vi.fn();
+    render(
+      <FirstRunState
+        fileName="rehearsal-take.wav"
+        selectedRoleId="whole-band"
+        onSelectRole={onSelectRole}
+        onStartAnalysis={onStartAnalysis}
+        onChooseDifferentFile={onChooseDifferentFile}
+      />
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: "Lead vocal" }));
+    fireEvent.click(screen.getByRole("button", { name: "Analyze this song" }));
+    fireEvent.click(screen.getByRole("button", { name: "Choose a different file" }));
+
+    expect(onSelectRole).toHaveBeenCalledWith("lead-vocal");
+    expect(onStartAnalysis).toHaveBeenCalledTimes(1);
+    expect(onChooseDifferentFile).toHaveBeenCalledTimes(1);
+    expect(screen.queryByText("/Users/test/Music/rehearsal-take.wav")).toBeNull();
+  });
+
+  it("shows the selected song basename without exposing local path segments", () => {
+    render(
+      <FirstRunState
+        fileName="/Users/test/Music/late-night-set.wav"
+        selectedRoleId="bass-guitar"
+        onSelectRole={vi.fn()}
+        onStartAnalysis={vi.fn()}
+        onChooseDifferentFile={vi.fn()}
+      />
+    );
+
+    expect(screen.queryByText(/\/Users\/test/)).toBeNull();
+    expect(screen.getByText("Selected song")).toBeTruthy();
+    expect(screen.getByText("late-night-set.wav")).toBeTruthy();
+    expect(document.querySelector('[data-selected-audio="late-night-set.wav"]')).toBeTruthy();
+  });
+
+  it("uses roving focus and arrow keys for the role radiogroup", () => {
+    const onSelectRole = vi.fn();
+    render(
+      <FirstRunState
+        fileName="rehearsal-take.wav"
+        selectedRoleId="whole-band"
+        onSelectRole={onSelectRole}
+        onStartAnalysis={vi.fn()}
+        onChooseDifferentFile={vi.fn()}
+      />
+    );
+
+    const wholeBand = screen.getByRole("radio", { name: "Whole band" });
+    const leadVocal = screen.getByRole("radio", { name: "Lead vocal" });
+    expect(wholeBand).toHaveAttribute("tabindex", "0");
+    expect(leadVocal).toHaveAttribute("tabindex", "-1");
+
+    wholeBand.focus();
+    fireEvent.keyDown(wholeBand, { key: "ArrowRight" });
+
+    expect(onSelectRole).toHaveBeenCalledWith("lead-vocal");
+    expect(document.activeElement).toBe(leadVocal);
+  });
+
+  it("localizes the first-run next-action copy", () => {
+    setNavigatorLanguage("ko-KR");
+    render(
+      <>
+        <EmptyState />
+        <LoadingState />
+        <FirstRunState
+          fileName="rehearsal-take.wav"
+          selectedRoleId="whole-band"
+          onSelectRole={vi.fn()}
+          onStartAnalysis={vi.fn()}
+          onChooseDifferentFile={vi.fn()}
+        />
+      </>
+    );
+
+    expect(screen.getByRole("heading", { name: "분석 준비 완료" })).toBeTruthy();
+    expect(screen.getByRole("heading", { name: "오디오 분석 중" })).toBeTruthy();
+    expect(screen.getByRole("heading", { name: "오늘 합주할 곡이 준비됐어요" })).toBeTruthy();
+    expect(screen.getByRole("button", { name: "이 곡 분석하기" })).toBeTruthy();
+    expect(screen.getByRole("button", { name: "다른 파일 선택" })).toBeTruthy();
+    expect(screen.getByRole("radio", { name: "리드 보컬" })).toBeTruthy();
+  });
+});