docs: add step-by-step user guides and docs-capture test suite

[lazabogdan]

Summary

Adds 24 new user guide files organized by workflow and topic, each illustrated with real app screenshots captured from the running UI. Consolidates 7 older user-guide files (agent-orchestration, configuration, getting-started, github-pr-mode, graph-view, ideation-studio, kanban) into the new workflow/topic/integration/advanced structure. Moves 4 technical docs (internal-skills, merge, execution, task-state-machine) to docs/architecture/ and reframes them for a maintainer audience. Adds a Playwright-based docs-capture test suite that automatically validates guide images stay fresh across UI changes.

User Impact

New guides — Users installing RalphX for the first time get a clear learning path:

1. Install and first run (provider setup, project creation)
2. Tour of the app (navigation, start modes, settings structure)
3. Five core workflows: planning, implementing, reviewing own work, reviewing PRs, asking questions
4. Integration guides (GitHub, Jira, Linear, ClickUp, Granola)
5. Configuration guides (choosing a provider, teaching RalphX about your project, capacity control)
6. Advanced features (task-managed delivery, automations, personas, external API access, troubleshooting)

Each workflow guide includes real app screenshots captured from the running UI, not mockups. Settings paths verified against the current app UI (7-section consolidated navigation post PR #930).

Reorganized docs — Technical reference docs (internal-skills, merge-pipeline, task-execution, task-state-machine) moved to docs/architecture/ with added maintainer-audience headers; they remain linked from the architecture index but out of the user-guide index.

README update — Simplified feature list, removed feature-tour copy, and added links to the new user guide index and per-topic guides.

Technical Context

Docs-capture suite — New frontend/tests/docs-capture/ with 5 test specs (onboarding-and-tour.spec.ts, planning-and-implementing.spec.ts, reviews-and-github.spec.ts, integrations.spec.ts, settings-panels.spec.ts) that:

• Inject mock chat scenarios and transcript state
• Hydrate artifact panes (Plan, Review tab states)
• Capture full app window at 1728px width (rendered at 1x logical pixels for legible guide use)
• Generate -docs-capture-darwin.png baselines

Image publishing pipeline — New assets/scripts/publish-guide-images.py script that:

• Compresses baselines from frontend/tests/docs-capture/snapshots/ to assets/public/guides/
• Stores baseline SHAs in assets/public/guides/baselines.sha256
• Strips the suffix and publishes as <scenario-name>.png (18 total guide images)

CI validation — New CI step checks that published guide images match their baseline SHAs, catching re-baselined screenshots not republished.

Risks / Follow-Ups

• Docs restructure is large; all markdown cross-references have been verified to resolve correctly.
• Playwright capture suite runs only on macOS (baselines carry -darwin suffix); other platforms will skip. CI gate is platform-aware.
• Guide viewport is 1728px; text and UI details have been verified as legible in all 18 screenshots.
• Future guide additions will need both markdown and a corresponding docs-capture test + image publish step before merge.

View full plan

User Guides: Prod Triage, Restructure, and Per-Guide Specs

Goal

"user guides need to be USAGE user guides not docs, not building from source etc. also we need to triage if anything is not in prod anymore or feature flagged in prod thats never reachable prod users (like extensibility) and remove stale guides. also we need a better tree/think structure for the guides… we need a list first with high level specs for the guides we should be working on, clear the existing guides, give it a structure etc."

Produce the specification, restructure, and the written core guides for docs/user-guides/: a prod-reachability triage of every current guide, a delete/salvage decision for each, a task-oriented guide tree named after what a user is trying to do, a high-level spec per guide, and finished prose for the nine P0 spine guides. P1 (integrations, configure) and P2 (advanced, troubleshooting) are specified here but written in a follow-on effort. The P0 guides ship with screenshots captured by a new Playwright docs-capture project, so guide images stay verified against the real UI rather than rotting silently.

Scope decisions

#	Decision	Source
A1	Deliverable = spec + restructure + write the core (P0) guides. P1/P2 stay specified-only.	Answered by you
A2	Direct implementation is the canonical path; task-managed delivery is a marked opt-in branch	Matches shipped defaults (Tasks is off by default)
A3	Salvage genuinely-useful reference content into docs/architecture/, then delete from docs/user-guides/	merge.md and task-state-machine.md are real maintainer reference, wrong audience
A4	Guides carry screenshots, produced by a new docs-capture Playwright suite — 14 images across the nine P0 guides, raw/unframed, dark theme, 1440×900 at 2×	Answered by you (superseded the earlier text-only decision)
A5	Each capture is both a regression baseline and the published image — UI drift fails CI	Retires the drift objection that motivated the old text-only stance
A6	Captures never render ambient mock seed data. Every image comes from a named, dedicated guide scenario the suite controls explicitly	Answered by you — the generic web mocks are not presentable enough for published guides
A7	No generic providers guide. Two specific guides instead: Using Claude Code with RalphX and Using Codex with RalphX	Answered by you. The two harnesses expose disjoint controls (permission modes vs approval policy + sandbox), so one guide could not be specific about either

A2, A3 remain assumptions; say so if either is wrong. A7's two guides stay P1 (specified only), consistent with A1 — promoting them into the written P0 set is a scope call you have not made.

---

The finding that reshapes everything

Tasks ships OFF by default. frontend/src/types/ideation-config.ts:51 sets tasksEnabled: false, and the settings row states: "Off by default. Disabling pauses all task-managed work immediately; history and worktrees are retained, and plans can still be implemented directly." (IdeationSettingsPanel.tsx:308-317)

Six of the twelve guides — execution.md, merge.md, task-state-machine.md, kanban.md, graph-view.md, agent-orchestration.md, about 163 KB of 227 KB — document that opt-in pipeline as if it were the product. A user who installs RalphX today and follows those guides cannot reach any of it.

The actual default journey is:

Plan → Approve Plan → Implement Directly → Workspace Review → Commit & Publish → Review PR

That is exactly the spine you proposed, and it happens to be the shipped default path.

---

Prod-reachability triage

Ground truth: frontend/src/components/layout/nav-items.ts:27-79 and config/ralphx.yaml:37-49.

Surface	Reachable in prod?	Gate
Agents, Ticketing, GitHub, Granola, Insights	Yes, always	visible: () => true
Automations	Yes	automations_page: true
Extensibility	No	extensibility_page: false, no in-app toggle
Activity	No	activity_page: false, no in-app toggle
Atlassian (Jira/Confluence) via API token	Yes	Settings → Integrations → Atlassian
Atlassian OAuth 2.0	No	atlassian_oauth: false
Agent Personas	Off by default, but user-togglable in Settings → Personas
Tasks / Kanban / Graph / execution / merge	Off by default, user-togglable	Settings → General → Tasks
Internal Skills	No user-facing UI at all	agent/config owned

There is no in-app "Labs" toggle for the config flags — docs/handoffs/ui-feature-flag-settings-toggle.md specs one but it is unimplemented, so extensibility_page and activity_page are unreachable for anyone running the installed app.

Two more corrections the current guides need:

• Install is Homebrew, not a git clone. docs/install/homebrew.md has the real path; getting-started.md:80-102 tells users to clone the repo and run npm run tauri dev.
• Kanban and Graph are not top-level views. They are toggles inside the Agents → Tasks artifact pane (AgentsArtifactPane.tsx:2175-2220). Two guides present them as destinations.
• docs/user-guides/ is orphaned — nothing in README.md links to it.

The root README repeats the same mistake

README.md:123-143 has the identical defect. Its First Workflow walks a new user through "Review proposals" → "Watch execution" → "Tasks move through Kanban" (:127-130) — the opt-in pipeline, presented as the first thing you do. Its Core Surfaces table lists Kanban, Graph, and Activity as surfaces (:140-142); Activity is unreachable in prod and the other two are toggles inside the Tasks artifact.

Since this effort already edits the root README to link the guide index, correcting those two sections is a small, in-scope addition — the same fix, in the doc most new users read first. It is scoped as one step and can be dropped without affecting anything else.

---

Disposition of the 12 existing guides

Guide	Verdict	Becomes
getting-started.md	Rewrite + split	01-install-and-first-run.md, 02-tour-of-the-app.md
ideation-studio.md	Rewrite	workflows/planning-a-feature.md
github-pr-mode.md	Rewrite + split	workflows/reviewing-a-pull-request.md, integrations/connect-github.md
configuration.md	Split	four configure/*.md guides; ralphx.yaml section → maintainer docs
agent-harnesses.md	Salvage → split	configure/using-claude-code-with-ralphx.md + configure/using-codex-with-ralphx.md; "Architecture direction" section dropped
kanban.md + graph-view.md	Merge	one section of advanced/task-managed-delivery.md
execution.md + merge.md	Salvage → architecture	condensed into advanced/task-managed-delivery.md; internals → docs/architecture/
task-state-machine.md	Move	docs/architecture/task-state-machine.md — real reference, wrong audience
agent-orchestration.md	Delete	architecture explainer, not usage
internal-skills.md	Move	docs/architecture/ — no prod UI exists

Net: 12 maintainer-ish documents → 0 remain in docs/user-guides/.

---

Proposed tree

docs/user-guides/
├── README.md                            ← index; "Start here" + pick-your-task map
├── 01-install-and-first-run.md
├── 02-tour-of-the-app.md
├── workflows/
│   ├── planning-a-feature.md
│   ├── implementing-a-feature.md
│   ├── reviewing-your-own-work.md
│   ├── reviewing-a-pull-request.md
│   └── asking-about-a-codebase.md
├── integrations/                        ← one dedicated guide per integration
│   ├── connect-github.md
│   ├── connect-jira-and-confluence.md
│   ├── using-jira-and-confluence.md
│   ├── connect-linear.md
│   ├── connect-clickup.md
│   ├── connect-granola.md
│   └── ticketing-dashboard.md
├── configure/
│   ├── using-claude-code-with-ralphx.md
│   ├── using-codex-with-ralphx.md
│   ├── project-setup-and-validation.md
│   └── capacity-and-concurrency.md
├── advanced/
│   ├── task-managed-delivery.md         ← opt-in; Tasks/Kanban/Graph/merge
│   ├── delivering-large-projects.md     ← the Automations surface
│   ├── personas.md                      ← opt-in; agent voice
│   └── external-access.md               ← API Keys + External MCP
└── troubleshooting.md

24 guides in three waves:

Wave	Guides	Count	This effort
P0 — the spine	README.md, 01, 02, five workflows/*, integrations/connect-github.md	9	Written
P1 — integrations + configure	6 remaining integrations/*, 4 configure/*	10	Specified only
P2 — advanced + troubleshooting	4 advanced/*, troubleshooting.md	5	Specified only

connect-github is pulled into P0 because reviewing-a-pull-request names it as a hard prerequisite, and a written guide must not depend on an unwritten one.

Those nine are what a user needs to go from install to a merged change on the default path, so they stand alone as a coherent set even before P1/P2 land. The directory skeleton and README.md router are created now so the later waves drop in without restructuring.

Each guide's spec — audience, prerequisite, exact UI surfaces walked, and the "you can now…" outcome — is in the Implementation Blueprint, along with the writing conventions the P0 prose must follow.

---

Affected Files

Path	Action
docs/user-guides/**	Delete 12 existing guides; create the new tree and write the nine P0 guides
docs/architecture/**	Receive four salvaged maintainer documents (git mv, shown as renames)
README.md	Link the guide index; correct First Workflow and Core Surfaces
frontend/playwright.config.ts	Add the docs-capture project; add testIgnore to chromium
frontend/src/api-mock/guide-scenarios.ts	New — the dedicated guide scenario fixtures (web-mode bundle only)
frontend/src/api-mock/chat-scenarios.ts	Register the guide scenarios into the existing scenario registry
frontend/tests/docs-capture/**	New capture specs, scenario-application fixtures, and committed baselines
frontend/package.json	Add the test:docs-capture script
assets/scripts/publish-guide-images.py	New publish helper (delegates to existing compress-assets.py)
assets/public/guides/**	14 published, compressed images
.github/workflows/ci.yml	Run the capture suite and check published-image freshness

No backend, schema, or runtime code is touched.

---

Decisions

Decision	Choice	Rationale
Organising principle	By user task, not by app feature	Your framing; features become sections inside task guides
Canonical path	Direct implementation	It is the shipped default (A2)
Tasks positioning	advanced/ with an explicit "turn this on first" step	Honest about the default
Unreachable features	Not documented at all	Extensibility, Activity, Atlassian OAuth, Internal Skills
Install story	Homebrew only; build-from-source stays in docs/development/	Usage guides, not build docs
Guide titles	Match your task phrasing	"Planning a feature with RalphX" etc.
Integrations	One dedicated guide per integration	Your instruction; no lumped "other trackers" guide. Jira and Confluence share a single Atlassian credential and panel, so they share one connect guide
Automations framing	"Delivering large projects with automated, supervised goals"	Your phrasing, and it matches the shipped feature: a goal decomposed into ordered items, each run gated by plan approval
Personas	Documented as advanced/personas.md	Your instruction; it is off by default but user-togglable, so it meets the enablement-step rule
Discoverability	README.md index + link from root README.md	Fixes the orphaning
Root README	Correct First Workflow + Core Surfaces in the same pass	Same defect, highest-traffic doc; scoped as one droppable step
Guide images	Captured by a new docs-capture Playwright project, raw/unframed, dark	Your answers. Reuses the existing e2e suite, page objects, and mock API rather than a new tool
Capture data source	Dedicated guide scenarios, named and seeded per capture; never the ambient mock defaults	Your answer. The generic mocks are shared with the regression suite and carry test-y strings; a published guide image needs data we control outright
Prod-chrome parity	setupCapture pins feature flags and integration state to the shipped baseline; captures gate on that state having settled	The web mock ships activityPage/extensibilityPage as true (tauri-api-core.ts:1342-1344) while config/ralphx.yaml:39-41 ships both false — today every web-target screenshot would show two nav destinations real users never have
Where guide scenarios live	frontend/src/api-mock/guide-scenarios.ts, registered into the existing scenario registry	Forced by architecture: api-mock/chat.ts (the web-mode mock) imports getMockChatScenario from chat-scenarios.ts; guide scenarios must extend MockChatScenarioName and chatScenarioFixtures there so Playwright can call window.__mockChatApi?.seedScenario() at test time. Guide scenario data is web-mode only — no Tauri command path imports it
Providers guide	Split into two specific guides, one per harness; no generic "providers" page	Your answer. Claude exposes permission modes; Codex exposes approval policy + sandbox mode + Fast mode + ultra effort. The overlap is the enable/CLI-status card, which each guide repeats rather than cross-references
Image resolution	1440×900 logical at deviceScaleFactor: 2 → 2880×1800 PNG	1440×900 is the smallest common MacBook logical size, so the layout is representative; 2× keeps it crisp on Retina when shown at 1440px wide
Capture isolation	New Playwright project, not a change to chromium	Raising DPI on the existing project would invalidate every committed regression baseline
Image count	14 across the nine P0 guides	One per decision point, not one per step
P1/P2 prose	Deferred to a follow-on effort	Keeps this effort reviewable; specs are complete enough to hand off

---

Risks And Open Questions

• P0 prose ships before P1/P2 exist, so P0 guides will link forward to files that are not yet written. Mitigation: the README.md router marks unwritten guides as coming soon rather than linking dead paths, and no P0 guide states an unwritten guide as a hard prerequisite except reviewing-a-pull-request → connect-github, which is why that one integration guide is pulled into P0 (see Blueprint §2).

• If Tasks becomes default-on, advanced/task-managed-delivery.md gets promoted to the spine — the tree absorbs that without reshuffling.

• Personas is labelled "Experimental." in its own settings row (PersonasEnableToggle.tsx:18). advanced/personas.md must carry that word so a reader knows the surface may still move.

• Automations is not a scheduler. Cron and time-based triggers are explicitly deferred beyond V1 (docs/features/automations.md:97). A guide that promises scheduling would document a feature that does not exist.

• Salvage target — docs/architecture/ has no existing state-machine or merge-internals doc, so moved files land as new documents rather than merging into existing ones.

• docs/external-mcp/ already holds solid integrator docs; advanced/external-access.md should link to them rather than restate.

Risks introduced by adding images

• Captures show scenario data, not a real project. The suite runs against dev:web, which is deterministic and free of personal paths or tokens. The ambient mock store is not used: it is shared with the regression suite and carries strings like "Execute task-mock-4" and "Widget matrix coverage" that would read as test scaffolding in a published guide. Blueprint §2c specifies dedicated guide scenarios instead — every capture names one, and a capture that renders ambient defaults is a bug the suite must catch (proof obligation 20).

• Guide scenarios add a second consumer to the mock fixtures. They live beside the regression scenarios in frontend/src/api-mock/, so a careless edit to shared helpers can move both. Mitigated by keeping guide fixtures in their own module and by obligation 21 (the visual suite's baselines must not move when guide scenarios change).

• Per-harness guides go stale faster than the rest of the tree. Model catalogs and CLI capability gates move on the vendors' cadence, not ours. Mitigation is editorial, stated in both specs: the guides explain how the catalog is gated — a model absent from the list means the installed CLI does not advertise it — rather than freezing an enumerated model list into prose.

• Some steps cannot be honestly captured. Real harness execution, real git push, and a live GitHub PR do not exist in mock mode. Those steps stay prose-only. The 14-image set is bounded by what an existing spec already proves reachable.

• Timestamp drift is not currently handled anywhere. Fixtures use new Date().toISOString() and there is no page.clock or mask: usage in frontend/tests. Relative labels are stable only because "now" always renders as "just now"; any surface showing an absolute date would break baselines overnight. §2c pins a fixed clock — this is new work, not an existing guarantee.

• The app has two independent feature-flag readers, and this effort does not fix that. useFeatureFlags.ts:20 and uiStore.ts:142 each define their own DEFAULT_FEATURE_FLAGS (both all-true for the page flags), and uiStore.ts:869 fires a second get_ui_feature_flags invoke at module load alongside the TanStack query. That is the WRITER/DRIFT pair in .claude/rules/big-pr-review-checklist.md, and it is why captures need an explicit settle gate rather than trusting first paint. Consolidating to one reader is production-code work and stays out of scope here — say so if you want it folded in, since the capture gate works either way.

• Each image is stored twice in git (test baseline + published asset). This is the deliberate price of CI-detected staleness. Worth revisiting if the image count grows well beyond 14.

• Capture cost lands on every UI PR. Any change to a captured surface now fails CI until the guide and its baseline are updated. That is the intended mechanism, but it is real ongoing cost — say so if the trade is not worth it, and the image scope can be cut to a smaller set without touching the rest of the plan.

---

Generated by RalphX

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[codecov]

Codecov Report

❌ Patch coverage is 97.72727% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
frontend/src/api-mock/guide-scenarios.ts	96.96%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!