Commit Graph
7 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]>
2026-09-17 11:15:48 +02:00
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]>
2026-08-25 22:51:42 +02:00
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]>
2026-07-23 10:10:05 +02:00
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]>
2026-07-20 19:59:18 +02:00
Aron PrinsandClaude Opus 4.8 9c5aae8962 Release docs for paperclip v2026.529.0
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]>
2026-05-30 19:00:46 +02:00
Aron PrinsandClaude Opus 4.8 534a8b4c0d nightly: skills CLI + catalog, first-admin browser claim (paperclip 524e18b)
Cumulative nightly sync v2026.525.0 → parent master 524e18b (24h quarantine).

- Skills CLI command group (paperclipai skills …): control-plane workflow
  section + full subcommand/flag reference (#6782).
- App-shipped skills catalog (bundled/optional) + install-catalog / audit /
  install-update / reset lifecycle in the skills reference and org guide (#6782).
- Private browser first-admin claim (POST /api/bootstrap/claim) in the
  instance-admin API reference and installation guide (#6755).

Verified against parent: 0 high-confidence unverified claims. No drift, no
renames, no auto-merge/env changes. 5 commits held in quarantine.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
2026-05-30 11:15:23 +02:00
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]>
2026-05-13 15:51:54 +02:00