paperclipai/paperclip-docs
1
0 Fork 0
mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-10 03:51:29 -10:00
Code Issues Packages Projects Releases Wiki Activity
265 Commits 59 Branches 11 Tags
codex/https-setup-guide
Commit Graph
4 Commits
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 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.
 2026-07-08 11:11:32 +02:00
Aron PrinsandClaude Opus 4.7 ee349a369a Release docs for paperclip v2026.525.0 (#14) 
* nightly: regenerate PENDING manifest (paperclip c0c5a82)

10 PR-tier candidates against v2026.517.0..master:
- modal sandbox provider plugin (new doc page)
- worktree init --force scope fix
- routine env runtime contract (migration 0086)
- workspace diff viewer plugin (new)
- plugin SDK surface + managed-resources concept
- environmentProbe RPC timeout 120s
- SecretBindingPicker in JsonSchemaForm
- inbox planning badge removed
- secret form textarea overflow fix
- new-issue autocomplete pointer fix

No drift, no reconciliation candidates. All 14 parent commits past
quarantine. Anchor-map db-migrations watcher path is stale
(packages/db/migrations -> packages/db/src/migrations) — noted for
maintenance.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* nightly: document Modal sandbox provider (paperclip 4b1e92a..e5a0f5d)

* nightly: clarify scope of worktree init --force (paperclip 242a2c2)

* nightly: document routine env + secret-ref binding picker (paperclip 705c1b8..c0c5a82)

* nightly: document workspace diff viewer plugin (paperclip 5071c4c)

* nightly: audit plugin SDK reference + add managed resources note (paperclip c0c5a82)

* nightly: nav for modal adapter and workspace-diff plugin

Merges the two NAV_ADDITION entries returned by the doc-draft subagents
in this run, in one coordinated edit so the index file stays consistent.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* nightly: workspace diff polish + manifest refresh (paperclip f2575305)

- docs/reference/plugins/workspace-diff.md: document split/unified toggle,
  working-tree vs against-ref toggle, base-ref input with defaultBaseRef
  prefill, sticky toolbar, and head → working-tree fallback when no
  base ref is set (paperclip #6383).
- PENDING.md: regenerate cumulative manifest against parent f2575305
  (20 commits in window, 13 doc-relevant entries). Adds entries for the
  provider vault secrets UX (#6381), cheap recovery model guard (#6371),
  sidebar fix (#6341), cloud tenant import exemption (#6378), and UI/dev
  QoL polish (#6384).
- .sync-state.json: bump last_seen_parent_sha to f2575305, refresh
  manifest hash, mark applied.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* docs(nightly): add troubleshooting for 401 after creating a new secret

Customer hit a 401 after adding a new secret at the company level. The
new how-to didn't flag that creating a secret doesn't auto-rewire the
agent's env-var binding — fixed by adding two troubleshooting entries
covering the unbound-secret case and the provider-side rejection path.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* nightly: manifest refresh (paperclip e3c875c, effective c91a062)

Cumulative window v2026.517.0 → c91a062 (21/29 commits; 8 quarantined).
Adds entry #14 for #6380 runtime control-plane fixes — overwhelmingly
internal correctness, surfaced as context-only with a note on the new
PORTABLE_JSON_BODY_LIMIT (64mb) constant for portable imports. All 13
prior entries still present in the cumulative diff — no reconciliation.
Drift check clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

* release: docs for paperclip v2026.525.0

Roll-up of nightly drafts plus newly-authored coverage for surfaces shipped
in v2026.525.0 that nightly hadn't reached yet:

- new: docs/how-to/sync-to-cloud-upstream.md (Cloud Upstream sync flow)
- new: docs/how-to/connect-aws-secrets-vault.md (AWS provider vault discovery)
- update: docs/reference/cli/commands.md — paperclipai cloud connect/push
- update: docs/reference/adapters/acpx-local.md — bare Claude model IDs, structured diagnostics, ~/.claude/settings.json handling
- update: docs/reference/api/agents.md — scoped permissions + authorization service, decision-reason table
- update: docs/reference/api/issues.md — retry-now endpoint
- update: docs/reference/deploy/secrets.md — Provider Vaults section
- update: docs/how-to/bring-your-own-agent.md — invite flow moved into add-agent modal

Bumped paperclip_version frontmatter to v2026.525.0 on all touched pages
(including nightly-authored Modal, workspace-diff, plugin SDK, routines,
worktree --force pages).

Updated .sync-state.json: base_release_tag v2026.517.0 -> v2026.525.0.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
 2026-05-25 20:36:18 +02:00