Skip to content

0026 — User guide + in-chrome help panel

  • Status: IMPLEMENTED (2026-07-16) — Slice A + Slice B shipped (§10); 18 topics across three groups, contextual ? on focus peaking / object removal / AI review. Open questions RESOLVED: Q1 → embed topics as raw HTML fragments, NOT markdown (Matt's steer: raw HTML is "more accurate and less prone to mistakes" and unlocks richer features — so no markdown renderer; the docs site keeps its own content, we accept duplication rather than a shared renderer); Q2 → a lean, purpose-written studio user guide, NOT the whole docs (embedding the full documentation is "excessively heavy… almost unusable" — 90% isn't useful while culling). Scoped to UI definitions · settings management · UI-based how-tos; the exhaustive reference (CLI, config, architecture, dev) stays on the docs site, and the panel links out. Q3/Q4: panel + core topics first then wire contextual ?; screenshots captured from a real shoot (Matt approved using Hailey's photos). Build in stages (§9). Third of the post-0022 chrome trilogy (0024 settings tabs · 0025 notifications bell · 0026 help).
  • Why now: the trigger was concrete — neither of us could read the focus- peaking overlay without it being explained. If a tool needs explaining, it needs documenting, in detail, with a picture. More broadly the studio has grown a full toolset (verdict, rating, reasons, faces, focus peaking, before/after wiper, burst compare/select, object removal, AI review, grid size, shortcuts, export) with no user-facing guide and no in-app way to learn a control without leaving the app. This spec writes the guide and surfaces it as a help panel in the chrome, so the answer is one click from the tool.
  • Depends on: 0022/0023 (the tools to document + Icon.svelte vocabulary), 0025 (the chrome affordance pattern the help button mirrors), the docs site (Diátaxis layout under docs/), the headless Puppeteer screenshot harness (global CLAUDE.md — no GUI browser), go:embed (how the studio ships assets).
  • Non-goals: not API/developer docs (that's docs/development/); not a rewrite of the CLI command pages (they exist under docs/commands/) — this adds the studio user guide and links to them. No interactive product tour / coach-marks in this spec (possible follow-up).

1. What we're building — a lean in-app guide, not embedded docs

The point is a help panel in the chrome that answers "what is this / how do I do this" without leaving the studio and without a network. The content behind it is a purpose-written, streamlined studio user guide — deliberately not a go:embed of the whole docs/ tree. Matt's steer: shovelling the full docs into the panel is "excessively heavy… almost unusable" because ~90% of it (CLI flags, config keys, architecture, dev process) is irrelevant while culling.

So two surfaces, single-sourced from the same lean topic set:

  1. The in-chrome help panel. A slide-over Help panel (a ? button by the 0025 bell / gear) presenting the curated topics; ideally contextual (open to the focus-peaking topic from the focus-peaking tooltip).
  2. A "User guide" section on the docs site. The same curated topics, rendered into the Diátaxis site so there's a web version too.

The exhaustive reference (CLI command pages, config keys, architecture, development) is not embedded — it stays on the docs site only, and the panel links out to it for the deep stuff. This keeps the embedded surface small, fast, and actually useful in the moment.

2. Scope of the embedded guide — three buckets only

The curated guide covers exactly three things a photographer needs at the studio, each topic lean (a short definition + how to read/use it + one screenshot), no deep reference:

  1. UI definitions — what each on-screen element is and how to read it:
  2. Focus peaking (the motivating case: green = in-focus edge energy; read whether it's on the eyes/face vs background; when it lies).
  3. Verdict (Keep / Maybe / Reject), rating pips, the why-reasons chips (0020).
  4. The grid tile — score chip, best-of-burst crown, verdict stripe.
  5. The inspector rails — cull scores + capture/EXIF (0023).
  6. Before/after wiper; burst compare / select.
  7. The loupe toolbar icons; the notifications bell (0025).
  8. Settings management — the settings rail (0024) and what each leaf does: Image (cull thresholds — what each slider changes), Object removal, Eye detection, AI review (incl. the privacy note — the image leaves the machine, R-PRIV-2), Updates, Shut down. Plus per-shoot cull-profile overrides.
  9. UI how-tos — short, studio-only task walkthroughs: cull a shoot & review the grid; keep/reject & rate; handle a burst; remove an object; run an AI review; export keepers (what it writes; the non-destructive guarantee); tune a cull profile; update from the bell.

Explicitly out of the embedded guide (link out to the docs site instead): the CLI command reference, config-key reference, MCP, architecture/specs, install/ packaging, development. A topic may end with a "More: " pointer.

3. Screenshots (headless, reproducible)

  • Captured with the headless Puppeteer / chrome-headless-shell harness (global CLAUDE.md: no GUI browser on this host) against a seeded demo shoot, scripted so they can be regenerated when the UI changes (a just/script target), not hand-taken one-offs.
  • Prefer the Pro Dark theme for the gallery, with a couple of Editorial-Light shots where theme is the point. Store under docs/assets/ (the guide) and, if the panel embeds images, a bounded set under the studio's embed tree.
  • Each shot captioned and referenced from the prose (Diátaxis: show, don't just tell).

4. The help panel — shape

  • A ? button in App.svelte's header (by the bell/gear), opening a slide-over/aside panel (same scrim/elevation as 0022 menus, not a full-screen takeover — the studio stays visible behind it).
  • A topic list (searchable/filterable) → a rendered topic (prose + image + shortcut hints). Reuse Icon.svelte so a topic's icon matches its toolbar button.
  • Contextual entry (the payoff). A tool's tooltip / a small ? affordance opens the panel to that topic (e.g. focus-peaking tooltip → focus-peaking help). This is what turns "there are docs somewhere" into "the answer is on the thing I'm confused by."
  • Keyboard: ?/Esc to toggle/close (guard against the shortcut HUD's key); focus-trapped; WCAG AA both themes.

5. Content source (RESOLVED — raw HTML fragments)

Topics are authored as raw HTML fragments (topics/*.html), imported as strings (Vite ?raw) and injected with {@html}. Chosen over a markdown renderer because raw HTML is "more accurate and less prone to mistakes" and unlocks richer structure (figures + captions, kbd, tables) — and it removes a hand-rolled parser (and its bug surface) entirely. Content is trusted, in-repo, so {@html} is safe. The docs site keeps its own content; we accept that duplication rather than maintain a shared renderer/pipeline. (The earlier markdown-embed option was dropped along with its renderer + tests.)

6. Requirements

  • R-HELP-1 Every studio tool in §2 has a guide topic with a screenshot; a reader can learn how to read focus peaking (and every other non-obvious tool) from it.
  • R-HELP-2 The help panel opens from the chrome and, for tools that have a tooltip, contextually to that tool's topic; the studio remains visible behind it; keyboard-operable, WCAG AA both themes.
  • R-HELP-3 Topics are authored as trusted, in-repo HTML fragments and injected with {@html}; no markdown parser. (The docs site keeps its own content — single-sourcing was dropped per Q1.)
  • R-HELP-4 Screenshots are regenerable by a scripted headless capture, not manual — re-runnable when the UI changes (Definition-of-Done: docs updated with the code, project CLAUDE.md).
  • R-HELP-5 No behaviour change to any documented tool; the guide describes, it does not alter. Non-destructive/privacy statements in the guide match the code (R-ND-*, R-PRIV-*).

7. Testing

  • Playwright: ? opens the panel; a tool tooltip's help affordance opens the panel to the matching topic; search filters topics; Esc closes; both themes.
  • A docs/build check that every tool in the §2 inventory has a topic + an image reference (guard against a tool shipping undocumented — ties to the DoD).
  • The screenshot script runs headless in CI-like conditions (or is at least idempotent locally) and writes the expected files.

8. Open questions

  • Q1 — content source → RESOLVED: raw HTML fragments, no markdown renderer. See §5. Raw HTML is more accurate, less error-prone, and richer; the markdown renderer (and its tests) was removed. The docs site keeps its own content.
  • Q2 — panel scope → RESOLVED: a lean, curated in-app guide, NOT the whole docs. Matt's steer: embedding all of docs/ is "excessively heavy… almost unusable" (90% irrelevant while culling). The embedded guide is scoped to the three buckets in §2 — UI definitions, settings management, UI how-tos — and links out to the docs site for CLI/config/architecture/dev. This is the central scoping decision and it drives §2 and the staging in §9.
  • Q3 — contextual depth → RESOLVED: panel + core topics first, then wire contextual ? (focus peaking first, the motivating case). Staged in §9.
  • Q4 — screenshot source → RESOLVED: capture from a real shoot (Matt approved using Hailey's own photos). The seeded-demo-shoot idea is dropped for now; the harness runs against a live studio with a real shoot.
  • Slice A — the machine + the motivating topics. The ? help button + slide- over panel, the HTML-fragment topic path, the topic index, the headless screenshot-capture harness, and a first handful of UI-definition topics — focus peaking first, plus verdict/grid tile — with screenshots. Contextual ? wired for focus peaking. Proves the whole path end to end and immediately answers the question that started this.
  • Slice B — the rest of the curated content. The remaining UI-definition topics, the settings-management topics (the 0024 rail leaf-by-leaf), and the UI how-tos; contextual ? extended to the other tooltipped tools; the completeness check (every §2 topic has content + a screenshot); and a docs-site User-guide section (its own content).

Slice A lands and is reviewable before the bulk of the writing in Slice B.

10. Slice A — as built (2026-07-16)

  • Render path. Topics are HTML fragments under pkg/studio/web/src/help/topics/*.html, imported ?raw and indexed in help/topics.js ({id,title,icon,group,body}); the panel injects the body with {@html}. No markdown renderer (the earlier hand-rolled one + its tests were removed per Q1).
  • Panel. HelpPanel.svelte — a right-hand slide-over over the studio (scrim, the app stays visible), a searchable/grouped topic index → a rendered topic with an "All topics" back; Esc/click-out to close; styled prose (figures, kbd, blockquote callouts) in both themes. Driven by a tiny help store (lib/help.svelte.js: show(id?)/select/close) so any component can open it.
  • Chrome + contextual. A ? button in the header (by the bell/gear) opens the index; the loupe's focus-peaking overlay shows a "What's this?" link that opens the panel straight to the focus-peaking topic — contextual entry for the motivating case. Icon.svelte gained help.
  • Topics shipped: Focus peaking, Verdict & rating, Grid tiles (group "Reading the frame").
  • Screenshots. scripts/help-shots.mjs — a regenerable headless harness that drives a running studio and writes public/help/*.png (served at /help/… from the embed tree). Captured from a real shoot (Matt-approved).
  • Verified. 28 Playwright (2 new: index+topic render, search+Esc), 80 vitest (help-store units; markdown tests removed), svelte-check 0/0, eslint (a scripts/** node-globals override added) + prettier clean. Panel screenshotted live in dark theme.

Slice B — as built (2026-07-16)

  • Full curated guide — 18 topics in three groups: Reading the frame (focus peaking, verdict, grid tiles, cull scores & capture, the loupe toolbar, before/ after wiper, notifications bell), Settings (overview, image thresholds, local models, AI review, updates & shut down), How-to (cull & review, pick the best of a burst, remove an object, run an AI review, export keepers, tune a cull profile). Each is a raw-HTML fragment with a screenshot.
  • Screenshots. The harness (scripts/help-shots.mjs) extended to capture all the UI surfaces — settings leaves, the loupe toolbar, cull-scores rail, wiper, burst compare, export finish-bar, bell popover — each padded (element paint + its own background, so overlapping fixed chrome can't leak in and nothing crops to the edge).
  • Contextual ? extended: the loupe's object-removal hints now link to the relevant topics (and the stale "edit your config" off-hint was corrected to point at Settings → Object removal); the AI-review panel gained a ? to its how-to.
  • Completeness guard. help/topics.test.js asserts every topic is well-formed (heading + a /help screenshot), ids are unique, and the three groups are present and ordered.
  • Verified. 28 Playwright, 84 vitest (+4 topic/completeness), svelte-check 0/0, eslint + prettier clean. Full 18-topic index screenshotted live.