[codex] Add document annotations and comments (#6733)

## Thinking Path

> - Paperclip orchestrates AI-agent companies through issues, documents,
runs, and durable company-scoped state.
> - Issue documents are where agents and operators capture plans,
handoffs, and work products.
> - Before this change, document collaboration could only happen through
whole-document edits and detached issue comments.
> - Inline document annotations need stable anchors, revision-aware
persistence, and UI affordances that do not break existing document
editing.
> - This pull request adds company-scoped document annotation threads,
comments, anchor snapshots, API routes, and board UI.
> - The benefit is that operators and agents can discuss specific
document passages without losing context as documents evolve.

## What Changed

- Added document annotation tables, schema exports, shared types,
validators, anchor hashing, and text-anchor helpers.
- Added server-side document annotation services and issue routes for
listing, creating, commenting, resolving, and reopening annotation
threads.
- Included annotation summaries in relevant issue document reads and
backup/recovery document workspace behavior.
- Added React UI for inline document highlights, comment panels, mobile
sheet behavior, deep-link focus, and resolved/open filtering.
- Added annotation design artifacts, Storybook coverage, screenshots,
and a screenshot helper script.
- Rebased the branch onto current `paperclipai/paperclip` `master` and
renumbered the annotation migration from `0085_old_swarm` to
`0091_old_swarm`; the SQL uses `IF NOT EXISTS` guards so environments
that previously applied the old migration number can safely apply the
new one.
- Adjusted the new annotation UI tests to use a local async flush helper
because this workspace's React 19.2.4 export does not expose
`React.act`.

## Verification

- `pnpm run preflight:workspace-links && pnpm exec vitest run
packages/shared/src/document-anchors.test.ts
server/src/__tests__/document-annotation-routes.test.ts
server/src/__tests__/document-annotations-service.test.ts
ui/src/components/DocumentAnnotationLayer.test.tsx
ui/src/components/IssueDocumentAnnotations.test.tsx
ui/src/lib/document-annotation-hash.test.ts
ui/src/lib/document-annotation-selection.test.ts`
- Confirmed `git diff --check` passes.
- Confirmed no `pnpm-lock.yaml` or `.github/workflows/*` files are
included in the PR diff.

## Risks

- Medium risk: this adds new persisted annotation tables and routes
across db/shared/server/ui.
- Migration risk is reduced by moving the branch migration to
`0091_old_swarm` after upstream `0090_resource_memberships` and keeping
the SQL idempotent for old `0085_old_swarm` adopters.
- UI risk is mostly around text range anchoring and panel positioning
across long documents, folded content, and mobile layouts; the PR
includes focused unit coverage and design screenshots.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- OpenAI Codex, GPT-5 coding agent, tool-using software engineering
mode. Context window size is not exposed in this Paperclip 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 run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

ui/src/lib/document-annotation-selection.test.ts

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import { describe, expect, it } from "vitest";
+import { verifyDocumentAnchorSelector } from "@paperclipai/shared";
+import {
+  buildAnchorFromContainerSelection,
+  getContainerTextOffset,
+  rangesForNormalizedSpan,
+} from "./document-annotation-selection";
+
+const MARKDOWN = `# Plan
+
+We **should** keep the current markdown stack for the first version.
+
+- Highlight a text segment in a plan document.
+- Anchor comments without mutating markdown.
+
+## Acceptance
+
+The annotation feature is ready when the basic flow works.`;
+
+const RENDERED_HTML = `
+<div>
+  <h1>Plan</h1>
+  <p>We should keep the current markdown stack for the first version.</p>
+  <ul>
+    <li>Highlight a text segment in a plan document.</li>
+    <li>Anchor comments without mutating markdown.</li>
+  </ul>
+  <h2>Acceptance</h2>
+  <p>The annotation feature is ready when the basic flow works.</p>
+</div>
+`;
+
+function makeContainer(): HTMLElement {
+  const div = document.createElement("div");
+  div.innerHTML = RENDERED_HTML;
+  document.body.appendChild(div);
+  return div.firstElementChild as HTMLElement;
+}
+
+function selectText(container: HTMLElement, needle: string): Range {
+  const walker = document.createTreeWalker(container, NodeFilter.SHOW_TEXT, null);
+  let node = walker.nextNode();
+  while (node) {
+    const data = (node as Text).data;
+    const index = data.indexOf(needle);
+    if (index !== -1) {
+      const range = document.createRange();
+      range.setStart(node, index);
+      range.setEnd(node, index + needle.length);
+      return range;
+    }
+    node = walker.nextNode();
+  }
+  throw new Error(`Could not find "${needle}" in container`);
+}
+
+describe("buildAnchorFromContainerSelection", () => {
+  it("produces a selector that verifies against the same markdown", () => {
+    const container = makeContainer();
+    const range = selectText(container, "current markdown stack");
+    const offset = getContainerTextOffset(container, range);
+    expect(offset).not.toBeNull();
+    const anchor = buildAnchorFromContainerSelection({
+      markdown: MARKDOWN,
+      containerOffset: offset!,
+    });
+    expect(anchor).not.toBeNull();
+    const verified = verifyDocumentAnchorSelector({
+      markdown: MARKDOWN,
+      selector: anchor!.selector,
+    });
+    expect(verified.ok).toBe(true);
+    expect(verified.anchor?.selectedText).toBe("current markdown stack");
+  });
+
+  it("returns null for empty selections", () => {
+    const container = makeContainer();
+    const range = document.createRange();
+    range.setStart(container, 0);
+    range.setEnd(container, 0);
+    const offset = getContainerTextOffset(container, range);
+    expect(offset).toBeNull();
+  });
+
+  it("returns null when selection is outside container", () => {
+    const container = makeContainer();
+    const outside = document.createElement("div");
+    outside.textContent = "outside";
+    document.body.appendChild(outside);
+    const range = document.createRange();
+    range.selectNodeContents(outside);
+    const offset = getContainerTextOffset(container, range);
+    expect(offset).toBeNull();
+  });
+});
+
+describe("rangesForNormalizedSpan", () => {
+  it("walks DOM text nodes to find span ranges", () => {
+    const container = makeContainer();
+    const ranges = rangesForNormalizedSpan({
+      container,
+      selectedText: "Highlight a text segment",
+    });
+    expect(ranges.length).toBeGreaterThan(0);
+    const merged = ranges.map((range) => range.toString()).join("");
+    expect(merged.replace(/\s+/g, " ")).toContain("Highlight a text segment");
+  });
+
+  it("returns an empty array if selected text is missing", () => {
+    const container = makeContainer();
+    const ranges = rangesForNormalizedSpan({
+      container,
+      selectedText: "this string does not exist in the document",
+    });
+    expect(ranges).toEqual([]);
+  });
+});