mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-10 03:51:29 -10:00
codex/https-setup-guide
3
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 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.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]>
|