mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
main
9
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Aron PrinsandClaude Opus 5.5
|
478d24ce5d |
ci: tag docs releases automatically on merge to main (#133)
Tags every docs release automatically, so the `docs/vX.Y.Z` tag stops depending on someone remembering to create it after the merge. So far, 11 of 16 releases were never tagged. ## What changes - **New workflow, `.github/workflows/tag-docs-release.yml`.** It runs on every push to `main`. For each new commit titled `Release docs for paperclip vYYYY.MDD.P`, it tags that commit `docs/vYYYY.MDD.P`. - Anything after a space in the title, such as `(#132)`, is ignored. - Pre-release versions like `-beta.1` are skipped. - Tags that already exist are left alone. - **`skills/sync-docs/SKILL.md` (Phase 9) and `maintenance/runbook.md`.** The after-merge step now checks that the tag exists instead of creating it by hand. It also tells you to keep the release PR title format, because the workflow reads the version from it. ## Tested I ran the version matching against all 16 release squash-commit titles on `main` and it matched every one, including `(content + screenshot overhaul) (#95)` and titles with no PR number. It rejects `-beta.1`. The workflow itself hasn't run on GitHub yet; the next release merge will be its first run. ## Needs The workflow needs permission to push tags: `permissions: contents: write`. If the repo's Actions permissions are read-only and that can't be changed per workflow, the first run will fail with a clear error. Fix it in Settings → Actions → Workflow permissions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]> |
||
|
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]>
|