Syncs docs to parent release **v2026.831.1** (cumulative from
`v2026.824.1`, via merge-base `664052f`). Authored fresh against the
release tag; every claim verified at the tag.
## What changed
**New**
- **Kimi Code adapter** (`kimi_local`) — new reference page, wired into
the adapters overview, nav, and anchor-map source mapping.
**Reference**
- **Env vars** — `PAPERCLIP_WORKSPACE_REAPER_COOLDOWN_DAYS`, opt-in
`SENTRY_DSN`, and the operator controls `PAPERCLIP_HIDDEN_SETTINGS` /
`PAPERCLIP_SETTING_DEFAULTS`.
- **Instance Settings** — new "operator controls for hosted deployments"
section (hide surfaces / override defaults).
- **Node.js floor → 24.11.0** across installation, setup,
local-development, plugin dev, Modal, and the getting-started/terminal
guides.
- **Grok adapter** — `permissionMode` no longer defaults to `dontAsk`;
when unset no flag is passed, and `--always-approve` is the unattended
policy.
- **CLI `agent`** — Kimi skills install path (`~/.kimi-code/skills`) +
`KIMI_CODE_HOME`.
**Guides**
- **Onboarding** — rebuilt around a single-card wizard that opens on
creating your agent; the mission step is gone, the goal is set
afterward.
- **Settings unification** — Invites folded into a Members tab, one
shared settings nav, and the company brand color + per-company
attachment size limit removed (also reflected in the Companies and Cases
APIs).
- **Governance behavior** — silent-run detection and stranded-task
recovery no longer act on their own; agent thought text is excluded from
automatic comments; invalid agent credentials now return `401`.
**Changelog** — entry added for v2026.831.1.
## Gates
- `docs:build`, SEO metadata, crawlable-links, sitemap-lastmod
(194/194), lint-links, verify-nav — all pass.
- **Edit verification:** every new high-confidence claim verified at the
tag.
- **Tag-accuracy gate:** 31 files checked, **0 post-tag leaks**, 30
clean, 1 review (below).
## ⚠ Drift (Verify before acting — not auto-resolved)
Medium-confidence REST-route drift in `docs/reference/api/companies.md`
— the import-transfer routes may no longer exist at these paths (likely
a false negative from prefix/dynamic registration; confirm before
editing):
- `POST /api/companies/import/transfers`
- `PUT /api/companies/import/transfers/{transferId}/parts/{partIndex}`
- `GET /api/companies/import/transfers/{transferId}`
- `POST /api/companies/import/transfers/{transferId}/preview`
- `POST /api/companies/import/transfers/{transferId}/apply`
## ⚠ Review
- `docs/reference/adapters/kimi-local.md` — new page; the only flagged
claim is the `secret-id` JSON **example placeholder** (not a real
identifier). Authored directly from the adapter's config surface at the
tag.
## Screenshots (deferred)
288 of 342 registered screenshots are stale (org-wide rename +
settings/onboarding rewrites), tracked in `SCREENSHOTS_PENDING.md`.
Recapture is a follow-up pass — **the merged pages describe the new
onboarding/settings UI while screenshots still show the old flow until
then.**
---------
Co-authored-by: Claude Opus 4.8 <[email protected]>
Makes /sync-docs correct under the canary→nightly→beta→stable channel model. Adds the release-mode tag-accuracy gate (scripts/sync/check-tag-accuracy.mjs) that verifies every changed page against the stable tag and flags post-tag leaks; stable-CalVer guard + channel glossary, tag-scoped drift/verify, and Phase 5.7 in the skill; realign fix that keeps nightly's drafts; a release-channels watcher; the analysis/plan doc; and a hermetic test (sync:test 38/38).
Co-Authored-By: Claude Opus 4.8 <[email protected]>
Ships the v2026.817.0 docs to live: the doc content that was authored
and verified
earlier, plus a full screenshot overhaul.
The content half (`cdf81e2` and the nightly commits behind it) has
already been
reviewed. **The screenshots are the part that needs eyes** — `f24d734`,
342 PNGs.
## Screenshots
Everything was recaptured against the release commit
`213dabab4f8e1f3bb1803a2924c0fea1289fcd4c`
(`upstream/candidate/release-2026.817.0`). The previous shots were 375
parent-commits stale (v2026.720.0), with 228 of 310 entries flagged
pending. All
342 registry entries now carry that SHA.
> ⚠️ Worth knowing: the release commit is **not** an ancestor of the
parent's
> `master`, and local `master` was four days *older* than it. Capturing
against
> `master` would have both missed release UI and leaked 93 post-tag
commits' worth
> of UI into the release docs.
### New coverage (34 entries)
Three guides shipped with **no images at all** despite being 115–136
lines. They
now have them:
| Guide | Shots |
|---|---|
| `guides/day-to-day/decisions.md` | queue, an agent-proposed decision
with its options, triage strip, filter panel, named queue, Decided
curtain, empty state |
| `experimental/status-cards.md` | board, New card dialog, and all four
drawer tabs |
| `experimental/task-chat.md` | thread, composer mode picker, side pane
|
| `reference/api/secrets.md` | the board-side Proposals tab |
Chat-Style Tasks is captured in a **separate pass**:
`enableTaskChatRedesign` is
instance-wide, so leaving it on would have turned every classic
issue/task/work-mode
shot into the redesigned chat.
## Two defects that were already live
Both were shipping in the docs before this PR:
1. **`issues/detail-chat.png` and the `tasks/*` shots were mostly plugin
debug
output.** The Kitchen Sink example plugin mounts a panel into the issue
page
that dumps the raw issue JSON, and the seed installed it. Those guides
were
illustrating a debug panel instead of the task page. The seed no longer
installs it.
2. **The seeded task thread was a monologue** — four board-user messages
in a row,
because the board actor cannot post agent comments. It is now a real
two-sided
exchange.
## Targets repointed because the UI moved
| Target | Why |
|---|---|
| `activity/*` | `Activity.tsx` deleted; `/activity` renders
`pages/audit/CompanyActivity.tsx` |
| `experimental/cloud-upstream` | `CloudUpstream.tsx` deleted; the route
now redirects to `/company/export` |
| `settings/*`, `plugins/*`, `adapters/*` | `/instance/settings/*` are
legacy redirects now |
| `dashboard/stale-tasks-panel` | panel removed from `Dashboard.tsx` —
target dropped |
Plus eight targets with **silent selector drift**. A failed interaction
step falls
back to "whatever state was reached", so these had been quietly
producing wrong
images — a plain inbox where the doc promised a mode picker, a whole
dashboard
where it promised one panel. Full table in
`docs/user-guides/screenshots/SCREENSHOTS_PLAN_v2026.817.0.md` §C2.
## Pipeline
Decisions, status-card summaries and secret proposals are all
**agent-authored**,
and the board actor the seed runs as is refused by every one of them
(`"Agent run context required"`, `"Secret proposals require a verified
run-bound
agent token"`). Rather than insert rows behind the API,
`seed-new-surfaces.mjs`
borrows the two doors a real run already has — a board-minted agent API
key, and a
locally signed agent JWT — so every write goes through the production
code path.
Also:
- `capture.mjs` records a real `captured_against` on a detached checkout
instead of
the literal string `"HEAD"` (which is what every pre-2026.817 entry
recorded), and
gains a `scrollTo` step for content below the fold.
- `run.mjs` gains `--serve` for iterating on the seed, the task-chat
phase, and a
keeper that holds the demo board's issue statuses steady — the demo
`process`
agents finish runs without declaring a disposition, so the stalled-work
sweep
re-blocks issues every few minutes over a capture that runs far longer.
## Reviewing
Light and dark both captured at 1440×900 @2x. The new surfaces are the
ones to
scrutinise; the rest is a like-for-like refresh.
### One leftover
Dropping `dashboard/stale-tasks-panel` leaves
`{light,dark}/dashboard/stale-tasks-panel.png`
tracked but unused — they need deleting by hand.
🤖 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]>
Co-authored-by: Dotta <[email protected]>
Co-authored-by: ClaudeCoder <[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]>
Closes the gap this run surfaced: packages/skills-catalog/** was unwatched, so
new bundled catalog skills (e.g. the wireframe product skill) weren't auto-detected.
Watches catalog/**/SKILL.md + generated/catalog.json, routes to docs/reference/skills.md
and docs/guides/org/skills.md (PR tier), distinct from the agent-skills watcher which
covers the server-forced bundled skills under skills/**.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Closes the design loop for the three helpers shipped in the
preceding commits and addresses the batched-exhaustiveness gap.
SKILL.md (+43 net):
- Phase 3: new substep runs detect-renames.mjs and routes detected
renames to the EXISTING doc page with change_kind: renamed (not a
new page). removed_dirs_no_match surfaces as a Reconcile-style
flag. added_dirs_genuinely_new flow through unchanged.
- Phase 5: new bold paragraph stating --batched mode is exhaustive
per window — no subsampling. Wet-run subsampling was scope-control
for testing, not skill design. Also: paperclip_version frontmatter
is now live (builder strips and surfaces it); added a new final
voice-rule bullet requiring concrete identifiers (flags, env vars,
routes, field names) be copied verbatim from parent code.
- New Phase 5.5: run verify-edit.mjs on every touched file. Auto-merge
edits roll back on any high-confidence unverified claim. PR-tier
edits get a Verification Failed callout; batched-release PRs never
auto-merge when any verification fails. Suspicious claims log but
never block.
- Phase 7 PR body template: three structured sections — Drift,
Verification Failures, Renames detected. Each omitted if empty,
never silently dropped.
- Helper-script index added near top.
anchor-map.json:
- adapters watcher detect rewritten to reference detect-renames.mjs
as the canonical rename check (no more inline heuristic prose).
- agent-skills, plugin-sdk, server-adapters: parenthetical pointers
added to detect-renames where renames apply.
- Other watchers unchanged (rename signal doesn't cleanly apply).
Follow-ups flagged but not done in this commit:
- Special-cases "Renames on parent" still describes the manual
fix-anchor-map workflow; would benefit from a one-line distinction
between watcher-path renames (manual) vs single-dir renames within
a watcher (automatic).
- file-path drift kind and verify-edit's file-path kind overlap —
worth deduping a future pass so one missing file doesn't appear
under both Drift and Verification Failures.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Two same-class glob bugs caught by the latest dry-run validation:
1. adapters watcher: parent_paths used `packages/adapters/*` and
`packages/plugins/sandbox-providers/*` — single-segment globs.
Real adapter files live deeper (packages/adapters/<name>/src/...).
Result: 123 adapter files in the 318→512 diff window, ZERO
watcher hits. The cursor-cloud doc only got written in the prior
wet run because reviewers eyeballed it. Fix: `**` recursive globs.
Hit count: 0 → 181.
2. agent-skills watcher: parent_paths used `skills/paperclip/**`,
expecting a literal `paperclip/` segment. Real skill bundles are
named `skills/paperclip-create-agent/`, `skills/diagnose-why-...`,
etc. The `skills/**/SKILL.md` fallback caught 11 files but missed
reference/script/fixture files in bundles.
Hit count: 11 → 19 (the 19 is all skills/ files in this window).
Detect rules updated to match the broader globs.
A similar trap exists in the schemas glob (`packages/**/schema/*.ts`
misses nested schema dirs). Deferred — current hit count (37) is
healthy for the typical flat-schema case.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
The wet-run found the plugin-sdk watcher's docs_paths
(docs/reference/skills.md, docs/how-to/write-a-company-skill.md)
target agent skill bundles, not the plugin SDK. Separate concerns.
- plugin-sdk now targets docs/reference/plugins/sdk.md (to be created
by the skill on first hit) and docs/administration/plugins.md.
- New agent-skills watcher targets the skills/ surface in parent and
routes to docs/reference/skills.md + docs/how-to/write-a-company-skill.md.
Watcher count: 11 → 12.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
A design-validation dry-run against the real 318→512 release gap
surfaced seven issues that would break or misbehave at runtime.
All addressed:
1. Parent default branch is `master`, not `main` (verified via
gh api ... -q .default_branch). Resolved dynamically at runtime:
new Preconditions step 5 calls the API once and stores the result
as <parent-default>; all subsequent references use that variable.
Resilient to future parent renames.
2. Two dead globs in anchor-map.json:
- env-vars: `server/src/env.ts` → replaced with `server/src/config.ts`
- schemas: dropped `server/src/db/schema/**` (dir doesn't exist;
coverage already provided by `packages/**/schema/*.ts`).
3. Truncation fallback was insufficient. The 318→512 gap had 5 of 6
tag-to-tag windows still hitting the 300-file cap. Rewrote Phase 2
to use recursive midpoint bisection by commit SHA: detect via
files.length==300 OR total_commits>commits.length, split at median
SHA, recurse until every leaf is within caps. Also corrected the
commits cap (250, not ~300) and added explicit status-merge rules
for unioning leaf file lists (added+removed → drop, etc.).
4. Adapter watcher would over-trigger on renames within the *-local
family. Extended detect rule to check for correlated add/remove
of similarly-named dirs (rename heuristic) before assuming a new
adapter — uses compare's status:'renamed' signal.
5. Four new watchers for previously unwatched busy surfaces:
- web-ui (ui/src/**) — invalidates screenshots and end-user flows
- server-services (server/src/services/**) — user-visible behaviour
- server-adapters (server/src/adapters/**) — distinct from packages/
- db-migrations (packages/db/migrations/**) — context-only
6. auto_merge_safety.max_lines_changed 20→50. The current gap shows
real-world .env.example additions land in batches (a feature ships
with 10–20 related env vars + comments) and were being needlessly
demoted to PR tier.
7. New Preconditions step 6: preflight every concrete (non-glob)
watcher path via gh api .../contents and warn on 404. Would have
caught the server/src/env.ts dead glob immediately.
Watcher count: 7 → 11.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Several issues found while reviewing the skill — most stemming from
the incremental-diff model that the first cut used. The fix is a
shift to cumulative diffs (always from the last release tag) plus
explicit reconciliation handling.
Changes:
- Cumulative diff window for BOTH modes. Nightly was using
yesterday's SHA as the diff base; now it uses base_release_tag
like release mode does. This makes reverts auto-cancel in the
manifest (they're net-zero across the cumulative window) instead
of needing message-regex filtering.
- Remove skip_patterns from anchor-map.json. They were dangerous:
filtering ^revert by message would HIDE the undo signal when a
previously-processed commit got reverted. The proper filter is
surface impact via watcher path globs + cumulative-diff cancellation.
- Add Phase 3.5 (Reconciliation) to the SKILL. Catches the remaining
case: a doc edit was committed in a prior run for a feature that
has since been reverted. The manifest_hash + last_applied_manifest_hash
comparison surfaces "disappeared" entries as ⚠ Reconcile flags for
manual review — the skill never auto-undoes prose edits.
- auto_merge_safety: add explicit forbid_kinds: [removed, renamed].
A 1-line rename is still a breaking change and was previously
guarded only by SKILL prose.
- Rename state fields for clarity. synced_to/synced_sha were
ambiguous between branches. New schema: branch_mode,
base_release_tag, base_release_sha, last_seen_parent_sha,
last_applied_manifest_hash. base_release_tag is the diff base
and only bumps on a successful release merge — the invariant
that makes cumulative diffs stable.
- Release mode is now self-sufficient (doesn't require nightly
drafts to exist). Fixes the chicken-and-egg for the first run
catching up multiple releases.
- PENDING.md is regenerated each run, not appended, so it never
carries stale entries from reverted commits.
- New special-cases entries for parent renames, nightly-with-open-PRs
at release time, and quarantine race conditions.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
Scaffolds the data layer for the /sync-docs skill:
- scripts/sync/anchor-map.json — declares which parent-repo paths each
watcher tracks, where they route in our docs, and whether changes
are auto-merge (mechanical, schema-bound) or PR tier (judgment calls).
- scripts/sync/state.example.json — template for .sync-state.json.
- .sync-state.json — per-branch sync state, seeded for an initial
release-mode run from v2026.318.0.
- docs/user-guides/screenshots/registry.json — screenshot dependency
tracking so the skill can flag stale captures.
The skill itself follows in the next commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
