Ships the v2026.817.0 docs to live: the doc content that was authored
and verified
earlier, plus a full screenshot overhaul.
The content half (`cdf81e2` and the nightly commits behind it) has
already been
reviewed. **The screenshots are the part that needs eyes** — `f24d734`,
342 PNGs.
## Screenshots
Everything was recaptured against the release commit
`213dabab4f8e1f3bb1803a2924c0fea1289fcd4c`
(`upstream/candidate/release-2026.817.0`). The previous shots were 375
parent-commits stale (v2026.720.0), with 228 of 310 entries flagged
pending. All
342 registry entries now carry that SHA.
> ⚠️ Worth knowing: the release commit is **not** an ancestor of the
parent's
> `master`, and local `master` was four days *older* than it. Capturing
against
> `master` would have both missed release UI and leaked 93 post-tag
commits' worth
> of UI into the release docs.
### New coverage (34 entries)
Three guides shipped with **no images at all** despite being 115–136
lines. They
now have them:
| Guide | Shots |
|---|---|
| `guides/day-to-day/decisions.md` | queue, an agent-proposed decision
with its options, triage strip, filter panel, named queue, Decided
curtain, empty state |
| `experimental/status-cards.md` | board, New card dialog, and all four
drawer tabs |
| `experimental/task-chat.md` | thread, composer mode picker, side pane
|
| `reference/api/secrets.md` | the board-side Proposals tab |
Chat-Style Tasks is captured in a **separate pass**:
`enableTaskChatRedesign` is
instance-wide, so leaving it on would have turned every classic
issue/task/work-mode
shot into the redesigned chat.
## Two defects that were already live
Both were shipping in the docs before this PR:
1. **`issues/detail-chat.png` and the `tasks/*` shots were mostly plugin
debug
output.** The Kitchen Sink example plugin mounts a panel into the issue
page
that dumps the raw issue JSON, and the seed installed it. Those guides
were
illustrating a debug panel instead of the task page. The seed no longer
installs it.
2. **The seeded task thread was a monologue** — four board-user messages
in a row,
because the board actor cannot post agent comments. It is now a real
two-sided
exchange.
## Targets repointed because the UI moved
| Target | Why |
|---|---|
| `activity/*` | `Activity.tsx` deleted; `/activity` renders
`pages/audit/CompanyActivity.tsx` |
| `experimental/cloud-upstream` | `CloudUpstream.tsx` deleted; the route
now redirects to `/company/export` |
| `settings/*`, `plugins/*`, `adapters/*` | `/instance/settings/*` are
legacy redirects now |
| `dashboard/stale-tasks-panel` | panel removed from `Dashboard.tsx` —
target dropped |
Plus eight targets with **silent selector drift**. A failed interaction
step falls
back to "whatever state was reached", so these had been quietly
producing wrong
images — a plain inbox where the doc promised a mode picker, a whole
dashboard
where it promised one panel. Full table in
`docs/user-guides/screenshots/SCREENSHOTS_PLAN_v2026.817.0.md` §C2.
## Pipeline
Decisions, status-card summaries and secret proposals are all
**agent-authored**,
and the board actor the seed runs as is refused by every one of them
(`"Agent run context required"`, `"Secret proposals require a verified
run-bound
agent token"`). Rather than insert rows behind the API,
`seed-new-surfaces.mjs`
borrows the two doors a real run already has — a board-minted agent API
key, and a
locally signed agent JWT — so every write goes through the production
code path.
Also:
- `capture.mjs` records a real `captured_against` on a detached checkout
instead of
the literal string `"HEAD"` (which is what every pre-2026.817 entry
recorded), and
gains a `scrollTo` step for content below the fold.
- `run.mjs` gains `--serve` for iterating on the seed, the task-chat
phase, and a
keeper that holds the demo board's issue statuses steady — the demo
`process`
agents finish runs without declaring a disposition, so the stalled-work
sweep
re-blocks issues every few minutes over a capture that runs far longer.
## Reviewing
Light and dark both captured at 1440×900 @2x. The new surfaces are the
ones to
scrutinise; the rest is a like-for-like refresh.
### One leftover
Dropping `dashboard/stale-tasks-panel` leaves
`{light,dark}/dashboard/stale-tasks-panel.png`
tracked but unused — they need deleting by hand.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Co-authored-by: Dotta <[email protected]>
Co-authored-by: ClaudeCoder <[email protected]>
Fixes the harness limitation flagged in #68: the seeded instance always
has a company, so the create-a-company wizard was unreachable and
onboarding shots fell back to the Dashboard.
**How:** `run.mjs` gains a phase 3.5 — after health check, before
seeding — that captures targets marked `phase: "pre-seed"` while the
instance is still company-less (`/onboarding` serves the wizard there).
`capture.mjs` gains a `phase` option (`--phase`); post-seed stays the
default, so existing invocations are unchanged.
**Retargeted:** the four true wizard shots to `/onboarding` (goal-field
fills the company name and advances to the Mission step); the two budget
shots to the agent configuration form, since the wizard has no budget UI
(verified at v2026.720.0).
**Validated with real runs against the v2026.720.0 tag** — all pre-seed
captures succeed with zero step failures, light and dark visually
verified (wizard step 1 empty, filled name, Mission step). Refreshed
PNGs included.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <[email protected]>
Recapture every screenshot flagged in SCREENSHOTS_PENDING.md (98 entries; 233
PNGs updated across light/dark) against parent `master`, and stamp registry.json
with the new captured_sha. Mark SCREENSHOTS_PENDING.md as caught up.
Also fix two isolation gaps that made `screenshots:refresh` unusable while a real
local Paperclip is running:
- Free embedded-Postgres port: onboard hard-codes port 54329 (no env/flag
override; the port comes only from config.json), which collides with a real
local instance. run.mjs now generates the config in external-DB mode (keeping
the scratch data dir pristine) and rewrites database.embeddedPostgresPort to a
scanned free port before boot.
- Parent .env neutralized: the server loads PARENT_REPO/.env from its cwd via
dotenv (override: false), which leaked DATABASE_URL (real external DB on 5432)
and SERVE_UI=false into the "isolated" instance. instanceEnv() now pins
DATABASE_URL="", DATABASE_MIGRATION_URL="" and SERVE_UI="true" so these win.
seed-execution-workspace.mjs now throws instead of falling back to 54329, so the
direct-DB seed can never connect to a real database.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Validated the pipeline against a live local_trusted instance and fixed what
the dry run surfaced, plus made the demo company look genuinely in-use.
seed.mjs — rich, idempotent, soft-failing demo dataset:
- brand color + monthly budget; 5-agent org (Ada/Bob/Cleo/Dax/Eve) with
titles, icons, instructions, per-agent budgets, assigned skills
- 4 company skills, 2 goals, 2 projects + a git workspace, 8 issues with
mixed statuses/priorities/assignees, 2 sub-issues, a 4-message chat thread
- routine + one execution-history row, 2 invites, bundled plugins installed,
32 cost events + 5 finance events so the Costs/Finance dashboards are non-zero
- enum/validation fixes from the live run: goal status "active" (not
"in_progress"), workspace sourceType "git_repo", comment authorType "user"
(a board actor cannot post as "agent")
run.mjs:
- kill the server's whole process group on teardown (was orphaning the
server child and holding port 3197)
- pre-clean the scratch home at startup so every run gets a fresh DB and the
one-shot seed steps (comments/invites/events) always fire
sync-registry.mjs: drop the scaffolder's _todo note once route/depends_on
are populated.
package-lock.json: pick up @playwright/test.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Builds an end-to-end pipeline that keeps docs screenshots in sync with the
latest Paperclip build, replacing the previously-manual capture step.
scripts/screenshots/:
- config.mjs isolated-instance env helpers (local_trusted/loopback,
scratch PAPERCLIP_HOME, never touches ~/.paperclip)
- seed.mjs idempotent demo-data seeding via REST (company/agents/
project/goal/issues/routine/workspace); writes .seed-ids.json
- routes.mjs 56 CAPTURE_TARGETS with real ui/src depends_on paths;
resolveRoute() uses the server-derived issuePrefix
- capture.mjs Playwright capture (light+dark, 1440x900 @2x), theme seeded
to match ui/index.html, stamps registry captured_sha
- sync-registry.mjs back-fills route + depends_on into registry.json
- run.mjs one-command orchestrator: onboard -> health -> seed ->
sync-registry -> capture -> teardown
- README.md prerequisites, flow, overhaul mode, safety notes
Wiring:
- package.json: screenshots:{seed,capture,sync-registry,refresh,refresh:all}
+ @playwright/test devDependency
- screenshots:refresh:all is the full re-take mode for major UI/UX overhauls
- sync-docs SKILL.md Phase 6: capture is now automatable (still PR-reviewed,
never auto-pushed); maintenance.md updated to match
- .gitignore: scripts/screenshots/.seed-ids.json
Auth is free in local_trusted mode (every request is admin), so no login flow
is needed. Capture/staleness still surface to a PR for human review.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
