# Scan project placement: toolbar action plus first-scan empty-state CTA

## Traceability

- Spec ID: `2026-09-10-studio-scan-action-placement`
- Status: Implemented
- Request: decide where the Studio "Scan project" control belongs, and move it
- AI involvement: analysis, implementation, and local validation by an AI agent

## Intent

`Scan project` is currently a permanent full-width control in the sidebar scope
region, wedged between the Project switcher and the date range. That region has
one stated job: the Project says *where* to look and the date range says *when*.
Scan is neither. It is the data-ingest action, and its placement misreads its
frequency in both directions.

Two facts from the current code set the frequency:

- `scanRequired` is set to `true` in exactly one place, `restoreActiveProject`,
  which runs once at boot. Switching Projects goes through `activateProject` and
  scans for real. So "first scan" is a once-per-launch blocking state.
- Live updates cover **artifacts only** — a recursive `watchDirectory` plus the
  `/api/artifacts/events` SSE stream. Sessions, Git history, Skills, MCP, hooks,
  and plugins have no watcher. Every one of them refreshes only when the reader
  presses Scan.

Studio exists to observe Coding Agent Sessions. The reader's loop is: the Agent
finishes a turn, the reader wants the new Sessions and commits, and Rescan is the
only way to get them. That makes Rescan one of the highest-frequency shell-level
actions in the product, not a rare maintenance action.

Two frequencies, so two hosts:

- Steady-state Rescan is frequent and crosses every View, so it belongs in the
  window toolbar, where it stays reachable at every breakpoint.
- First scan is a once-per-launch blocking state, so its call to action belongs
  in the main-area empty state the reader is already looking at.

The sidebar scope region keeps only *where* and *when*.

## Acceptance Scenarios

- **AC-1** Given a scannable local Project, when the shell renders at wide,
  compact, or narrow width, then a Scan control is present in the toolbar and no
  Scan control is rendered in the sidebar.
- **AC-2** Given a restored Project that has not been scanned, when a Project
  View is shown, then the main-area empty state offers a Scan button that starts
  the scan, and the empty-state copy does not direct the reader to the sidebar.
- **AC-3** Given a scan in flight, when the reader inspects the toolbar control,
  then it is disabled, reports `aria-busy`, and exposes its progress through a
  status region while showing a spinner in place of its icon.
- **AC-4** Given a completed scan, when the toolbar control is read, then its
  accessible name is the Rescan wording and it is enabled again.
- **AC-5** Given a narrow layout, when the reader reaches the toolbar Scan
  control, then it is reachable without first opening the sidebar overlay.
- **AC-6** Given the active View publishes its own toolbar action, when both are
  present, then the View action and the shell Scan control are both visible and
  right-aligned, and the Scan control stays right-aligned when the View slot is
  empty.

## Non-goals

- Adding a watcher or SSE stream for Session discovery. That is the real fix for
  manual refresh pressure, and it is tracked separately; this change only places
  the control that exists today.
- Auto-scanning on boot. The restore path deliberately does not scan, so that a
  stale catalog cannot stop Studio from starting.
- Changing what a scan collects, or the `POST /api/projects/:id/scan` contract.
- Touching the Project switcher menu, which stays a Project-selection menu.
- Changing the date range control or the sidebar View list.

## Plan and Tasks

1. `ProjectSidebar.tsx`: drop the `studio-project-scan` block and the
   `canScanProject` / `scanRequired` / `scanning` / `onScanProject` props. Remove
   the now-unused `ArrowClockwise` import.
2. `App.tsx`: add a `ProjectScanAction` shell control rendered in the context bar
   after the View action slot, and pass the scan action into the scan-pending
   `EmptyWorkspace` so the blocking state carries its own CTA.
3. `shell.css`: add `.studio-shell-actions`, keep it right-aligned when the View
   slot is empty via `.studio-context-actions:empty + .studio-shell-actions`, and
   delete the `.studio-project-scan` rules.
4. i18n `en` / `zh-CN`: rewrite `scanPendingDetail` so it describes the scan
   instead of pointing at the sidebar.
5. `test/browser/project-scan.spec.mjs`: drop the nav-toggle prelude, assert the
   toolbar control at every layout, and assert the empty-state CTA starts a scan.

## Test and Review Evidence

- `npm run harness-studio:build`
- `npx vitest run --config vitest.config.mjs packages/harness-studio/test`
- `npx playwright test test/browser/project-scan.spec.mjs` from
  `packages/harness-studio` — 6 layout/theme combinations, screenshots retained
- Console and page errors asserted empty in the browser spec