HawkeyePierce89 · HawkeyePierce89 · Nov 8, 2025 · Nov 8, 2025
diff --git a/.github/workflows/sync-wiki.yml b/.github/workflows/sync-wiki.yml
@@ -22,6 +22,9 @@ jobs:
     - name: Copy documentation to Wiki
       run: |
         cp docs/*.md wiki-repo/
+        if [ -d docs/images ]; then
+          cp -r docs/images wiki-repo/
+        fi
 
     - name: Commit and push to Wiki
       working-directory: wiki-repo

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -72,6 +72,55 @@ DEBUG=true npm run test:e2e
 - **Puppeteer**: Browser automation for E2E testing
 - Tests organized by functionality for easy maintenance and selective execution
 
+## Documentation
+
+The project includes comprehensive documentation in the `docs/` folder, which is automatically synced to the GitHub Wiki.
+
+### Documentation Structure
+
+```
+docs/
+├── Home.md                      # Main documentation landing page
+├── Getting-Started.md           # Installation and first steps
+├── Variables.md                 # Variables system documentation
+├── Auto-Refresh-Tokens.md       # Auto-refresh feature guide
+├── Advanced-Features.md         # Power user features
+├── Examples.md                  # Real-world configuration examples
+├── FAQ.md                       # Frequently asked questions
+└── images/                      # Screenshots for documentation
+    ├── README.md                # Screenshot catalog
+    └── *.png                    # Screenshot files (15 files)
+```
+
+### Generating Documentation Screenshots
+
+```bash
+# Generate all documentation screenshots
+npm run screenshots
+```
+
+This command:
+1. Builds the extension (`npm run build`)
+2. Launches Chrome with the extension loaded (via Puppeteer)
+3. Creates various UI configurations (rules, variables, auto-refresh setups)
+4. Captures screenshots in 1280x800 resolution (light theme)
+5. Saves them to `docs/images/`
+
+**Screenshot Generation Script:** `scripts/generate-screenshots.ts`
+- Reuses test helpers from `tests/helpers/` (browser launch, configuration)
+- Automatically creates 15+ screenshots covering all major features
+- Screenshots are version-controlled and should be updated when UI changes
+
+### Wiki Synchronization
+
+Documentation is automatically synced to GitHub Wiki via GitHub Actions:
+- **Workflow:** `.github/workflows/sync-wiki.yml`
+- **Trigger:** Push to `master` branch with changes in `docs/**`
+- **Synced content:**
+  - All `*.md` files from `docs/`
+  - All images from `docs/images/`
+- **Requirements:** `WIKI_TOKEN` secret must be configured in repository settings
+
 ## Architecture
 
 ### Core Components

diff --git a/docs/Auto-Refresh-Tokens.md b/docs/Auto-Refresh-Tokens.md
@@ -64,6 +64,10 @@ Transform Response: access_token
 3. ModHead extracts `new_token_123` using the transform path
 4. Variable `accessToken` is updated to `new_token_123`
 
+Here's what the auto-refresh configuration looks like:
+
+![Auto-Refresh Configuration](images/11-auto-refresh-config.png)
+
 ## HTTP Methods
 
 ModHead supports all standard HTTP methods for refresh requests.

diff --git a/docs/Examples.md b/docs/Examples.md
@@ -130,6 +130,8 @@ All requests to `localhost:*` will include CORS headers, allowing your local fro
 
 These headers are added to **requests**, not responses. For proper CORS handling, your server must return the appropriate CORS headers in **responses**. However, this configuration can help with certain testing scenarios.
 
+![CORS Headers Configuration](images/15-cors-headers.png)
+
 ---
 
 ## 4. OAuth 2.0 Token Refresh
@@ -185,6 +187,8 @@ Headers:
 - Long-running development sessions
 - Testing OAuth flows
 
+![OAuth 2.0 Configuration](images/13-oauth-example.png)
+
 ---
 
 ## 5. Multi-Stage Authentication
@@ -579,6 +583,8 @@ Headers:
 - Long development sessions
 - Avoiding manual token updates
 
+![JWT Token with Auto-Refresh](images/12-jwt-refresh-example.png)
+
 ---
 
 ## Combining Examples

diff --git a/docs/Getting-Started.md b/docs/Getting-Started.md
@@ -45,6 +45,10 @@ There are two ways to access ModHead's options page:
 1. **Click the extension icon** in the Chrome toolbar
 2. **Right-click the icon** → Select "Options"
 
+When you first open the options page, it will be empty:
+
+![Empty Options Page](images/01-options-page-empty.png)
+
 ## Creating Your First Rule
 
 Let's create a simple rule to add a custom header to all requests to `httpbin.org`.
@@ -54,6 +58,8 @@ Let's create a simple rule to add a custom header to all requests to `httpbin.or
 1. Click the **"Create Rule"** button
 2. The rule editor modal will open
 
+![Rule Editor Modal](images/02-rule-editor-empty.png)
+
 ### Step 2: Configure Basic Settings
 
 **Rule Name:** Give your rule a descriptive name
@@ -81,7 +87,9 @@ This will match all URLs that start with `httpbin.org` (e.g., `httpbin.org/get`,
 
 ### Step 5: Save the Rule
 
-Click **"Save"** to create the rule.
+Click **"Save"** to create the rule. Your new rule will appear on the options page:
+
+![Rule Card with Single Header](images/03-rule-single-header.png)
 
 ## Understanding URL Pattern Matching
 
@@ -117,6 +125,10 @@ Matches URLs that exactly match the specified pattern.
 
 **Use case:** Target a specific endpoint
 
+Here's an example of a rule with multiple target domains using different match types:
+
+![URL Pattern Matching Examples](images/06-url-pattern-matching.png)
+
 ## Multiple Target Domains
 
 A single rule can have multiple target domains with different match types:
@@ -147,6 +159,10 @@ Header 3:
   Value: v2
 ```
 
+Here's what a rule with multiple headers looks like:
+
+![Rule with Multiple Headers](images/14-multiple-headers.png)
+
 ## Testing Your Rule
 
 Let's verify that your rule is working:

diff --git a/docs/Home.md b/docs/Home.md
@@ -35,6 +35,8 @@ ModHead is a Chrome extension that allows you to dynamically modify HTTP request
 - Enable/disable rules with a single click
 - Visual feedback with toast notifications
 
+![ModHead Options Page](images/05-multiple-rules.png)
+
 ## Documentation Navigation
 
 ### Getting Started

diff --git a/docs/Variables.md b/docs/Variables.md
@@ -26,6 +26,10 @@ Variables are named placeholders that store values you can reuse throughout your
 
 4. **Click "Save"**
 
+Here's the variable editor interface:
+
+![Variable Editor](images/08-variable-editor-empty.png)
+
 ### Sensitive Variables
 
 Sensitive variables are displayed with password masking in the UI to prevent shoulder-surfing.
@@ -46,6 +50,10 @@ When enabled, the value will display as `••••••••` in the UI but
 - Client secrets
 - Any confidential data
 
+Here's how sensitive variables appear in the UI:
+
+![Sensitive Variable Masked](images/10-sensitive-variable-masked.png)
+
 ## Using Variables in Headers
 
 Use the `${variableName}` syntax to reference variables in header values.
@@ -109,6 +117,14 @@ Header Value: user=${userId};session=${sessionId}
 X-Session-Info: user=12345;session=xyz789
 ```
 
+Here's an example of using variables in header values:
+
+![Variable Usage in Headers](images/09-variable-in-header.png)
+
+The variables section showing multiple variables:
+
+![Variables Section](images/07-variables-section.png)
+
 ## Variable Naming Best Practices
 
 ### Valid Names

diff --git a/docs/images/01-options-page-empty.png b/docs/images/01-options-page-empty.png
diff --git a/docs/images/02-rule-editor-empty.png b/docs/images/02-rule-editor-empty.png
diff --git a/docs/images/03-rule-single-header.png b/docs/images/03-rule-single-header.png
diff --git a/docs/images/04-rule-card.png b/docs/images/04-rule-card.png
diff --git a/docs/images/05-multiple-rules.png b/docs/images/05-multiple-rules.png
diff --git a/docs/images/06-url-pattern-matching.png b/docs/images/06-url-pattern-matching.png
diff --git a/docs/images/07-variables-section.png b/docs/images/07-variables-section.png
diff --git a/docs/images/08-variable-editor-empty.png b/docs/images/08-variable-editor-empty.png
diff --git a/docs/images/09-variable-in-header.png b/docs/images/09-variable-in-header.png
diff --git a/docs/images/10-sensitive-variable-masked.png b/docs/images/10-sensitive-variable-masked.png
diff --git a/docs/images/11-auto-refresh-config.png b/docs/images/11-auto-refresh-config.png
diff --git a/docs/images/12-jwt-refresh-example.png b/docs/images/12-jwt-refresh-example.png
diff --git a/docs/images/13-oauth-example.png b/docs/images/13-oauth-example.png
diff --git a/docs/images/14-multiple-headers.png b/docs/images/14-multiple-headers.png
diff --git a/docs/images/15-cors-headers.png b/docs/images/15-cors-headers.png
diff --git a/docs/images/README.md b/docs/images/README.md
@@ -0,0 +1,82 @@
+# Documentation Screenshots
+
+This directory contains screenshots for the ModHead documentation.
+
+## Screenshot List
+
+### UI Components
+
+| File | Description | Used In |
+|------|-------------|---------|
+| `01-options-page-empty.png` | Empty options page (initial state) | Getting-Started.md |
+| `02-rule-editor-empty.png` | Empty rule editor modal | Getting-Started.md |
+| `03-rule-single-header.png` | Rule card with single header | Getting-Started.md |
+| `04-rule-card.png` | Rule card with multiple headers | - |
+| `05-multiple-rules.png` | Options page with multiple rules | Home.md |
+| `06-url-pattern-matching.png` | Rule with different URL match types | Getting-Started.md |
+| `08-variable-editor-empty.png` | Empty variable editor modal | Variables.md |
+
+### Variables
+
+| File | Description | Used In |
+|------|-------------|---------|
+| `07-variables-section.png` | Variables section with multiple variables | Variables.md |
+| `09-variable-in-header.png` | Variable usage in header values | Variables.md |
+| `10-sensitive-variable-masked.png` | Sensitive variable with masked value | Variables.md |
+
+### Auto-Refresh
+
+| File | Description | Used In |
+|------|-------------|---------|
+| `11-auto-refresh-config.png` | Auto-refresh configuration interface | Auto-Refresh-Tokens.md |
+| `12-jwt-refresh-example.png` | JWT token with auto-refresh setup | Examples.md |
+| `13-oauth-example.png` | OAuth 2.0 configuration example | Examples.md |
+
+### Feature Examples
+
+| File | Description | Used In |
+|------|-------------|---------|
+| `14-multiple-headers.png` | Rule with multiple custom headers | Getting-Started.md |
+| `15-cors-headers.png` | CORS headers configuration | Examples.md |
+
+## Generation
+
+Screenshots are automatically generated using:
+
+```bash
+npm run screenshots
+```
+
+This command:
+1. Builds the extension (`npm run build`)
+2. Runs the screenshot generation script (`scripts/generate-screenshots.ts`)
+3. Saves all screenshots to this directory
+
+The generation script uses Puppeteer to:
+- Launch Chrome with the extension loaded
+- Create various configurations (rules, variables, auto-refresh)
+- Capture screenshots of different UI states
+- Save them as PNG files
+
+## Screenshot Specifications
+
+- **Resolution**: 1280x800
+- **Format**: PNG
+- **Theme**: Light mode only
+- **Browser**: Chrome/Chromium (via Puppeteer)
+
+## Updating Screenshots
+
+If the UI changes and screenshots need to be updated:
+
+1. Make your changes to the extension
+2. Run `npm run screenshots` to regenerate all screenshots
+3. Review the updated screenshots
+4. Commit the changes
+
+## Notes
+
+- Screenshots are version controlled and should be updated when significant UI changes occur
+- The GitHub Action workflow (`.github/workflows/sync-wiki.yml`) automatically syncs this directory to the GitHub Wiki
+- All screenshots use English language interface
+- Screenshots are captured in headless mode for consistency
diff --git a/package.json b/package.json
@@ -18,7 +18,8 @@
     "test:variables": "vitest run tests/e2e/variables.test.ts",
     "test:refresh": "vitest run tests/e2e/auto-refresh.test.ts",
     "test:theme": "vitest run tests/e2e/theme.test.ts",
-    "test": "npm run build && npm run test:e2e"
+    "test": "npm run build && npm run test:e2e",
+    "screenshots": "npm run build && tsx scripts/generate-screenshots.ts"
   },
   "dependencies": {
     "react": "^19.0.0",