mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
1f6b9f38463c835518907d840dd699c9ed4adb78
247
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 DottaandDevRel Gemini
|
1f6b9f3846 |
docs: redirect legacy what-is-paperclip URL (#93)
## Thinking Path > - Paperclip uses a public documentation site to help users learn the product. > - The site build reads legacy routes from `site/redirects.json`. > - Two old `/start/` routes redirect to current guide pages. > - The old `/start/what-is-paperclip` route has no matching redirect. > - Search engines still send users to that old route. > - This pull request adds the missing redirect entry. > - The benefit is a working 301 response for both slash variants. ## Linked Issues or Issue Description **Issue type** Outdated documentation route. **Where is the issue?** `https://docs.paperclip.ing/start/what-is-paperclip` **What's wrong?** The legacy URL returns a hard 404. The live replacement is `/guides/welcome/what-is-paperclip/`. **Suggested fix** Add the proven legacy path to `site/redirects.json`. Do not add speculative `/start/` redirects. ## What Changed - Added `start/what-is-paperclip` to the legacy redirect map. - Kept the existing `start/quickstart` and `start/core-concepts` mappings unchanged. ## Verification - Ran `npm run docs:test:static-routes` successfully. - Ran `npm run docs:build` successfully. - Confirmed the generated `_redirects` file contains 301 rules for both `/start/what-is-paperclip` variants. - Confirmed the generated sibling rules remain present. ## Risks - Low risk. The change adds one redirect map entry and does not change page content or route generation logic. ## Model Used - OpenAI `gpt-5.4` through Codex CLI, with reasoning, tool use, and code execution. The runtime does not expose the context window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change and contains no internal ticket ID - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All configured CI gates are green - [x] No Greptile check is configured for this repository, and no Greptile comments are open - [x] I will address all Greptile and reviewer comments before requesting merge Co-authored-by: DevRel Gemini <[email protected]> |
||
|
|
c7b3f4cacf |
Render full SKILL.md as a code snippet on per-skill pages (PAP-16980) (#89)
> **Updated on current main:** #87 and the #90 cache hotfix are merged. This PR now targets `main`, was rebased onto merge commit `8c5976f`, and has a fresh successful Cloudflare preview plus post-rebase browser smoke evidence. ## What & why (PAP-16980) Improves SEO/AEO on the bundled/optional **per-skill reference pages** (from PAP-16670) by clearly separating the *human-readable catalog summary* (top of page) from the *authoritative full skill definition*. Previously the "Full skill definition" section rendered the `SKILL.md` as **parsed Markdown**, so each skill's own `##` headings, lists, and fenced examples became real page content — competing with the summary, inflating the on-page TOC (e.g. qa-acceptance went from **16 → 6** "On this page" entries), and confusing crawlers/answer engines about the page's true structure. Now each per-skill page shows the **complete, verbatim `SKILL.md`** (frontmatter + body) inline, rendered through the **existing production code-snippet treatment**. ## Changes - **Content (10 per-skill pages):** replaced the old `### Skill frontmatter` bullets + parsed `### Skill instructions` layout with the full `SKILL.md` embedded in a fenced ````markdown skill-source` block. Source bytes were taken verbatim from each skill's authoritative `SKILL.md` at the page's pinned `paperclip_version`, verified against the page's own prior instructions body + frontmatter (name/description) so no content drifted. - **Renderers (`site/build-release.mjs`, `site/app.js`):** a `skill-source` fence renders as `<pre><code class="language-markdown" data-skill-download="SKILL.md">`. Every other code block is delegated to marked's default renderer, so existing snippets are byte-for-byte unchanged. Rendered identically in the crawler-visible build HTML and on client SPA navigation. - **Copy + Download (`site/app.js`, `site/styles.css`):** `decorateCodeBlocks` reuses the existing Copy affordance and adds a **Download `SKILL.md`** control beside it. Both share dimensions, styling, hover/focus visibility, and the copied-success state; both carry accessible labels/titles. - **Readable full-source wrapping (`site/styles.css`):** only the downloadable `SKILL.md` block uses `white-space: pre-wrap` and safe long-token wrapping. Ordinary code snippets retain the existing horizontal-scroll treatment. - **Test:** `scripts/verify-skill-source-blocks.mjs` (`npm run docs:test:skill-source-blocks`) asserts the render contract (single H1, single `<pre>`, frontmatter present, no legacy headings) and that ordinary docs pages emit no `data-skill-download`. ## Scope statement No catalog-page layout, navigation, typography, summary-copy, metadata-card, or information-architecture changes. `paperclip-website` and generated `.site/` output are untouched. `optional/finance/ramp.md` is intentionally excluded — it is a newer summary page with no embedded full-definition section to reformat. The diff is the 10 skill pages + the narrow renderer/Copy-Download support + the test. ## Evidence **1–2. Before/after (desktop, 1280×900) + mobile after (390×844)** — attached to Paperclip issue [PAP-16980](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/3098577a-4f6f-4eb2-9151-a4b61917dffd) (`before-desktop.png`, `after-desktop-controls.png`, `after-controls-zoom.png`, `after-mobile.png`). GitHub cannot render the auth-gated attachment URLs inline, so they live on the issue for reviewers. **4. Raw DOM/HTML (build output, qa-acceptance):** - Article renders exactly **one H1**: `<h1 id="qa-acceptance">QA Acceptance</h1>` - Full source inside a single code block: ```html <pre><code class="language-markdown" data-skill-download="SKILL.md">--- name: qa-acceptance description: Produce QA acceptance criteria and a manual validation plan … key: paperclipai/bundled/quality/qa-acceptance recommendedForRoles: - qa … </code></pre> ``` - Article `<pre>` count: **1** (inner ````` fences stay literal — no breakout). 10/10 skill pages carry the block; 0 non-skill pages do. **5. Copy + Download behavior (Playwright against the built site):** ```json { "downloadFilename": "SKILL.md", "downloadMatchesBlock": true, // downloaded file === code block text, byte-identical "downloadBytes": 3853, "copyShowsSuccess": true, // Copy toggles the existing is-copied success state "accessibleLabels": { "copy": "Copy code", "download": "Download SKILL.md" } } ``` Both controls reach `opacity: 1` on `.code-wrap:hover` and on keyboard `:focus-visible` (verified `matches(':focus-visible') === true` → computed opacity `1`). **H1 audit (every generated route, incl. all skill URLs — requested on the issue):** built the site on current `main` and scanned **all 184 generated `index.html` routes** (16 skill routes among them). **Every route has exactly one `<h1>`.** The skill source's own `#`/`##` headings live *inside* the `<pre><code>` block as literal text, so they do **not** create competing H1s — the SEO/AEO goal. ## Tests Run against current `main` after #87 and #90: ``` docs:build ............................. ok (184 routes) docs:test:static-routes ................ pass (5 routes + 404 + root + subpath) docs:test:skill-source-blocks .......... pass (10 skill pages, 1 control page) H1 audit (all 184 routes) .............. pass (exactly 1 h1 each; 16 skill routes) ``` **Do not merge/deploy** — returning to Dotta/reviewers for approval per PAP-16980. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
|
8c5976ffd3 |
URGENT: fingerprint docs client bundle to fix mixed-version cache regression (PAP-16990) (#90)
## Urgent hotfix — mixed-version asset cache regression (PAP-16990) Restores reliable navigation on https://docs.paperclip.ing/ without undoing the PAP-16670/#87 server-render + single-H1 SEO/AEO work. ### Root cause The server-render change shipped new HTML that removed `#loading` / `#error-state`, but every generated route still loaded the client bundle from a **stable URL**: `<script src="app.js" defer>`. Cloudflare/browsers cache `/app.js` for up to ~4h independently of the HTML, so a returning visitor could pair freshly-revalidated new HTML with a **pre-merge cached `app.js`**. The old click path looked for the removed elements, threw before render, hid the homepage, and left a blank `#main` (no URL update). Forced refresh recovered — not acceptable. CSS was never part of this: it is inlined into every page and travels with the (revalidating) HTML. `content.json` is byte-identical prod↔preview. ### Fix (narrow cache-bust, no rollback) 1. **Content-fingerprint the client bundle.** Emit `app.<hash>.js` (+ `styles.<hash>.css`) and rewrite the shell so *every* route references the exact build's asset URL. A changed bundle gets a brand-new URL no cache can satisfy with stale bytes — closes the mixed-version window in **both** directions. No unversioned `/app.js` is emitted, so a stale cache has nothing to pin. 2. **`_headers`:** fingerprinted JS/CSS cached `immutable` (1y); HTML routes (`/`, `/*/`) and `content.json` set `max-age=0, must-revalidate`. 3. `inlineReleaseStyles` now matches the fingerprinted stylesheet link so CSS stays inlined. ### Before / after ``` - <script src="app.js" defer></script> # stable URL — cacheable across versions + <script src="app.1b669c8d0aec.js" defer></script> # content-hash URL — cache miss on any change ``` `_headers` (new): ``` /app.*.js Cache-Control: public, max-age=31536000, immutable / /*/ Cache-Control: public, max-age=0, must-revalidate /content.json Cache-Control: public, max-age=0, must-revalidate ``` ### Verification (local build, base path `/`) - `npm run docs:build` → emits `app.1b669c8d0aec.js`, `styles.9e3f24983c72.css`; **184/185** HTML files reference the fingerprinted bundle (185th is the scriptless `404.html`); **no** bare `app.js`/`styles.css` file or reference remains. - `npm run docs:test:asset-fingerprints` ✅ (new) — proves the URL is the content hash of the served bytes, changes on any content change, is referenced identically by root + interior routes, has no unversioned sibling, and the cache headers are present. - `npm run docs:test:static-routes` ✅ — single-H1 interior pages, no-JS server-render, homepage manifest completeness, 404 separation, root + `/paperclip-docs/` builds. ### Remaining (post-merge, needs a real browser on the live domain) Chromium can't launch in the CI/agent sandbox (missing system libs), so **cold + returning/cached** browser smoke on https://docs.paperclip.ing/ must be run after merge → redeploy from `main`. Checklist: cold load, homepage-card nav (URL updates, one H1, no blank), interior↔interior, Back/Forward, All Docs, search, 404, and a returning/cached session (prior `/app.js` in cache). Does **not** touch the SKILL.md formatting PR (PAP-16980), per the issue. Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Claude Opus 4.8 <[email protected]> |
||
|
|
e2adb1c167 |
PR1 — server-render the docs root and split it from interior routes (Phase 1) [DO NOT MERGE] (#87)
# PR1 — server-render the docs root and split it from interior routes (Phase 1) **Do not merge — Dotta alone may merge.** This PR is opened for review only, per the hard write-gate on the approved plan. ## Provenance | item | link | |---|---| | Accepted plan | [PAP-16672 · plan document](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16672#document-plan) | | Phase 0 review packet | [PAP-16671 · packet comment](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16671#comment-f653273d-6450-4f8d-bcd6-f805ad28b923) | | Implementation candidate | [PAP-16682](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16682) | | Independent QA — **PASS** | [PAP-16683](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16683) | | Finalization / this PR | [PAP-16684](https://paperclip-dev.tail29c1aa.ts.net/PAP/issues/PAP-16684) | | Full evidence gallery (screenshots + raw JSON probes) | https://pages.paperclip.ing/pap-16684-pr1-evidence/ | Base: approved `main` @ `2ab76e8e4`. Head: `f5bbba24c` (exactly one commit on top; `main` has not moved). ## What changed - **1.1 — root-only landing shell.** The hero is *physically absent* from interior documents (removed at build time, not CSS/JS/ARIA hidden); the build throws if removal fails. Header, footer, search, sidebar, breadcrumbs and article nav are preserved on every page. - **1.2 — server-rendered homepage directory** generated from the same canonical `site/content.json` manifest that already feeds the sidebar, breadcrumbs, prev/next, routes and sitemap. No second URL manifest was introduced. - **Single descriptive H1 per interior page** (was 2 — the hero H1 bled onto every route). - **Truthful runtime UI.** `Loading…` / `Could not load this guide.` no longer ship inside success HTML; they are produced only by `app.js` at runtime on the empty, `hidden` `#runtime-status` mount, so they can only appear during a genuine client transition or failure. ``` scripts/verify-static-routes.mjs | 200 +++++++++++++++++++++++++++++++++- site/app.js | 90 ++++++++++++---- site/build-release.mjs | 189 ++++++++++++++++++++++++++++++-- site/index.html | 17 ++-- site/styles.css | 70 ++++++++++- 5 files changed, 528 insertions(+), 38 deletions(-) ``` `.site/` is **generated build output and remains uncommitted** (gitignored): `git ls-files | grep '^\.site/'` → 0 files. ## Before → after, raw HTTP/HTML for the six representative routes Both trees built with the identical command and base path, then served by a production-equivalent static server (real 404 status, honors `_redirects`). "Before" is a real build of approved `main` @ `2ab76e8e4`. | route | HTTP | content type | H1 count before → **after** | H1 text (after) | `id="landing"` before → after | `Loading…` | `Could not load this guide.` | internal directory anchors | |---|---|---|---|---|---|---|---|---| | `/` | 200 | `text/html` | 1 → **1** | Everything you need to run Paperclip. | 1 → 1 (root-only ✓) | 1 → **0** | 1 → **0** | 4 → **184** | | `/guides/welcome/what-is-paperclip/` | 200 | `text/html` | 2 → **1** | What is Paperclip? | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/reference/api/overview/` | 200 | `text/html` | 2 → **1** | API Overview | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/how-to/add-mcp-server-to-agent/` | 200 | `text/html` | 2 → **1** | Add an MCP server to an agent's toolkit | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/reference/changelog/` | 200 | `text/html` | 2 → **1** | Documentation Changelog | 1 → **0** | 1 → **0** | 1 → **0** | 4 → 4 | | `/guides/welcome/this-route-does-not-exist/` | **404** | `text/html; charset=utf-8` | 1 → **1** | Not found | 0 → 0 | 0 → 0 | 0 → 0 | 0 → 0 | Machine-readable probes: [before-raw.json](https://pages.paperclip.ing/pap-16684-pr1-evidence/before-raw.json) · [after-raw.json](https://pages.paperclip.ing/pap-16684-pr1-evidence/after-raw.json). ### Homepage bleed and false state — absence proof - `id="landing"` returns **zero** matches in every interior document. Only inlined `#landing-*` **CSS selector text** remains (stylesheet, not markup). - Interiors carry no directory manifest (4 internal anchors — the footer); the 184-anchor directory is root-only. - The two false-state phrases appear in **0** built HTML files across the whole bundle. ### 404 / noindex / sitemap - Real HTTP **404** for the nonexistent route (root base and `/paperclip-docs/` subpath build). - `404.html`: exactly one `<h1>Not found</h1>`, `<meta name="robots" content="noindex, nofollow">`, `<title>Not found | Paperclip Docs</title>`. - Absent from `sitemap.xml` (0 occurrences); no built file for the route. - `sitemap.xml` has 184 `<loc>` (183 routes + root) and the root directory anchor set covers **183/183** non-root sitemap routes — 0 missing. - `_redirects` contains **no wildcard `200` rewrite** (0 lines with a `200` status), so unknown routes cannot be masked as success. - `robots.txt`: `User-agent: * / Allow: /` + `Sitemap: https://docs.paperclip.ing/sitemap.xml`. ## Focused checks — rerun on the final revision (`f5bbba24c`) | command | result | |---|---| | `npm run docs:test:static-routes` | **PASS** — "Static route verification passed (5 representative routes + /guides/welcome/this-route-does-not-exist/, root and /paperclip-docs/ builds)." | | `npm run docs:build` | **PASS** — "Generated 183 crawlable route pages plus sitemap.xml and robots.txt." | `git status` is clean after the build (no generated output enters the tree). ## Browser matrix — desktop 1440×900 and mobile 390×844 Run with Playwright + Chromium 1228. The QA sandbox could not exercise this (blank-glyph text rendering); the root cause turned out to be that **no fonts are installed on the host at all** — installing DejaVu TTFs with a minimal fontconfig makes text render correctly, which unblocked the full interactive matrix here. Screenshots: https://pages.paperclip.ing/pap-16684-pr1-evidence/ ### Per-route, JavaScript enabled (both viewports) All six routes on both viewports: expected HTTP status, **exactly 1 `<h1>`** with the correct text, `#landing` present **only** on `/`, no `Loading`/`Could not load this guide.` text in the rendered body, `#runtime-status` hidden, **no horizontal overflow**. ### Interactive | check | result | |---|---| | root directory link → interior (client nav) | ✅ `/guides/welcome/what-is-paperclip/`, single H1 "What is Paperclip?", hero gone, not stuck loading | | direct load vs client-nav parity | ✅ identical H1 set | | back / forward history | ✅ back → `/` with hero restored; forward → interior with correct H1 | | home nav from an interior doc | ✅ `/` with hero | | theme toggle | ✅ toggles (`dark` → light) | | desktop sidebar / TOC / breadcrumbs / prev-next / search / footer | ✅ 191 sidebar links, 14 TOC links, breadcrumbs rendered, article nav present, search control present, 15 footer links | | mobile drawer | ✅ opens (screenshot `mobile-drawer-open.png`) | | mobile horizontal scroll | ✅ none | | unknown route | ✅ 404 page, single H1, noindex | ### JavaScript disabled | check | result | |---|---| | `/` directory usable with JS off | ✅ 202 anchors present in raw markup; hero + card directory fully rendered | | clicking a directory link with JS off | ✅ full page load to `/reference/api/overview/` | | that interior page with JS off | ✅ 1 H1 ("API Overview"), no hero, no false loading/error state, 6368 chars of real article text | | mobile with JS off | ✅ root and interior both render correctly | ### Console / network No JavaScript errors and no page errors on any route. Exactly two non-2xx requests, **both reproduced identically on approved `main` @ `2ab76e8e4`** — neither is introduced by this PR: - `GET /redirects.json` → 404. Pre-existing: neither the before nor after build emits this file. Verified byte-for-byte identical behaviour on `main`. - `GET https://api.github.com/repos/paperclipai/paperclip` → 403. Unauthenticated GitHub API rate limit for the header star counter; environmental, external, not a product defect. Also confirmed unchanged before → after on the same interior page: header (1), footer (1), search controls (4), sidebar links (191), TOC links (14), article nav (2), article text length (4328 chars). The **only** rendered difference is the intended H1 2 → 1 and the removed hero. ## Verified against the real Cloudflare Pages deploy, not just a local server The Cloudflare Pages check on this PR is **green** and produced a live preview: **https://pap-16682-server-render-root.paperclip-docs-74t.pages.dev** I reran the entire matrix against that real deploy. Every invariant reproduces **identically** to the local run — so these results hold on actual production hosting, including Cloudflare's own 404 handling: | route | HTTP | H1 | `#landing` | `Loading…` | `Could not load…` | noindex | anchors | |---|---|---|---|---|---|---|---| | `/` | 200 | 1 — Everything you need to run Paperclip. | present (root-only) | 0 | 0 | – | 184 | | `/guides/welcome/what-is-paperclip/` | 200 | 1 — What is Paperclip? | absent | 0 | 0 | – | 4 | | `/reference/api/overview/` | 200 | 1 — API Overview | absent | 0 | 0 | – | 4 | | `/how-to/add-mcp-server-to-agent/` | 200 | 1 — Add an MCP server to an agent's toolkit | absent | 0 | 0 | – | 4 | | `/reference/changelog/` | 200 | 1 — Documentation Changelog | absent | 0 | 0 | – | 4 | | nonexistent route | **404** | 1 — Not found | absent | 0 | 0 | **yes** | 0 | Browser matrix on the live preview, desktop 1440×900 and mobile 390×844: identical outcomes — client nav, direct-load parity, back/forward, home-nav, theme toggle, 191 sidebar links, 14 TOC links, mobile drawer opens, no horizontal scroll, and with **JavaScript disabled** the root directory (202 anchors) navigates by real page load into an interior with 1 H1, no hero, no false state and 6368 chars of article text. **Console/network on the live deploy: zero page errors.** The same two known non-product requests appear (`/redirects.json` and the GitHub star-count API). `/redirects.json` returns **404 on live production `docs.paperclip.ing` today** and on the `main` branch preview — conclusively pre-existing and unrelated to this PR. Screenshots from both the Cloudflare deploy and the local server are in the gallery: https://pages.paperclip.ing/pap-16684-pr1-evidence/ ## Out of scope — pre-existing observation, not a regression On the `--base-path /paperclip-docs/` subpath build, 4 footer links (`/reference/api/overview`, `/guides/org/agents/`, `/guides/org/adapters/`, `/guides/getting-started/five-minute-path/`) are emitted un-prefixed. Building approved `main` @ `2ab76e8e4` with the identical flag reproduces **exactly the same 4 links**, so this is a pre-existing footer-template issue untouched by this PR. Smallest fix would be routing the footer's hardcoded hrefs through the base-path prefixer, in a separate ticket. ## Merge policy `.site/` is generated output and is intentionally uncommitted. **This PR must remain open and unmerged — Dotta alone may merge it.** Co-authored-by: ClaudeCoder <[email protected]> Co-authored-by: Claude Opus 5 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
2ab76e8e4b |
docs: fix goals reparenting, human-invite signup, macOS install, first-company step (#80)
Addresses open documentation-feedback issues, each verified against the `paperclipai/paperclip` source. ## Changes - **Goals — reparenting (#13):** The goal properties panel renders the parent goal as a read-only link (unlike issues, which have an editable parent picker), and the goal update mutation never sends `parentId`. The docs claimed you could "change the parent field" in the panel. Corrected to describe the real path — `paperclipai goal update <id> --parent-id <id|null>` / `PATCH /goals/{id}` — and removed "parent" from the list of panel-editable fields. - **Add a human teammate — signup (#50):** The reported "Email and password sign up is not enabled" is thrown by Better Auth when `emailAndPassword.disableSignUp` is set, which Paperclip wires from `auth.disableSignUp` / `PAPERCLIP_AUTH_DISABLE_SIGN_UP`. Added a troubleshooting callout naming the cause and how to re-enable self-service signup. - **Installation — macOS Apple Silicon (#74):** The Terminal install path had no troubleshooting section. Added a note for the embedded PostgreSQL start failure caused by missing `libzstd`/`liblz4` compatibility symlinks, with a copy-paste fix. - **Create your first company (#16):** Renamed the step 4 heading from "Save and continue" to "Create the company" to match the actual **Create Company** button. ## Verification - `sync:lint-links` passes — 186 markdown files, no broken internal links. - Product-behaviour claims (#13, #50) confirmed directly in parent source; #74 documents the reporter's symptom (doc-gap confirmed, not independently reproduced). Closes #13, #16, #50, #74 Co-authored-by: Claude Opus 4.8 <[email protected]> |
||
|
Michael Nguyenandanicca
|
f80e8a7289 |
Make docs navigation crawlable and sitemap dates accurate (#77)
## Summary - emit previous and next article navigation as real anchors in generated HTML - preserve the existing client-side navigation behavior - derive sitemap lastmod values from each Markdown file's Git history - omit lastmod when history is unavailable instead of publishing the build date - remove ignored changefreq and priority values - add regression assertions for crawlable links and sitemap dates ## Verification - npm run docs:test:static-routes - npm run sync:lint-links - npm run docs:build - generated 183 pages with zero server-rendered orphans, minimum one inbound link, and 23 distinct lastmod dates - git diff --check ## Risk Low. No routes, redirect rules, canonicals, robots directives, or index/noindex policy changed. Production still requires merge through the existing workflow. Co-authored-by: anicca <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
8c21935aa6 |
Add documentation changelog page with reusable accordion (#73)
## What Adds a **Changelog** category (Reference tier) with a **Docs** page that tracks what changed in *these docs* — pages added, rewritten, or expanded — per release. It's framed as a changelog for the documentation itself, not a mirror of Paperclip's product release notes (which it links out to). Backfilled with the full documentation history: **10 releases** from `v2026.513.0` (this repo's genesis) through `v2026.722.0`, reconstructed from each release commit's own docs summary. Each release is a collapsible accordion; the newest stays open. ## New design-system component Introduces a reusable native `<details>`/`<summary>` **accordion** (no JS): - `site/styles.css` — `details.accordion` styled with existing tokens (border/radius, parchment hover, rotating chevron, theme-aware), with an optional `.accordion-meta` right-aligned label. - `site/app.js` — allowlists `DETAILS`/`SUMMARY` + the `open` attribute in the client-side markdown sanitizer so collapsible content survives SPA rendering. Usage: ```html <details class="accordion" open> <summary>Title <span class="accordion-meta">meta</span></summary> <div class="accordion-body"> Markdown content — keep the blank lines so it parses. </div> </details> ``` ## Files - `docs/reference/changelog.md` (new) - `site/content.json` — Changelog category / Docs page nav entry - `site/styles.css`, `site/app.js` — accordion component ## Verification - `npm run sync:lint-links` — clean, no broken internal links (links verified against current tree; renamed/retired pages point at live targets). - `npm run sync:verify-nav` — passes (only orphans are the intentional CLI redirect pages). - `npm run docs:build` — all 10 accordions render, `/reference/changelog/` route builds. ## Note This is a **manual** changelog for now. A follow-up could hook a "prepend a new accordion" step into the `/sync-docs` release phase so future releases self-populate. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.8 <[email protected]> |
||
|
|
44e12ab37c |
Release docs for paperclip v2026.722.0 (#72)
Release docs for **paperclip v2026.722.0** (window `v2026.720.0 → v2026.722.0`; 256 changed parent files, 60 commits, diff window clean — 0 truncated leaves). Nothing here goes live until this PR is merged to `main`. ## Surfaces authored this run | Surface | Docs | Parent PR | |---|---|---| | **Run-bound agent secret access** — `access.`-prefixed / `api` delivery mode; `GET /api/agents/me/secrets`, `POST /api/agents/me/secrets/:key/value` (`Cache-Control: no-store`) | `api/secrets.md`, `api/agents.md` | #9921 | | **Local agents run natively on Windows** (ACPX, no Bash wrapper; env via session options; `.cmd` shim; symlink→copy on EPERM) | `adapters/acpx-local.md` | #9980 | | **`PAPERCLIP_*` bindings flow through**; only `PAPERCLIP_API_KEY` rejected (override removed); `DO_NOT_TRACK` / `PAPERCLIP_TELEMETRY_DISABLED` opt-out | `deploy/environment-variables.md` | #9974, #9946, #9906 | | **Safer `CODEX_HOME` sandbox sync** — explicit allowlist, not whole home | `adapters/codex.md` | #9972 | | **Plugin SDK** environment-sync exports + `onEnvironmentSyncIn/Out` hooks | `reference/plugins/sdk.md` | — | | **CLI `company export --force`** | `reference/cli/company.md` | — | | **Connections v3 (Apps)** experimental foundation — `remote_http`→`mcp_remote`, `connection_grants`, AppDefinition catalog | `experimental/connections-apps.md` (new) | #9958, #9981, #9982 | Riding along from earlier nightly drafts (part of this release): secret folders (`administration/secret-folders.md`), searchable agent picker, cloud-managed bootstrap gate (`api/instance-admin.md`). ## Verification All authored claims verified against parent code at tag `v2026.722.0` (`verify-edit`): **0 high-confidence unverified**. `docs:build`, `sync:lint-links`, and `sync:verify-nav` all pass. Frontmatter stamped `paperclip_version: v2026.722.0`. The 2 nav orphans (`cli/commands.md`, `cli/control-plane-commands.md`) are the intentional redirect anchors. ### ⚠ Drift (all resolved as false positives — no action) `sync:check-drift` flagged 4 `rest-route-missing` candidates: - `GET /api/agents/me/secrets` and `POST /api/agents/me/secrets/{key}/value` (in `api/agents.md` and `api/secrets.md`). These are the **new** routes this PR documents. The flags fire because the drift checker searched a stale `last_seen` sha and REST-route matching is medium-confidence (router-prefix registration hides the literal). Both routes were verified verbatim against `server/src/routes/secrets.ts` at tag `v2026.722.0`. No change needed. One `verify-edit` env-var flag (`PAPERCLIP_CLOUD_PROD_PROVIDER_RAILWAY_TOKEN`) is the release-note **illustrative example** of a user-chosen name, framed in prose as "for example a secret called …" — not a real product variable. No change needed. ### ↻ Renames detected None. ### ⚠ Reconcile None. ## Screenshots See `SCREENSHOTS_PENDING.md`. 13 unique captures (×2 light/dark) are genuinely stale — mainly agent-config surfaces (`AgentConfigForm.tsx` gained the Secret access editor) and secrets. Net-zero `+0/-0` UI touches were filtered out. Not auto-captured — recapture via `npm run screenshots:refresh` goes to a separate review PR. The new `secret-folders.md` and `connections-apps.md` pages have no captures yet. ## Post-merge (squash-only repo) After squash-merging, run `node scripts/sync/realign-nightly.mjs release/v2026.722.0 --push` and bump `.sync-state.json` `base_release_tag` to `v2026.722.0`. Skipping the realign arms the add/add-conflict trap 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]> |
||
|
|
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]> |
||
|
Aron PrinsandClaude Fable 5
|
5fdce2b098 |
screenshots: pre-seed capture phase for onboarding-wizard shots (#70)
Fixes the harness limitation flagged in #68: the seeded instance always has a company, so the create-a-company wizard was unreachable and onboarding shots fell back to the Dashboard. **How:** `run.mjs` gains a phase 3.5 — after health check, before seeding — that captures targets marked `phase: "pre-seed"` while the instance is still company-less (`/onboarding` serves the wizard there). `capture.mjs` gains a `phase` option (`--phase`); post-seed stays the default, so existing invocations are unchanged. **Retargeted:** the four true wizard shots to `/onboarding` (goal-field fills the company name and advances to the Mission step); the two budget shots to the agent configuration form, since the wizard has no budget UI (verified at v2026.720.0). **Validated with real runs against the v2026.720.0 tag** — all pre-seed captures succeed with zero step failures, light and dark visually verified (wizard step 1 empty, filled name, Mission step). Refreshed PNGs included. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 <[email protected]> |
||
|
Aron PrinsandClaude Fable 5
|
215dc2ed2d |
screenshots: wire routes for 20 unrouted registry entries (#69)
Backfills `route` + `dependsOn` for the 20 registry entries flagged in #68 as never wired for automated capture (plus marks the hand-annotated `dashboard-overview-annotated` as intentionally manual instead of leaving its stale `_todo`). Routes verified against the v2026.720.0 route table in `ui/src/App.tsx`; every `dependsOn` path verified to exist at that tag. Details and caveats (dialog-step captures, the onboarding harness limitation) in the commit message. No images change in this PR — next capture pass picks these up. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Fable 5 <[email protected]> |
||
|
Aron PrinsandClaude Fable 5
|
ef28814c68 |
Screenshot overhaul for paperclip v2026.720.0 (#68)
Full screenshot overhaul for **paperclip v2026.720.0** — the design-system convergence in this release (single-source tokens, retuned theme, Card/Badge adoption, radius ladder, Lucide status glyphs) invalidated 248 of 298 registry entries, so this recaptures everything with a route rather than a targeted refresh. Captured with `npm run screenshots:refresh:all` against parent tag `v2026.720.0` (`903bd157c`), on the standard isolated seeded instance (loopback :3197, embedded Postgres on a free port). 1440×900 @2x, light + dark. ## What's in here - **246 recaptured PNGs** (123 logical shots × light + dark), all stamped `captured_sha: 903bd157c…` in `registry.json`. - Dimensions, theme correctness, and file sanity verified by an automated review pass: all full-page captures 2880×1800, dark variants genuinely dark, no blank/error/login pages, no 0-byte files. The two intentionally small cropped stat-panel shots are correct. ## Excluded after review (kept on their old captures, still marked stale) Five logical captures came out showing the **wrong UI state** and were reverted rather than shipped: | Capture | What went wrong | |---|---| | `onboarding/goal-field` | Onboarding flow unreachable — seeded instance already has a company, capture fell back to Dashboard | | `onboarding/new-company-modal-empty` | Same Dashboard fallback | | `onboarding/sidebar-new-company-button` | Same Dashboard fallback | | `work-modes/work-mode-picker` | Picker overlay click timed out (8s); shows Inbox without the picker open | | `routines/cron-picker` | Schedule-builder click timed out; shows routine Overview without the builder | Harness fixes needed before these can recapture: a company-less (or resettable) instance for the onboarding set, and longer interaction timeouts / fixed locators for the two pickers. ## Worth a look during review - `skills/assign-to-agent` shipped but is **partial**: the "Add to agent" button is visible but the dropdown isn't expanded. Usable, flagging for judgement. - **42 registry entries (21 logical) remain uncaptured** — they have `route: null` and a `_todo` note, i.e. never wired for automated capture. Mostly `company/*`, `tasks/*`, `org/*`, plus two export-import shots. Deciding whether to add routes for these is follow-up work, not part of this PR. - 8 PNGs on disk are pre-existing hand-made assets outside the registry (`hermes/*`, two diagrams) — untouched, expected. ## Checklist - [ ] Spot-check a few light/dark pairs render correctly in the docs - [ ] Confirm the five excluded captures' old images are still acceptable placeholders - [ ] File follow-up for the onboarding-harness fix + the 21 unrouted registry entries 🤖 Generated with [Claude Code](https://claude.com/claude-code) 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]> |
||
|
|
dcd77edb7e |
Use white text in dark theme (#66)
## Summary - replace the dark-theme manila primary text color with white - update dark code blocks, navbar CTA states, and footer text consistently ## Verification - `npm run docs:build` - confirmed generated output contains no `#f3e6c4`, `manila`, or `manilla` references Issue: PAP-14695 --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
|
87bcacc731 |
docs: move desktop app guidance to unofficial community page (#65)
## Summary - Add a dedicated **Community Desktop App (unofficial)** guide covering installation, Local/Remote modes, server connections, updates, and troubleshooting. - Clearly identify `aronprins/paperclip-desktop` as community-maintained, unofficial, and unsupported by the Paperclip team. - Remove the desktop app as a primary installation/start path across the installation, update, quickstart, glossary, terminal setup, export/import, and overview docs. - Register the new page under **How-to Guides → Deploy & Maintain** and retain small cross-links where desktop-specific guidance is useful. ## Verification - `npm run docs:build` — passed on the final PR branch. - `sync:lint-links` — previously passed across 162 files with no broken links. - `sync:verify-nav` — previously passed with only two pre-existing orphan pages. - `docs:test:static-routes` — previously passed. - Verified the new route, sitemap entry, and cross-links in the built `.site` output. Closes PAP-14693. --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
55de2cbb81 |
fix(sync): pin drift check to an immutable SHA, key cache by SHA (#62)
Ports the drift-checker fix to `main` (same change already merged to `nightly` in #61). `check-drift.mjs` is byte-identical across branches, so this cherry-pick applies cleanly. ## Problem The drift checker printed the parent's **live** SHA in its header but keyed its file cache by the moving name `drift-master` with no invalidation — reusing days-old file contents while claiming to check today's commit, silently hiding real drift. ## Fix - Resolve the ref to a full commit SHA before any reads; cache key = `drift-<sha>`, never `drift-master`. - Fail closed if the ref can't be resolved. - Mode-aware ref from `.sync-state.json` (release → `base_release_sha`, nightly → `last_seen_parent_sha`) before falling back to the default branch. `main` is release-mode, so its checks now pin to the release SHA instead of moving `master`. - Testable cache path (`PAPERCLIP_SYNC_CACHE_DIR` + fixture SHA stub); +2 regression tests. `npm run sync:test`: 37 passed, 0 failed. ## Triage note Running the fixed checker on `main`'s released docs against the release tag `v2026.707.0` returns **0 drift** — released docs are correct about the shipped product; this is a tooling fix only, no doc content changes. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 4.8 <[email protected]> |
||
|
|
773f72838a |
docs: Checkbox Confirmations API reference (v2026.609.0) (#54)
## Summary - New API reference page `docs/reference/api/checkbox-confirmations.md` for the `request_checkbox_confirmation` issue-thread interaction kind (shipped in v2026.609.0, paperclipai/paperclip#7649): create/list/accept/reject routes, full payload schema + validation limits, results/outcomes, continuation policy, target staleness, idempotency. - Registered in the API nav (`site/content.json`) after Issues. - Card screenshot added under `docs/user-guides/screenshots/{light,dark}/interactions/` (same capture both themes — the delegated QA pass produced a light capture; swap-safe path). Campaign v2026-609-0 · piece `api-docs--checkbox-confirmations` · PAP-13235. **Merging this PR = publishing the page** (delivery gate for the campaign piece). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
DottaandPaperclip
|
ad0d5a930b |
Glossary: add per-term stable anchors (#52)
Convert glossary terms into citable heading sections and add matching static heading IDs to the release build. Static-route verification now asserts representative glossary term anchors. Verification: - npm ci --include=dev - npm run docs:build - npm run docs:test:static-routes - git diff --check origin/main...HEAD - Cloudflare preview glossary contains id="adapter", id="board-operator", and id="heartbeat" 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.docs/v2026.707.0 |
||
|
|
cd2b7d89b1 |
docs: enrich Task Watchdogs guide — lifecycle visuals + oversight framing [v2026.626.0] (#45)
## Summary - Updates the **existing** `docs/guides/projects-workflow/task-watchdogs.md` page (re-scoped from a would-be duplicate page, per board direction on PAP-12840 — no-duplicates rule holds). - Adds: watchdog lifecycle diagram, review-outcome thread screenshot (light & dark), activity-feed labeling note, the fingerprint dedupe explanation (one review per distinct stopped state), and a new "Watchdogs, approvals, and execution policy" comparison section. - Adds the `paperclip_version: v2026.626.0` pin. Staged from the v2026.626.0 release-content pipeline (`docs-guide--task-watchdogs`, PAP-12840). **Do not merge without the publish gate** — merge = live on docs.paperclip.ing. Canary preview is for board review. ## Test plan - [ ] Cloudflare Pages preview: page renders at `/guides/projects-workflow/task-watchdogs/` - [ ] Diagram + screenshot render; screenshot swaps with theme toggle - [ ] New comparison section reads well in page flow 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
|
ce13816179 |
[codex] Fix docs SEO crawl hygiene (#46)
## Summary Fixes the docs-side causes behind the Google Search Console duplicate/canonical SEO issues by tightening generated static routing behavior. ## What changed - Removed the Cloudflare Pages wildcard `/* /index.html 200` SPA fallback from the generated docs release so deleted or unknown asset URLs can return 404 instead of serving docs HTML. - Removed the global `X-Robots-Tag: index, follow` header and replaced it with noindex coverage for non-page static assets, `sitemap.xml`, `robots.txt`, and the generated `404.html`. - Added legacy route handling for removed docs URLs and extended static route verification for redirects, removed assets, noindex headers, and 404 behavior. ## Root cause The generated Cloudflare Pages release treated too many non-page/static URLs as indexable page responses. That allowed removed assets or auxiliary files to be crawled as duplicate indexable documents instead of clear 404/noindex responses. ## Validation - `npm run docs:test:static-routes` - `npm run docs:build` PAP-12839 --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
|
4dfa41449d |
docs: drop launch-context link from Work modes guide (#43)
## Summary - Removes the trailing "Related — launch context" section (release blog link) from the Work modes guide, per operator request on PAP-12809. Docs pages should not link back to the release. ## Test plan - [x] Page body otherwise unchanged; markdown-only edit. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
Dotta
|
ac9e4a35e0 |
docs: Work Modes guide (ask work mode) [v2026.626.0]
Publish the approved Work modes docs guide for ask work mode.\n\nSource: PAP-12809 / release-content docs-guide--ask-work-mode |
||
|
|
b214cdebda |
[codex] Improve docs Lighthouse scores (#41)
## Summary Improves the docs page Lighthouse profile for the report attached to [PAP-12441](/PAP/issues/PAP-12441). - Removed render-blocking third-party docs shell requests for Google Tag Manager, Google Fonts, and Lucide. - Vendored the existing `[email protected]` parser locally and copied `site/vendor` into release builds. - Replaced Lucide runtime icon rendering with inline SVG paths for the existing docs section icons. - Fixed reported accessibility issues: mobile zoom disabling, hidden drawer focusability, TOC ARIA semantics, footer heading order, muted-text contrast, TOC button accessible name, and article link affordance. - Added smaller responsive WebP variants for the dashboard overview screenshot and explicit dimensions/fetch hints for article images. - Minified CSS in release builds. ## Canary - Commit preview: https://2f89e7fc.paperclip-docs-74t.pages.dev - Branch preview: https://codex-lighthouse-docs-scores.paperclip-docs-74t.pages.dev - Target route from the report: https://2f89e7fc.paperclip-docs-74t.pages.dev/guides/getting-started/five-minute-path/ ## Root Cause The docs shell was paying for several third-party render-blocking requests before first contentful render, and the target guide loaded a large full-size dashboard PNG for a small mobile viewport. Several Lighthouse accessibility audits were caused by UI semantics rather than content: a hidden but focusable drawer, menu roles around plain links, a non-zoomable viewport, footer heading level skips, and color-only article links. ## Validation - `npm run docs:build` passes. - `npm run docs:test:static-routes` passes. - `npm run docs:test:hierarchical-skills-nav` passes. - `node --check site/app.js`, `node --check .site/app.js`, and `node --check site/build-release.mjs` pass. - Static release checks pass for preserved SEO metadata, removed third-party assets, zoomable viewport, inert drawer, no footer headings, underlined article links, responsive screenshot wiring, TOC nav semantics, and copied optimized assets. - Cloudflare Pages check passed for commit `129baaa`. Local Lighthouse could not complete in this container because the available cached Chromium binaries fail to start without `libatk-1.0.so.0`. PageSpeed Online is also quota-limited from this environment. The canary URL above is ready for a browser-capable Lighthouse run. --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
|
dd7fa3e1c6 |
Canonicalize docs route redirects (#40)
## Summary - Generates explicit Cloudflare Pages `_redirects` entries for every slash-terminated static docs route. - Sends no-trailing-slash docs URLs to their canonical slash URL with a one-hop 301 before the SPA fallback. - Extends the static-route verifier to assert those redirects are emitted and ordered before the catch-all fallback. ## Root cause Google Search Console was inspecting the no-trailing-slash URL. The live page currently reaches content after a redirect chain, while the sitemap and canonical URL use the trailing-slash form. Making the redirect explicit in `_redirects` removes ambiguity for crawlers and keeps the canonical route consistent. ## Verification - `npm run docs:test:static-routes` - `git diff --check origin/main...HEAD` Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
Dotta
|
28a1c40933 |
Add crawlable docs SEO outputs
Add sitemap, robots, Cloudflare routing/header files, route-specific SEO metadata, JSON-LD, and static crawlable docs page HTML. |
||
|
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 Prins
|
a6b1fc3d45 |
Merge pull request #36 from paperclipai/release/v2026.626.0
Release docs for paperclip v2026.626.0: nightly drafts + release authoring, 98 refreshed screenshots + screenshot-pipeline isolation fixes, verify-edit hermes path resolution fix, and New Issue searchable reuse-workspace docs. |
||
|
Aron PrinsandClaude Opus 4.8
|
1d5f257f2f |
docs(issues): document searchable reuse-workspace selector in New Issue dialog
Author parent commit 50ae8fc6 (#8597): the New Issue dialog's reuse-existing workspace mode now uses a searchable selector that ranks visible workspace-name matches ahead of hidden path text. Add a "Choose where the work runs" step to the Creating a New Issue flow covering the workspace mode picker and the searchable reuse dropdown (search by name, branch, or folder), with a cross-link to the Execution workspaces guide. Mark the item authored in PENDING.md. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
e282e1a881 |
docs(pending): mark screenshots + plugin target done; flag snapshot as stale
Hand-edit (out of band) of the nightly sync state file: all 98 screenshots and the `plugin target` CLI command are now authored; the cumulative window and quarantine math predate the v2026.626.0 release and are stale until next sync. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
ae046f058b |
docs(screenshots): refresh all 98 stale shots + harden pipeline isolation
Recapture every screenshot flagged in SCREENSHOTS_PENDING.md (98 entries; 233 PNGs updated across light/dark) against parent `master`, and stamp registry.json with the new captured_sha. Mark SCREENSHOTS_PENDING.md as caught up. Also fix two isolation gaps that made `screenshots:refresh` unusable while a real local Paperclip is running: - Free embedded-Postgres port: onboard hard-codes port 54329 (no env/flag override; the port comes only from config.json), which collides with a real local instance. run.mjs now generates the config in external-DB mode (keeping the scratch data dir pristine) and rewrites database.embeddedPostgresPort to a scanned free port before boot. - Parent .env neutralized: the server loads PARENT_REPO/.env from its cwd via dotenv (override: false), which leaked DATABASE_URL (real external DB on 5432) and SERVE_UI=false into the "isolated" instance. instanceEnv() now pins DATABASE_URL="", DATABASE_MIGRATION_URL="" and SERVE_UI="true" so these win. seed-execution-workspace.mjs now throws instead of falling back to 54329, so the direct-DB seed can never connect to a real database. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Sonnet 4.6
|
e46c6631e0 |
fix(sync): teach verify-edit to resolve hermes-local/hermes-gateway → packages/adapters/hermes
The hermes adapter package was consolidated under packages/adapters/hermes/
in v2026.626.0, but the doc files keep the hermes-local.md and
hermes-gateway.md names. verify-edit.mjs derives the source path from the
doc basename, so it was searching packages/adapters/hermes-local and
packages/adapters/hermes-gateway (non-existent) and flagging all claims as
unverified — false positives.
Fix: add an adapter_doc_sources map to anchor-map.json that overrides the
source-path lookup for these two docs, and update fetchAdapterFiles() to
read and apply that map before falling back to the default
packages/adapters/${adapter} pattern.
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
|
||
|
Aron PrinsandClaude Sonnet 4.6
|
04a7b32f47 |
fix: correct two verification errors from release review
- hermes-gateway.md: rename dangerouslyAllowRemoteHttp →
dangerouslyAllowInsecureRemoteHttp (actual field name in
packages/adapters/hermes/src/gateway/server/transport-security.ts)
- reference/skills.md: correct Agent→Skills tab section labels from
"Company skills"/"Unmanaged" to the actual rendered headings:
"Installed skills", "Other skills", and
"({N}) User-installed skills, not managed by Paperclip"
Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
|
||
|
Aron Prins
|
79411f5c3e | Merge branch 'nightly' into release/v2026.626.0 | ||
|
Aron PrinsandClaude Sonnet 4.6
|
57cd932896 |
Release docs for paperclip v2026.626.0
Covers Hermes built-in adapters (hermes_local + hermes_gateway), ask work mode, task watchdogs, plugin target command, routine date variables, and workspace file downloads. Co-Authored-By: Claude Sonnet 4.6 <[email protected]> |
||
|
DottaandPaperclip
|
eb86e8250d |
docs: update Hermes gateway setup duration
Co-Authored-By: Paperclip <[email protected]> |
||
|
DottaandPaperclip
|
413c547781 |
docs: add Hermes agent connection guide (#35)
## Summary - Adds a Hermes-specific how-to guide for connecting Hermes Agent to Paperclip through the external invite and gateway flow. - Includes the attached screenshots in the docs release asset tree and references them throughout the walkthrough. - Adds the guide to the How-to navigation and cross-links it from Bring Your Own Agent. ## Validation - `npm run sync:verify-nav` - `npm run sync:verify-screenshots` - `npm run docs:test:static-routes` - `npm run docs:build:auto` - Targeted link check for `docs/how-to/connect-hermes-agent.md` ## Notes `npm run sync:lint-links` still fails on an unrelated pre-existing link in `docs/reference/skills/optional/research/last30days.md` that resolves to `docs/reference/skills/optional/research/url`. --------- Co-authored-by: Paperclip <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
0decd79019 |
nightly: sync bookkeeping, no doc changes (paperclip 841742fc)
Cumulative window v2026.618.0 → master 841742fc (9 new commits since 51ffbb38). 8 of 9 are <24h old and held by the 24h quarantine; the one eligible commit (50ae8fc6, reusable workspace selector search) is a UX refinement with no documented surface and no screenshot dependency, so nothing was authored. Drift: 0. Reconcile: 0. Regenerated PENDING.md (quarantined queue for next run) and SCREENSHOTS_PENDING.md (98 stale across cumulative window). State: last_seen_parent_sha → 841742fc; last_applied_manifest_hash unchanged so the quarantined commits remain pending next run. Co-Authored-By: Claude Opus 4.8 (1M context) <[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 Prins
|
4ba43e3bd9 | Merge remote-tracking branch 'origin/main' into nightly | ||
|
Dotta
|
a21e720dff |
Implement persistent docs On this page sidebar (#33)
## Summary - Adds a persistent wide-screen `On this page` right rail to article pages. - Realigns the docs shell to a wider three-column grid with the left docs nav moved farther left. - Keeps the existing compact TOC dropdown for narrower widths and mobile. - Refactors TOC generation so route changes clear/rebuild both desktop and compact TOC mounts, with stable h2/h3 scrollspy and reduced-motion-safe active styling. ## Verification - `npm run docs:build:auto` - `npm run docs:test:static-routes` - `node --check site/app.js` - Served `.site` locally at `http://127.0.0.1:4321/`. ## Browser inspection note Attempted Playwright inspection for desktop/tablet/mobile against `docs/reference/api/issues`, but local Chromium could not launch because the container is missing `libatk-1.0.so.0`; `npx playwright install-deps chromium` could not complete because sudo requires a password. Existing QA follow-up should perform real browser review on the PR/canary. ## Canary No Cloudflare canary URL is available from this local PR creation step yet. |
||
|
DottaandPaperclip
|
5b4b489154 |
[codex] Add Skills docs hierarchy (#34)
## Summary - Add generated reference pages for bundled and optional skills. - Add Skills index pages and hierarchy-aware sidebar/breadcrumb navigation. - Add verification scripts for hierarchical Skills routes and static docs routes. ## Verification - `npm run sync:verify-nav` - `npm run docs:test:static-routes` - `npm run docs:build` - QA in PAP-11775 also verified browser rendering for hierarchy, bundled `task-planning`, and optional `last30days` pages with screenshots. ## Issues - PAP-11770 - PAP-11783 --------- Co-authored-by: Paperclip <[email protected]> |
||
|
DottaandPaperclip
|
91bbe2cdbd |
[codex] Add static SEO docs routes (#32)
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - The public docs site is how operators and contributors discover reference material and guides. > - The docs pages were routed through hash URLs, which makes individual pages harder for crawlers and link previews to treat as first-class documents. > - The release build needs to emit static HTML pages for each docs route while preserving the client-side docs experience. > - This pull request adds static docs route generation and verification around canonical, crawlable route output. > - The benefit is that docs pages can be indexed and shared as normal path-based URLs without losing local navigation behavior. ## Linked Issues or Issue Description No public GitHub issue exists for this docs-site improvement. Problem: - Docs pages were reachable primarily through hash routes such as `/#/reference/skills`. - Crawlers and social previews benefit from static route-specific HTML at normal paths such as `/reference/skills`. - The release build should publish those pages predictably and verify that they include canonical metadata, page titles, and visible article content. ## What Changed - Added static route generation to the docs release build so each nav route gets an `index.html` output with route-specific title, canonical URL, article content, and sitemap entry. - Updated the browser app bootstrap to support path-based docs routes and retain compatibility with hash links. - Added `docs:test:static-routes` coverage for generated static route output. - Documented Cloudflare Pages preview and production deployment details. ## Verification - `npm run docs:test:static-routes` - `npm run docs:build` ## Risks Low to medium risk. This changes release output shape for the docs site, so the main risk is a Pages deployment configuration mismatch. The build keeps existing client-side rendering behavior and includes a static-route verification script to catch missing canonical pages before publishing. ## Model Used OpenAI GPT-5 Codex coding agent, tool-using software engineering mode. Exact service context window was not exposed in this runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <[email protected]> |
||
|
DottaandClaude Opus 4.8
|
b65db4d0e1 |
Fix horizontal scroll on docs pages on mobile
Long unbreakable inline code tokens (file paths, API routes, config
keys like <paperclipInstanceRoot>/skills/{companyId}/...) and tab bars
with many tabs (e.g. one per provider) widened the page past the
viewport on narrow screens, causing horizontal scroll — most visibly
on /reference/skills.
- Inline <code> now wraps long tokens (overflow-wrap:anywhere) while
block code in <pre> keeps its own horizontal scroll.
- #article and links wrap long words/URLs.
- .tabs-bar scrolls horizontally instead of overflowing the page;
tab buttons keep their width (matches the code-tabs variant).
Verified with headless Chromium across all 135 docs pages at 320px
and 375px viewports: no page exceeds the viewport width (0 overflow).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
|
||
|
Dotta
|
130e55a797 | Add Google Analytics tag to docs | ||
|
Aron PrinsandClaude Opus 4.8
|
e2a0882bfe |
nightly: update sync state after round-2 review items
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 Opus 4.8
|
d852ec21f4 |
nightly: update sync state (manifest hash, parent HEAD 9ac2431)
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron PrinsandClaude Opus 4.8
|
46965fc667 |
nightly: codex-local auth + monitor, gemini exec notes, auth --no-browser (paperclip d1e6662e)
Cumulative nightly sync from parent v2026.618.0..d1e6662e (HEAD 9ac2431 quarantined, <24h). Applied (PR-tier, verified against parent): - codex-local: outputInactivityTimeoutMs config field + new "Authentication And Per-Agent Homes" section (host login inheritance, per-agent home seeding, fail-fast on no creds). - gemini-local: execution note now states --prompt (not stdin) and the headless-safe terminal/browser env for unattended runs. - CLI auth login: new --no-browser flag. Verify-edit: codex-local 38/40, gemini-local 27/28, authentication 37/37; the 2 unverified are pre-existing example placeholders, not this run. PENDING.md / SCREENSHOTS_PENDING.md regenerated. 7 surfaces left for human review (skills "required" retirement, paperclip-dev removal, instance-scoped environments, task watchdogs, experimental features, skills store, plugin-sdk lease params). 80/276 screenshots stale. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> |
||
|
Aron Prins
|
23e4457432 |
Merge pull request #30 from paperclipai/release/v2026.618.0
Release docs for paperclip v2026.618.0 |