mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-08 17:37:51 -10:00
codex/https-setup-guide
9
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]>
|
||
|
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]>
|
||
|
|
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]> |
||
|
|
175648e771 |
docs: add Experimental feature section and screenshots (#71)
## Summary - adds a new **Experimental** documentation section with an overview and 10 feature pages covering motivation, enablement, usage, and caveats - wires the section into `site/content.json` and refreshes the experimental flag list in administration settings - adds six screenshot capture targets and 12 QA-verified screenshots (light and dark) for experimental feature surfaces - includes the screenshot-pipeline fixes needed to seed and capture those surfaces reliably ## Screenshots Adds light and dark captures for: - environments - cloud upstream - file viewer - external objects - server info - recovery preview The 12 PNGs were verified on Paperclip task PAP-14814 on July 21, 2026 and were preserved byte-for-byte during the rebase. ## Verification - `npm run sync:lint-links` — pass; no broken internal links - `npm run sync:verify-nav` — pass; only the two pre-existing CLI orphans - `npm run sync:verify-screenshots` — pass; every documented screenshot is tracked and indexed - `npm run docs:build` — pass Paperclip: PAP-14705 --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Claude Fable 5 <[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 PrinsandClaude Opus 4.8
|
e6e9f629ca |
nightly: external object references, streamlined sidebar default, Daytona leases, routine annotations, plugin SDK provider (paperclip 51ffbb38)
Authored from parent master (cumulative base v2026.618.0), delta since last run 9ac24317 → 51ffbb38. All five edits verify clean (0 unverified, 0 suspicious). - docs/guides/day-to-day/issues.md: External object references — GitHub PR/issue status-aware pills across issue surfaces, External object status filters, inbox/sidebar severity badges (PR #8512). - docs/administration/settings.md: Streamlined Left Navigation Bar is now default-on; classic sidebar is the opt-out (PR #8496). - docs/reference/adapters/sandbox-providers.md: Daytona reusable leases (opt-in), quota-safe auto-archive defaults, image-only resource overrides (#8513/#8561/#8564). - docs/guides/projects-workflow/routines.md: routine description annotations — comment on / inline-edit instructions like an issue document (PR #8229). - docs/reference/plugins/sdk.md: plugin SDK external-object reference provider surface — detect→resolve→refresh lifecycle, declaration + protocol types (PR #8512). PENDING.md / SCREENSHOTS_PENDING.md regenerated; .sync-state.json advanced to 51ffbb38. 60 screenshots flagged stale (UI changes), surfaced for human recapture. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
2ff5539127 |
nightly: skills "required" retirement, paperclip-dev cleanup, task watchdogs guide (paperclip d1e6662e)
Round 2 — worked the human-review items, verified each against parent source: - Skills: the per-agent `required` attribute is retired upstream (AgentSkillEntry dropped required/requiredReason; AgentSkillOrigin dropped paperclip_required; resolveDesiredSkillAssignment now persists exactly the desired set with no bundled union). Fixed reference/skills.md and reference/cli/skills.md: removed "non-required" qualifiers, the retired `required` frontmatter row, the wrong "forced into every agent" claim, and corrected the snapshot example + the UI grouping (Company skills + Unmanaged, no "Required" group). - paperclip-dev skill removed upstream: dropped from the bundled list and swapped stale source/key examples to paperclip-create-agent. - Experimental features: strengthened the settings.md caution to match the new in-app "no compatibility guarantees" warning. - Task watchdogs: new operator guide page (guides/projects-workflow/ task-watchdogs.md) + nav entry. API/config/behaviour verified against routes/issues.ts, schema/issue_watchdogs.ts, and doc/TASK-WATCHDOG.md intent. Reviewed, no change needed: instance-scoped environments (routes still match docs), skills store (UI reframe; guide already accurate), plugin-sdk lease params (fields not documented). verify-edit all clean; build/links/nav/drift all green. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Sonnet 4.6
|
cca57525ce |
Add 274 screenshots (light + dark) and fix screenshot paths across docs
Captured all required screenshots for the new IA in both light and dark mode using the Horizon Labs company (PAP). Fixed the app's theme toggle (ignores prefers-color-scheme; requires clicking its own toggle button) so all dark shots use the real dark theme. Fixed broken screenshot paths in administration and guides docs: - Corrected guides/ path prefix in administration docs - Updated images/ references to screenshots/light/ across all guides - Fixed filename mismatches (e.g. dashboard-tab.png → dashboard.png) Co-Authored-By: Claude Sonnet 4.6 <[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]>
|