consolidation-task: merge thread on #64 into single spec

Consolidation target: #64

Parent issue: #64 in Ultimate-Multisite/docs
Parent title: Screenshot audit and refresh program (master)
Parent labels: documentation,enhancement,help wanted,origin:worker,origin:interactive,status:available,consolidation-in-progress

You do NOT need to read #64. Everything required is inlined below.
Reading the parent wastes the token budget and is explicitly disallowed for this task.

What to do

1. Read the parent body and substantive comments inlined below. Identify:

   • The original problem statement
   • Scope modifications added by commenters (additions, corrections, clarifications)
   • Resolved questions, rejected ideas, or superseded decisions
   • The final agreed-upon approach

2. Compose a single coherent issue body in the aidevops brief format (see templates/brief-template.md):

   • ## What — the deliverable
   • ## Why — the problem and rationale
   • ## How — approach with explicit file paths and line references
   • ## Acceptance Criteria — testable checkboxes
   • ## Context & Decisions — which commenter contributed which insight (attribution matters)
   • ## Contributors — a cc line @-mentioning every author from the list below

   Start the merged body with: _Supersedes #64 — this issue is the consolidated spec._

3. File the new consolidated issue:

gh issue create --repo "Ultimate-Multisite/docs" \
  --title "consolidated: <concise description derived from the merged spec>" \
  --label "consolidated,origin:worker,auto-dispatch,<copy relevant labels from parent, excluding needs-consolidation, consolidation-task, and origin:interactive>" \
  --body "<merged body from step 2>"

Note (GH#18670): origin:worker is mandatory on this label list — consolidated issues are pulse-generated artifacts, not interactive maintainer work. Without it, the issue is born origin:interactive (raw gh issue create has no origin auto-detection), which triggers the GH#18352 dispatch-dedup block and drains the queue.

Dispatch handoff: auto-dispatch is also mandatory. The consolidated successor marker and this explicit handoff must both be present before _has_consolidated_label permits implementation dispatch.

Capture the new issue number as $NEW_NUM.

4. Close the parent #64:

gh issue comment 64 --repo "Ultimate-Multisite/docs" \
  --body "Superseded by #$NEW_NUM. The merged spec is inlined on the new issue — continue discussion there."
gh issue edit 64 --repo "Ultimate-Multisite/docs" \
  --add-label "consolidated" --remove-label "needs-consolidation"
gh issue close 64 --repo "Ultimate-Multisite/docs" --reason "not planned"

5. Close this consolidation-task issue with a summary comment:

gh issue comment $THIS_ISSUE --repo "Ultimate-Multisite/docs" \
  --body "Consolidation complete. Parent: #64 → New: #$NEW_NUM. Contributors @-mentioned: @superdav42."
gh issue close $THIS_ISSUE --repo "Ultimate-Multisite/docs" --reason "completed"

Constraints

• Do NOT read #64 — it is inlined below. Reading it wastes the token budget.
• Preserve all substantive content. Merging is not summarising. If a comment adds a constraint, that constraint must appear in the merged body.
• Preserve author attribution for specific contributions: "per @user1: …".
• No PR is required. This is an operational task. The completion signal is the new issue number + parent closure + self-close.
• Contributors to @-mention on the new issue: @superdav42

Parent body (verbatim)

Summary

A repo-wide audit of every screenshot in static/img/ and every /img/... reference in docs/ revealed widespread problems:

• 147 image files are tracked, but only 98 unique paths are referenced from docs/ — and many of those single paths are reused for dozens of unrelated concepts.
• At least 32 files are byte-for-byte duplicates of each other (same MD5 hash) saved under different names.
• At least 4 walkthroughs (Zapier, Stripe, PayPal, Customer account page) currently use a single screenshot as a placeholder for every step.

This issue tracks the program of work. Each focused area has its own child issue (linked below).

Goal

Every screenshot in the docs should:

1. Show the actual UI being described.
2. Be unique per concept (no recycled placeholder).
3. Be cropped/sized to highlight the relevant control, not buried in chrome.
4. Be reasonably small (file size + image dimensions) so the docs site stays fast.

---

Capture environment

The dev WordPress used to take new screenshots:

• URL: http://wordpress.local:8080
• Username: admin
• Password: admin
• Plugin: Ultimate Multisite (current main build) active on the network.

Open the login page at http://wordpress.local:8080/wp-login.php, sign in, then go to My Sites → Network Admin → Ultimate Multisite to reach every screen referenced in the docs.

If wordpress.local:8080 is not reachable from your machine, ask in the issue thread for access (a staging clone can be provided).

Capture standards

Rule	Value
Browser window for screen captures	1280 × 800 (consistent across the whole doc set)
Device pixel ratio	1× (use a normal/external monitor, not a Retina-only display)
Theme	WordPress default admin colour scheme, no admin-bar customisations
Browser zoom	100% — confirm with Ctrl/Cmd + 0 before each shot
File format	PNG, 8-bit RGB, non-interlaced
Max longest edge	1568 px — anything larger gets auto-downscaled and wastes bytes
Min readable text height	≥ 12 px after any cropping
Crop policy	Crop tightly to the panel/section being described. Do not capture the whole admin chrome unless the doc text refers to the sidebar / admin bar.
Annotations	None by default. If the doc text already describes the control, the screenshot should speak for itself.
File name	Keep the existing filename when replacing. For new shots, use kebab-case-area-element.png and place under static/img/admin/, static/img/config/, or static/img/installation/ to match siblings.
Optimisation	Run pngquant --quality=70-90 --skip-if-larger -f -o out.png in.png (or oxipng -o 4 in.png) before committing. Target < 200 KB unless the screen genuinely needs more detail.

Recommended capture tools

• Linux: Flameshot (flameshot gui), GNOME Screenshot, or gnome-screenshot -w for a window.
• macOS: Cmd + Shift + 4, then space, then click the browser window. To remove window shadows: defaults write com.apple.screencapture disable-shadow -bool true.
• Cross-platform: Playwright/Chromium headed: open http://wordpress.local:8080/wp-admin/network/admin.php?page=wp-ultimo, resize window to 1280 × 800 via the OS or DevTools device toolbar, then capture.

For full reproducibility you can drive the capture from a tiny Playwright script (1280 × 800 viewport, deviceScaleFactor 1) — useful if you’re doing many at once. Ask in this issue if you want a starter script.

Filename hygiene

• Never paste a screenshot with macOS’s default name Screenshot 2026-… PM.png into commits — rename to the target path first.
• On macOS, the AM/PM in the default filename contains a U+202F narrow no-break space which breaks many tools. Rename to ASCII before committing.

---

Audit findings

A. Exact byte-identical duplicates (same file content, different names)

These were verified with md5sum. The recycled name almost always implies a screenshot that was never actually captured.

MD5	Affected files	Tracking issue
023edc1399…	static/img/config/product-{custom-domains,disk-space,hide-credits,plugins,post-types,reset-limitations,site-templates,themes,upgrades}.png (9 files, all 28 236 B)	#69
1dce0a089f…	static/img/admin/network-dashboard-{activity-stream,first-steps,full,news,right-now,summary}.png + static/img/installation/network-dashboard.png (7 files, all 125 540 B)	#70
28184a7caf…	static/img/admin/settings-payments-{bottom,gateways-2,options}.png (3 files)	#71
1c1ac4f60f…	static/img/config/period-selection-field-{options,settings}.png (2 files)	#72
74f697dd4b…	static/img/installation/plugin-activated.png, static/img/installation/wizard-welcome.png	#75
b9c1d601bb…	static/img/admin/um-dashboard-bottom.png, static/img/admin/um-dashboard-stats.png	#76

Total: 32 files that should collapse to ~10 distinct shots.

B. One screenshot reused for many concepts inside one doc (placeholder pattern)

Doc file	Distinct concepts illustrated	Image used	Tracking issue
docs/user-guide/integrations/zapier.md	14 (Zapier dashboard, app search, trigger picker, auth modal, UM API settings, credentials, payment_received event, test step, action setup …)	webhooks-list.png — wrong screen for every step	#65
docs/user-guide/payment-gateways/stripe.md	13 (UM active gateways, inline card field, Checkout redirect, API keys, Stripe Dashboard, test-data toggle, Stripe webhooks, listener URL, endpoint paste …)	settings-payment-gateways.png — wrong screen for most steps	#66
docs/user-guide/payment-gateways/paypal.md	5 (UM active gateways, API credentials, PayPal account settings, PayPal API integration, generated credentials)	settings-payment-gateways.png — wrong screen for the PayPal-side steps	#67
docs/user-guide/client-management/account-page.md	16 (account menu, account overview, plan summary, Site Limits, Billing Address, update form, change template button, switch confirmation, Add Domain, DNS instructions, change password form, Danger Zone …)	Recycled mix of dashboard.png, customers-list.png, domains-list.png from the network admin — but the doc is about the customer-facing subsite account page.	#68

C. Cross-doc placeholder reuse (heaviest offenders)

Image	Times referenced	Used for	Tracking issue
/img/admin/webhooks-list.png	35	Mostly Zapier walkthroughs	#65, #74
/img/config/settings-payment-gateways.png	34	PayPal + Stripe walkthroughs	#66, #67
/img/admin/memberships-list.png	17	Memberships list, but reused for cancel / downgrade / upgrade flows where the actual screens differ	(future)
/img/config/checkout-form-step.png	16	Re-used for every field type configuration	#72, #73
/img/config/settings-taxes.png	15	VAT add-on walkthrough	(future)
/img/config/discount-codes-list.png	14	Multiple distinct discount-code editor screens	(future)

---

Workflow per child issue

For each linked child issue:

1. Open wordpress.local:8080, log in as admin / admin.
2. Re-create / open the screen described in the doc text.
3. Capture per the standards table above (1280×800, tight crop, < 200 KB).
4. Save to the exact path listed in the issue (overwrite existing file — keep the filename).
5. If the issue says "split into N shots", add the new filenames to static/img/.../ and update the markdown references in the listed docs/... file accordingly.
6. Run npm start, visit the doc page, and confirm every shot renders and matches the surrounding text.
7. Commit with a message like docs(screenshots): refresh <area> per issue #<N> and open a PR referencing the issue.

Child issues

• #65 — Screenshots: Zapier integration walkthrough (14 placeholders)
• #66 — Screenshots: Stripe payment gateway walkthrough (13 placeholders)
• #67 — Screenshots: PayPal payment gateway walkthrough (5 placeholders)
• #68 — Screenshots: Customer account page (16 placeholders)
• #69 — Screenshots: Product limitation tabs (9 identical duplicates)
• #70 — Screenshots: Network admin dashboard widgets (7 identical duplicates)
• #71 — Screenshots: Settings → Payments tabs (3 identical duplicates)
• #72 — Screenshots: Checkout form editor flow (heavy reuse)
• #73 — Screenshots: Customizing the registration form (depends on #72)
• #74 — Screenshots: Webhooks setup walkthrough
• #75 — Screenshots: Installation wizard (1 duplicate + verify currency)
• #76 — Screenshots: UM analytics dashboard (1 duplicate)
• #77 — Screenshots: Site templates documentation

How this audit was done

# All tracked images
git ls-files | grep -iE '\.(png|jpg|jpeg|gif|webp)$'

# Exact-duplicate detection
find static/img -type f -name '*.png' -exec md5sum {} \; | sort | uniq -d -w 32

# Reference counts per image
grep -rohE '/img/[^)" ]+\.png' docs/ | sort | uniq -c | sort -rn

# Image dimensions / file sizes
find static/img -name '*.png' -exec file {} \;

Future work (not yet ticketed)

The audit also found heavy reuse in the following areas, which are smaller scope but still worth fixing:

• VAT / Tax handling (tax-handling.md) — settings-taxes.png used as the VAT add-on install screenshot.
• Discount codes (creating-discount-codes.md) — discount-codes-list.png re-used for save / active / advanced screens.
• Domain mapping (how-to-configure-domain-mapping.md) — domains-list.png used for several different screens.
• WooCommerce add-on (addons/woocommerce/index.mdx) — uses addons-page.png and settings-payment-gateways.png for different steps.
• GoCardless / PayFast / Language Selector / Site Exporter / Admin Page Creator add-on docs — each has 1–2 shots that could be more specific.
• Touring the admin panel (touring-the-admin-panel.md) — verify each linked screen still matches the current UI.

These can be ticketed as needed once the high-impact issues above are landed.

Substantive comments (verbatim, in chronological order)

Comment 1 — @superdav42 at 2026-05-19T05:13:04Z

Heads-up: an automated worker session published a parallel audit at #78 / #79 / #80 about a minute after this one (both running from the same prompt as different sessions). Cross-link comments left on each. The other audit adds these areas that I only listed as "future work" here:

• 28 addon index.mdx pages with zero screenshots
• 48 orphan files in static/img/ that exist on disk but are not referenced
• Heavy single-image reuse in tax-handling.md (15×), creating-discount-codes.md (14×), zapier-register-account.md (12×), how-to-configure-domain-mapping.md (9×), sending-emails-and-broadcasts.md (9×), canceling-a-membership.md (6×), client-websites.md (6×)

Recommend keeping #64 as the program tracker, opening new child issues for those extra areas, and closing #79 / #80 as superseded by the narrower #65–#77 series.

---

aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.

---

Comment 2 — @superdav42 at 2026-05-19T05:31:07Z

Gap analysis from the duplicate session (#78 program)

A second audit pass (#78 / #79–#85, created minutes after #64) covered the same ground via a different methodology (reference-count per page rather than MD5-hash collision detection). The findings overlap heavily but surface 11 additional doc pages with placeholder-reuse problems that aren't yet covered by #65–#77, plus two meta-categories (addons with zero screenshots, and 48 orphan files in static/img/).

Closing #78–#83 as duplicates of this master. Keeping #84 and #85 as net-new sub-issues. Recording the remaining 11 gap pages below so they can be picked up as needed.

Existing per-page coverage (already filed)

Page	Sub-issue
integrations/zapier.md	#65
integrations/zapier-register-account.md	#74
integrations/webhooks.md	#65, #74
payment-gateways/stripe.md	#66
payment-gateways/paypal.md	#67
client-management/account-page.md	#68
configuration/creating-your-first-subscription-product.md	#69
administration/dashboard-overview.md, understanding-the-dashboard.md	#70, #76
getting-started/installing-ultimate-multisite.md	#70, #75
administration/managing-payments-and-invoices.md	#71
configuration/checkout-forms.md	#72
configuration/customizing-your-registration-form.md	#73
configuration/site-templates.md, auto-search-and-replace-in-site-templates.md	#77

Gap pages — placeholder reuse, not yet filed

Each entry below is a candidate for its own per-page issue matching the #65–#77 template (For #64. / ## Problem / ref table / ## Captures required / 1280×800 / ## Done when). Line numbers are from main at the time of this audit.

1. docs/user-guide/payment-gateways/getting-paid.md — 18 placeholder reuses

settings-payment-gateways.png × 7 on L16,22,26,30,34,36,42; settings-general.png × 11 on L62,66,70,74,78,86,90,94,102,106,110. Alt-text describes 18 distinct screens — Settings → Payments rows (auto-renew toggle, trial toggle, invoice scheme, sequential invoice number) and the add-on install dialogs for WooCommerce, GoCardless, Payfast.

2. docs/user-guide/payment-gateways/manual-payments.md — 6 placeholder reuses

settings-payment-gateways.png × 3 on L20,24,28 (manual gateway toggle, frontend instructions, Thank You page); payments-list.png × 3 on L34,38,42 (payments list, payment-detail page, status-change + activate-membership toggle).

3. docs/user-guide/payment-gateways/tax-handling.md — 15 placeholder reuses

settings-taxes.png × 15 on L18,26,38,42,52,54,58,60,80,84,86,90,94,102,110 covering: Enable Taxes toggle, Inclusive Tax toggle, Manage Tax Rates button, tax rates editor, Add new Tax Category, tax category modal, switch categories, Add-ons sidebar link, VAT add-on listing, VAT install dialog, VAT network-activate, Enable VAT Support toggle, EU VAT rate pull, frontend VAT field.

4. docs/user-guide/configuration/creating-discount-codes.md — 14 placeholder reuses

discount-codes-list.png × 14 on L16,22,24,28,36,40,44,50,54,64,66,70,74,78. Note: orphan files discount-code-edit.png, discount-code-active.png, discount-code-advanced.png, discount-code-description.png, discount-code-save.png, discount-codes-empty.png already exist in static/img/config/ — verify accuracy and wire in before re-capturing.

5. docs/user-guide/configuration/the-registration-flow.md — 9 reuses across 3 images

checkout-forms-list.png (L20), checkout-form-editor.png × 2 (L26,32), settings-payment-gateways.png × 3 (L46,50,54), payments-list.png × 4 (L60,64,66,70). Covers customer-side registration form, Thank You page, site activation, manual-payment instructions, and admin-side payment processing. Frontend captures needed.

6. docs/user-guide/client-management/upgrading-a-plan.md — 8 reuses across 2 images

memberships-list.png × 5 on L16,20,26,32,36 (customer-side: account page, Your Membership / Change button, checkout with plans, upgrade summary, "no-change" message); product-upgrades.png × 3 on L50,54,56 (admin: Up/Downgrades tab, plan-group assignment). Customer captures and admin captures should be split.

7. docs/user-guide/client-management/canceling-a-membership.md — 6 placeholder reuses

memberships-list.png × 6 on L16,20,24,26,30 (note: L30 has two images on one line). Customer Danger Zone, Confirm Account Deletion, logged-out state, cancellation confirmation, customer-still-exists-after-cancel.

8. docs/user-guide/client-management/downgrading-a-plan.md — 4 reuses across 2 images

memberships-list.png × 3 on L16,20,26 (Change button, plan options, pending-change message); settings-sites.png × 1 on L38 (post-limit-exceeded options).

9. docs/user-guide/client-management/client-websites.md — 6 placeholder reuses

customers-list.png × 6 on L12,18,22,26,30,34 — customer-side captures: My Sites link, My Sites page, Account menu, Change Default Site button, dropdown, confirmation.

10. docs/user-guide/domain-mapping/how-to-configure-domain-mapping.md — 16 placeholder reuses

settings-domain-mapping.png × 7 on L22,30,40,98,102,126,128 (sunrise.php wizard step, Domain Mapping enable, Force Admin Redirect, allow subsite users, product custom-domain option, Integration tab, hosting integration); domains-list.png × 9 on L62,66,74,76,80,106,110,114,116 (admin domains list, Add Domain modal, stage transitions, domain detail page, subsite-side metabox/modal/form).

11. docs/user-guide/miscellaneous/sending-emails-and-broadcasts.md — 14 placeholder reuses

broadcasts-list.png × 9 on L18,22,30,40,44,56,62,70,74 (Notice broadcast on customer dashboard, Broadcasts menu, Add modal as Message and Email, targeting, content editor); settings-emails.png × 5 on L96,100,104,108,120 (Emails settings tab, Customize System Emails button, Reset and Import, Import Emails options, Reset to defaults).

Gap pages — data-state refresh (not placeholder reuse)

These don't have placeholder-reuse problems — each image is unique — but the captures show empty or near-empty state.

• docs/user-guide/administration/touring-the-admin-panel.md — 13 list-page captures (Dashboard, Checkout Forms, Products, Memberships, Payments, Customers, Sites, Domains, Discount Codes, Broadcasts, Settings, Events, Webhooks). Each capture should be re-taken with the seed data from the capture playbook so lists look populated.
• docs/user-guide/administration/managing-memberships.md — small page, two captures. Re-take with seed data.

These two pages could be handled in a single "populate Network Admin lists with seed data and re-capture the touring + managing-memberships shots" issue.

Net-new categories kept as separate issues

• #84 — docs/addons/*/index.mdx: 28 addon pages with zero screenshots.
• #85 — 48 orphan files in static/img/ not referenced from any English doc; many appear to be the correct per-step captures that should be wired into the gap pages above (e.g. the orphan discount-code-edit.png family is the right destination for #4 above).

Closures

• #78 (master) — duplicate of this issue. Closed.
• #79 (Integrations section) — duplicate of #65 + #74. Closed.
• #80 (Payment Gateways section) — covered by #66 + #67 + #71; gap pages 1–3 above kept here. Closed.
• #81 (Configuration section) — covered by #69 + #72 + #73 + #77; gap pages 4–5 above kept here. Closed.
• #82 (Client Management section) — covered by #68; gap pages 6–9 above kept here. Closed.
• #83 (Domain Mapping + Admin + Misc section) — gap pages 10–11 and the data-state refresh kept here. Closed.

Audit methodology: git ls-files + Python ref-counter against docs/**/*.{md,mdx} on main, plus manual review of each affected file. Mapping of which doc references each image is reproducible from the cached results at /tmp/opencode/docs-audit/.

---

aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 9h and 383 tokens on this as a headless worker.

---

Comment 3 — @superdav42 at 2026-05-19T05:45:51Z

Sub-issues filed — complete index

The 11 gap pages from the gap-analysis comment have now been filed as per-page issues matching the #65–#77 template.

Per-page sub-issues

Doc page	Issue	Placeholder reuses
integrations/zapier.md	#65	14
integrations/zapier-register-account.md	#74	12
integrations/webhooks.md	#65 / #74	8
payment-gateways/stripe.md	#66	13
payment-gateways/paypal.md	#67	5
payment-gateways/getting-paid.md	#86	18
payment-gateways/manual-payments.md	#87	6
payment-gateways/tax-handling.md	#88	15
configuration/checkout-forms.md	#72	heavy
configuration/customizing-your-registration-form.md	#73	heavy
configuration/creating-discount-codes.md	#89	14 (+ 6 orphans to wire)
configuration/the-registration-flow.md	#90	9
configuration/creating-your-first-subscription-product.md	#69	9 identical
configuration/site-templates.md + auto-search-and-replace…	#77	—
client-management/account-page.md	#68	16
client-management/upgrading-a-plan.md	#91	8
client-management/canceling-a-membership.md	#92	6
client-management/downgrading-a-plan.md	#93	4
client-management/client-websites.md	#94	6
domain-mapping/how-to-configure-domain-mapping.md	#95	16
miscellaneous/sending-emails-and-broadcasts.md	#96	14
administration/managing-payments-and-invoices.md	#71	3 identical
administration/dashboard-overview.md, understanding-the-dashboard.md	#70 / #76	7 identical / 1 dup
getting-started/installing-ultimate-multisite.md	#70 / #75	wizard dup

Bold entries are the new per-page issues filed in this consolidation pass.

Net-new categories

• #84 — 28 addon index.mdx pages with zero screenshots.
• #85 — 48 orphan files in static/img/ (markdown-only rewire wins; tackle before #89/#95/#87 to avoid re-capturing files that already exist).

Not yet filed (lower priority)

administration/touring-the-admin-panel.md and administration/managing-memberships.md are not placeholder-reuse — each capture is unique — but show empty/zero-state lists. A single "populate Network Admin lists with seed data and re-capture touring + managing-memberships shots" issue would close that gap when convenient.

Closures recap

• #78 — duplicate of #64. Closed.
• #79 — duplicate of #65 + #74. Closed.
• #80 — duplicate of #66 + #67 + #71; gaps split into #86, #87, #88. Closed.
• #81 — duplicate of #69 + #72 + #73 + #77; gaps split into #89, #90. Closed.
• #82 — duplicate of #68; gaps split into #91, #92, #93, #94. Closed.
• #83 — gaps split into #95, #96 and the not-yet-filed touring/managing-memberships refresh. Closed.

Total active screenshot audit issues under this master: 24 (was 14 from Session A; +#84, +#85, +11 from this consolidation = 26 created total; 1 master + 24 children remaining open).

---

aidevops.sh v3.15.64 plugin for OpenCode v1.15.5 with claude-sonnet-4-6 spent 4d 10h and 383 tokens on this as a headless worker.

---

Self-contained dispatch packet generated by _dispatch_issue_consolidation() in pulse-triage.sh (t1982). Everything above is sufficient — do not read #64.

Read the inlined parent body and substantive comments, then use templates/brief-template.md to assemble the consolidated spec with attribution and acceptance criteria. Create the successor with the required labels using gh issue create, record its number, comment on and close #64, then comment on and close this issue. Done means the new issue contains the merged decisions and both closure handoffs are recorded.