docs: deploy-pages SHA fix, v1.2 screenshots, redesigned carousel + lightbox

[cjimti]

Three threads bundled because they all surfaced together when the v1.2 docs deployment failed and the homepage screenshot tour got audited end-to-end.

Summary

• Fixes the docs deployment. actions/deploy-pages was pinned to a SHA that never existed in the action's history (d6db90af...); the real v4.0.5 SHA is d6db90164.... Single-character-class diff in .github/workflows/docs.yml. Every push to main since the v1.2.0 release has been failing the Deploy Documentation workflow with Unable to resolve action ... unable to find version <sha>.

• Refreshed every existing screenshot, added 8 new ones for v1.2 features. Drawer (4 tabs), comparison page, live tail, JSONB filters. The screenshot script now seeds audit_payloads rows alongside audit_events so the new captures have meaningful content (real-looking request_params with user.id + tenant, response_result via callToolResultToMap, [redacted] headers matching the v1.2 redaction contract, progress notifications for the chatty tools).

• Redesigned the homepage carousel + added a lightbox. Slides ~30% smaller so neighbor cards are always peeking in. Side-rail navigation flanks the active slide instead of hiding in the header. Click any slide to open a near-full-screen lightbox over a deep-midnight backdrop with copper haze. ESC closes; arrow keys step through; backdrop-click dismisses. role=dialog + aria-modal + focus trap + body-scroll lock. Reduced-motion gates every introduced transition.

Closes the broken docs CI; lays in the visuals the v1.2.0 release notes already promised.

Files

Area	Files
CI fix	.github/workflows/docs.yml
Screenshot script + workflow	scripts/screenshots/screenshots.mjs (+213), scripts/screenshots/README.md (new), Makefile (dev-secrets prereq + .env.dev sourcing for make screenshots)
Captured PNGs	8 new (audit-compare, audit-drawer, audit-jsonb, audit-livetail × light + dark), 16 re-rendered
Carousel + lightbox	docs/overrides/home.html (+118), docs/javascripts/shots.js (+187), docs/stylesheets/extra.css (+503)
Doc prose	docs/operations/inspection.md (4 inline embeds), docs/operations/portal.md (Audit inspection section), mkdocs.yml (nav adds inspection.md between Audit Log and Portal)

Total: 32 files, +1052 / −107.

CI fix detail

actions/deploy-pages@d6db90af4856ee69a657050a5670eb98513188ba was a typo. The other three pinned actions on the workflow (actions/checkout, actions/setup-python, actions/upload-pages-artifact) all resolved cleanly. Verified via the GitHub API:

$ curl -fs -H "Accept: application/vnd.github+json" \
    https://api.github.com/repos/actions/deploy-pages/git/refs/tags/v4.0.5
{ "ref": "refs/tags/v4.0.5", "object": { "sha": "d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e" } }

The SHAs share the prefix d6db90 then diverge; looks like a hand-edited or copy-paste transcription error.

Screenshot script changes

scripts/screenshots/screenshots.mjs:

• seed() now writes audit_payloads rows for the 20 most-recent events. Realistic shape: request_params includes user: {id, tenant} and request_id; response_result is a JSON-shaped CallToolResult; request_headers shows Authorization: [redacted] / Cookie: [redacted] matching the v1.2 production redaction policy. Progress / chatty tools get notification arrays so the Notifications tab renders.
• Stashes DRAWER_TARGET_ID, COMPARE_A_ID, COMPARE_B_ID from the seeded data so the deep-link captures (/portal/audit?id=…, /portal/audit/compare?a=…&b=…) hit real rows.
• New PAGES entries: audit-drawer, audit-compare, audit-livetail, audit-jsonb. Each has a prep function that drives the UI into the right state (open drawer via deep-link, toggle Live tail, expand the JSONB filter editor and add a param.user.id=alice filter that actually returns matches).
• Added path can now be a function so deep-link captures can read seed-time state.

Makefile:

• make screenshots now declares dev-secrets as a prereq and sources .env.dev so MCPTEST_DEV_KEY matches the running binary's accepted file API key. Previous flow hardcoded SHOTS_API_KEY=devkey-please-change, which made every captured page bounce to /login because make dev generates a random per-session key.
• Explicit SHOTS_API_KEY=… override still wins (e.g. for staging).

scripts/screenshots/README.md (new): regenerate-and-preview workflow, the slug → screen mapping, and troubleshooting for Postgres connection failed, drawer-empty, and timeout cases.

Carousel + lightbox detail

docs/overrides/home.html:

• Slides moved into a 3-column stage grid: auto | minmax(0, 1fr) | auto, with the rail buttons in the side columns. Old header arrows removed.
• Each frame is a <button> (not just a div) carrying data-zoom-{title,body,light,dark,slug} so the lightbox JS can populate without re-fetching.
• New zoom-hint glyph (top-right of the active frame) telegraphs the click affordance.
• New counter under the stage: 01 / 11 (tabular-nums DM Sans, copper accent on the current value).
• Lightbox markup at the section root: backdrop, shell, toolbar (eyebrow + title baseline-aligned + count + prev + next + close), stage with light/dark images stacked + caption.

docs/stylesheets/extra.css:

• Slide width: min(40vw, 580px) desktop, min(72vw, 480px) mobile (was min(56vw, 832px) / min(66vw, 704px) — 30% reduction). Inactive slides go to opacity: 0.5; transform: scale(0.96) so the active slide reads as the focal point without cards-fight-for-attention disorder.
• Lightbox: 92vw × 90vh shell, object-fit: contain, deep-midnight backdrop with copper radial haze, same cubic-bezier(0.22, 1, 0.36, 1) easing as the carousel translate (one motion vocabulary).
• Toolbar fix: h3.plex-lightbox__title and span.plex-lightbox__eyebrow use element-qualified selectors so they tie with Material's .md-typeset h3 (specificity 0,1,1) and win on source order. Otherwise Material's margin: 1.6em 0 0.8em bloats the toolbar to ~25% of the viewport. Header is now ~3.5rem tall (7% of viewport on a 900px-tall window).
• @media (prefers-reduced-motion: reduce) gates every introduced transition: track, slide, rail, zoomhint, frame img, lightbox shell.

docs/javascripts/shots.js:

• Carousel logic preserved (track translate, wraparound, resize-aware step calc).
• New bindLightbox() handles open/close/prev/next, keyboard (ESC + arrow keys, captured on window so the modal owns dismissal), focus management (saves document.activeElement on open, focuses the close button, restores on close), and a clear-pending-hide-timer guard in open() so re-opens during the 260ms close-fade don't yank the modal back to hidden.
• One bug caught and fixed during browser smoke-test: initial focus target was closeBtns[0] which selected the backdrop <div> (not focusable) instead of the close button. Now uses lightbox.querySelector("button[data-shots-close]").

Verification

• make verify ✓ (Go side untouched; all suites green).
• mkdocs build --strict ✓ (zero warnings, no broken refs, inspection.md now in the nav).
• pnpm tsc --noEmit + pnpm build ✓ (UI side untouched; sanity).
• Browser smoke-test on make docs-serve confirmed: side-rail nav advances slides, counter updates, click opens lightbox with correct content from data attributes, prev/next inside lightbox walks through, ESC + backdrop click dismiss cleanly, focus moves to close button on open and returns on close, body-scroll lock applies/releases.

Pre-commit gate

One review round; one BLOCKER caught (em-dashes throughout new prose violated the project's no-em-dash hard rule), 2 MAJORs (Makefile error message, shots.js _hideTimer race in non-frame-click reopen path), 4 MINORs (reduced-motion gate on slide transitions, comment accuracy, README count clarification, fragile selectors). All addressed in-tree. Verdict CLEAN before commit.

Test plan

• CI: Deploy Documentation workflow runs green on this branch.
• Local: make dev → make screenshots regenerates all 24 PNGs without errors.
• Browser: open make docs-serve, scroll to the carousel.
  • Side rails advance slides; counter updates.
  • Click any slide → lightbox opens at near-full-screen with the right title + caption.
  • Lightbox prev/next walks through all 11 shots.
  • ESC closes the lightbox and returns focus to the originating slide.
  • Backdrop click closes the lightbox.
  • Body scroll is locked while open and released on close.
  • Theme toggle in the header swaps light/dark images both inside and outside the lightbox.
• Mobile breakpoint: lightbox goes full-screen, count hidden, controls compact.