Insights RSC
→ current Anchor view (exact extractionVersion)
→ GET /app/documents/{id}/deep-read-envelope?extractionVersion={uuid}
→ generated DeepReadEnvelope schema validation
→ server QueryClient prefetch + dehydrate
→ useAppGetDocumentDeepReadEnvelope() from the hydrated cache
The browser uses the existing /app/documents/* BFF mapping.
The new
/api/internal/documents/[docId]/deep-read-envelope proxy
allowlists only extractionVersion, forwards Clerk
authentication server-side, and validates the response against the
generated contract before it reaches UI.
| Envelope field | Insights rendering |
|---|---|
summary |
The JUDGE summary appears first in the single elevated hero. It was generated last, after rulings. |
section rows |
Semantic label, title, page range, materiality note, and a jump to the matching Original page/section. |
attention rows |
Critical / Read / Skim / Skip grade, read order, time, and reason in the section's left margin. Suppressed low-confidence grades stay hidden. |
finding rows |
Type, confidence, judged statement, V-CITE quote, and a source-page pin. Assertions and coverage receipts remain in the envelope but are not expanded into extra UI. |
A missing successful envelope is a typed
pramaan.deep_read.envelope_not_found 404, not a broken
card. The route renders Not yet read. Other failures
stay failures and show an inline retry surface; they are never
mislabeled as an unread document.
90 file(s), +4887 / -1867 lines
| Path | Role | + | - |
|---|---|---|---|
| messages/en.json | Config | +25 | -12 |
| messages/hi.json | Config | +25 | -12 |
| openapi/app-api.json | Config | +623 | -5 |
| openapi/permission-map.json | Config | +2 | -2 |
| src/app/[locale]/(workspace)/matters/[matterId]/record/doc/[documentId]/insights/page.tsx | App route | +40 | -47 |
| src/app/[locale]/(workspace)/matters/[matterId]/record/doc/[documentId]/layout.tsx | App route | +2 | -2 |
| src/app/api/internal/documents/[docId]/deep-read-envelope/route.ts | App route | +5 | -0 |
| src/components/documents/viewer/deep-read-findings.stories.tsx | Component | +61 | -0 |
| src/components/documents/viewer/deep-read-findings.tsx | Component | +66 | -0 |
| src/components/documents/viewer/deep-read-presentation.test.ts | Component | +101 | -0 |
| src/components/documents/viewer/deep-read-presentation.ts | Component | +95 | -0 |
| src/components/documents/viewer/deep-read-section.stories.tsx | Component | +83 | -0 |
| src/components/documents/viewer/deep-read-section.tsx | Component | +92 | -0 |
| src/components/documents/viewer/document-insights-dossier.stories.tsx | Component | +109 | -138 |
| src/components/documents/viewer/document-insights-dossier.tsx | Component | +79 | -84 |
| src/components/documents/viewer/document-insights-live.tsx | Component | +28 | -155 |
| src/components/documents/viewer/insights-fixtures.ts | Component | +0 | -147 |
| src/components/documents/viewer/insights-presentation.ts | Component | +0 | -97 |
| src/components/documents/viewer/insights-types.ts | Component | +0 | -51 |
| src/components/documents/viewer/insights/dossier-assertions.tsx | Component | +0 | -93 |
| src/components/documents/viewer/insights/dossier-audit.tsx | Component | +0 | -69 |
| src/components/documents/viewer/insights/dossier-contradictions.tsx | Component | +0 | -87 |
| src/components/documents/viewer/insights/dossier-details.tsx | Component | +0 | -115 |
| src/components/documents/viewer/insights/dossier-notes.tsx | Component | +0 | -71 |
| src/components/documents/viewer/insights/dossier-outline.tsx | Component | +0 | -68 |
| src/components/documents/viewer/insights/dossier-read.tsx | Component | +0 | -48 |
| src/components/documents/viewer/insights/dossier-what-matters.tsx | Component | +0 | -57 |
| src/gen/client/appGetDocumentCard.ts | Generated contract | +0 | -64 |
| src/gen/client/appGetDocumentDeepReadEnvelope.ts | Generated contract | +67 | -0 |
| src/gen/client/index.ts | Generated contract | +1 | -1 |
| src/gen/hooks/index.ts | Generated contract | +8 | -8 |
| src/gen/hooks/useAppGetDocumentCard.ts | Generated contract | +0 | -128 |
| src/gen/hooks/useAppGetDocumentCardSuspense.ts | Generated contract | +0 | -126 |
| src/gen/hooks/useAppGetDocumentDeepReadEnvelope.ts | Generated contract | +142 | -0 |
| src/gen/hooks/useAppGetDocumentDeepReadEnvelopeSuspense.ts | Generated contract | +143 | -0 |
| src/gen/index.ts | Generated contract | +64 | -30 |
| src/gen/schemas/deepReadAssertionRow.json | Generated contract | +94 | -0 |
| src/gen/schemas/deepReadAttentionGrade.json | Generated contract | +5 | -0 |
| src/gen/schemas/deepReadAttentionRow.json | Generated contract | +78 | -0 |
| src/gen/schemas/deepReadCoverageOmission.json | Generated contract | +13 | -0 |
| src/gen/schemas/deepReadCoverageReceipt.json | Generated contract | +47 | -0 |
| src/gen/schemas/deepReadEnvelope.json | Generated contract | +544 | -0 |
| src/gen/schemas/deepReadEnvelopeRow.json | Generated contract | +382 | -0 |
| src/gen/schemas/deepReadEvidenceSpan.json | Generated contract | +37 | -0 |
| src/gen/schemas/deepReadExaminedReceipt.json | Generated contract | +29 | -0 |
| src/gen/schemas/deepReadFindingRow.json | Generated contract | +87 | -0 |
| src/gen/schemas/deepReadProposedRow.json | Generated contract | +323 | -0 |
| src/gen/schemas/deepReadSectionRow.json | Generated contract | +46 | -0 |
| src/gen/schemas/deepReadTrace.json | Generated contract | +25 | -0 |
| src/gen/types/AppGetDocumentCard.ts | Generated contract | +0 | -69 |
| src/gen/types/AppGetDocumentDeepReadEnvelope.ts | Generated contract | +79 | -0 |
| src/gen/types/DeepReadAssertionRow.ts | Generated contract | +66 | -0 |
| src/gen/types/DeepReadAttentionGrade.ts | Generated contract | +9 | -0 |
| src/gen/types/DeepReadAttentionRow.ts | Generated contract | +66 | -0 |
| src/gen/types/DeepReadCoverageOmission.ts | Generated contract | +26 | -0 |
| src/gen/types/DeepReadCoverageReceipt.ts | Generated contract | +35 | -0 |
| src/gen/types/DeepReadEnvelope.ts | Generated contract | +46 | -0 |
| src/gen/types/DeepReadEnvelopeRow.ts | Generated contract | +21 | -0 |
| src/gen/types/DeepReadEvidenceSpan.ts | Generated contract | +43 | -0 |
| src/gen/types/DeepReadExaminedReceipt.ts | Generated contract | +37 | -0 |
| src/gen/types/DeepReadFindingRow.ts | Generated contract | +50 | -0 |
| src/gen/types/DeepReadProposedRow.ts | Generated contract | +24 | -0 |
| src/gen/types/DeepReadSectionRow.ts | Generated contract | +52 | -0 |
| src/gen/types/DeepReadTrace.ts | Generated contract | +25 | -0 |
| src/gen/types/index.ts | Generated contract | +31 | -11 |
| src/gen/zod/{appGetDocumentCardSchema.ts => appGetDocumentDeepReadEnvelopeSchema.ts} | Generated contract | +39 | -32 |
| src/gen/zod/deepReadAssertionRowSchema.ts | Generated contract | +38 | -0 |
| src/gen/zod/deepReadAttentionGradeSchema.ts | Generated contract | +15 | -0 |
| src/gen/zod/deepReadAttentionRowSchema.ts | Generated contract | +53 | -0 |
| src/gen/zod/deepReadCoverageOmissionSchema.ts | Generated contract | +21 | -0 |
| src/gen/zod/deepReadCoverageReceiptSchema.ts | Generated contract | +32 | -0 |
| src/gen/zod/deepReadEnvelopeRowSchema.ts | Generated contract | +28 | -0 |
| src/gen/zod/deepReadEnvelopeSchema.ts | Generated contract | +48 | -0 |
| src/gen/zod/deepReadEvidenceSpanSchema.ts | Generated contract | +24 | -0 |
| src/gen/zod/deepReadExaminedReceiptSchema.ts | Generated contract | +23 | -0 |
| src/gen/zod/deepReadFindingRowSchema.ts | Generated contract | +35 | -0 |
| src/gen/zod/deepReadProposedRowSchema.ts | Generated contract | +43 | -0 |
| src/gen/zod/deepReadSectionRowSchema.ts | Generated contract | +33 | -0 |
| src/gen/zod/deepReadTraceSchema.ts | Generated contract | +21 | -0 |
| src/gen/zod/index.ts | Generated contract | +24 | -10 |
| src/lib/documents/deep-read-errors.test.ts | Library | +29 | -0 |
| src/lib/documents/deep-read-errors.ts | Library | +14 | -0 |
| src/lib/documents/gateway-views.test.ts | Library | +23 | -0 |
| src/lib/documents/gateway.ts | Library | +26 | -0 |
| src/lib/documents/get-anchor-view.ts | Library | +11 | -0 |
| src/lib/documents/route-helper.test.ts | Library | +28 | -2 |
| src/lib/documents/route-helper.ts | Library | +22 | -2 |
| src/lib/gateway.ts | Library | +22 | -8 |
| src/lib/surface-registry/route-registry.ts | Library | +2 | -2 |
| tests/unit/lib/gateway.test.ts | Test | +52 | -14 |
InsightsDossier / Full — all four attention grades plus a
pinned finding.
InsightsDossier / No findings — display-sparse read.InsightsDossier / Not read yet and Loading —
honest non-result states.
DeepReadSection — critical, skim, suppressed-grade, and
no-finding states.
DeepReadFindings — quoted, quote-free, and empty states.
T3h proves app transport, contract validation, rendering, i18n, and Storybook states. T3e / Story-2497 owns the signed-in staging upload → glance → envelope liveness smoke and silent-skip census. T3f / Story-2498 owns the Deep Read schema, V-CITE, coverage, normalization, and injection-refusal evals. This app PR does not claim either sibling gate.
This is a read-only Insights cutover. Finding verdict lifecycle, unread-critical counters, Original-page gutters, and exact character highlighting remain with T5a/T5b. The existing page/section permalink is the supported pin seam here. The new BFF route is covered by the shared gateway instrumentation; no manual span is added under pramaan-docs ADR-124.