Story-2168: The Document Page v2 — Original · Insights, live

Every uploaded document becomes a conversation. This story ships the Document Page per the Claude Design contract (cd-document-view-v2.dc.html) and the desk RFD: a route-per-mode page whose Original view is untouched paper you talk to (select → Counsel Control Bar → note, wired live to the span-anchored notes substrate), whose Insights view is "a briefing, not a brief" (THE READ + accordions), and whose header carries the document's identity + a Details card + Reclassify. Text is demoted to a machine-copy utility link.

The one load-bearing discovery (founder-ratified path)

The brief assumed the Original anchored notes to an existing document_pages blocks read path with normalized bbox. That path does not exist — the Text route reads one derived/text.txt blob (no blocks, no bbox, no char/page map; CE-17 unmirrored), and the live PDF rendered its text layer off. Founder ratified the honest path: turn the pdfjs text layer on, anchor each note by quote (byte-exact V-CITE) + pageNumber (blockIndex = null = whole page), render page-level gutter marks v1, and design the overlay/gutter/margin components to upgrade to per-¶ when the blocks/bbox endpoint lands (an optional blocks prop; absent = page-level). The blocks read-path story is filed separately on pramaan-functions.

Design states → what shipped

Live wiring (no fixtures on the shipped path)

• Notes substrate proxy (new). The gen annotation hooks existed but had no BFF proxy — they 404'd. Added GET/POST /api/internal/documents/[docId]/annotations + [annotationId]/keep|dismiss and the gateway methods (listAnnotations, createAnnotation, resolveAnnotation), HR-21 parsed at the boundary.
• Optimistic notes. useDocumentAnnotations — list (author resolved against the firm roster: real photo + name), useAppCreateDocumentAnnotation with onMutate prepend + rollback + onSettled invalidate. Posted note is instant.
• Reclassify proxy (new). PATCH /api/internal/matters/[matterId]/documents/[docId]/{home,declared-side} + gateway setHome/setDeclaredSide + toBrowserRoute rules, mirroring the privilege proxy.
• Surface registry. New matter.record.doc.insights agentSurface + pnpm gen:routes (40 surfaces). Presence key in both locales.

Storybook (verify here)

• Documents/Viewer/Insights → Pending — the live honest state.
• Documents/Viewer/Insights → FullRead — THE READ + punch cards + accordions (Order_S.17 fixture).
• Documents/Viewer/CounselBar → Default — the CCB verbs.
• Documents/Viewer/DetailsSheet → Default — the identity card.
• Documents/Viewer/Reclassify → Default — the two-question dialog.
• Documents/Viewer/DocumentPermalinkShell → OriginalActive · InsightsActive · TextActive — the tab chrome per route.

Verification

• pnpm typecheck — clean.
• pnpm lint — clean (changed files).
• pnpm test — 168 files / 1035 tests green.
• pnpm build — green; all six new routes compiled (insights page; annotations + keep/dismiss; home; declared-side).
• Token + i18n pre-PR scans — no color literals, no hardcoded user-facing copy in the new code; keys in both en + hi.

Live-data seams (honest, reported on the issue): (1) Insights content — no read/facts-derived endpoint exists (Station 4). The route renders the pending state; the full layout is fixture-driven in Storybook and lights up when the read-brief endpoint lands. (2) Per-¶ fidelity — the gutter/margin are page-level until the document_pages blocks (text + bbox + kind per page) read path ships; the components take an optional blocks prop to upgrade with zero call-site changes. (3) Explain / What-this-means route to the matter agent — present but dimmed ("wired next") pending the Wave B app sender. The on-staging check is a real note on the Order_S.17 doc (3ee1dc28, matter 13): select → Note → it persists and reloads, and the page gets a gutter ●.