mirror of
https://github.com/paperclipai/paperclip-docs.git
synced 2026-11-07 06:16:07 -10:00
main
25
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 DottaandPaperclip
|
29a78936e5 |
docs: explain and set up experimental GitHub review bots (#130)
## Thinking Path > - Paperclip runs agent work as tasks and runs. > - The experimental GitHub chat connector lets GitHub conversations and PR events enter those tasks. > - Installing an App, scheduling reviews, and requiring a passing check are independent choices. > - Readers need both that explanation and a concrete setup tutorial. > - These guides pair the mental model with a Storybook reviewer that can be tested from failure to success. ## What Changed - Group all four GitHub pages under an expandable GitHub sidebar section, with matching breadcrumbs. - Add **Understanding GitHub PR review bots**, preserving the conversational explanation of installation, triggers, scores, checks, and formal reviews. - Add a separate **Set up a GitHub review bot** tutorial with a copyable Storybook instruction, agent/runtime prerequisites, App registration and installation, repository selection, identity linking, and required-check configuration. - Mark both pages as experimental chat documentation and cross-link them. Update the older GitHub pages to remove conflicting legacy setup advice. - Include four real setup UI screenshots in both themes, using explicitly labeled demo responses. Register all eight images for reproducible capture and source-change tracking. - Add a screenshot-only fixture and small capture helpers for native selects, required content, and a configurable local port. ## Verification - Latest-head GitHub `docs-test` and Cloudflare Pages checks passed at `b4e7943f8e77bc3320ea6eb0379dd1ff65f87a98`. - Deployed preview browser-checked: [understanding review bots](https://5e364a56.paperclip-docs-74t.pages.dev/connectors/understanding-github-review-bots/) and [setup tutorial](https://5e364a56.paperclip-docs-74t.pages.dev/connectors/github-review-bot-setup/). - GitHub sidebar collapse/expand and navigation between nested pages checked in the embedded browser. - Both pages checked in the embedded browser. Followed the cross-links in both directions and verified all four images load in light and dark themes. - All eight screenshots captured from the actual UI at Paperclip revision `7ba761fe007bb798400d3e62346fa964f607f0f8`. No live GitHub credentials or agent runs are represented by these fixtures. - `npm run sync:lint-links`, `npm run sync:verify-nav`, and `npm run sync:verify-screenshots` passed. Navigation reports only the three pre-existing unlisted/orphan pages. - `npm run docs:build` and the complete `npm run docs:test` suite passed, including static routes, sitemap history, asset fingerprints, navigation, crawlable links, source blocks, 1,945 link-resolution checks, and SEO metadata. - Reviewed the current GitHub documentation for required checks, expected App sources, and neutral results. ## Risks The chat feature is experimental and the UI may change. Screenshot dependencies and capture commands are recorded for refreshes. The tutorial distinguishes illustrative UI captures from the live acceptance tests readers must perform. This changes documentation and its screenshot pipeline only. ## Model Used OpenAI GPT-6 through Codex, using repository tools and the embedded browser. The precise serving model variant and context-window size were not exposed. ## Checklist - [x] Both requested pages exist and cross-reference each other. - [x] Both identify the experimental chat feature. - [x] Screenshots include light and dark themes with capture provenance. - [x] Documentation build and targeted verification passed. - [x] Complete docs test suite and PR checks passed. --------- Co-authored-by: Paperclip <[email protected]> |
||
|
Dotta
|
8d83401d7b |
docs: explain low-trust agents for GitHub review bots (#129)
GitHub review bots read code and conversation text supplied from outside the company. This adds a dedicated section to the existing low-trust review page explaining the agent preset, concrete work boundary, isolated sandbox, governed connection tools, and the separate limits of guest sponsorship. The approved connector setup links to this existing page and warns when the chosen agent uses standard trust. Choosing the warning does not silently change the agent policy. Validation: documentation build passed for 258 pages. No site configuration or navigation changes. Model: OpenAI GPT-6 through Codex, using repository inspection, editing, and build tools; exact serving model ID/context size were not exposed. |
||
|
Dotta
|
480c133b1f |
docs: explain HTTPS setup for self-hosted Paperclip (#128)
Some Connections need a trusted HTTPS callback, and self-hosters need to distinguish private browser access from public provider webhooks. Add a setup guide covering HTTPS included with Paperclip Cloud, private Tailscale Serve, a separate Funnel callback route, and Caddy on a custom domain. The guide includes Paperclip's authenticated deployment settings, canonical and webhook origins, certificate requirements, and verification. Add it to Deployment navigation and cross-link the existing overview and Tailscale private-access pages. Validation: production docs build, full docs test suite, internal-link lint, and diff checks. Examples checked against Paperclip configuration and official Tailscale/Caddy documentation. No runtime or deployment configuration changes. |
||
|
|
39633c2217 |
docs: connectors catalog, operator-first third revision (#124)
Connector catalog, setup guides, and shared access documentation, followed by a final code-accuracy repair pass. This PR does not change application behavior. ## Final accuracy pass Checked against shipped Paperclip `v2026.916.0`, commit `dffc2b3ca1b9e88fa21cb17493083e682dffd1ca`, rather than the dirty local checkout or the earlier canary baseline. - Corrects connector/method-specific identity choices, human audiences, and managed GitHub versus PAT scope and verification. - Explains that **Always allow** covers different arguments for the same agent/action/connection, with project scope when present; uses actual button labels and removes the test-panel control from review instructions. - Qualifies new-action quarantine, including safe-default read exceptions. Removes unconditional approval guarantees. - Separates provider channel/repository reach from Paperclip sender authorization. - Completes sandbox sign-in and model credential-selection instructions from the current UI implementation. - Repairs Notion's hub summary, removes incomplete optional Notion/Sentry client-registration procedures, and corrects Linear's provider-versus-Paperclip attribution. - Removes unsupported Postman tier claims, contradictory Cloudinary/Mem0 verification assertions, API-equivalence claims, and overbroad successful-test assurances. - Retains Supabase's required project reference: both released method definitions explicitly require it. An earlier review suggested otherwise; release code is authoritative here. - Updates the release baseline and removes draft commit chronology from the public introduction. ## Availability and remaining runtime gates - **Google:** Verification is pending. Per the product-owner clarification, authorization can continue where Google offers an Advanced option; this is not available for every account and does not override Workspace policy or other Google prerequisites. Notices on the hub and all Google guides now distinguish an unverified-app warning from blocked authorization. - **Slack is available but not yet fully functional; follow-up fixes are planned.** For agent tools, the released OAuth endpoint/scope defaults differ from Slack's documented MCP contract. The page now warns against treating that route as production-ready and removes the misleading bot-scope walkthrough. Chat-channel bot setup remains separate. Engineering must reconcile the integration and run OAuth plus one read before removing this warning. Source: https://docs.slack.dev/ai/slack-mcp-server/ - No credentialed connector run was performed in this pass. Code consistency, provider documentation, UI rendering, and successful live execution are separate evidence levels. No claim of runtime certification for all connectors. ## Validation - Root build: 253 crawlable documentation pages. - Full `docs:test`: all eight suites passed locally, including root/subpath routes, sitemap history, fingerprints, navigation, skill source blocks, crawlable links, doc-link resolution, and SEO metadata. - Internal-link lint: 258 Markdown files; no broken internal links. - Latest cleanup: full build, all eight docs:test suites, internal-link lint and diff whitespace checks passed; 1,878 link-resolution checks. - Fixed the Calendar MCP reference URL; browser-checked the five inconclusive external destinations (Miro article loads; Asana, Google Cloud, OpenAI and xAI reach sign-in/console screens). Authenticated destinations were not tested beyond those screens. - Replaced the Sandbox providers editorial TODO with a scope note and removed the CLI overview's unfinished-guide announcement. - Browser client navigation: 687 checks passed using installed Chrome. Initial launch lacked the downloaded Playwright browser; rerun used `DOCS_CHROMIUM_PATH` without changing the tests. - Nine representative connector/shared pages at 1440px and 390px: HTTP 200, one article H1, no page-level horizontal overflow. Mobile screenshot inspected; approval page opened in the Codex browser. - Navigation audit reports three existing non-connector orphan files; this patch does not alter those files or their navigation. The previous revision's provider-page expansion, Google shared setup guide, navigation additions, and accidental node_modules-symlink cleanup remain in this PR. Internal review ledgers remain outside the publication branch. No merge or production deployment authorized. --------- Co-authored-by: DevRel Gemini <[email protected]> Co-authored-by: Paperclip <[email protected]> Co-authored-by: Claude Opus 5 (1M context) <[email protected]> Co-authored-by: Michael Nguyen <[email protected]> |
||
|
|
ebbab07ca3 |
docs: correct decisions triage UI guidance (#100)
## Summary - describe the **When to decide** row as the primary triage path - keep the Decisions API as an additional path ## Verification - `npm run sync:lint-links` - `git diff --check` Co-authored-by: Dev Agent <[email protected]> Co-authored-by: Paperclip <[email protected]> |
||
|
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]> |
||
|
|
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]> |
||
|
|
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]> |
||
|
|
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]> |
||
|
|
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. |
||
|
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]> |
||
|
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]> |