mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-08 17:37:51 -10:00
codex/https-setup-guide
8
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Aron PrinsandClaude Opus 5
|
63e10a3cd6 |
sync-docs: require verifying the release is live before calling it shipped (#112)
## What happened Today's `v2026.824.0` release **did** write its docs-changelog entry. The accordion is on `main` in `docs/reference/changelog.md`, every one of the 15 pages the release touched is listed, and `npm run docs:build` renders it correctly with exactly one open accordion. What didn't happen is publication. `docs.paperclip.ing` is still serving the build from `ebbab07` (#100, the pre-release hotfix): | Check | Expected | Live | |---|---|---| | `/reference/deploy/tailscale-https-broker/` | `200` | `404` | | `paperclipai channels` on `/reference/cli/installation/` | present | absent | | top changelog entry | `v2026.824.0` | `v2026.817.0` | The `main`-branch Pages preview is stale in the same way, so neither commit pushed to `main` today (#110, #111) deployed. `npm run docs:build` succeeds from a clean checkout of `main`, so it isn't a build break — the Cloudflare Pages deploy simply never ran. ## Why the skill didn't catch it Phase 7 builds into `.site`, which is gitignored — nothing reader-facing is ever committed — and Phase 8 hands off at the merge. There was no step that looked at the live site. The runbook had a soft "Confirm `docs.paperclip.ing` is rebuilt successfully" bullet with no method and no fallback, and it was skipped along with its siblings: the `docs/v2026.824.0` tag was never cut (last one is `docs/v2026.707.0`), and `nightly`'s `.sync-state.json` still reads `branch_mode: "release"`. ## What this changes - **`skills/sync-docs/SKILL.md`** — new **Phase 9 — Publish & verify live** (release mode only): do every post-merge follow-up (tag, realign, flip `branch_mode`), verify production against three independent live signals, republish via `wrangler pages deploy` if stale, and report the status codes as evidence. Verification is mandatory even when pushing isn't approved. Plus a failure-mode row, a diagnosis-order special case, and a pointer from Phase 6.5 (the entry isn't done until it's live). - **`maintenance/runbook.md`** — replaces the soft "confirm" bullet with the actual checks and the manual republish fallback. - **`README.md`** — it claimed there is no Wrangler publish step for this repo; notes the auto-deploy isn't guaranteed and documents the fallback. No changelog content changed — the `v2026.824.0` entry needed no correction. Merging this PR pushes to `main`, which should also re-trigger the deploy that stalled. ## Verification - `npm run docs:build` — clean - `npm run sync:check` — lint-links and verify-nav pass; the 5 `rest-route-missing` drift candidates are pre-existing medium-confidence `Verify:` entries from the release, untouched here 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
8a858777f2 |
sync-docs: tag-accuracy gate + release-channel-aware skill (#111)
Makes /sync-docs correct under the canary→nightly→beta→stable channel model. Adds the release-mode tag-accuracy gate (scripts/sync/check-tag-accuracy.mjs) that verifies every changed page against the stable tag and flags post-tag leaks; stable-CalVer guard + channel glossary, tag-scoped drift/verify, and Phase 5.7 in the skill; realign fix that keeps nightly's drafts; a release-channels watcher; the analysis/plan doc; and a hermetic test (sync:test 38/38). Co-Authored-By: Claude Opus 4.8 <[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 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. |
||
|
Aron PrinsandClaude Opus 4.8
|
1bba6f6601 |
docs(access): document members, roles, permissions, invites & offboarding (#38)
Back-fills documentation for the human multi-user collaboration surface (company members, invites, roles, permissions, offboarding). These features are already shipped and live; this fills doc gaps and fixes one live permission-key drift. Branched off `main` (not `nightly`) because it's editorial back-fill of released features, intended to ship independently of the nightly sync cadence. ## Tier 1 — correctness - **Fix live permission drift** in `administration/company.md`: the grant list and Owner/Admin role descriptions were missing `environments:manage` and `tasks:manage_active_checkouts` (both present in `packages/shared/src/constants.ts` `PERMISSION_KEYS`; `environments:manage` is an Owner/Admin default in `server/src/services/company-member-roles.ts`). - **New** `administration/roles-and-permissions.md`: canonical 8-key catalog (what each gates), role→default-grant matrix, additive precedence rule, `instance_admin` layer, and current limitations. - `maintenance/follow-ups.md`: note to teach the drift checker the permission catalog so this can't silently drift again. (Sync tooling itself untouched.) ## Tier 2 — how-tos - `how-to/add-a-human-teammate.md` — invite → join request → approve → set role/grants (UI + CLI). - `how-to/offboard-a-member.md` — suspend vs archive, work reassignment, membership-status-gates-access, instance-level cleanup. - `how-to/enable-multi-user-login.md` — `local_trusted → authenticated`, board-claim handoff, then invite people. ## Tier 3 — concept - `guides/org/members-and-access.md` — shared human+agent principal model, roles vs grants, human roles ≠ agent org chart, instance admin, the member profile page, and the "left a project ≠ lost access" clarification. ## Verification - All 5 new pages registered in `site/content.json` (valid JSON, +5 pages). - `sync:lint-links` and `sync:verify-nav` clean for these changes. The single link the linter reports pre-exists on `main` in a skills file untouched here; the 2 nav orphans are the intentional CLI redirect anchors. - All content verified against `paperclipai/paperclip@master` source (permission keys, role defaults, CLI syntax, deployment modes). ## Follow-up after merge Back-merge `main → nightly` so the next release merge stays clean. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
5f00622542 |
Add automated screenshot capture pipeline + skill wiring
Builds an end-to-end pipeline that keeps docs screenshots in sync with the
latest Paperclip build, replacing the previously-manual capture step.
scripts/screenshots/:
- config.mjs isolated-instance env helpers (local_trusted/loopback,
scratch PAPERCLIP_HOME, never touches ~/.paperclip)
- seed.mjs idempotent demo-data seeding via REST (company/agents/
project/goal/issues/routine/workspace); writes .seed-ids.json
- routes.mjs 56 CAPTURE_TARGETS with real ui/src depends_on paths;
resolveRoute() uses the server-derived issuePrefix
- capture.mjs Playwright capture (light+dark, 1440x900 @2x), theme seeded
to match ui/index.html, stamps registry captured_sha
- sync-registry.mjs back-fills route + depends_on into registry.json
- run.mjs one-command orchestrator: onboard -> health -> seed ->
sync-registry -> capture -> teardown
- README.md prerequisites, flow, overhaul mode, safety notes
Wiring:
- package.json: screenshots:{seed,capture,sync-registry,refresh,refresh:all}
+ @playwright/test devDependency
- screenshots:refresh:all is the full re-take mode for major UI/UX overhauls
- sync-docs SKILL.md Phase 6: capture is now automatable (still PR-reviewed,
never auto-pushed); maintenance.md updated to match
- .gitignore: scripts/screenshots/.seed-ids.json
Auth is free in local_trusted mode (every request is admin), so no login flow
is needed. Capture/staleness still surface to a PR for human review.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
|
||
|
Aron PrinsandClaude Opus 4.7
|
fc74da5f6b |
Document nightly catch-up; stop rendering version footer
Two related cleanups noticed during the v2026.513.0 release run: 1. Release ceremony was missing the nightly catch-up step. After the release PR merges, main is ahead of nightly by the release commits and nightly's .sync-state.json still says branch_mode "nightly" with the old base_release_tag. The merge-down + branch_mode flip is manual the first time and must be done by hand. Added as the 4th post-merge follow-up, plus a troubleshooting row for the symptom "nightly run reports release mode unexpectedly". 2. paperclip_version frontmatter was being rendered as a visible "Documenting Paperclip vX.Y.Z" footer on every release-stamped page. Treat the field as internal metadata only: build-release.mjs still parses and surfaces it into content.json (queryable for tooling), but the SPA no longer prints it on-page. Updated the skill's builder note to match. Co-Authored-By: Claude Opus 4.7 <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.7
|
840c2a7d54 |
maintenance: split MAINTENANCE.md into maintenance/ folder
Reorganize the operational docs into a dedicated maintenance/ folder
with two focused files plus the deferred-items tracker:
- MAINTENANCE.md (deleted) → split into:
- maintenance/maintenance.md — repo layout, commands, base paths,
pages, screenshots, publishing, and the /sync-docs design
reference (Sync workflow + Architecture diagrams).
- maintenance/runbook.md — operational guide (first-time setup,
creating the nightly branch, daily operation, release ceremony,
review workflow, helper scripts, troubleshooting).
- FOLLOW-UPS.md (deleted) → maintenance/follow-ups.md (verbatim).
Cross-references updated:
- skills/sync-docs/SKILL.md pointers to MAINTENANCE.md retargeted
to maintenance/maintenance.md (via relative path).
- Inside maintenance.md: anchor refs to Runbook subsections
(#first-time-setup, #helper-scripts-full-list) rewritten as
cross-file links to runbook.md#anchor.
- Inside runbook.md: anchor ref to Screenshots rewritten as
maintenance.md#screenshots. Heading levels demoted one level
(the section title is now top-level # Runbook). Intro paragraph
updated to reflect the standalone file.
- Inside both files: pointer paragraphs at the top linking to the
sibling file so readers can jump between design and operations.
No prose was rewritten or removed — only relocated and re-linked.
Verified zero remaining references to the old filenames across .md,
.mjs, .json, .js, .html. Build clean (90 md files). Lint-links
exit 1 only for the 3 pre-existing broken screenshot refs already
tracked in follow-ups.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
|