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]>
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]>
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]>
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]>
- 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]>
## 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]>
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]>
## 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.
## 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]>
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]>
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]>
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]>
Keep PR #29's reviewed Novita AI section (header, `provider: "novita"`
convention, install/secrets framing, timeout min-validation) and extend it
with the fuller field reference from the release draft: install-by-package-name
steps plus a complete configSchema table covering every field — including
`secure` and the explicit defaults (timeoutMs 300000, requestTimeoutMs 30000)
that the prose-only version omitted.
All fields/defaults/validations verified against parent v2026.618.0
(packages/plugins/sandbox-providers/novita/src/{manifest,plugin}.ts):
defaults 300_000 / 30_000, validations >= 10_000 / >= 1_000, API key required.
verify-edit: 6/6 claims verified. docs:build + lint-links clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Two follow-ups to the server/src env-var scan widening:
1. verify-edit.mjs had its own copy of shouldFetchEnvSource with the same
narrow server allowlist — apply the identical server/src/**/*.ts widening
so the verify phase stops emitting unverified env-var false positives.
2. Both scripts now also scan all non-test packages/adapters/<name>/src/**/*.ts.
Adapter packages read env vars directly in their server/index modules —
e.g. SANDBOX_INSTALL_COMMAND (packages/adapters/{pi,claude,gemini,cursor}-local/src/...)
and per-runtime API-key fallbacks — which the old allowlist never fetched.
Verified against parent v2026.618.0:
- check-drift: 0 drift (65 env vars checked).
- verify-edit docs/reference/adapters/sandbox-providers.md: 6/6 claims verified
(SANDBOX_INSTALL_COMMAND, previously unverified, now resolves).
- sync:test 33/33.
Selection grows to ~452 files, still well under the 700 cap.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
The env-var drift checker only fetched a narrow allowlist of server files
(config.ts, a few auth/service files), so env vars read elsewhere in
server/src showed up as env-var-missing false positives every run.
Verified against parent v2026.618.0 that the 5 recurring false positives are
real, read env vars the old scan never looked at:
- TRUST_PROXY server/src/app.ts:167 (parseTrustProxyEnv(process.env.TRUST_PROXY))
- OTEL_EXPORTER_OTLP_ENDPOINT server/src/instrumentation.ts:29
- OTEL_EXPORTER_OTLP_PROTOCOL server/src/instrumentation.ts:69
- OTEL_SERVICE_NAME server/src/instrumentation.ts:144
- OTEL_SERVICE_VERSION server/src/instrumentation.ts:145
Fix: replace the three narrow server/src rules in shouldFetchEnvSource with a
single rule covering every non-test server/src/**/*.ts file (tests already
excluded above). Selection grows 130 → 326 files, well under the 700 cap.
Result: check-drift against both v2026.618.0 and master now reports 0 drift
(was 5 env-var-missing), with identical coverage (65 env vars, 235 routes,
57 CLI commands, 7 paths). sync:test 33/33 pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
The "Bundled with the Paperclip server (skills/)" list claimed three skills
that are NOT server-bundled — they live under .agents/skills/ (repo-development
skills) at v2026.618.0 and also at v2026.609.0, so this is pre-existing drift.
Verified against parent v2026.618.0:
- server-bundled skills/ contains exactly 6 dirs (all force-imported + required
by ensureBundledSkills): paperclip, paperclip-board, paperclip-create-agent,
paperclip-dev, paperclip-converting-plans-to-tasks, para-memory-files.
- paperclip-create-plugin, diagnose-why-work-stopped, terminal-bench-loop are
under .agents/skills/, not skills/.
Fixes:
- Remove the 3 non-bundled skills from the bundled list (now matches skills/ 1:1).
- Drop the brittle "five paperclip-*" count (it also wrongly excluded the bundled
para-memory-files); phrase count-free.
- Repair the paperclip-create-plugin link: parent has no `main` branch and the
skill moved, so blob/main/skills/... (404) -> blob/master/.agents/skills/...
verify-edit: 7/7 claims verified. sync:check clean (no broken internal links).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Cumulative window v2026.609.0 → 1b89a8e. The only commit added since the
last run (412a04c → 1b89a8e) is a Dockerfile fix removing VOLUME
["/paperclip"] for Railway compatibility — untracked by any watcher and
with no doc impact (the fly.toml volume still mounts at /paperclip).
Drift: 5 records (TRUST_PROXY, OTEL_*) all false positives — real server
env vars the drift checker can't see because it doesn't scan server/src
process.env reads. Confirmed present upstream; documented in the prior run.
No edits applied. Refreshed PENDING.md / SCREENSHOTS_PENDING.md headers
and bumped last_seen_parent_sha + last_run_outcome=no-changes.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- The per-project Workspaces tab is hidden until the project has workspace
activity (showWorkspacesTab requires summaries > 0); say so instead of
'shows up on each project', and drop the never-shown per-project empty
string. The reliable empty state is the company-wide 'No workspace
activity yet.'
- Correct the surfacing rule: a primary workspace surfaces because it's the
primary (not 'has a working directory and runtime config'); non-primary
project workspaces need runtime services/config.
- Replace the stale 'Each entry shows' list (old table columns: mode /
provider type / opened) with the actual ProjectWorkspaceSummaryCard fields
(kind, name, branch, path, services, status, linked tasks, updated).
- Note plugin tabs appear alongside the base tabs (e.g. workspace-diff's
Changes tab), not strictly after them.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
A user reported the Workspaces screen looked empty with "no options," and
that all but one of the workspace screenshots were blank/identical.
Both were real problems:
Docs (docs/guides/projects-workflow/workspaces.md)
- Add a "Before you start" section: workspaces are gated behind the
experimental "Enable Isolated Workspaces" flag, the screen is monitor-only
(no manual create), and it stays empty until an agent runs an isolated
task — with the actual empty-state strings ("No workspace activity yet." /
"No non-default workspace activity yet.").
- Correct the detail screen: it now has Tasks / Services / Configuration /
Runtime logs / Routines tabs (+ plugin tabs), not "three tabs." Rename the
Issues tab to Tasks (its real label) and add a Services tab section. The
former "Workspace commands panel above the tabs" is now the Services tab
plus header quick controls.
- Clarify the company-wide Workspaces screen vs. the per-project Workspaces
tab and the surfacing rules. Fix the misleading "multiple isolated
workspaces" caption.
Screenshots
- Root cause: the seed only created a *project* workspace and pointed the
execution-workspace detail routes at its id, so those pages were captured
mid "Loading workspace…". Execution workspaces have no REST create endpoint
(they're provisioned by a real heartbeat), so seed-execution-workspace.mjs
now inserts a realistic one directly into the instance's embedded Postgres:
an isolated git-worktree workspace with runtime config, a running service,
provision/start/failed-job operation logs, and linked tasks.
- routes.mjs: add the {executionWorkspaceId} token, repoint the detail routes
to it, add a Services tab target, and drop the duplicate
org/execution-workspaces-list target (same URL as workspaces/list).
- Recaptured workspaces/{list,configuration,services,runtime-logs,issues} in
light + dark; all now render real content.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
main shipped v2026.609.0 (PR #25). Advance nightly's cumulative-diff base
to v2026.609.0, switch branch_mode back to nightly, clear the applied
manifest hash, and reset PENDING.md so the next nightly run starts from a
clean v2026.609.0 baseline.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Publish accumulated nightly drafts to main and document the new surfaces
shipped between v2026.529.0 and v2026.609.0 (130 parent commits).
New pages (gaps not covered by nightly drafts):
- docs/reference/cli/token.md — `token agent` / `token board` API-key commands
- docs/reference/cli/connect.md — interactive `connect` setup wizard
- docs/reference/api/teams-catalog.md — teams catalog REST API
Also:
- Stamp paperclip_version: v2026.609.0 on 49 release doc pages
- Register the 3 new pages in site/content.json nav
- Bump .sync-state.json base_release_tag to v2026.609.0
Verification: 49 pages checked against v2026.609.0; 11 verifier flags,
all confirmed false-positives (flagged flags/env-vars exist in parent).
Drift: 0. Reconciliation: 0.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
- docker.md / gemini-local.md: Gemini CLI now bundled in the official
image (GEMINI_SANDBOX=false); backfill opencode_local in bundled list
(paperclip #7693)
- external-adapters.md: external adapters can override built-in types;
document override + fallback lifecycle, correct stale 'cannot be
overwritten' note (paperclip #7394)
- regenerate PENDING.md / SCREENSHOTS_PENDING.md (18 settings/adapter
screenshots stale after instance-settings IA move, paperclip #7680)
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
`company current` exists in the CLI source
(cli/src/commands/client/company.ts) but was missing from the company
reference page. Add it to the Read Commands code block and table with a
note on how it resolves the scoped company (--company-id, context,
PAPERCLIP_COMPANY_ID, or agent credential) and that it returns the same
full record as `company get <companyId>`.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Three settled surfaces aged past the 24h quarantine since the last run:
- Teams Catalog (#7550): new `teams` CLI page + Team Catalog guide for the
installable bundled/optional starter teams.
- Company Artifacts (#7621): new Artifacts guide + `GET /api/companies/{id}/artifacts`
API section under Companies.
- Low-trust review containment / trust presets (#7530): new Administration page
covering the `standard` / `low_trust_review` presets and quarantine-then-promote
review flow.
Nav merged in site/content.json. PENDING.md and SCREENSHOTS_PENDING.md regenerated
(40 screenshots stale in the settled window). Phase 5.5 verification clean; drift clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
