App Docs

App Documentation Generator

Browse a running web app, screenshot every screen, and produce documentation good enough to publish. Not a screenshot dump — a structured guide that teaches someone how to use the app.

Browser Tool Detection

Same as ux-audit — Chrome MCP, Playwright MCP, or playwright-cli.

URL Resolution

Same as ux-audit — prefer deployed/live URL over localhost.

Depth Levels

Default: standard

Workflow

1. Get App Details

Ask the user:

• App URL (required — or auto-detect from wrangler.jsonc / running dev server)
• App name (for the guide title)
• Auth — Chrome MCP uses their session; Playwright needs credentials
• Depth — quick, standard, thorough, or exhaustive
• Audience — who reads this? (end users, admins, new team members, clients)

2. Discover All Routes

Navigate the app and build a complete page inventory:

• Read the sidebar/navigation menu
• Click through all top-level items and sub-items
• Note sub-pages, tabs within pages, and nested navigation
• Check for settings, profile, admin areas, help pages
• Record the URL and purpose of each page
• Note which pages have interactive elements (forms, buttons, filters)

Create a task list to track documentation progress.

3. Document Each Page

For each page in the inventory:

a. Navigate and Prepare

• Navigate to the page
• Wait for data to load (no skeleton/spinner in screenshot)
• Resize browser to 1280x720 for consistent screenshots
• Make sure the page has realistic data — not "Test Client" or empty tables

b. Screenshot the Default State

• Take a clean screenshot showing the page populated with data
• Save to docs/screenshots/ with descriptive names

c. Write the Page Section

For each page, write:

## [Page Name]
[One sentence: what this page is for and when you'd use it]
![Page name](screenshots/NN-page-name.png)
### What You'll See[Describe the key elements: sidebar shows X, main area shows Y, toolbar has Z]
### What You Can Do[List the actions available, each as a brief description]
### How To: [Primary Action]1. [Step with screenshot reference]2. [Step]3. [Step — screenshot the result]
> **Tip:** [Helpful shortcut or non-obvious feature]

d. Document Key Workflows

For interactive pages, document step-by-step with screenshots at each significant step:

### How To: Add a New Client
1. Click the **"Add Client"** button in the top right   ![Add button location](screenshots/12-clients-add-button.png)
2. Fill in the required fields — Name and Email are required, everything else is optional   ![New client form](screenshots/13-clients-new-form.png)
3. Click **"Save"** — you'll be taken to the new client's detail page   ![Client saved confirmation](screenshots/14-clients-saved.png)
> **Tip:** You can also press **Cmd+N** from anywhere to create a new client.

e. Depth-Specific Extras

4. Write Supporting Sections

Beyond per-page documentation:

Getting Started (all depths):

## Getting Started
### Accessing [App Name]- URL: [production URL]- Supported browsers: Chrome, Firefox, Safari, Edge- Mobile: [responsive / PWA / not supported]
### Logging In[Screenshot of login page + steps]
### Your First 5 Minutes1. [First thing to do after logging in]2. [Second thing — the quick win]3. [Third thing — explore the main feature]

Navigation Guide (standard+):

## Navigation
### Sidebar[Screenshot with annotations describing each section]
### Quick Actions- **Cmd+K**: Quick switcher — jump to any page or record- **Cmd+N**: Create new [item][Other shortcuts]
### Breadcrumbs / Back Navigation[How to navigate back, where breadcrumbs appear]

Keyboard Shortcuts Reference (thorough+):

## Keyboard Shortcuts
| Shortcut | Action ||----------|--------|| Cmd+K | Quick switcher || Cmd+N | New [item] || Cmd+S | Save || Escape | Close dialog / cancel |

Troubleshooting (thorough+):

## Troubleshooting
### [Error message or symptom]**What it means**: [explanation]**How to fix**: [steps]
### Common Questions[FAQ generated from what would confuse a new user — based on the documentation process itself]

Admin Guide (exhaustive):

## Admin Guide
### User Management[How to invite users, set roles, remove access]
### Settings Reference| Setting | What it does | Default | Recommendation |[Every setting documented]
### Data Management[Export, import, backup, delete account]

5. Output Formats

Markdown (default): docs/USER_GUIDE.md

• Relative image paths: ![alt](screenshots/NN-description.png)
• GitHub-flavoured markdown — renders on GitHub, in VS Code, in Obsidian

HTML (exhaustive depth, or on request): docs/user-guide.html

• Single self-contained HTML file with Tailwind CDN
• Screenshots as relative paths (not base64 — keeps file size sane)
• Table of contents sidebar with smooth scroll
• Print-friendly CSS (@media print)
• Dark mode support

Screenshot naming: docs/screenshots/NN-section-description.png

• Numbers for sort order: 01-, 02-, 03-
• Section prefix: 01-dashboard-, 05-clients-, 12-settings-
• Descriptive suffix: -overview.png, -add-form.png, -saved-confirmation.png

6. Mockups and Diagrams

Mix screenshots with diagrams where it helps understanding:

Workflow diagrams (text-based, no external tools):

### How a Client Moves Through the System

New Enquiry → Create Client → Add Policy → Send Renewal → Archive ↓ ↓ ↓ ↓ ↓ [Email] [Client Page] [Policy Page] [Email Outbox] [Archive]

Annotated screenshots: When a screenshot needs callouts, describe them in the text:

![Dashboard](screenshots/01-dashboard.png)
The dashboard shows:- **A** (top left): Your client count and active policies- **B** (centre): Items needing attention today- **C** (right): Recent activity feed

UI element reference: For complex pages, a labelled diagram helps:

### Editor Layout
| Area | What it does ||------|-------------|| Left panel | Folder tree — organise your notes || Centre panel | Note list — shows notes in the selected folder || Right panel | Editor — write and preview your note || Top bar | Navigation, search (Cmd+K), and view toggles |

Screenshot Quality

• Resolution: 1280x720 (desktop), 375x812 (mobile)
• Data: Realistic data. Not "Test" or "Lorem ipsum". Use the app as it would actually be used.
• Timing: Wait for data to load. No spinners, no skeleton screens in final shots.
• State: Show the page in a useful state — with data populated, relevant section expanded, key feature visible
• Consistency: Same viewport size, same zoom level, same browser throughout
• Dark mode: If documenting dark mode, switch BEFORE taking screenshots — don't mix modes in one section

Autonomy Rules

• Just do it: Navigate pages, take screenshots, read page content, write documentation
• Brief confirmation: Before writing large doc files
• Ask first: Before submitting forms with real data, before clicking delete
• Thorough/exhaustive mode: Skip confirmation for writing files and filling forms with test data

Quality Bar

The documentation should be good enough that:

1. A new user can complete any task by following the guide without asking for help
2. Every screenshot has context — what am I looking at? What should I do?
3. Steps are atomic — one action per numbered step, never "click X and then fill in Y and Z"
4. Tips reveal hidden value — shortcuts, power features, things the user wouldn't discover on their own
5. Troubleshooting is real — based on actual confusing moments encountered during documentation, not hypothetical FAQs
6. It's scannable — headings, screenshots, tables, tips. Nobody reads documentation top-to-bottom. They search for what they need.