Detail pane states — one family, re-applied

Every state the detail pane can show, sorted into five groups by what the researcher can do about it. The Mac draws each one with the stock ContentUnavailableView that eight panes already use: an icon, a headline, one line of body, and at most one action. Where bristlenose serve has a twin, the browser frame shows the shipped status page. Nothing here is a new component. What changes is the words and the icon in each slot. Every changed string is outlined, and the string table in §5 lists them all in one place.

Artefact — what shipsCommentary — whyProposed string (owner to word)

Commentary — the rule this applies

Native primitives only, as they are today. The stock ContentUnavailableView, the run's progress on the sidebar row's status line, app-global progress in the toolbar pill, and the shipped status page for the browser. The run ring is the sidebar's own SidebarActivityRing.
How the panes are drawn. The pane sizes were measured from a real ContentUnavailableView, rendered through ImageRenderer on this Mac. The icons are the real SF Symbols, rendered from AppKit by experiments/icon-system/render_sf.swift. The status page CSS is templates/status-page.css, inlined verbatim. detail-pane-states.gen.py regenerates those three blocks.
What is not drawn. The report itself, the Welcome window, and the popovers, except where a before/after needs the popover beside the pane.

1 · The five groups

Group 1 — Nothing here yet

N00 · no selection

Drop a folder of recordings or transcripts

Bristlenose adds the folder as a project.

N04a · empty project

Drag interviews here

Recordings or transcripts.

N04b · files waiting (keep)

6 files to analyse

Analyse

N10 · several projects selected

3 projects selected

Choose one to see its report.

W02 · browser, never analysed (CLI)

localhost:8150/report/

This folder hasn’t been analysed yet

$ bristlenose run interviews/

Commentary — group 1

N00’s keys belong to this pane alone. welcome.dropFolderTitle and dropFolderHint are read only by the no-selection pane (ContentView.swift:3903). Since Model 2 (3 Oct 2026) the Welcome window has no drop card — “the Drop-a-folder card lives in the main window” (WelcomeHomeView.swift:11) — so rewording them changes nothing else. The Welcome window’s nearest line is the Ingest cell: “Drop a folder of recordings or transcripts — Bristlenose transcribes, analyses and reports back.” (welcome.home.tools.ingest.text). Checked 24 Oct 2026.
One icon for “empty”. N04 uses square.and.arrow.down today and N00 uses tray.and.arrow.down. The proposal puts the tray on both, since they are one concept.
N04b stays as it is. The row says “6 files not analysed” and the pane says “6 files to analyse”. Both are existing keys. Decided (Q5): the wording may differ, the fact may not.

Group 2 — Working

Boot · starting / loading report — bar only (decided, keep)

Queued · cover over a stale status page

Queued · position 2

Starts when the analysis before it finishes.

Analysing · cover, animation preference off or Reduce Motion

Transcribing · 3 of 8 · ~12 min left

The report opens as soon as the first interview is readable.

Analysing · the shoal, animation preference on (decorative, keep)

W-IP · browser, analysis in progress

localhost:8150/report/

Analysing interviews

Commentary — group 2

No icon while working. The ring takes the icon slot. It is SidebarActivityRing drawn at icon size and fed by the same run_progress fraction the row uses. The headline is the row’s own line, composed by RunProgressSubtitle from keys that already exist, so the pane and the row cannot disagree and there is no new headline key. Only the body is new.
Queued keeps its line. “Queued · position 2” is already the headline. The proposal adds one line of body to explain the wait.
The browser page keeps its glyph. The status template always draws its kind glyph (ℹ for info). That is left as shipped. Only the words change.
Global progress stays in the toolbar pill. The Ollama model download is the one example today. No per-project activity goes there.

Group 3 — Needs you

N02 · folder moved or deleted

Can’t find this project’s folder

It may have been moved, renamed or deleted. If you know where it is, point Bristlenose at it.

Locate…

Refused · no AI provider set up

Choose an AI provider to analyse this project

Bristlenose sends the transcripts to an AI provider such as Claude or ChatGPT. Pick one in Settings.

Set Up Provider…

Stopped · the researcher stopped it, no earlier report (with one, the pane shows that report — Q4)

Analysis stopped

Resume Analysis

W03 · browser, stopped

localhost:8150/report/

Analysis stopped

Commentary — group 3

Each pane names the one door. Locate… and Set Up Provider… are the buttons the popover already carries, under their existing keys. The pane reuses them and adds nothing.
Stopped becomes neutral. Today the status page shows a warning glyph while the row shows none. Stopping is something the researcher did, not a fault, so the page takes the info kind and the row stays as it is. Decided (Q4): when an earlier report exists the pane shows that report and the row says Stopped; this pane is for a stop with no report yet. That is D4-B for cancelled runs only (docs/design-project-condition.md §6.1); D4 for failed runs stays open.

Group 4 — Can’t reach it

N01 · drive not connected

“Samsung T7” isn’t connected

Reconnect to continue.

N01n · network share unreachable

“server.local” can’t be reached

Reconnect to continue.

Stranded · the run lost its process

The analysis stopped before it finished

The app quit, or the Mac lost power.

Resume Analysis

W-stranded · browser

localhost:8150/report/

The analysis stopped before it finished

N08 · analysis engine failed to start — plain family (decided Q2; buttons: docs/design-feedback-native.md § “Feedback and problem reports” (mockup n08-button-set.html))

Couldn’t start Bristlenose

Bristlenose stopped before it finished starting (code 1).

RetryShow details

Report crash · keep (decided 20–21 Oct)

This report couldn’t be shown.

Commentary — group 4

The drive and the share get separate headlines. Today both say “Connect the drive to access this project.” Each proposed headline names the thing by its own name; the body is one shared line, “Reconnect to continue.” (owner, 24 Oct 2026), so both read the drive’s key. The row lines are kept as they are.
N05 (loose-file project) is removed, 22 Oct 2026. Every study is a folder study: UnsupportedSubsetView and its unsupportedSubset.* keys were deleted (d94edf6d1), and nothing has created a loose-file study since 10 Jul 2026 (0ac2136d).
N03 (iCloud) is removed, 22 Oct 2026. The in-iCloud state, its pane and the row’s cloud glyph were deleted (bbf75243). A cloud folder that has gone is N02 (Project Moved or Deleted, Locate…); an evicted one still exists and is simply ready. No cloud pane, glyph or provider advice — docs/design-cloud-files.md.
Stranded’s body is Mac-only. “The app quit, or the Mac lost power.” names the Mac and its app, so the browser twin has no body (a dt()/ct() fork, docs/platform-text-map.md). The button is Resume Analysis (owner, 24 Oct 2026): Analyse already resumes from the partial output, so the button names what it does.
N08 carries two buttons in both versions. Retry is the action. Show details is BootView’s existing disclosure, not a second action.

Group 5 — It broke

Failed · the run failed; the remedy decides the button

The analysis didn’t finish

Claude wouldn’t accept the API key. Check it in Settings ▸ LLM Provider.

Set Up Provider…Show details

W04 · browser, failed

localhost:8150/report/

The analysis didn’t finish

Claude wouldn’t accept the API key.

Show details

category: auth

W05 · build incomplete (dev only) — today

localhost:8150/report/

Build incomplete

The Bristlenose React bundle is missing from this build. Serve mode refuses to start without it.

If you are running the desktop app, this build is broken — reinstall or report a bug.

If you are a developer: run npm run build in frontend/ and restart bristlenose serve.

W05 · restyle only — same English, status-page template

localhost:8150/report/

Build incomplete

The Bristlenose React bundle is missing from this build. Serve mode refuses to start without it.

Show details

If you are running the desktop app, this build is broken — reinstall or report a bug.

If you are a developer: run npm run build in frontend/ and restart bristlenose serve. If running from the PyInstaller sidecar, check that bristlenose/server/static/ is in the spec’s datas.

BUG-3 class — see the C3 smoke test post-mortem for context.

Commentary — group 5

One vocabulary: the popover’s. The pane’s body is the popover’s reason sentence, and the button is chosen by the remedy, as in error-patterns-and-chrome-crash.html: a remedy-1 cause gets the button that goes to the fix (Set Up Provider…, Locate…), a remedy-2 cause gets Retry, and the others get no button.
The remedy sentence is not shipped yet. “Claude wouldn’t accept the API key. Check it in Settings ▸ LLM Provider.” comes from analysis-failure-states.html § D. The popover ships pipeline.failure.auth, which says “Your {{provider}} key was rejected.” Either wording gives one vocabulary. The owner words it once, and both surfaces then read the same key (see §2.3).
Show details shows the English forensic record. It is the existing disclosure, revealing what _format_cause writes (category, code, stage, provider, message). The record stays English, as forensic records do.
W05 is restyled only. The text stays English (it is dev-only), and the hard-coded inline style is replaced by the status-page template.

2 · Before and after — the four worst

2.1 · iCloud — removed 22 Oct 2026: the in-iCloud pane was deleted (bbf75243), so there is no before or after. A gone cloud folder is N02; policy docs/design-cloud-files.md.

2.2 · Refused run — before: the reason is only on the row

before — the pane is the serve’s status page

Not analysed yet.

after — the popover’s reason, and its existing door

Choose an AI provider to analyse this project

Bristlenose sends the transcripts to an AI provider such as Claude or ChatGPT. Pick one in Settings.

Set Up Provider…

2.3 · Failed run — before: two vocabularies for one state

before — pane (serve’s status page)

Last run failed.

Error code: 401 - {'type': 'error', 'error': {'type': 'authentication_error', 'message': 'invalid x-api-key'}}

Show details

category: auth

before — the row’s popover

after — pane

The analysis didn’t finish

Claude wouldn’t accept the API key. Check it in Settings ▸ LLM Provider.

Set Up Provider…Show details

after — the row’s popover, same sentence

2.4 · Analysis engine failed to start (BootView) — decided Q2: option B, the plain family

before / option A — brand block kept

Bristlenose

Sensemaking for User Research

Couldn’t start Bristlenose

Bristlenose stopped before it finished starting (code 1).

RetryShow details

option B — the plain family

Couldn’t start Bristlenose

Bristlenose stopped before it finished starting (code 1).

RetryShow details

Commentary — §2

2.1: removed 22 Oct 2026 — the iCloud pane no longer exists (see above).
2.2: the Mac refuses the run, and the serve can only say “Not analysed yet.” because it cannot know why. The reason stayed on the row. The proposal has the Mac take the pane natively for this state (Q1), with the popover’s door.
2.3: the pane printed the provider’s raw text under “Last run failed.”, while the row’s popover said “Your Claude key was rejected.” After the change both read the popover’s sentence. The raw text moves behind Show details, where the forensic record already lives.
2.4: option B drops the app icon, the wordmark and the tagline. Its strings (boot.failedTitle, boot.failure.*, boot.retry, boot.showDetails) are all kept, and only boot.tagline would lose its one consumer here. Retry stays the default button, as .keyboardShortcut(.defaultAction) makes it today.

3 · The analysing pane — queued, transcribing, then the report

1 · queued behind another study

Queued · position 2

Starts when the analysis before it finishes.

2 · transcribing — the row’s line under the ring

Transcribing · 3 of 8 · ~12 min left

The report opens as soon as the first interview is readable.

3 · first interview readable — the pane hands over to the Sessions lens

Commentary — §3

Nothing here is a new surface. Frames 1 and 2 are the two existing RunCover cases (DetailPaneKind.runCover), with a body line added and the ring standing in for waveform. Frame 3 is the shipped progressive hand-over (shoalTakesPane gives way when sessionsReadable > 0, design-progressive-lenses.md). It is drawn here only as a schematic, so the sequence reads end to end.
The row keeps narrating throughout. Its ring and line carry on after the hand-over, because the pane is now the report and the row is where the run’s progress lives.
The body promises what frame 3 delivers. “The report opens as soon as the first interview is readable” is a promise only if the Mac performs this hand-over for every run, the cover path included (shoal off or Reduce Motion). That needs checking when this is built.

4 · Icon sheet — SF Symbol and its Lucide twin, one concept each

Concept	SF Symbol (Mac)	Lucide (browser)	Used by	Today
Empty — add interviews	`tray.and.arrow.down`	`inbox`	N00, N04a, N04b	`square.and.arrow.down` on N04
Several selected	`square.stack`	`layers`	N10	same
Queued	`clock`	`clock`	Queued cover	same
Working	no icon — the run ring takes the slot		Analysing cover	`waveform`
Folder moved	`questionmark.folder`	`folder-search`	N02	same
Needs a provider	`key`	`key-round`	Refused	— (status page ℹ)
Stopped	`stop.circle`	`circle-stop`	Stopped	— (status page ⚠)
Drive not connected	`externaldrive.badge.xmark`	`hard-drive`	N01	`externaldrive.trianglebadge.exclamationmark`
Share unreachable	`network.slash`	`wifi-off`	N01n	the drive’s icon
Stopped unexpectedly / failed	`exclamationmark.triangle`	`triangle-alert`	Stranded, Failed, N08 (option B)	— (status page ⚠ / ✗; N08 the app icon)

Commentary — §4

Where the Lucide twin is used. The browser’s status page draws a text glyph (ℹ ⚠ ✗, CLI_GLYPH), not an icon, and this proposal leaves it that way. The Lucide twin is the name the SPA reaches for when the same concept appears in the report. Listing both keeps one concept to one picture on each platform.
Three pane icons change. N04 moves to the tray, N01 to a drive with an ×, and the analysing cover moves from waveform to the ring. Every other icon is the one the pane already uses. The SF Symbols were rendered on this Mac from AppKit. The Lucide icons come from the installed lucide-react.

5 · String table — edit the English here

E existing key, reworded N new key (the suggested key name is in amber) K keep as shipped. Each E or N row is a change across 21 locales.

State	Element	Key	Current	Proposed
Group 1 — Nothing here yet
N00 no selection	headline	desktop.welcome.dropFolderTitle	Drop a folder	Drop a folder of recordings or transcripts	E
	body	desktop.welcome.dropFolderHint	Drag a folder of recordings or transcripts here to add it as a project.	Bristlenose adds the folder as a project.	E
N04a empty	headline	desktop.chrome.dragInterviews	Drag Interviews Here	Drag interviews here	E
	body	desktop.chrome.dragInterviewsDescription	Add interview recordings or transcripts to get started.	Recordings or transcripts.	E
N04b files waiting	headline	desktop.chrome.filesToAnalyse_one / _other	1 file to analyse / {{count}} files to analyse	—	K
	action	desktop.menu.project.analyse	Analyse	—	K
N10 multi-select	headline	desktop.chrome.multipleSelected	%d items selected	{{count}} projects selected (becomes a plural set, `_other` etc.)	E
	body	desktop.chrome.multipleSelectedHint	Select a single project to view its report.	Choose one to see its report.	E
W02 CLI, never run	headline	server.statusPage.noRunCliShort	Nothing to see here, yet.	This folder hasn’t been analysed yet	E
	body	literal, not localised	$ bristlenose run interviews/	—	K
Group 2 — Working
Boot	—	desktop.boot.startingSidecar / loadingReport	not drawn (bar only)	—	K
Queued	headline	desktop.chrome.pipeline.queuedPosition	Queued · position {{position}}	—	K
	body	desktop.chrome.pipeline.queuedHint	(none)	Starts when the analysis before it finishes.	N
Analysing	headline	desktop.chrome.pipeline.analysing → RunProgressSubtitle (stage.* · sessionsCount · etaMinutes)	Analysing…	the row’s own line, e.g. Transcribing · 3 of 8 · ~12 min left — no new key	K
	body	desktop.chrome.pipeline.analysingHint	(none)	The report opens as soon as the first interview is readable.	N
W-IP in progress	headline	server.statusPage.inProgressShort	Analysing…	Analysing interviews	E
Shoal	—	—	no text	—	K
Group 3 — Needs you
N02 moved	headline	desktop.chrome.projectMoved	Project Moved or Deleted	Can’t find this project’s folder	E
	body	desktop.chrome.projectMovedDescription	The project folder couldn’t be found. It may have been moved or deleted.	It may have been moved, renamed or deleted. If you know where it is, point Bristlenose at it.	E
	action	desktop.chrome.locate	Locate…	—	K
Refused, no provider	headline	desktop.chrome.providerNeeded (pane today: server.statusPage.noRunDesktopHasInterviews)	Not analysed yet.	Choose an AI provider to analyse this project	N
	body	desktop.chrome.providerNeededHint	(none — the reason is only on the row: “Provider not set up”)	Bristlenose sends the transcripts to an AI provider such as Claude or ChatGPT. Pick one in Settings. (two examples, not the list — decided Q6)	N
	action	desktop.pipeline.diagnostic.action.setUpProvider	Set Up Provider… (popover only)	— (reused in the pane)	K
Stopped	headline	server.statusPage.cancelledShort (+ desktop.chrome.stoppedTitle for the native pane)	Last run was cancelled.	Analysis stopped	E
	body	server.statusPage.cancelledLong	Re-run when ready.	— no body; the key is retired	E
	action	desktop.chrome.resumeAnalysis	—	Resume Analysis (the same key as the stranded button; Analyse after a stop resumes from the partial output, `adaa97e5`)	N
Group 4 — Can’t reach it
N01 drive	headline	desktop.chrome.projectUnavailable + the volume name as a second line	Project Unavailable / Samsung T7	“{{name}}” isn’t connected	E
	body	desktop.chrome.projectUnavailableHint	Connect the drive to access this project.	Reconnect to continue.	E
N01n network share	headline	desktop.chrome.shareUnreachable	(the drive’s: Project Unavailable / server.local)	“{{host}}” can’t be reached	N
	body	desktop.chrome.projectUnavailableHint	Connect the drive to access this project.	Reconnect to continue. (the drive’s key: one body for both)	K
Stranded	headline	server.statusPage.strandedShort · desktop.pipeline.failure.stranded	Analysis stopped unexpectedly.	The analysis stopped before it finished	E
	body	server.statusPage.strandedLong (+ desktop.chrome.strandedHint, the Mac form)	Re-run when ready.	Mac: The app quit, or the Mac lost power. Browser: — no body; `strandedLong` is retired	E
	action	desktop.chrome.resumeAnalysis	—	Resume Analysis (Analyse after a stranded run resumes from the partial output, `adaa97e5`; the menu item for the same command stays Analyse)	N
N08 engine failed	headline · reason · buttons	desktop.boot.failedTitle · boot.failure.* · boot.retry · boot.showDetails	Couldn’t start Bristlenose · e.g. Bristlenose stopped before it finished starting (code 1). · Retry · Show details	—	K
	tagline	desktop.boot.tagline	Sensemaking for User Research	no longer drawn here (option B, decided Q2)	K
Report crash	body · button	common.labels.reportError · buttons.retry	This report couldn’t be shown. · Retry	— (settled 20–21 Oct)	K
	row · popover	desktop.pipeline.diagnostic.header.reportError · desktop.pipeline.diagnostic.reportError	Report couldn’t be shown · Your analysis is safe — only the display failed. …	— (settled)	K
Lens / part crash	body	common.labels.lensError · common.labels.partError	This lens couldn’t be shown. Try again, or choose another lens. · This couldn’t be shown.	— (settled)	K
Group 5 — It broke
Failed	headline	server.statusPage.failedShort (+ desktop.chrome.failedTitle)	Last run failed.	The analysis didn’t finish	E
	body	today: raw `cause.message`; proposed: the popover’s reason key, e.g. desktop.pipeline.failure.auth	Error code: 401 - {'type': 'error', …} (provider’s raw text). The popover today says: Your {{provider}} key was rejected.	Claude wouldn’t accept the API key. Check it in Settings ▸ LLM Provider. (from analysis-failure-states.html § D; one sentence per cause, read by both the popover and the pane; the browser drops the Settings clause)	E
	action	desktop.pipeline.diagnostic.action.setUpProvider · desktop.boot.retry	—	Set Up Provider… or Retry, by remedy	K
	disclosure	server.statusPage.showDetails · desktop.boot.showDetails	Show details	—	K
W05 build incomplete	page	app.py literal (dev only)	Build incomplete + three paragraphs	— (restyle only)	K

Commentary — §5

Count. 16 rows reword an existing key, 2 retire one (the stopped and stranded bodies) and 7 add a new one (two of them share one key, Resume Analysis). Three rows also add a native twin for the Mac pane (the stopped headline, the stranded body, the failed headline), so that is 9 new keys in all, each in 21 locales. The suggested key names (amber) follow their neighbours’ namespaces. They are placeholders for whoever builds this, not part of the decision.
Casing. Every proposed Mac headline is in sentence case. That ends the native/server split the June catalogue recorded (“Project Moved or Deleted” beside “Last run failed.”). Buttons stay in Title Case. Decided (Q3): sentence case, no full stop — the HIG’s Writing rule, one style per element type. Proposed headlines also drop the full stop, as ContentUnavailableView titles do on macOS.
Interpolated names. “{{name}}” and “{{host}}” are typeset with each locale’s own quotation marks, so the curly quotes are part of the translated string, not code.

6 · Questions for you — answered 24 Oct 2026

Commentary — decisions this mockup needed, with the owner’s answers

Native or unified copy only? Should the Mac take over the failed, stopped and stranded panes natively, as drawn? The alternative keeps the serve’s status page in the pane and only unifies its words with the popover’s.
Answer: native, as drawn. The Mac draws failed, stopped, stranded and refused with ContentUnavailableView; the browser keeps the status page with the same words.
Brand on the engine-failed pane? Should it keep the app icon, wordmark and tagline (option A), or join the plain family (option B, §2.4)?
Answer: option B, the plain family. Starting is already bar-only, so no pane keeps the brand block. N08’s buttons are decided elsewhere: docs/design-feedback-native.md § “Feedback and problem reports” (mockup n08-button-set.html).
Casing. Should Mac pane headlines be sentence case, with Title Case kept for buttons only?
Answer: sentence case, no full stop; buttons Title Case. The HIG’s Writing page asks for one style per element type, used consistently; its Alerts page (fragment → Title Case, sentence → sentence case with a stop) was considered and not taken.
Stopped. Should it show a neutral pane with Analyse, or show the previous report when one exists?
Answer: the previous report when one exists, the row saying Stopped; the neutral “Analysis stopped” pane with Resume Analysis only when there is no report. This is D4-B for cancelled runs only (docs/design-project-condition.md §6.1); D4 for failed runs is not decided here.
Pane and row wording. May a pane headline differ from the row’s sentence for the same state? For example “6 files to analyse” beside “6 files not analysed”, or “Choose an AI provider…” beside “Provider not set up”.
Answer: yes — the wording may differ, the fact may not. The row is the status, the pane the instruction; queued and analysing keep the row’s own line.
Naming providers. May the no-provider sentence name the four providers? Each new provider would then mean a copy change in 21 locales.
Answer: two examples, not the list — “Bristlenose sends the transcripts to an AI provider such as Claude or ChatGPT. Pick one in Settings.” It stays true as providers are added, and with Local.
Multi-select. Should the multi-select pane stay a dead end, as drawn (no action)?
Answer: a dead end, as drawn. Actions on several projects stay in the sidebar’s context menu and the Project menu.

Commentary — owned elsewhere, linked not duplicated

N08’s buttons and the whole-report crash pane’s (Retry first; after a failed Retry, Show details · Send Feedback…): docs/design-feedback-native.md § “Feedback and problem reports” (mockup n08-button-set.html). Stranded-run copy was being worded in another session; the owner set it here on 24 Oct 2026 (body “The app quit, or the Mac lost power.”, button Resume Analysis; sleep never strands a run, so “the Mac may have slept” was dropped), so that session should take these words.