paperclip-docs

paperclipai/paperclip-docs

0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-10 03:51:29 -10:00

Commit Graph

Author	SHA1	Message	Date
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]>	2026-09-02 13:06:00 +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
Aron Prins Claude Opus 4.8 DevRel Gemini Paperclip	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

Author

SHA1

Message

Date

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]>

2026-09-02 13:06:00 +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

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