Add inline comments to Docs

[brsbl]

Human comments

What was wrong

Docs had no way to discuss selected text without changing the Markdown document or moving feedback into chat.

What changed

• Add inline comment threads (select text, then Comment or ⌘⌥M), with replies, resolve/reopen, and edit/delete of your own messages. Threads whose text is gone show "Text not found"; there is no Reattach in v1.
• Store comments in a hidden <doc dir>/.bb-comments/<file>.json sidecar, anchored by quote plus surrounding context. Every write uses compare-and-swap with up to 3 re-applies before returning conflict. The Markdown is never touched, and rename, move and delete through Docs carry the sidecar along.
• Add bb docs comments list/add/reply/resolve and RPC methods that share one service. HTTP exposes only /comments/list and /comments/folder. Authors are set on the server: the Docs UI posts as the user, and the CLI posts as the invoking thread (BB_THREAD_ID). No input field sets an author, and edit/delete is UI-only. @mentioning a thread sends it the comment with a Docs context block, and "New thread" spawns one.
• Known limit: bb plugin RPC can't tell the Docs UI from an agent calling bb plugin rpc call, so an agent that goes around the CLI can still post as the user. Closing that needs a core caller identity, which is tracked separately.
• Comments belong to a document only while Docs knows its identity. Each comments file records the document hash Docs last saw, and Docs re-saves it only for changes it vouches for: Docs saves, comment writes, bb docs write, push, proposal accept, and Docs moves. After an outside change, such as a direct file edit, a replaced file, or a reused path, the document shows a Keep on this document / Leave banner instead of highlights. The same choice is available as bb docs comments keep|leave.
• Never delete: deletes through Docs, bb docs remove, folder deletes, and push --delete move comments to <vault>/.bb-comments/orphaned/. These, plus comments stranded by external moves, appear in a read-only N without a document list with View, Copy text, and a confirmed Delete (comments list --folder, read-file, delete-file --yes). There is no cross-document attach or merge in v1.
• Folder deletes move each .bb-comments directory to the orphan area whole, and are refused if the subfolder listing is truncated. Docs creating a document at a path with leftover comments orphans them first. The watcher, the inventory, and failed reads move comments of missing documents to the orphan area, so a later file at that path starts clean. One known limit, documented in the spec: identical bytes re-created outside Docs before any sweep keep the old comments.
• A comment re-anchors only when its quote plus context occur exactly once, with no fuzzy matching. Duplicates and edited text become "Text not found" with Reattach. External reloads clear highlights before they can be saved, and a refreshed anchor is accepted only if its quote is unchanged.
• Horizontal rules count as atomic blocks in the stored visible text, matching the editor, so anchors after --- or *** stay aligned.
• While a proposal is pending, highlights are re-anchored onto the draft by quote and context. Adding and reattaching comments wait until the proposal is accepted or rejected.
• Show the margin when the pane is wide enough, and fall back to the shared responsive drawer on phones and in panes narrower than 720px.
• Document the workflow in the Docs skill. Additive only: the simple-notes ID, existing files, vaults, settings and sync are unchanged, and older builds ignore the hidden folder.

How you verified

• Remote CI on the latest head. Regression coverage includes concurrent sidecar writes, malformed sidecars (read as empty, writes fail closed), anchor recovery after external edits, and sidecar moves and deletes alongside documents.
• Branch web app, isolated data dir: bb docs comments list, add --json, ambiguous_quote (lists occurrences, exit 1) and quote_not_found (exit 1), plus the UI flows below.
• Full Slop Cop and full e2e are reserved for the requesting lead. Do not merge.

Screenshots (2×, branch web app)

	Before	After
Desktop
Desktop, wide pane	—
390px
390px, thread	—
Desktop, outside change and without a document	—
390px, outside change	—
390px, without a document	—

BB-Thread-ID: thr_dxfjrhdzmm

🤖 Generated with Claude Code

AGENT GENERATED