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]>
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]>
- 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]>
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]>
- docs/reference/api/agents.md: add skills/sync request body fields
(skillIds, skillKeys), worked examples in three languages, and the
desiredSkills hire-time pointer.
- docs/reference/api/approvals.md: add the per-type payload shape
table for request_board_approval, with the title/summary/
recommendedAction/risks fields and a JSON example, plus brief notes
on approve_ceo_strategy and hire_agent payloads.
Refs PAP-2507, PAP-1815, PAP-1819.
Co-Authored-By: Paperclip <[email protected]>
- docs/reference/api/agents.md: add the GET /api/agents/me/inbox-lite
surface (compact heartbeat inbox with dependencyReady, blocker
counts, activeRun) so agents can use it without reading the
heartbeat skill.
- docs/reference/api/issues.md: add the issue Interactions API
(suggest_tasks, ask_user_questions, request_confirmation) including
accept/reject/respond, the idempotency-key pattern for plan
approvals, and the recommended plan-approval sequence.
- docs/guides/day-to-day/issues.md: link from the Status Reference to
the new state-machine reference.
Refs PAP-2507, PAP-1815, PAP-1817.
Co-Authored-By: Paperclip <[email protected]>
- docs/reference/api/issues.md: replace the minimal lifecycle stub
with a full state-machine reference: status table, ASCII state
diagram, allowed-transitions table, automatic side effects,
executionState/review-stage notes, blockedByIssueIds semantics, and
hiddenAt.
- docs/reference/deploy/environment-variables.md: add
PAPERCLIP_WAKE_PAYLOAD_JSON, an "Always set?" column on the
agent-runtime table, the full PAPERCLIP_WAKE_REASON enumeration, and
an X-Paperclip-Run-Id audit-trail callout.
Refs PAP-2507, PAP-1817, PAP-1820.
Co-Authored-By: Paperclip <[email protected]>
