mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-08 17:37:51 -10:00
codex/https-setup-guide
18
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
c65bc9a9bf |
Release docs for paperclip v2026.916.0 (#125)
Brings **paperclip-docs** in line with paperclip **v2026.916.0**, shipping the `v2026.831.1 → v2026.916.0` cycle drafted on `nightly`, stamped to the release tag, with a documentation changelog entry. This branch was cut from `nightly` **after** merging `origin/main` into it, so it sits on top of the operator-first connectors catalog (#124) rather than reverting it. ## Manifest **New pages (4)** - `docs/reference/api/connection-intents.md` — Connection Intents API - `docs/reference/cli/connections.md` — `connections` command - `docs/reference/cli/managed-agent.md` — `managed-agent` command - `docs/reference/cli/test-drive.md` — `test-drive` command **Updated pages (17)** - Roles & Permissions + Company Administration — `tools:*` role-default changes - Connect an Agent to GitHub — managed GitHub connection (Connectors), Option C - Agents API — Managed/Remote Agent Profiles, `***REDACTED***` env serialization - Tool Gateway API — agent self-authorization (`start-authorization`, `token`) - Instance Admin API — instance-settings + task-drain routes - Plugin SDK — `ctx.access` + `ctx.authorization` clients, login-PTY/duplex streaming - Environment Variables — Paperclip ID Connector block + HTTP adapter allowlist var - Adapters: Codex (`gpt-5.6-sol` default, Fast mode, auth cache), Claude Code (Fable 5.1 + CLI floor), Grok Local (SuperGrok subscription auth), HTTP (SSRF guard), Sandbox Providers (Daytona warm runner), OpenCode (model pre-flight) - CLI: `adapter detect-model`, `onboard` tool-action signing secret - Command palette — recent tasks in sidebar - `docs/reference/changelog.md` — new `v2026.916.0` accordion entry All 21 touched pages stamped `paperclip_version: v2026.916.0`. ## Verification **Tag-accuracy gate (Phase 5.7)** — `check-tag-accuracy.mjs --tag v2026.916.0 --base main --head nightly` flagged 5 pages, **every one verified present in the code at the release tag** and cleared as known `verify-edit` false-positive classes. No content was quarantined; **no post-tag leaks**: | Page | Flagged claim(s) | Verified at tag | |---|---|---| | `cli/connections.md` | `PAPERCLIP_RUNTIME_TOOLS_*` (3) | present in `cli/src/commands/client/connections.ts` (runtime-injected env) | | `cli/managed-agent.md` | `--profile-key`, `--api-key-secret-id` | present in `cli/src/commands/managed-agent.ts` (`.requiredOption`/`.option`) | | `cli/test-drive.md` | `--harness` | present in `cli/src/commands/test-drive.ts` (`new Option`) | | `deploy/environment-variables.md` | `PAPERCLIP_ID_CONNECTOR_*` (5) | present in `.env.example` at tag | | `plugins/sdk.md` | `PLUGIN_*` (6) | present in `packages/plugins/sdk/src/index.ts` (exported constants) | Rationale: nightly's drafts were authored from parent `af8439a`, **226 commits inside the tag**, so they document in-tag surfaces by construction. ### ⚠ Drift `check-drift.mjs --against v2026.916.0` returned 14 records — **all verified present at the tag** (checker false positives), listed here for the reviewer to confirm: - **env-var (9, high-confidence in the tool, verified present):** `PAPERCLIP_WORKSPACE_GIT_SCAN_{CONCURRENCY,QUEUE_CAPACITY,TIMEOUT_MS,CACHE_TTL_MS}` and `PAPERCLIP_ID_CONNECTOR_{BASE_URL,ENVIRONMENT,INSTANCE_ID,SIGN_PRIVATE_KEY,SEAL_PRIVATE_KEY}` — all present in `.env.example` at the tag; the drift scanner's scoped file scan missed them. - **Verify: rest-route (5, medium-confidence):** `POST/PUT/GET /api/companies/import/transfers*` — present at the tag in `server/src/routes/companies.ts`, registered via the `COMPANY_IMPORT_TRANSFERS_ROUTE_PATH` prefix constant (the documented prefix/dynamic-registration blind spot). ### ⚠ Verification Failures None. All tag-accuracy and drift flags above were verified present at the tag. ### ↻ Renames detected None. The connectors catalog (`docs/connectors/**`) arrived via the `main` merge (#124), not as a renamed surface; no new top-level draft directories were introduced this cycle. ## Screenshots **238 of 342 screenshots** flagged stale across 50 routes (see `SCREENSHOTS_PENDING.md`). This is a wide 16-day window touching ~921 UI files, so most are dependency-touch flags rather than confirmed visual changes. Recommend `npm run screenshots:refresh` on this release branch as a dedicated follow-up before merge; PNGs go to a separate PR for human review. ## Build gates (all green on this branch) - `npm run docs:build` — 257 pages - `npm run docs:test` — SEO metadata, crawlable-links (71,749 links resolve), doc-link-resolution, skill-source-blocks, static-routes, hierarchical-nav ## Post-merge checklist (Phase 9 — do NOT skip) - [ ] Squash-merge this PR (repo is squash-only) - [ ] `git checkout main && git pull` - [ ] `git tag docs/v2026.916.0 && git push --tags` - [ ] `node scripts/sync/realign-nightly.mjs release/v2026.916.0 --push` (restore ancestry; keep nightly post-tag drafts) - [ ] Flip `nightly` `.sync-state.json` back to `"branch_mode": "nightly"` (leave `base_release_tag` at `v2026.916.0`) - [ ] Verify `docs.paperclip.ing` serves the release: a new page (`/reference/cli/test-drive/`), a changed page, and the changelog top entry reads `Docs for v2026.916.0` - [ ] If production is stale, republish: `npm run docs:build && npx wrangler pages deploy .site --project-name paperclip-docs --branch main` 🤖 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]> |
||
|
Aron PrinsandClaude Opus 4.8
|
27d7a5ab4c |
Release docs for paperclip v2026.831.1 (#120)
Syncs docs to parent release **v2026.831.1** (cumulative from
`v2026.824.1`, via merge-base `664052f`). Authored fresh against the
release tag; every claim verified at the tag.
## What changed
**New**
- **Kimi Code adapter** (`kimi_local`) — new reference page, wired into
the adapters overview, nav, and anchor-map source mapping.
**Reference**
- **Env vars** — `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS`, opt-in
`SENTRY_DSN`, and the operator controls `PAPERCLIP_HIDDEN_SETTINGS` /
`PAPERCLIP_SETTING_DEFAULTS`.
- **Instance Settings** — new "operator controls for hosted deployments"
section (hide surfaces / override defaults).
- **Node.js floor → 24.11.0** across installation, setup,
local-development, plugin dev, Modal, and the getting-started/terminal
guides.
- **Grok adapter** — `permissionMode` no longer defaults to `dontAsk`;
when unset no flag is passed, and `--always-approve` is the unattended
policy.
- **CLI `agent`** — Kimi skills install path (`~/.kimi-code/skills`) +
`KIMI_CODE_HOME`.
**Guides**
- **Onboarding** — rebuilt around a single-card wizard that opens on
creating your agent; the mission step is gone, the goal is set
afterward.
- **Settings unification** — Invites folded into a Members tab, one
shared settings nav, and the company brand color + per-company
attachment size limit removed (also reflected in the Companies and Cases
APIs).
- **Governance behavior** — silent-run detection and stranded-task
recovery no longer act on their own; agent thought text is excluded from
automatic comments; invalid agent credentials now return `401`.
**Changelog** — entry added for v2026.831.1.
## Gates
- `docs:build`, SEO metadata, crawlable-links, sitemap-lastmod
(194/194), lint-links, verify-nav — all pass.
- **Edit verification:** every new high-confidence claim verified at the
tag.
- **Tag-accuracy gate:** 31 files checked, **0 post-tag leaks**, 30
clean, 1 review (below).
## ⚠ Drift (Verify before acting — not auto-resolved)
Medium-confidence REST-route drift in `docs/reference/api/companies.md`
— the import-transfer routes may no longer exist at these paths (likely
a false negative from prefix/dynamic registration; confirm before
editing):
- `POST /api/companies/import/transfers`
- `PUT /api/companies/import/transfers/{transferId}/parts/{partIndex}`
- `GET /api/companies/import/transfers/{transferId}`
- `POST /api/companies/import/transfers/{transferId}/preview`
- `POST /api/companies/import/transfers/{transferId}/apply`
## ⚠ Review
- `docs/reference/adapters/kimi-local.md` — new page; the only flagged
claim is the `secret-id` JSON **example placeholder** (not a real
identifier). Authored directly from the adapter's config surface at the
tag.
## Screenshots (deferred)
288 of 342 registered screenshots are stale (org-wide rename +
settings/onboarding rewrites), tracked in `SCREENSHOTS_PENDING.md`.
Recapture is a follow-up pass — **the merged pages describe the new
onboarding/settings UI while screenshots still show the old flow until
then.**
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
|
||
|
Aron PrinsandClaude Opus 5
|
325c9eb819 |
seo: hand-write titles and descriptions for all 192 pages (#115)
## Why
The build derived `<title>` from the **sidebar label** and the
description from the **first paragraph clipped to 220 characters**. Both
are the wrong source. A sidebar label is written for a 240px-wide nav
that supplies its own context; a search result has none.
On production that produced:
- **7 pages titled "Overview"**, and 32 pages sharing a title with
another page
- **109 of 193 descriptions cut off mid-word**, and 174 over 160
characters (where Google truncates)
```
/guides/welcome/key-concepts/
BEFORE (220): ...and if you misunderstand them early, the product wi
```
Near-identical titles are the weak-differentiation signal behind
"crawled — currently not indexed", which is the exact symptom on this
property.
## What changed
`seo_title` and `seo_description` frontmatter on **every one of the 192
pages**, written by hand against each page's real content and optimised
for the click — lead with what the reader can do, name the concrete
things covered, no keyword stuffing, no repeating the title.
| | Before | After |
|---|---|---|
| Duplicate titles | 32 pages | **0** |
| Duplicate descriptions | — | **0** |
| Descriptions cut mid-word | 109 | **0** |
| Descriptions over 160 chars | 174 | **0** |
| Title length (incl. suffix) | up to "Overview" | **26–60** |
| Description length | 31–240 | **122–158** |
**No prose was rewritten.** I measured content overlap between the
colliding pairs first — only 17–23%, so these were always distinct pages
wearing the same label, not duplicate content. The `docs/` diff is **564
insertions, zero deletions**.
### Examples
```
BEFORE — all seven identical: "Overview | Paperclip Docs"
AFTER: "Adapters Overview" "API Overview" "CLI Overview"
"Deployment Overview" "Bundled Skills" "Optional Skills"
"Experimental Features"
BEFORE — both identical: "Issues | Paperclip Docs"
AFTER: "Issues: Creating and Tracking Work" /guides/day-to-day/issues/
"Issues API" /reference/api/issues/
```
```
/guides/getting-started/five-minute-path/
BEFORE (220): The shortest route from a running Paperclip instance to an agent that has
just completed work for you. After Paperclip is installed, the path takes
about 5 minutes: create a company, hire a CEO agent, approve its first s
AFTER (131): Install Paperclip, create a company, hire a CEO agent, and approve its
first strategy — a working AI company in about five minutes.
```
## Plumbing
- **`site/build-release.mjs`** prefers the authored fields; the derived
path stays only as a fallback the CI gate prevents ever reaching.
`<title>`, `<meta name="description">`, and the `TechArticle` JSON-LD
all read from the same source.
- **`site/app.js`** uses the same fields, so a client-side transition
cannot leave a different title on screen than the crawler was served.
Verified in-browser: navigating `/guides/day-to-day/issues/` →
`/reference/api/issues/` swaps to exactly the server-rendered values, no
JS errors.
- **`scripts/verify-seo-metadata.mjs`** (new) enforces presence,
uniqueness, length, complete-sentence endings, and the
frontmatter-safety rules. Wired into `docs:test` and CI as its own step.
I negative-tested the gate rather than assuming it works — it correctly
fails on a duplicate title, a mid-word description, and a missing field,
and passes again once restored.
## Automating it going forward
`skills/sync-docs/SKILL.md` now:
- gains an **"Authored SEO metadata"** section: why the fields exist,
the enforced rules as a table, and how to actually write them (title
names the subject not the nav position; description writes for the
click; never generate mechanically from the first paragraph — *that is
the fallback the gate exists to prevent*).
- requires both fields in the **page-authoring instruction** given to
every subagent, with guidance on when to update an existing description
versus leave it.
- runs `docs:test:seo-metadata` and `docs:test:crawlable-links` as
**fail-loud gates in Phase 7** before commit.
- documents all six build gates in the files/gates section.
So once this lands, a new page cannot ship without hand-written
metadata, and a title collision cannot reach production.
## Verified
All six verifiers pass:
```
Static route verification passed
Asset fingerprint verification passed
Hierarchical Skills nav verification passed
Skill source block verification passed (11 skill pages, 1 control page)
Crawlable-link contract passed: 40886 internal links across 194 pages resolve in one hop
Authored-SEO contract passed: 192 pages carry a unique, hand-written seo_title and seo_description
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
|
||
|
Aron PrinsandClaude Opus 4.8
|
6c4519af4a |
Release docs for paperclip v2026.824.0 (#110)
Cumulative docs sync from v2026.817.0 to the v2026.824.0 stable tag. New/updated: Tailscale HTTPS broker, workspaces HTTPS exposure, release channels + `paperclipai channels`, resumable company import (guide + companies API), secret catalog, Claude setup-token login, adapter device-login, issue file-resource availability, document comments, interaction resolver-policy/governance. Version-stamped touched pages and added the v2026.824.0 docs-changelog entry. Verified every page against the v2026.824.0 tag; stripped post-tag master leaks (Kimi adapter, reaper-cooldown env var, mission-less onboarding rewrite) that nightly had drafted ahead of the release. Screenshots flagged (192 stale) but not recaptured this release. Co-Authored-By: Claude Opus 4.8 <[email protected]> |
||
|
|
631a6a0c53 |
Release docs for paperclip v2026.817.0 (content + screenshot overhaul) (#95)
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]> |
||
|
|
44e12ab37c |
Release docs for paperclip v2026.722.0 (#72)
Release docs for **paperclip v2026.722.0** (window `v2026.720.0 → v2026.722.0`; 256 changed parent files, 60 commits, diff window clean — 0 truncated leaves). Nothing here goes live until this PR is merged to `main`. ## Surfaces authored this run | Surface | Docs | Parent PR | |---|---|---| | **Run-bound agent secret access** — `access.`-prefixed / `api` delivery mode; `GET /api/agents/me/secrets`, `POST /api/agents/me/secrets/:key/value` (`Cache-Control: no-store`) | `api/secrets.md`, `api/agents.md` | #9921 | | **Local agents run natively on Windows** (ACPX, no Bash wrapper; env via session options; `.cmd` shim; symlink→copy on EPERM) | `adapters/acpx-local.md` | #9980 | | **`PAPERCLIP_*` bindings flow through**; only `PAPERCLIP_API_KEY` rejected (override removed); `DO_NOT_TRACK` / `PAPERCLIP_TELEMETRY_DISABLED` opt-out | `deploy/environment-variables.md` | #9974, #9946, #9906 | | **Safer `CODEX_HOME` sandbox sync** — explicit allowlist, not whole home | `adapters/codex.md` | #9972 | | **Plugin SDK** environment-sync exports + `onEnvironmentSyncIn/Out` hooks | `reference/plugins/sdk.md` | — | | **CLI `company export --force`** | `reference/cli/company.md` | — | | **Connections v3 (Apps)** experimental foundation — `remote_http`→`mcp_remote`, `connection_grants`, AppDefinition catalog | `experimental/connections-apps.md` (new) | #9958, #9981, #9982 | Riding along from earlier nightly drafts (part of this release): secret folders (`administration/secret-folders.md`), searchable agent picker, cloud-managed bootstrap gate (`api/instance-admin.md`). ## Verification All authored claims verified against parent code at tag `v2026.722.0` (`verify-edit`): **0 high-confidence unverified**. `docs:build`, `sync:lint-links`, and `sync:verify-nav` all pass. Frontmatter stamped `paperclip_version: v2026.722.0`. The 2 nav orphans (`cli/commands.md`, `cli/control-plane-commands.md`) are the intentional redirect anchors. ### ⚠ Drift (all resolved as false positives — no action) `sync:check-drift` flagged 4 `rest-route-missing` candidates: - `GET /api/agents/me/secrets` and `POST /api/agents/me/secrets/{key}/value` (in `api/agents.md` and `api/secrets.md`). These are the **new** routes this PR documents. The flags fire because the drift checker searched a stale `last_seen` sha and REST-route matching is medium-confidence (router-prefix registration hides the literal). Both routes were verified verbatim against `server/src/routes/secrets.ts` at tag `v2026.722.0`. No change needed. One `verify-edit` env-var flag (`PAPERCLIP_CLOUD_PROD_PROVIDER_RAILWAY_TOKEN`) is the release-note **illustrative example** of a user-chosen name, framed in prose as "for example a secret called …" — not a real product variable. No change needed. ### ↻ Renames detected None. ### ⚠ Reconcile None. ## Screenshots See `SCREENSHOTS_PENDING.md`. 13 unique captures (×2 light/dark) are genuinely stale — mainly agent-config surfaces (`AgentConfigForm.tsx` gained the Secret access editor) and secrets. Net-zero `+0/-0` UI touches were filtered out. Not auto-captured — recapture via `npm run screenshots:refresh` goes to a separate review PR. The new `secret-folders.md` and `connections-apps.md` pages have no captures yet. ## Post-merge (squash-only repo) After squash-merging, run `node scripts/sync/realign-nightly.mjs release/v2026.722.0 --push` and bump `.sync-state.json` `base_release_tag` to `v2026.722.0`. Skipping the realign arms the add/add-conflict trap 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]> |
||
|
|
8121a9c947 |
Release docs for paperclip v2026.720.0 (#67)
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]> |
||
|
Aron Prins
|
7e25158fca |
Release docs for paperclip v2026.707.0 (#49)
Promotes v2026.707.0 docs from nightly: Custom sandbox images + Ramp skill (new), Work Timeline (#48) and Secret scopes (#47) content, screenshot capture targets, environments nav reconcile, sync-state bump to v2026.707.0, and accuracy fixes from adversarial verification. 0 drift. |
||
|
Aron PrinsandClaude Opus 4.8
|
2368a2be5f |
Release docs for paperclip v2026.618.0
Promote nightly drafts (v2026.609.0 → v2026.618.0) to main and fill coverage gaps. New surfaces authored: - Novita Agent Sandbox provider (driver: novita) — sandbox-providers.md - paperclip-board bundled skill — skills.md (skills/ went 5 → 6; "four" → "five") Promoted nightly drafts (all ⊆ v2026.618.0, no post-tag leakage): - adapters: codex/gemini/opencode/pi/openclaw-gateway, sandbox-providers (Kubernetes) - api/agents, plugins/sdk, environment-variables (TRUST_PROXY/OTEL) - day-to-day guides: artifacts, issues, routines Stamped paperclip_version: v2026.618.0 on all 13 touched pages. Regenerated SCREENSHOTS_PENDING.md (90/276 stale — flag only, separate capture PR). Deferred: experimental conference-room board-chat (flag-gated). sync:check clean (no broken links); drift = 5 known server-env false positives. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
acfebdf637 |
nightly: K8s sandbox provider, adapter gateway routing, TRUST_PROXY/OTEL, agent read-config access (paperclip 412a04c)
Cumulative window v2026.609.0 -> master HEAD 412a04c (59 commits). Applied:
- environment-variables.md: TRUST_PROXY (reverse-proxy trust), OpenTelemetry
opt-in tracing (OTEL_*), and adapter provider-override env vars.
- api/agents.md: read-only config/skill/config-revision endpoints no longer
require agents:create for board members (agents still gated).
- adapters/sandbox-providers.md: new Kubernetes sandbox provider section.
- adapters/{codex,pi,opencode}-local.md: PAPERCLIP_*_PROVIDERS gateway routing
(+ codex GPT-5.5 / omit-default-model, opencode small-model).
- adapters/gemini-local.md: headless auth pre-selection + token-overflow
fresh-session retry.
- adapters/openclaw-gateway.md: role/scopes/paperclipApiUrl/workspaceRuntime.
- plugins/sdk.md: optional companyId tenant scoping on metrics.write + log.
Deferred (experimental/half-built) to PENDING.md: Conference Room Chat,
Skills Store, dark mode, onboarding NUX, activity feed, issues list filters.
All edits verified against parent code (Phase 5.5).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
|
||
|
Aron PrinsandClaude Opus 4.7
|
2b5368e5af |
release: address v2026.512.0 coverage gaps
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]> |
||
|
Aron PrinsandClaude Opus 4.7
|
c7a93614ee |
release: address review gaps from catchup-2
- 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]> |
||
|
Aron PrinsandClaude Opus 4.7
|
37d016d9e9 |
release: bring docs forward to v2026.427.0
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]> |
||
|
Aron PrinsandClaude Opus 4.7
|
0b76a127b6 |
release: bring docs forward to v2026.416.0
Manifest summary: - auto-merge/env-vars: NEW PAPERCLIP_BIND, PAPERCLIP_BIND_HOST, PAPERCLIP_TAILNET_BIND_HOST [evidence: server/src/config.ts process.env reads]. - pr/rest-routes: NEW server-side route files server/src/routes/inbox-dismissals.ts and server/src/routes/sidebar-preferences.ts (sidebar/inbox UI state — internal-facing, intentionally not documented in the public API reference yet). NEW workspace-command-authz.ts and workspace-runtime-service-authz.ts are authz helpers, not user-facing routes. - pr/cli-commands: 8 internal CLI file modifications, no new top-level commands. - pr/adapters: claude-local, codex-local, openclaw-gateway extensive internal refactors — no surface-level user-facing changes documented. - pr/plugin-sdk, pr/agent-skills, pr/schemas, pr/web-ui, pr/server-services, pr/server-adapters: internal. Edits applied: 1 - docs/reference/deploy/environment-variables.md (add PAPERCLIP_BIND, PAPERCLIP_BIND_HOST, PAPERCLIP_TAILNET_BIND_HOST rows; bump paperclip_version) Verification: - New env vars verified verbatim against server/src/config.ts process.env reads. - New route files inspected but deliberately not surfaced in api reference (UI-state APIs). Renames detected: none Reconcile flags: none (workspace-command-authz / workspace-runtime-service-authz are new files but represent internal authz extraction, not removed surfaces) Release notes one-liner: "Bind-mode selection (tailnet/loopback/custom), inbox dismissals & sidebar preferences, server bind validation." Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
38df45dbbb |
release: bring docs forward to v2026.403.0
Manifest summary: - pr/cli-commands: NEW `paperclipai feedback report|export` and `paperclipai routines disable-all` commands [evidence: cli/src/commands/client/feedback.ts and cli/src/commands/routines.ts added]. - auto-merge/env-vars: NEW PAPERCLIP_FEEDBACK_EXPORT_BACKEND_URL/TOKEN and legacy aliases PAPERCLIP_TELEMETRY_BACKEND_URL/TOKEN [evidence: server/src/config.ts process.env reads]. - pr/rest-routes: 11 server-side route modifications — no new top-level route surfaces beyond existing companies/skills/routines pages. - pr/adapters: opencode-local runtime-config refactor; codex-local internal test reorg — no user-facing change. - pr/plugin-sdk: 6 internal SDK files modified, no new exported surface beyond existing reference page. - pr/agent-skills: paperclip skill bundle internals. - pr/schemas, pr/web-ui, pr/server-services, pr/server-adapters: internal. Edits applied: 2 - docs/reference/cli/commands.md (add `feedback` and `routines` command sections; bump paperclip_version) - docs/reference/deploy/environment-variables.md (add Telemetry & Feedback Export section; add paperclip_version frontmatter) Verification: - New env vars verified verbatim against server/src/config.ts - New CLI flags verified verbatim against cli/src/commands/client/feedback.ts and cli/src/commands/routines.ts - Pre-existing PAPERCLIP_* CLI env vars surface as suspicious — known false positives (CLI-only, not in server config) Renames detected: none Reconcile flags: none Release notes one-liner: "Feedback inspection/export pipeline, telemetry forwarding, local routines maintenance." Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
3fad7c71b1 |
docs(secrets): clarify strict-mode scope and instance-level llm.apiKey (#3)
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]> |
||
|
DottaandPaperclip
|
3e78cda1b3 |
Expand issue lifecycle and agent runtime env var reference
- 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]> |
||
|
Aron PrinsandClaude Opus 4.7
|
56b8d7d52d |
Refactor docs IA into Guides + Reference tiers; add 10 new guides
Reorganise all docs under a two-tier sidebar (Guides / Reference) with
tier-grouped landing cards that auto-size to the section count (3-col
default, 2x2 when a tier has 4 cards).
Moves
- docs/user-guides/guides/** -> docs/guides/{welcome,getting-started,
day-to-day,org,projects-workflow,power}/
- docs/{api,cli,adapters,deploy} -> docs/reference/{api,cli,adapters,deploy}
- New docs/administration/ for company/settings/plugins/cli-auth
- 265 internal cross-links rewritten by scripts/rewrite-links.mjs
- site/redirects.json preserves old URLs
New guides
- guides/org/agents.md (absorbs how-agents-work.md)
- guides/day-to-day/issues.md (absorbs managing-tasks.md)
- guides/day-to-day/costs.md (absorbs costs-and-budgets.md)
- guides/projects-workflow/routines.md (absorbs heartbeats-and-routines.md)
- guides/projects-workflow/workspaces.md (absorbs execution-workspaces.md)
- guides/projects-workflow/projects.md
- guides/projects-workflow/goals.md
- guides/org/adapters.md (AdapterManager UI walkthrough)
- administration/{company,settings,plugins,cli-auth}.md
Expanded
- approvals.md, skills.md, org-structure.md with missing UI walkthroughs
Site
- content.json: tier field, merged Welcome into Getting Started, collapsed
Administration to single section
- app.js: tier-grouped sidebar + landing; redirect map on route changes
- styles.css: tier headers and adaptive landing grid
Screenshots
- docs/user-guides/screenshots/SCREENSHOTS_TODO.md runbook for capturing
on a disposable demo instance. No screenshots captured in this branch.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|