[iscekic]

Changelog for users

• The docs-sync bot opens one pull request per product surface — cli, vscode, jetbrains, gateway, web — plus one other, in place of the single rolling PR.
• Each surface PR is assigned and review-requested to two people chosen for that surface.
• Reviewers are ranked from recent commits that touch the surface's source paths; bots and people without write access are skipped.
• other keeps its fixed reviewer pair because it has no source paths to rank.
• A changed doc file lands in exactly one surface PR by longest matching prefix; a path matching no surface goes to other.
• Every kilo run now uses maximum reasoning effort by default, overridable through repository variables.
• The previous rolling PR is commented on and closed; its branch becomes the integration base.

Changelog for maintainers

• bun install prunes patches/ghostty-web@0.3.0.patch: no dependency is patched with it, so the orphan file is removed.
• The trustedDependencies and patchedDependencies order in bun.lock is the package manager's; bun install rewrites those lists.
• .github/docs-sync/surfaces.json is the surface map; surfaces.mjs assigns each doc path to exactly one surface by longest prefix match, with other last.
• reviewers.mjs ranks contributors by recency with a 180-day half-life, skips bots and users below write permission, and returns no reviewers plus a named reason on failure instead of throwing. The single DOCS_OWNER constant is gone.
• upsert-pr.mjs rebuilds each surface branch in a throwaway worktree, carries existing PR rows forward, and isolates per-surface failures so one surface cannot lose another's changes or stall the watermark.
• prepare-branch.mjs merges open surface branches into docs/auto-sync, then comments on and closes the legacy rolling PR; because a git ref cannot be a path prefix of another, the durable integration tree is pushed to docs/auto-sync-integration.
• The workflow defaults both models to kilo/deepseek/deepseek-v4.1-flash, sets DOCS_SYNC_VARIANT: "max", passes --variant on every kilo run, and runs the .github/docs-sync/*.test.mjs unit tests in the selftest job.
• Review first the ref handling in prepare-branch.mjs and upsert-pr.mjs, and the other fallback in surfaces.json. Selftest cases 12–16 cover segmentation, failure isolation, prepare-branch, update, and deletion; scope.test.mjs guards that the ghostty-web patch is orphaned without pinning a blob hash.

E2E proof

node .github/docs-sync/selftest.mjs against a fixture change set, with the GitHub API served by a local stub (no real pull request or review request is created):

case 12 — per-surface segmentation
  computed surface map (file -> surface):
  docs-sync surface map (4 changed files):
    vscode <- packages/kilo-docs/pages/code-with-ai/platforms/vscode/new.md
    other <- packages/kilo-docs/pages/community/new.md
    gateway <- packages/kilo-docs/pages/gateway/new.md
    cli <- packages/kilo-docs/pages/getting-started/new.md
  surface PRs it would open:
  docs/auto-sync/cli: "docs: auto-sync cli with merged PRs (through 2026-09-01)" assignees=alice,bob reviewers=alice,bob draft=false
  docs/auto-sync/vscode: "docs: auto-sync vscode with merged PRs (through 2026-09-01)" assignees=erin,frank reviewers=erin,frank draft=false
  docs/auto-sync/gateway: "docs: auto-sync gateway with merged PRs (through 2026-09-01)" assignees=carol,dave reviewers=carol,dave draft=false
  docs/auto-sync/other: "docs: auto-sync other with merged PRs (through 2026-09-01)" assignees=lambertjosh,intentionally-left-nil reviewers=lambertjosh,intentionally-left-nil draft=false
  ok: case12_surfaceSegmentation

selftest: all cases passed

Owner request

Surface: the docs sync GitHub Action (.github/docs-sync/**), PR #14085.

An earlier round of this item asked you to restore patches/ghostty-web@0.3.0.patch and to revert the lockfile re-sorting. That instruction was wrong and it cost five rounds. The evidence: nothing in bun.lock references ghostty-web, so bun install prunes the orphan patch file and rewrites the trustedDependencies and patchedDependencies lists in its own order. The deletion is the package manager's work, not a hand edit. Do NOT try to restore either file, and do not pin a check to a blob hash that bun install regenerates.

Do this instead:

• Leave bun.lock and the deleted patch file exactly as bun install leaves them.
• In the PR body, state in two lines that bun install prunes patches/ghostty-web@0.3.0.patch because no dependency is patched with it, and that the lockfile list order is the package manager's.
• The PR is a draft because it recorded "No live proof applies". A GitHub Action is provable. Run the action's own dry run path, or the selftest against a fixture change set, and capture the output that shows the computed surface map, the two assignees chosen per surface, and the titles of the pull requests it would open. Put that output in the PR body as the proof. Open no real pull request and request review from no real person while proving it.
• Keep every docs-sync change already on the branch. Update PR 14085 in place; do not open a second PR.

[kilo-code-bot]

WARNING: A renamed doc file leaves the old path in the surface branch

changedFiles comes from git diff --name-only origin/main...HEAD, and with default rename detection that collapses a rename to only the destination path (I verified locally: a historical rename shows the new path only, while --no-renames shows both old and new). Because partitionByPresence only ever sees that collapsed list, the old path is classified neither present nor removed, so git rm never runs for it. The rebuilt surface branch therefore keeps the stale file that the integration tree deleted, and merging the PR leaves the old doc in place - the rename is only half-applied.

Consider building the changed-file set with --no-renames (or otherwise unioning the deleted/old-path side of renames) so renamed-away paths are still passed to git rm.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

WARNING: Legacy branch cleanup depends on an open legacy PR

The docs/auto-sync ref is deleted (and its stale remote-tracking ref cleared) only inside if (legacy) {. If the old rolling branch outlives its PR - for example the PR was closed or merged manually, the branch was left behind by an auto-delete-off setting, or the delete below failed on an earlier run - then legacy is null, no cleanup happens, and because a git ref may not be a path prefix of another ref, every push of docs/auto-sync/<surface> fails with a directory/file ref conflict. That silently disables all per-surface PRs on every subsequent run. Detecting and deleting the remote docs/auto-sync branch independently of an open legacy PR would make the migration idempotent.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

WARNING: A non-404 permission error discards reviewers already found

The permission lookup rethrows any error that is not a 404, and the outer catch at the end of computeSurfaceReviewers replaces the whole result with reviewers: []. So if the first ranked candidate already had write access and was pushed, but the next candidate's permission call fails (403, secondary rate limit, or a 5xx after the retries in lib.mjs), the accumulated reviewer is thrown away and the PR is created with no assignee and no requested reviewer. Returning the reviewers found so far (and naming the failure in note) would degrade more gracefully.

---

Reply with @kilocode-bot fix it to have Kilo Code address this issue.

[kilo-code-bot]

Code Review Summary

Status: 3 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	3
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
.github/docs-sync/upsert-pr.mjs	450	Renamed doc files leak the old path into the surface branch: git diff --name-only collapses renames to the destination, so partitionByPresence never removes the old path and the merge half-applies the rename.
.github/docs-sync/prepare-branch.mjs	183	Legacy docs/auto-sync branch cleanup only runs when an open legacy PR is found; if the branch outlives its PR, the ref namespace collision blocks every docs/auto-sync/<surface> push.
.github/docs-sync/reviewers.mjs	124	A non-404 permission error on a later candidate makes the outer catch return reviewers: [], discarding reviewers already selected and leaving the PR with no assignee/reviewer.

Files Reviewed (15 files)

• .github/docs-sync/edit.mjs
• .github/docs-sync/learn.mjs
• .github/docs-sync/lib.mjs
• .github/docs-sync/model-config.test.mjs
• .github/docs-sync/prepare-branch.mjs
• .github/docs-sync/reviewers.mjs
• .github/docs-sync/scope.test.mjs
• .github/docs-sync/selftest.mjs
• .github/docs-sync/surfaces.json
• .github/docs-sync/surfaces.mjs
• .github/docs-sync/surfaces.test.mjs
• .github/docs-sync/triage.mjs
• .github/docs-sync/upsert-pr.mjs
• .github/workflows/docs-sync.yml
• bun.lock

Fix these issues in Kilo Cloud

---

_{Reviewed by deepseek-v4.1-flash · Input: 0 · Output: 0 · Cached: 0}

_{Review guidance: REVIEW.md from base branch kwf/docs-sync-surface-prs-34e3}

[iscekic]

Superseded by #14093, which now targets main directly.

This branch was an independent re-implementation of the same docs-sync change, not an increment on #14085, so GitHub read it as CONFLICTING against its own base. Four merge-conflict fix attempts were spent on it (the cap) without resolving it, and the stack above it could not move.

#14093 is a single branch off main that carries the whole feature — the surface map, per-surface PRs, the reviewer ranking, the model config, the lockfile change and the orphan patch removal — plus this branch's scope.test.mjs and the new cloud product surfaces. It merges into main with no conflict.