Repository navigation
Description
Supersedes #64 — this issue is the consolidated spec.
What
Run the repository-wide Screenshot Audit and Refresh Program. Every documentation screenshot must depict the UI described beside it, be unique to that concept, tightly cropped to the relevant control, readable, and optimized for the documentation site. Deliver the work through the already-filed child issues; retain this issue as the program tracker.
Program inventory and delivery structure
- The English docs currently track 147 image files, reference 98 unique image paths, and include at least 32 byte-identical duplicate files.
- Existing focused children remain the implementation queue: Screenshots: Zapier integration walkthrough (14 placeholders) #65 Zapier, Screenshots: Stripe payment gateway walkthrough (13 placeholders) #66 Stripe, Screenshots: PayPal payment gateway walkthrough (5 placeholders) #67 PayPal, Screenshots: Customer account page (16 placeholders) #68 customer account, Screenshots: Product limitation tabs (9 identical duplicates) #69 product limitation tabs, Screenshots: Network admin dashboard widgets (7 identical duplicates) #70 network dashboard widgets, Screenshots: Settings → Payments tabs (3 identical duplicates) #71 payment tabs, Screenshots: Checkout form editor flow (heavy reuse) #72 checkout editor, Screenshots: Customizing the registration form (depends on checkout forms) #73 registration form (after Screenshots: Checkout form editor flow (heavy reuse) #72), Screenshots: Webhooks setup walkthrough #74 webhooks, Screenshots: Installation wizard (1 duplicate + verify currency) #75 installation wizard, Screenshots: UM analytics dashboard (1 duplicate) #76 analytics dashboard, Screenshots: Site templates documentation #77 site templates.
- The second audit added children Screenshots: docs/addons — 28 addon pages with zero images need screenshots #84 (28 addon
index.mdxpages with no screenshots), Screenshots: rewire 48 orphan files under static/img (quick markdown-only wins) #85 (48 unreferencedstatic/img/files; examine reusable captures before recapturing), and Screenshots: Getting paid overview (18 placeholders across 2 images) #86–Screenshots: Sending emails and broadcasts (14 placeholders) #96 for the gap pages listed in How. - Keep Screenshot audit and refresh program (master) #64 as the historical source, but use this issue as the single current specification. Issues Screenshot audit — replace placeholder reuse and missing captures across docs #78–Screenshots: user-guide/domain-mapping, administration, miscellaneous — domain mapping flow, broadcasts, system emails, populated dashboards #83 were duplicate section programs and remain superseded; do not reopen them.
- Lower-priority, not-yet-filed work: re-capture the populated-list states in
docs/user-guide/administration/touring-the-admin-panel.mdanddocs/user-guide/administration/managing-memberships.mdwith seed data.
Why
The audit found screenshots reused for unrelated concepts, including walkthroughs where one placeholder illustrates every step. This makes instructions misleading, conceals current product UI, and adds unnecessary static assets. The program replaces placeholders with accurate shots, wires in useful orphan captures before taking new ones, and keeps images fast and consistent.
How
Capture and asset standards
| Requirement | Standard |
|---|---|
| Capture viewport | 1280 × 800 at device-pixel-ratio 1 and browser zoom 100% |
| Admin appearance | Default WordPress admin colour scheme; no admin-bar customisation |
| Format | 8-bit RGB, non-interlaced PNG |
| Size | Longest edge no more than 1568 px; normally target under 200 KB |
| Readability | Text remains at least 12 px after cropping |
| Crop | Tight panel/section crop; include WordPress chrome only when the docs discuss it |
| Annotation | None unless the existing documentation requires it |
| Naming | Preserve replacement names; new captures use kebab-case-area-element.png under the matching static/img/admin/, static/img/config/, or static/img/installation/ directory |
| Optimization | Run pngquant --quality=70-90 --skip-if-larger -f -o out.png in.png or oxipng -o 4 in.png before commit |
Capture against the current Ultimate Multisite main build in the authorized local WordPress environment. Use authorized credentials without recording them in commits, comments, screenshots, or issues. Standard tools include Flameshot/GNOME Screenshot, macOS Screenshot, or a headed Playwright/Chromium window configured to the capture viewport. Rename macOS screenshots to ASCII before committing; the default name can contain a narrow no-break space. Do not retain default Screenshot … AM/PM.png names.
Per-child workflow
- Re-create or open the screen described by the target documentation text.
- Capture to the exact existing asset path, or add the narrowly named new asset path stated by the child issue.
- For a split walkthrough, update the listed Markdown/MDX references to the new per-step captures.
- Optimize the image, run
npm start, visit the target documentation page, and verify every image renders and matches the adjacent text. - Commit with
docs(screenshots): refresh <area> per issue #<N>and open a PR for the child issue.
Audit findings and assigned children
Exact duplicate asset groups
The following MD5-equal groups must become concept-specific captures through their assigned children:
| Duplicate group | Paths | Child |
|---|---|---|
| 9 product limitation tabs | static/img/config/product-{custom-domains,disk-space,hide-credits,plugins,post-types,reset-limitations,site-templates,themes,upgrades}.png (28,236 B each) |
#69 |
| 7 dashboard views | static/img/admin/network-dashboard-{activity-stream,first-steps,full,news,right-now,summary}.png, static/img/installation/network-dashboard.png (125,540 B each) |
#70 |
| 3 payment settings shots | static/img/admin/settings-payments-{bottom,gateways-2,options}.png |
#71 |
| 2 period-selection views | static/img/config/period-selection-field-{options,settings}.png |
#72 |
| 2 installation shots | static/img/installation/plugin-activated.png, static/img/installation/wizard-welcome.png |
#75 |
| 2 dashboard shots | static/img/admin/um-dashboard-bottom.png, static/img/admin/um-dashboard-stats.png |
#76 |
Placeholder walkthroughs already covered
- Screenshots: Zapier integration walkthrough (14 placeholders) #65:
docs/user-guide/integrations/zapier.mdhas 14 distinct Zapier concepts but useswebhooks-list.png; it needs the dashboard, app search, trigger picker, auth, Ultimate Multisite API settings, credentials,payment_received, test step, action setup, and the other described steps. - Screenshots: Stripe payment gateway walkthrough (13 placeholders) #66:
docs/user-guide/payment-gateways/stripe.mdhas 13 concepts but repeatedly usessettings-payment-gateways.png; cover active gateways, inline card, Checkout redirect, keys, Stripe dashboard, test data, webhooks, listener URL, and endpoint setup. - Screenshots: PayPal payment gateway walkthrough (5 placeholders) #67:
docs/user-guide/payment-gateways/paypal.mdhas 5 concepts but reuses the payment settings image for PayPal-side steps. - Screenshots: Customer account page (16 placeholders) #68:
docs/user-guide/client-management/account-page.mdhas 16 customer-facing account concepts but reuses network-admin images. Cover account menu/overview, plan, limits, billing, profile update, template switching, domain/DNS flow, password, and Danger Zone. - Screenshots: Webhooks setup walkthrough #74: replace the heavy
/img/admin/webhooks-list.pngplaceholder reuse in the Zapier registration/webhook flow.
High-reuse images and the corresponding program work
/img/admin/webhooks-list.png is referenced 35 times (#65, #74); /img/config/settings-payment-gateways.png 34 times (#66, #67); /img/admin/memberships-list.png 17 times; /img/config/checkout-form-step.png 16 times (#72, #73); /img/config/settings-taxes.png 15 times; and /img/config/discount-codes-list.png 14 times. The last four are resolved by the child issues below or future focused work, not by a blanket asset replacement.
Gap-page children from the second audit
Use these exact page-level findings when executing #86–#96. The line references were recorded on the audit revision; verify current context before editing.
| Child | Documentation file | Required distinct captures |
|---|---|---|
| #86 | docs/user-guide/payment-gateways/getting-paid.md |
Replace 18 placeholders: settings-payment-gateways.png at L16,22,26,30,34,36,42 for payment rows/toggles/invoice settings, and settings-general.png at L62,66,70,74,78,86,90,94,102,106,110 for WooCommerce, GoCardless, and Payfast install dialogs. |
| #87 | docs/user-guide/payment-gateways/manual-payments.md |
Replace three settings-payment-gateways.png uses (manual toggle, frontend instructions, Thank You page) and three payments-list.png uses (list, detail, status change/activate-membership). Check reusable orphans before recapture. |
| #88 | docs/user-guide/payment-gateways/tax-handling.md |
Replace 15 settings-taxes.png uses (L18,26,38,42,52,54,58,60,80,84,86,90,94,102,110): tax toggles/rates/categories, VAT add-on install and activation, VAT support, EU rate pull, and frontend VAT field. |
| #89 | docs/user-guide/configuration/creating-discount-codes.md |
Replace 14 discount-codes-list.png uses (L16,22,24,28,36,40,44,50,54,64,66,70,74,78). First assess and wire accurate orphan assets discount-code-edit.png, discount-code-active.png, discount-code-advanced.png, discount-code-description.png, discount-code-save.png, and discount-codes-empty.png. |
| #90 | docs/user-guide/configuration/the-registration-flow.md |
Replace 9 uses across checkout-forms-list.png (L20), checkout-form-editor.png (L26,32), settings-payment-gateways.png (L46,50,54), and payments-list.png (L60,64,66,70); include customer registration, Thank You page, activation, manual payment, and admin payment processing. |
| #91 | docs/user-guide/client-management/upgrading-a-plan.md |
Replace 5 memberships-list.png placeholders (customer account, membership change, plan checkout, upgrade summary, no-change state) and 3 product-upgrades.png placeholders (admin up/downgrades and plan-group assignment). |
| #92 | docs/user-guide/client-management/canceling-a-membership.md |
Replace 6 memberships-list.png usages (L16,20,24,26,30; two images on L30) with customer Danger Zone, confirmation, logged-out, cancellation, and retained-customer states. |
| #93 | docs/user-guide/client-management/downgrading-a-plan.md |
Replace 3 memberships-list.png shots (change control, plans, pending-change) and settings-sites.png (post-limit options). |
| #94 | docs/user-guide/client-management/client-websites.md |
Replace 6 customers-list.png shots (L12,18,22,26,30,34) with customer My Sites, account menu, default-site selection, dropdown, and confirmation. |
| #95 | docs/user-guide/domain-mapping/how-to-configure-domain-mapping.md |
Replace 7 settings-domain-mapping.png and 9 domains-list.png placeholders: sunrise wizard, mapping controls, redirects/user access, product custom-domain choice, integration/hosting, domains list/add modal/transitions/detail, and subsite controls. |
| #96 | docs/user-guide/miscellaneous/sending-emails-and-broadcasts.md |
Replace 9 broadcasts-list.png uses (customer notice, menu, add modal as message/email, targeting, editor) and 5 settings-emails.png uses (Emails settings, customization, reset/import/options). |
Additional program scope and decisions
- Screenshots: docs/addons — 28 addon pages with zero images need screenshots #84 owns the 28 addon index pages with no screenshots.
- Screenshots: rewire 48 orphan files under static/img (quick markdown-only wins) #85 owns the 48 orphan static images; use accurate existing images before creating replacements, particularly for Screenshots: Creating discount codes (14 placeholders + 6 orphans to wire) #89, Screenshots: How to configure domain mapping (16 placeholders) #95, and Screenshots: Manual payments walkthrough (6 placeholders) #87.
- Future focused issues may cover VAT/tax, discount codes, domain mapping, WooCommerce, GoCardless, PayFast, Language Selector, Site Exporter, Admin Page Creator, and administration-tour refreshes when not already covered above.
- Do not reopen Screenshot audit — replace placeholder reuse and missing captures across docs #78 (duplicate master), Screenshots: user-guide/integrations — replace 34 placeholder reuses (zapier, webhooks) #79 (covered by Screenshots: Zapier integration walkthrough (14 placeholders) #65/Screenshots: Webhooks setup walkthrough #74), Screenshots: user-guide/payment-gateways — replace placeholder reuses (stripe, paypal, manual, getting-paid, tax-handling) #80 (covered by Screenshots: Stripe payment gateway walkthrough (13 placeholders) #66/Screenshots: PayPal payment gateway walkthrough (5 placeholders) #67/Screenshots: Settings → Payments tabs (3 identical duplicates) #71 and Screenshots: Getting paid overview (18 placeholders across 2 images) #86–Screenshots: Tax handling walkthrough (15 placeholders) #88), Screenshots: user-guide/configuration — checkout-forms, discount-codes, site-templates, products, registration flow #81 (covered by Screenshots: Product limitation tabs (9 identical duplicates) #69/Screenshots: Checkout form editor flow (heavy reuse) #72/Screenshots: Customizing the registration form (depends on checkout forms) #73/Screenshots: Site templates documentation #77 and Screenshots: Creating discount codes (14 placeholders + 6 orphans to wire) #89/Screenshots: The registration flow (9 placeholders, frontend captures) #90), Screenshots: user-guide/client-management — account-page (frontend), upgrading, canceling, downgrading, client-websites #82 (covered by Screenshots: Customer account page (16 placeholders) #68 and Screenshots: Upgrading a plan (8 placeholders, customer + admin) #91–Screenshots: Client websites / My Sites (6 placeholders, customer-side) #94), or Screenshots: user-guide/domain-mapping, administration, miscellaneous — domain mapping flow, broadcasts, system emails, populated dashboards #83 (covered by Screenshots: How to configure domain mapping (16 placeholders) #95/Screenshots: Sending emails and broadcasts (14 placeholders) #96 plus the future list-state refresh).
Audit reproducibility
Use the following checks when reassessing a target area:
git ls-files | grep -iE '\.(png|jpg|jpeg|gif|webp)$'
find static/img -type f -name '*.png' -exec md5sum {} \; | sort | uniq -d -w 32
grep -rohE '/img/[^)" ]+\.png' docs/ | sort | uniq -c | sort -rn
find static/img -name '*.png' -exec file {} \;Acceptance Criteria
- Each child issue has an accurate, per-concept capture plan; no implementation PR reuses a known placeholder image for a materially different UI state.
- New/replaced screenshots meet the capture standards, optimize their PNGs, and render correctly in the relevant documentation page.
- The duplicate groups and per-page placeholder work are completed only through their focused child issues, with Screenshots: rewire 48 orphan files under static/img (quick markdown-only wins) #85 assessed before recapturing candidate orphan assets.
- The screenshot program retains the documented child-issue coverage and does not reopen superseded duplicate programs Screenshot audit — replace placeholder reuse and missing captures across docs #78–Screenshots: user-guide/domain-mapping, administration, miscellaneous — domain mapping flow, broadcasts, system emails, populated dashboards #83.
- The two populated-list refresh pages remain explicitly deferred until separately filed.
Context & Decisions
- Original audit / Screenshot audit and refresh program (master) #64: established the asset counts, duplicate groups, capture standards, child Screenshots: Zapier integration walkthrough (14 placeholders) #65–Screenshots: Site templates documentation #77 queue, and original future-work candidates. Its core decision was one focused issue per screenshot area rather than a monolithic asset change.
- @superdav42, Comment 1: reported a parallel duplicate audit (Screenshot audit — replace placeholder reuse and missing captures across docs #78/Screenshots: user-guide/integrations — replace 34 placeholder reuses (zapier, webhooks) #79/Screenshots: user-guide/payment-gateways — replace placeholder reuses (stripe, paypal, manual, getting-paid, tax-handling) #80), added the zero-screenshot addon and orphan-file categories, and recommended retaining the Screenshot audit and refresh program (master) #64 program with focused children rather than parallel section trackers.
- @superdav42, Comment 2: reconciled the two methodologies, recorded 11 additional placeholder-reuse pages and two data-state pages, retained Screenshots: docs/addons — 28 addon pages with zero images need screenshots #84/Screenshots: rewire 48 orphan files under static/img (quick markdown-only wins) #85 as net-new issues, and confirmed Screenshot audit — replace placeholder reuse and missing captures across docs #78–Screenshots: user-guide/domain-mapping, administration, miscellaneous — domain mapping flow, broadcasts, system emails, populated dashboards #83 were duplicates.
- @superdav42, Comment 3: confirmed that the 11 gap pages were filed as Screenshots: Getting paid overview (18 placeholders across 2 images) #86–Screenshots: Sending emails and broadcasts (14 placeholders) #96 and supplied the complete index tying every affected page to its focused child. This supersedes the earlier proposal to create those children.
- Final agreed approach: this single issue is the program specification; execute focused children, reuse accurate orphan assets where possible, and keep capture operations reproducible and optimized.
Contributors
cc @superdav42
Files Scope
Hard boundaries: This is a coordination tracker. It authorizes no direct repository-file changes; source and asset edits belong only to the explicitly linked child issues.
AI brief owner: Pulse consolidation workflow.
aidevops.sh v3.34.13 plugin for OpenCode v1.18.31 with gpt-5.6-terra
Activity
superdav42 commentedon Oct 12, 2026
DISPATCH_CLAIM nonce=cd59a0378a855f34e9618cccd64bfb04 runner=superdav42 ts=2026-10-12T23:44:32Z max_age_s=1800 version=3.39.25 opencode_version=1.18.31 lease_token=cd59a0378a855f34e9618cccd64bfb04 device=device-1783824528-2609248-26808 session=issue-191 phase=prelaunch expires_at=1791848794
superdav42 commentedon Oct 12, 2026
DISPATCH_LEASE phase=prelaunch lease_token=cd59a0378a855f34e9618cccd64bfb04 device=device-1783824528-2609248-26808 session=issue-191 expires_at=1791849139 ts=2026-10-12T23:44:49Z attempt_id=attempt:b9df3e56-59a6-4469-bed3-4d5b762202e6
superdav42 commentedon Oct 12, 2026
DISPATCH_LEASE phase=prelaunch lease_token=cd59a0378a855f34e9618cccd64bfb04 device=device-1783824528-2609248-26808 session=issue-191 expires_at=1791849140 ts=2026-10-12T23:45:50Z attempt_id=attempt:b9df3e56-59a6-4469-bed3-4d5b762202e6
superdav42 commentedon Oct 12, 2026
Dispatching worker (deterministic).
150 remaining items
superdav42 commentedon Nov 4, 2026
DISPATCH_CLAIM nonce=d7f6a9cb05f33c19ab92ccb78c4a4e8a runner=superdav42 ts=2026-11-04T18:26:57Z max_age_s=1800 version=3.39.119 opencode_version=1.18.31 lease_token=d7f6a9cb05f33c19ab92ccb78c4a4e8a device=device-1783824528-2609248-26808 session=issue-191 phase=prelaunch expires_at=1793816940
superdav42 commentedon Nov 4, 2026
DISPATCH_LEASE phase=prelaunch lease_token=d7f6a9cb05f33c19ab92ccb78c4a4e8a device=device-1783824528-2609248-26808 session=issue-191 expires_at=1793817290 ts=2026-11-04T18:27:20Z attempt_id=attempt:9cb98254-50cc-47a0-b055-d17971f9a551
superdav42 commentedon Nov 4, 2026
DISPATCH_LEASE phase=prelaunch lease_token=d7f6a9cb05f33c19ab92ccb78c4a4e8a device=device-1783824528-2609248-26808 session=issue-191 expires_at=1793817291 ts=2026-11-04T18:28:03Z attempt_id=attempt:9cb98254-50cc-47a0-b055-d17971f9a551
superdav42 commentedon Nov 4, 2026
Dispatching worker (deterministic).
superdav42 commentedon Nov 4, 2026
DISPATCH_LEASE phase=ready lease_token=d7f6a9cb05f33c19ab92ccb78c4a4e8a device=device-1783824528-2609248-26808 session=issue-191 expires_at=1793824137 ts=2026-11-04T18:28:57Z attempt_id=attempt:9cb98254-50cc-47a0-b055-d17971f9a551
aidevops.sh v3.39.119 automated scan.
superdav42 commentedon Nov 4, 2026
CLAIM_RELEASED reason=blocked runner=superdav42 ts=2026-11-04T18:31:07Z aidevops_version=3.39.119 opencode_version=1.18.31 claim_id=6638666775 nonce=d7f6a9cb05f33c19ab92ccb78c4a4e8a lease_token=d7f6a9cb05f33c19ab92ccb78c4a4e8a device=device-1783824528-2609248-26808 session=issue-191
Terminal blocker: reason=files_scope_excluded owner=brief-author task=191 attempt=549900226a05472732e0119e.
Projected state: status:blocked.
Next action: The AI brief owner must review the protected integration dossier, check concurrent ownership and correct the permitted paths before resuming the existing checkpoint. Preserve explicit hard boundaries and security guarantees; do not retry an unchanged brief.
Raw evidence remains in protected worker telemetry.
aidevops.sh v3.39.119 plugin for OpenCode v1.18.31