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]>
## Summary
- adds a new **Experimental** documentation section with an overview and
10 feature pages covering motivation, enablement, usage, and caveats
- wires the section into `site/content.json` and refreshes the
experimental flag list in administration settings
- adds six screenshot capture targets and 12 QA-verified screenshots
(light and dark) for experimental feature surfaces
- includes the screenshot-pipeline fixes needed to seed and capture
those surfaces reliably
## Screenshots
Adds light and dark captures for:
- environments
- cloud upstream
- file viewer
- external objects
- server info
- recovery preview
The 12 PNGs were verified on Paperclip task PAP-14814 on July 21, 2026
and were preserved byte-for-byte during the rebase.
## Verification
- `npm run sync:lint-links` — pass; no broken internal links
- `npm run sync:verify-nav` — pass; only the two pre-existing CLI
orphans
- `npm run sync:verify-screenshots` — pass; every documented screenshot
is tracked and indexed
- `npm run docs:build` — pass
Paperclip: PAP-14705
---------
Co-authored-by: DevRel Gemini <[email protected]>
Co-authored-by: Paperclip <[email protected]>
Co-authored-by: Claude Fable 5 <[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]>
Backfills `route` + `dependsOn` for the 20 registry entries flagged in
#68 as never wired for automated capture (plus marks the hand-annotated
`dashboard-overview-annotated` as intentionally manual instead of
leaving its stale `_todo`).
Routes verified against the v2026.720.0 route table in `ui/src/App.tsx`;
every `dependsOn` path verified to exist at that tag. Details and
caveats (dialog-step captures, the onboarding harness limitation) in the
commit message.
No images change in this PR — next capture pass picks these up.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude Fable 5 <[email protected]>
Ships the docs for **paperclip v2026.720.0** to `docs.paperclip.ing`.
Window: `v2026.707.0...v2026.720.0` — 196 commits, 1,523 changed files,
0 truncated leaves.
Most of this release was already drafted on `nightly` over the past
cycle (Cases, Folders, Decision Training, Attention, Built-in Agents,
company skill policy, inbox agent policy, `costStatus`, the ACP engine
graduation and `acpx_local` retirement, and
`PAPERCLIP_TOOL_ACTION_SIGNING_SECRET`). This PR adds the surfaces
nightly had **not** yet covered, then stamps the release version across
everything touched this cycle.
## New pages
**`docs/reference/api/tool-gateway.md`** — the MCP Tool Gateway, the
headline experimental feature. Covers applications and connections,
catalog entries and risk levels, profiles/entries/bindings, the
tool-access policy and its decision outcomes, named MCP gateways and
their tokens, the audit feed, and the Smoke Lab. Documents the five
`tools:*` permission keys and the viewer/membership rules on routes that
don't use a permission key. Flags both experimental gates (`enableApps`,
and `enableSmokeLab` separately).
**`docs/reference/api/summary-slots.md`** — the built-in Summarizer and
summary slots. Covers slot addressing (`scopeKind` / `scopeId` /
`slotKey`), generation, revisions, and the `enableSummaries` gate.
Cross-references Built-in Agents rather than duplicating it.
## Updated
**`docs/guides/org/skills.md`** — Skill Studio (the three-pane authoring
workspace, saved inputs, test runs and their unavailability reasons, run
templates, version history), nested skill folders and the My Skills
view, importing skills straight from a project, and company skill forks.
Cross-references the existing Folders and Company Skill Policy API pages
instead of restating them.
## Release stamping
`paperclip_version: v2026.720.0` applied to all 26 pages touched this
cycle — bumped on 10 that already had frontmatter, added to 13 that had
none (including the API pages nightly authored, which were intentionally
versionless until they merged to `main`).
## ↻ Renames detected
`detect-renames.mjs` reports no directory renames. It flags one
`removed_dirs_no_match`:
- `packages/adapters/acpx-local` — **already reconciled on nightly.**
The adapter was retired upstream (ACP became a capability of each
harness adapter rather than a standalone adapter).
`docs/reference/adapters/acpx-local.md` is now a retired stub that
points at Claude Code / Codex / Gemini CLI and documents the automatic
migration. No action needed.
## Screenshots — full overhaul recommended
**248 of 298** registry entries are stale. This release landed a
design-system convergence (single-source design tokens, retuned theme,
broad Card/Badge adoption, a multiplicative radius ladder, unified list
surfaces, Lucide task-status glyphs), so nearly every captured surface
moved. This is an overhaul cycle, not a targeted refresh:
```sh
npm run screenshots:refresh:all
```
Full per-entry breakdown in `SCREENSHOTS_PENDING.md`. Captures go to
their own PR for review — nothing is auto-pushed.
## Verification
- **Drift:** clean — 0 records against `903bd15` (8 parent paths, 57 CLI
commands, 66 env vars, 389 REST routes, 18 permission keys, 4 roles).
- **Claim verification:** `verify-edit.mjs` against `v2026.720.0` — **0
unverified, 0 suspicious** across all three authored files.
- **Reconciliation:** no disappeared manifest entries.
- **`npm run docs:build`:** passes — 169 markdown files, sitemap and
robots generated.
- **`npm run sync:check`:** links clean (172 files), nav clean,
screenshots indexed, drift clean.
- **Nav orphans:** `docs/reference/cli/commands.md` and
`docs/reference/cli/control-plane-commands.md` — intentional redirect
anchors, expected.
`.sync-state.json` bumped to `base_release_tag: v2026.720.0` /
`base_release_sha: 903bd157…`, which also repoints the drift checker's
pinned ref (the previous `f12bb27…` no longer resolves upstream).
No open `nightly-draft/*` PRs to fold in.
## Checklist
- [ ] Tool Gateway page reads correctly for an operator enabling
`enableApps` for the first time
- [ ] Summary Slots experimental gating is accurate
- [ ] Skill Studio guide matches what you see in the running UI
- [ ] Decide whether to run the screenshot overhaul before or after
merging this
- [ ] **After squash-merging: run `node scripts/sync/realign-nightly.mjs
release/v2026.720.0 --push` before the next nightly sync.** The squash
severs `main`↔`nightly` ancestry; the realign (shipped in this PR)
prevents add/add conflicts at the next nightly run.
🤖 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]>
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]>
A user reported the Workspaces screen looked empty with "no options," and
that all but one of the workspace screenshots were blank/identical.
Both were real problems:
Docs (docs/guides/projects-workflow/workspaces.md)
- Add a "Before you start" section: workspaces are gated behind the
experimental "Enable Isolated Workspaces" flag, the screen is monitor-only
(no manual create), and it stays empty until an agent runs an isolated
task — with the actual empty-state strings ("No workspace activity yet." /
"No non-default workspace activity yet.").
- Correct the detail screen: it now has Tasks / Services / Configuration /
Runtime logs / Routines tabs (+ plugin tabs), not "three tabs." Rename the
Issues tab to Tasks (its real label) and add a Services tab section. The
former "Workspace commands panel above the tabs" is now the Services tab
plus header quick controls.
- Clarify the company-wide Workspaces screen vs. the per-project Workspaces
tab and the surfacing rules. Fix the misleading "multiple isolated
workspaces" caption.
Screenshots
- Root cause: the seed only created a *project* workspace and pointed the
execution-workspace detail routes at its id, so those pages were captured
mid "Loading workspace…". Execution workspaces have no REST create endpoint
(they're provisioned by a real heartbeat), so seed-execution-workspace.mjs
now inserts a realistic one directly into the instance's embedded Postgres:
an isolated git-worktree workspace with runtime config, a running service,
provision/start/failed-job operation logs, and linked tasks.
- routes.mjs: add the {executionWorkspaceId} token, repoint the detail routes
to it, add a Services tab target, and drop the duplicate
org/execution-workspaces-list target (same URL as workspaces/list).
- Recaptured workspaces/{list,configuration,services,runtime-logs,issues} in
light + dark; all now render real content.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
The seeded org agents were created as `process` adapters with an empty
adapterConfig. The screenshot instance runs with no LLM provider and the
scheduler heartbeats every enabled agent, so each agent's heartbeat failed
instantly — the captured UI was dominated by red "error" states ("5 errors"
on the dashboard, "Ada failed after 1 second" on agent detail).
Give every demo agent a shared DEMO_AGENT_CONFIG: a process command that
always exits 0. Heartbeats now complete cleanly, so agents render as healthy
idle/running/paused with tidy transcripts. Recaptured all targets (light +
dark) against paperclip 911a1e8 — dashboard now reads "0 errors".
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Previously sync-registry only *updated* existing registry entries, so a newly
introduced screenshot target was captured but never indexed — and the
/sync-docs staleness check only flags entries it can see, so such a shot would
silently drift out of date (exactly what happened to issues/inbox-unread).
sync-registry now appends a registry entry (file, theme, viewport, route,
depends_on) for any CAPTURE_TARGET that has none, and sorts entries for stable
diffs. run.mjs runs sync-registry on every capture, so the index now stays
complete automatically. Audit: 0 target files missing from the registry, 0
without depends_on — every documented screenshot is tracked for staleness.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Close the remaining gap so every screenshot referenced in the docs is current.
seed.mjs — process-adapter "runner" agents (no LLM needed; the process adapter
executes a shell command):
- "Task Runner" runs `sh -c "echo ..."` → a real completed run with a STDOUT
transcript (run-transcript-view, test-environment-success via the config
Test button which now passes: command sh is executable)
- "Live Task" runs `sh -c "sleep 3600"` and is woken last, so it stays
in-flight through the whole capture phase → genuine "running" agent status
and an in-progress run row
routes.mjs — targets for run-transcript-view, run-history-in-progress,
agent-status-running, test-environment-success (click "Test" → wait for the
Passed result), approvals/revision-request-input (the detail note box),
adapters/health (the adapter rows), and onboarding/goal-field (wizard step 1).
dashboard.md — the dashboard image pointed at a hand-annotated PNG that can't
be auto-captured; repoint it to the freshly captured dashboard-overview.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Grow capture coverage from 56 to 110 targets so the docs' UI screenshots are
refreshed end to end, not just the plain-URL surfaces.
capture.mjs — interaction engine:
- `steps` per target (click / fill / waitFor / press) run after the page
settles; each step is best-effort (logs + continues) so selector drift
degrades to a partial capture instead of aborting
- `clip` captures a single element (e.g. a dashboard panel), falling back to
full-page if the element isn't found
- robust locator DSL: testid / role+name / label / title / placeholder / text / css
routes.mjs — +54 targets across dashboard, tasks, issues, activity, org,
routines, skills, workspaces, settings, costs (incl. budget-bar 50/80/100%
states), new-agent forms, approvals, and empty-state onboarding. New seed-id
tokens for empty company, budget-state agents, http agent, skill, approvals.
Documents the 8 shots that are genuinely not auto-capturable offline (live-run
transcripts/status, real adapter test-pass, a nonexistent revision input, a
nonexistent adapter-health route, the hand-annotated overview, onboarding goal).
seed.mjs — extended dataset: a second empty company for empty-state shots;
three budget-utilisation agents seeded to 50/80/100% (last one paused); an
http-adapter agent; four approval items (hire / strategy / board / approved)
via REST; a resolved skill id; and the isolated-workspaces experimental flag
(PATCH /api/instance/settings/experimental).
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]>
