- The per-project Workspaces tab is hidden until the project has workspace
activity (showWorkspacesTab requires summaries > 0); say so instead of
'shows up on each project', and drop the never-shown per-project empty
string. The reliable empty state is the company-wide 'No workspace
activity yet.'
- Correct the surfacing rule: a primary workspace surfaces because it's the
primary (not 'has a working directory and runtime config'); non-primary
project workspaces need runtime services/config.
- Replace the stale 'Each entry shows' list (old table columns: mode /
provider type / opened) with the actual ProjectWorkspaceSummaryCard fields
(kind, name, branch, path, services, status, linked tasks, updated).
- Note plugin tabs appear alongside the base tabs (e.g. workspace-diff's
Changes tab), not strictly after them.
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]>
Publish accumulated nightly drafts to main and document the new surfaces
shipped between v2026.529.0 and v2026.609.0 (130 parent commits).
New pages (gaps not covered by nightly drafts):
- docs/reference/cli/token.md — `token agent` / `token board` API-key commands
- docs/reference/cli/connect.md — interactive `connect` setup wizard
- docs/reference/api/teams-catalog.md — teams catalog REST API
Also:
- Stamp paperclip_version: v2026.609.0 on 49 release doc pages
- Register the 3 new pages in site/content.json nav
- Bump .sync-state.json base_release_tag to v2026.609.0
Verification: 49 pages checked against v2026.609.0; 11 verifier flags,
all confirmed false-positives (flagged flags/env-vars exist in parent).
Drift: 0. Reconciliation: 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- docker.md / gemini-local.md: Gemini CLI now bundled in the official
image (GEMINI_SANDBOX=false); backfill opencode_local in bundled list
(paperclip #7693)
- external-adapters.md: external adapters can override built-in types;
document override + fallback lifecycle, correct stale 'cannot be
overwritten' note (paperclip #7394)
- regenerate PENDING.md / SCREENSHOTS_PENDING.md (18 settings/adapter
screenshots stale after instance-settings IA move, paperclip #7680)
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
`company current` exists in the CLI source
(cli/src/commands/client/company.ts) but was missing from the company
reference page. Add it to the Read Commands code block and table with a
note on how it resolves the scoped company (--company-id, context,
PAPERCLIP_COMPANY_ID, or agent credential) and that it returns the same
full record as `company get <companyId>`.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Three settled surfaces aged past the 24h quarantine since the last run:
- Teams Catalog (#7550): new `teams` CLI page + Team Catalog guide for the
installable bundled/optional starter teams.
- Company Artifacts (#7621): new Artifacts guide + `GET /api/companies/{id}/artifacts`
API section under Companies.
- Low-trust review containment / trust presets (#7530): new Administration page
covering the `standard` / `low_trust_review` presets and quarantine-then-promote
review flow.
Nav merged in site/content.json. PENDING.md and SCREENSHOTS_PENDING.md regenerated
(40 screenshots stale in the settled window). Phase 5.5 verification clean; drift clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Cumulative window v2026.529.0 → e78c064 (24h-quarantined nightly cutoff).
Three user-visible surfaces newly documented this run:
- skills: app-shipped catalog now supports *referenced* entries fetched from
an external GitHub repo pinned to a commit (CatalogSkill.source). First one
is the research-category last30days skill. Documented in the Skills
reference and the org Skills guide.
- routines: scheduled ticks are suppressed (recorded as skipped, no backfill)
while the routine's project is paused.
- companies: archiving runs a cascade that pauses active agents
(pauseReason company_archived) and cancels queued wake-ups.
All claims verified against parent code (Phase 5.5 clean). Build + link/nav
checks pass; no drift. Teams Catalog, company-artifacts page, and low-trust
review containment are quarantined (<24h) and deferred to the next run.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Recapture the 82 stale screenshots (light + dark, 1440×900 @2x) against
a release-code instance booted at v2026.529.0 (911a1e8). Registry was
already stamped at that SHA, so captured_sha is unchanged.
Verification pass against the release codebase also found one authored
claim wrong: the execution-workspace environment precedence is
issue → project → agent → instance default (project policy outranks an
agent's own default), not issue → agent → project. Corrected
docs/guides/projects-workflow/workspaces.md to match
server/src/services/execution-workspace-policy.ts.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Add the two release features quarantined from nightly, and stamp
paperclip_version on every touched page.
- Claude Local: document UI-driven live model discovery (#6953) —
/v1/models lookup via ANTHROPIC_API_KEY, 60s cache, built-in fallback,
Bedrock IDs, and the refresh control.
- Workspaces: document reused-workspace environment consistency and
finalize-gated dependent wakes / interaction.accept (#6969).
- Stamp paperclip_version: v2026.529.0 on all 14 touched pages.
- Regenerate SCREENSHOTS_PENDING.md: 90/276 stale for this window.
Inherits the six features already drafted on nightly: resource
memberships (#6677), document annotations (#6733), bundled plugins in
plugin manager (#6734), skills CLI + catalog (#6782), first-admin
claim (#6755).
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]>
Refresh the shots unlocked by the runner-agent seeding and new targets:
agent runs/transcript/status, environment test pass, approval revision box,
adapter health rows, and the onboarding goal field. registry.json stamped.
Every screenshot referenced in the docs is now captured against the current
build; the only un-refreshed files are unreferenced orphans.
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]>
Full automated recapture via the extended pipeline against a richly-seeded
demo instance: 220 screenshots (110 targets x light/dark, 1440x900 @2x).
Adds coverage for dashboard, tasks, activity, org chart, routines, skills,
workspaces, approvals, budget-utilisation states, new-agent forms, and
empty-state onboarding. registry.json route/depends_on backfilled and
captured_sha stamped for all 220 entries.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Full automated capture of the docs UI screenshots (light + dark, 1440x900 @2x)
via `npm run screenshots:refresh`, run against a fresh seeded demo instance.
- 112 PNGs (56 light + 56 dark) refreshed across all covered surfaces
- registry.json: route + depends_on backfilled for the 110 captured entries,
captured_sha/captured_against stamped to the parent commit they were taken at
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Cumulative nightly sync from v2026.525.0 → parent master b754582:
- New API page for resource memberships (join/leave projects & agents)
- Document annotations API + guide sections on issue documents
- Bundled plugin discovery (experimental first-party plugins) in admin + API docs
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Adds docs/how-to/update-paperclip.md covering the three install paths
(Desktop App, npx/CLI, git clone) and wires it into the How-to Guides
sidebar.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
Covers both storage shapes (plain value on the agent vs secret reference
via Company Settings → Secrets), with per-provider notes for Anthropic,
OpenAI, Google Gemini, xAI, Cursor, and OpenCode. Includes a callout for
the Claude.ai subscription → console-key switch that's been tripping up
existing users.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
- OpenCode's non-sandbox default is 60s, not 45s.
- Cursor has two probes (version + hello) with different sandbox/non-sandbox
defaults.
- Grok Local does NOT have sandbox-aware probe timeouts in this release —
it ships with a flat 45s. Called out as follow-up.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- UTF-8 partial-chunk claim was wrong: the actual fix routes bridge-channel
commands through the non-streaming exec path so the `@cloudflare/sandbox`
SDK can't drop the final stdout chunk on short shells. Adapter sessions
still stream.
- Probe-budget claim sharpened: the change is a static doubling of
`helloProbeTimeoutSec` to 90s when targeting a sandbox (45s otherwise),
not a dynamic warming-aware budget. Lives in each local adapter's
test.ts, not in the Cloudflare provider.
- Pi install fix sharpened: the actual change is a corrected npm package
namespace + version pin (`@earendil-works/[email protected].0`), not
a path inside the bridge image.
- Added the previously-missing `DEFAULT_BRIDGE_REQUEST_TIMEOUT_MS` bump
from 30s to 300s, which was also in the v2026.517.0 window.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- New adapter page: Grok Local (`grok_local`), wired into the Adapters
overview table and nav.
- Issues guide: document locking workflow (lock/unlock, derived-document
redirect for agents) and the new Board-view scaling controls (density,
cold-lane mode, column page size). Documents are now live-refreshed.
- Issues API reference: lock / unlock endpoints, plus the
`redirectedFromLockedDocument` response for agent writes into locked
documents.
- Sandbox Providers (Cloudflare): reliability tuning notes — larger
instance type, SSE keepalives, UTF-8-safe stdout, sandbox-aware probe
budgets, corrected Pi install path.
- LLM Wiki plugin: bundled bootstrap assets and namespace-safe spaces
migration validation.
- SCREENSHOTS_PENDING.md regenerated for v2026.517.0.
- .sync-state.json bumped to v2026.517.0.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Address operator confusion observed in support channels: users on
non-Docker / systemd installs report not being able to install the
LLM Wiki plugin. Root cause is documentation, not code — the plugin
is published to npm and installs cleanly via the standard CLI, but:
- Our reference page buried the npm package name in the "developing
from a checkout" subsection. Operators scanning for the install
command had to read past the dev section to find @paperclipai/...
Now the Quick install section is the first actionable thing on
the page, with the explicit `paperclipai plugin install` line.
- `paperclipai plugin examples` (and the dashboard's Available
Plugins list) only returns the four reference example plugins
from BUNDLED_PLUGIN_EXAMPLES in server/src/routes/plugins.ts. It
is NOT the full first-party catalogue. Operators who looked there
for LLM Wiki concluded it wasn't shipped. Added a callout to
docs/administration/plugins.md to make this explicit and link out
to the LLM Wiki reference page for plugins installed by full npm
name.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Three first-party plugins were missing from the docs because they
shipped before /sync-docs started tracking the repo (or were missed
in a prior batched catchup):
- NEW docs/reference/plugins/llm-wiki.md — full reference page for
the LLM Wiki plugin (introduced in v2026.512.0, PR #5716). Covers
what the plugin contributes to the dashboard, its managed agent
and skills, REST routes, and operator tips.
- docs/administration/plugins.md — adds the missing
plugin-orchestration-smoke-example bullet to the first-party
examples list (sibling to the four already listed).
- docs/reference/adapters/sandbox-providers.md — adds a Fake Sandbox
(provider: "fake-plugin") section for the private
@paperclipai/plugin-fake-sandbox package, intended for testing and
reproducing plugin-runtime issues without external infrastructure.
- site/content.json — nav entry for the new LLM Wiki page under
Reference / Plugins.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Authored docs to track the v2026.512.0 → v2026.513.0 window:
- New: docs/how-to/develop-a-plugin-locally.md — friendly walkthrough
of `paperclipai plugin init`, local-path install, dev watcher, reload.
- New: docs/guides/day-to-day/blocked-inbox.md — guide to the new
Blocked Inbox tab, chip variants, filters, sort, and triage.
- docs/guides/day-to-day/issues.md — Blocked tab cross-ref; new
"Recovery actions" and "Walking through sub-issues" sections.
- docs/reference/api/issues.md — "Recovery actions" API section
(routes, RecoveryAction shape, resolution-outcome enum).
- docs/reference/adapters/claude-local.md — "Resuming a session's
workspace" subsection (host cwd, system-root rejection, non-file
skip, driver-plugin allowlist).
- docs/reference/plugins/sdk.md — "Worker entrypoint validation"
section; version bumped to v2026.513.0.
- docs/administration/plugins.md — "Developing plugins locally"
subsection linking the new how-to.
- site/content.json — nav entries for the two new pages.
- SCREENSHOTS_PENDING.md — new UI surfaces flagged for capture.
Co-Authored-By: Claude Opus 4.7 <[email protected]>
Closes the four coverage gaps surfaced by the docs audit:
Gap 1 — env vars (verify-edit: 0 high-confidence unverified)
- docs/reference/deploy/environment-variables.md
- Added `BETTER_AUTH_SECRET` row to "Deployment And Auth" (falls back
to `PAPERCLIP_AGENT_JWT_SECRET`; server refuses to start without
either), and `SERVE_UI` row to "Server Configuration" (overrides
`server.serveUi`). Both values copied verbatim from parent at
v2026.512.0 (.env.example + server/src/auth/better-auth.ts).
Gap 2 — skill bundles (verify-edit: 0 unverified)
- docs/reference/skills.md
- Added one-liner entries for `diagnose-why-work-stopped`,
`paperclip-converting-plans-to-tasks`, `para-memory-files`,
`terminal-bench-loop`. Descriptions distilled from each parent
`SKILL.md` frontmatter at v2026.512.0.
Gap 3 — Plugin SDK page (verify-edit: 0 high-confidence unverified)
- docs/reference/plugins/sdk.md (new)
- site/content.json (new "Plugins" section under Reference tier)
- Comprehensive reference for @paperclipai/plugin-sdk. Every public
export (definePlugin, runWorker, startWorkerRpcHost, test harness,
bundler presets, dev server, host-client factory, JSON-RPC protocol
helpers, all manifest/protocol types, zod re-export, constants)
is listed verbatim from packages/plugins/sdk/src/index.ts at
v2026.512.0. 13 unverified items are SHOUT_CASE SDK constants
mis-classified as env vars by verify-edit (all confidence: null).
Gap 4 — REST routes (verify-edit: 0 high-confidence unverified)
- docs/reference/api/adapters.md (new) — 9 endpoints from
server/src/routes/adapters.ts.
- docs/reference/api/plugins.md (new) — install/lifecycle/config/jobs/
webhooks/local-folders/bridge endpoints from
server/src/routes/plugins.ts.
- docs/reference/api/instance-admin.md (new) — umbrella covering
instance-settings, instance-database-backups, llms reflection,
environments, and execution-workspaces.
- site/content.json — added the three new pages to the API section.
- All seven flagged route files turned out to be public/admin surfaces;
none qualified as internal-only.
FOLLOW-UPS.md
- Added "Internal REST routes — intentionally undocumented" section
recording the Gap 4 triage outcome.
Verification gates
- npm run sync:test — 26/26 passed
- npm run docs:build — clean (90 markdown files)
- npm run sync:lint-links — same 3 pre-existing broken screenshots
- npm run sync:verify-nav — same 1 pre-existing orphan
- check-drift: 41 -> 43 (+2; both are the new SERVE_UI / BETTER_AUTH_SECRET
rows hitting the known env-var-missing false-positive class tracked
in FOLLOW-UPS.md; the routes-missing item for instance-admin.md is a
filename-normalization false positive — routes exist in parent).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
- cursor-cloud.md: add JSON Example block with adapterType: cursor_cloud
mirroring claude-local's structure (placeholder secret-ref for
env.CURSOR_API_KEY).
- acpx-local.md: add JSON Example block with adapterType: acpx_local
plus a leading sentence reiterating the staged-runtime callout.
- environment-variables.md: audited 428->512 window via compare-window.mjs
intersected with the env-vars watcher's parent_paths; only
server/src/config.ts and a new cloudflare driver config.ts touched —
no new env-vars beyond the existing PAPERCLIP_SECRETS_STRICT_MODE row
(refactor only). Frontmatter bumped to v2026.512.0.
- FOLLOW-UPS.md: track deferred items (tutorial narrative additions,
sandbox per-vendor depth, drift triage, screenshot anchors,
pre-existing doc issues).
verify-edit.mjs: 79 claims verified across the 3 verifiable touched
files (cursor-cloud 26/27, acpx-local 20/21, environment-variables
33/62). Remaining unverified records are pre-existing false-positive
classes documented in FOLLOW-UPS.md (env-vars watcher source list,
adapter-config envelope key not present in adapter package source,
placeholder secret-id literal).
Build clean. sync:test 26/26. sync:lint-links and sync:verify-nav
unchanged from baseline (same 3 pre-existing broken screenshot refs,
same 1 pre-existing orphan).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Manifest summary:
- pr/cli-commands: NEW `paperclipai secrets list|declarations|create|link|doctor|providers|migrate-inline-env` command group [evidence: cli/src/commands/client/secrets.ts added].
- pr/adapters/cursor-cloud: NEW adapter package (genuinely new per detect-renames; agentConfigurationDoc surfaced from src/index.ts).
- pr/adapters/acpx-local: NEW adapter package (genuinely new); ACPX runtime execution still being enabled in stages.
- pr/adapters (sandbox-providers): NEW cloudflare, daytona, exe-dev sandbox provider plugins (genuinely new per detect-renames). E2B already shipped in v2026.427.0; now grouped with siblings on the new sandbox-providers page.
- auto-merge/env-vars: 20 file matches but no new env vars added beyond a code re-org of PAPERCLIP_SECRETS_STRICT_MODE.
- pr/rest-routes: 12 modifications, no new top-level routes.
- pr/agent-skills: NEW skills/diagnose-why-work-stopped and skills/terminal-bench-loop (genuinely new) — internal skills.
- pr/plugin-sdk, pr/schemas, pr/web-ui, pr/server-services, pr/server-adapters: internal.
Edits applied: 5
- docs/reference/adapters/cursor-cloud.md (NEW page mirroring cursor-local structure)
- docs/reference/adapters/acpx-local.md (NEW page mirroring claude-local structure)
- docs/reference/adapters/sandbox-providers.md (NEW page covering cloudflare, daytona, exe-dev, e2b)
- docs/reference/cli/commands.md (add `secrets` command group; bump paperclip_version)
- site/content.json (nav additions: Cursor Cloud, ACPX Local, Sandbox Providers in Adapters Reference)
Verification:
- All `paperclipai secrets` subcommand names and flags verified verbatim against cli/src/commands/client/secrets.ts.
- All cursor-cloud and acpx-local field names verified verbatim against agentConfigurationDoc strings in packages/adapters/*/src/index.ts.
- Sandbox provider env vars (DAYTONA_API_KEY, EXE_API_KEY, E2B_API_KEY) flagged as high-confidence-unverified — known false positives: these env vars are documented in plugin README.md and plugin manifest.ts files, not in server/src/config.ts. verify-edit.mjs only searches the server env source set. Logged in CATCHUP_RUN_REPORT_2.md.
Renames detected: none (detect-renames confirmed all five new dirs are genuinely new)
Reconcile flags: none
Release notes one-liner: "Secrets CLI, Cursor Cloud and ACPX adapters, Cloudflare/Daytona/exe.dev sandbox providers."
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Manifest summary:
- pr/cli-commands: NEW `paperclipai env-lab up|status|down|doctor` command group [evidence: cli/src/commands/env-lab.ts added].
- auto-merge/env-vars: NEW DATABASE_MIGRATION_URL [evidence: server/src/config.ts process.env.DATABASE_MIGRATION_URL].
- pr/adapters: NEW packages/plugins/sandbox-providers/e2b/** — first-party E2B sandbox provider plugin (genuinely new, confirmed by detect-renames). Documented at high level via the existing plugins page; a dedicated adapter reference page is deferred to a follow-up (the surface is plugin-driven, not adapter-driven).
- pr/rest-routes: NEW server/src/routes/auth.ts, instance-database-backups.ts, user-profiles.ts. The auth and user-profile routes are user-account internals (managed by the UI flows already documented in administration/cli-auth.md). instance-database-backups already surfaced indirectly via docs/reference/deploy/database.md.
- pr/agent-skills: NEW skills/paperclip-dev (genuinely new per detect-renames) — internal contributor skill, not user-facing.
- pr/plugin-sdk, pr/schemas, pr/web-ui, pr/server-services, pr/server-adapters: internal.
Edits applied: 2
- docs/reference/cli/commands.md (add `env-lab` command group; remove orphan `routines` heading from previous window; bump paperclip_version)
- docs/reference/deploy/environment-variables.md (add DATABASE_MIGRATION_URL row; bump paperclip_version)
Verification:
- env-lab subcommand names/flags verified verbatim against cli/src/commands/env-lab.ts
- DATABASE_MIGRATION_URL verified verbatim against server/src/config.ts
Renames detected: none (detect-renames confirmed skills/paperclip-dev and packages/plugins/sandbox-providers/e2b are genuinely new)
Reconcile flags: none
> ⚠ TODO: dedicated docs/reference/adapters/e2b.md (or plugins reference) for the E2B sandbox provider plugin. The configSchema (template/apiKey/timeoutMs) and capability `environment.drivers.register` are stable in v2026.427.0 — write the page when the broader sandbox provider story is documented.
Release notes one-liner: "env-lab SSH fixtures, E2B sandbox provider plugin, instance database backups, user profiles."
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Manifest summary:
- pr/cli-commands: company import accepts .zip archives; new `paperclipai auth login|logout|whoami` subcommands (already documented in administration/cli-auth.md); new worktree:merge-history (already documented in cli/commands.md).
- pr/rest-routes: new server/src/routes/routines.ts (already documented at docs/reference/api/routines.md); new server/src/routes/company-skills.ts referenced via docs/how-to/write-a-company-skill.md (POST /api/companies/{companyId}/skills/import).
- pr/adapters: each local adapter (claude/codex/cursor/gemini/opencode/pi) gained an internal server/skills.ts surface — no user-facing doc change.
- pr/agent-skills: paperclip and paperclip-create-agent skill bundle internals — no user-facing doc change beyond existing reference.
- pr/schemas, pr/web-ui, pr/server-services: internal — no surface-level user-facing changes.
Edits applied: 1
- docs/reference/cli/commands.md (note .zip support on `company import`; add paperclip_version frontmatter)
Verification:
- Verified claims: dominantly verified
- Unverified high-confidence: 0 net-new (pre-existing PAPERCLIP_* CLI-only env vars are not in server config — known false positives, logged as suspicious)
- Suspicious: ~21 (existing CLI env vars not in server config sources)
Renames detected: none
Reconcile flags: none
Release notes one-liner: "Authenticated CLI device-code login, board claim, company import/export v2, routines API."
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Closes the five deferred items from the prior gotcha audit:
A. Link checker — scripts/sync/lint-links.mjs walks docs/**/*.md and
verifies every relative markdown/image link resolves to an existing
file. Skips external URLs, absolute SPA routes (/...), URI schemes
(mailto:, agent://, etc.), and template placeholders. Found 3 real
pre-existing broken links to missing screenshots — not fixed in
this commit, but the tool will now block any new ones.
B. Nav verification — scripts/sync/verify-nav.mjs cross-checks
site/content.json against the docs filesystem. Dangling entries
(in nav but missing on disk) are errors; orphans (on disk but not
in nav) are warnings. Found 1 real orphan (require-board-approval-
before-spend.md from c0ff148 — never registered in content.json)
that the user should triage separately.
C. Screenshot registry backfill — scripts/sync/backfill-screenshots.mjs
scaffolds entries for every PNG under docs/user-guides/screenshots/.
Run once; registry.json now ships with 274 scaffolded entries
(137 light + 137 dark). Each has placeholder `depends_on: []` and
a `_todo` field; humans fill in parent-repo path anchors over time
to activate staleness detection per-entry. Re-runs preserve any
entry with non-empty depends_on.
D. content.json edit serialisation — SKILL Phase 5 now requires
subagents to return a structured `nav_addition` object alongside
page content rather than editing site/content.json directly. The
orchestrator merges all nav_additions on the main thread after
subagents finish. Prevents the parallel-write race where two
subagents creating new pages clobber each other's nav entries.
E. gh compare truncation — SKILL Phase 2 now explicitly documents
the GitHub compare endpoint's ~300-file/~300-commit cap and the
window-splitting fallback (walk intermediate release tags for
release mode; binary-split commit list for nightly mode).
Also wires the scripts into package.json (sync:lint-links,
sync:verify-nav, sync:check, sync:backfill-screenshots) and into
SKILL Phase 7 (sync:check runs before commit; dangling/broken-link
failures abort the run).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Scaffolds the data layer for the /sync-docs skill:
- scripts/sync/anchor-map.json — declares which parent-repo paths each
watcher tracks, where they route in our docs, and whether changes
are auto-merge (mechanical, schema-bound) or PR tier (judgment calls).
- scripts/sync/state.example.json — template for .sync-state.json.
- .sync-state.json — per-branch sync state, seeded for an initial
release-mode run from v2026.318.0.
- docs/user-guides/screenshots/registry.json — screenshot dependency
tracking so the skill can flag stale captures.
The skill itself follows in the next commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Strict mode is server-side enforcement for persisted env bindings only;
it does not cover `paperclipai configure --section llm`. Document the
four enforcement points, note that `config.llm.apiKey` is plaintext-only
with no `secret_ref` support, and flag `pnpm secrets:migrate-inline-env`
as a repo-source script that scans only `agent.adapterConfig.env`.
Mirror the strict-mode wording on the env-vars reference page.
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
Practitioner-focused recipe for the company budget brake — copy-pasteable
cURL for caps and per-agent caps, alert configuration, billing-code
attribution, and an end-to-end verification flow that forces a 100% pause
and recovers from it. Closes PAP-1811.
Co-Authored-By: Paperclip <[email protected]>
- Add a collapsible Mermaid state-diagram alongside the ASCII diagram for renderers that support it.
- Document that release preserves assigneeUserId (verified against svc.release in the runtime: only assigneeAgentId, checkoutRunId, and status are written).
- Add a Common Mistakes table covering PATCHing into in_progress, retrying 409s, free-text blockers, cancelled blockers, executionState participant rules, reopen vs status, and the X-Paperclip-Run-Id header.
Co-Authored-By: Paperclip <[email protected]>
Three side-by-side paths (OpenClaw invite, HTTP webhook, custom Python
script) with copy-pasteable examples, a tradeoffs table, and pointers to
the companion adapter references.
Closes PAP-1807. Companion example repo tracked in PAP-2578.
Co-Authored-By: Paperclip <[email protected]>
Adds docs/reference/skills.md covering file shape, install
pipeline, assignment, scoping, skill-vs-plugin-vs-adapter,
naming collisions, versioning, and troubleshooting. Wires it
into the Reference tier in content.json and updates the org
skills guide to link to it. Also corrects the agents API page,
which advertised skillIds/skillKeys for /agents/:id/skills/sync
but the validator only accepts desiredSkills.
Co-Authored-By: Paperclip <[email protected]>
Introduces docs/reference/cli/commands.md — a single searchable
reference covering every paperclipai subcommand, flag, environment
variable, and exit code, plus five end-to-end example flows. Linked
into the Reference → CLI nav and cross-referenced from the CLI
overview. Resolves PAP-1794.
Co-Authored-By: Paperclip <[email protected]>
Two static-review findings from PAP-2514 applied:
- Rename to "Quickstart Path" (was "5-Minute Path"). The 5-minute claim
with a 15-minute table read as misleading; the title is now honest and
the 5-minute promise stays in the body where it can be qualified.
- Move installation out of the numbered path. Install is one-time setup;
the path proper is now three steps totaling ~5–11 min, which lines up
with the body's promise sentence. Drops the misleading "Desktop App
is faster if you're not a Node developer" line — Claude Code being a
separate prereq breaks that claim.
Co-Authored-By: Paperclip <[email protected]>
Cross-link the org/skills guide to the agents API surface so a reader
who wants to script skill assignment can find /skills/sync and the
desiredSkills hire-time pointer without having to reverse-engineer the
endpoint from the UI.
Refs PAP-2507, PAP-1819.
Co-Authored-By: Paperclip <[email protected]>
