@cyber-dash-tech/revela 0.12.0 → 0.14.0

package/lib/narrative-state/render-plan.ts

@@ -1,4 +1,6 @@
 import { upsertDeck, upsertSlides, type DecksState, type EvidenceRef, type RequiredInputs, type SlideSpec } from "../decks-state"
+import { ensureActiveHtmlDeckRenderTarget } from "../workspace-state/render-targets"
+import { getClaimSlideRefs } from "./queries"
 import { computeNarrativeHash } from "./hash"
 import { normalizeNarrativeState } from "./normalize"
 import { narrativeToBrief } from "./project-compat"
@@ -64,6 +66,23 @@ export function compileDeckPlanFromNarrative(state: DecksState, options: Compile
   })
   next = upsertSlides(next, slug, slides)
   next.narrative = { ...narrative, updatedAt: options.now ?? narrative.updatedAt }
+  const htmlTarget = ensureActiveHtmlDeckRenderTarget(next)
+  if (htmlTarget) {
+    htmlTarget.data = {
+      ...(htmlTarget.data ?? {}),
+      narrativeId: narrative.id,
+      narrativeHash,
+      claimSlideRefs: getClaimSlideRefs(next).map((ref) => ({
+        claimId: ref.claimId,
+        claimText: ref.claimText,
+        slideIndex: ref.slideIndex,
+        slideTitle: ref.slideTitle,
+        match: ref.match,
+        role: ref.role,
+        location: ref.location,
+      })),
+    }
+  }
 
   return {
     state: next,
@@ -110,6 +129,7 @@ function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
 
   for (const claim of centralClaims) slides.push(claimSlide(slides.length + 1, claim, evidenceByClaim.get(claim.id) ?? []))
   if (supportingClaims.length > 0) {
+    const supportingBindings = supportingClaims.flatMap((claim) => evidenceByClaim.get(claim.id) ?? [])
     slides.push({
       index: slides.length + 1,
       title: "Supporting Logic",
@@ -118,16 +138,24 @@ function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
       layout: "card-grid",
       qa: true,
       components: ["card"],
+      claimIds: supportingClaims.map((claim) => claim.id),
+      claimRefs: supportingClaims.map((claim) => ({ claimId: claim.id, role: "supporting" as const })),
+      evidenceBindingIds: supportingBindings.map((binding) => binding.id),
       content: {
         headline: "Supporting claims and boundaries",
         bullets: supportingClaims.slice(0, 5).map((claim) => claim.text),
       },
-      evidence: supportingClaims.flatMap((claim) => (evidenceByClaim.get(claim.id) ?? []).map(evidenceRefFromBinding)),
+      evidence: supportingBindings.map(evidenceRefFromBinding),
       status: "planned",
     })
   }
 
   if (narrative.risks.length > 0 || narrative.objections.length > 0) {
+    const challengedClaimRefs = [
+      ...narrative.risks.map((risk) => risk.claimId ? { claimId: risk.claimId, role: "risk" as const } : undefined).filter((ref): ref is { claimId: string; role: "risk" } => Boolean(ref)),
+      ...narrative.objections.map((objection) => objection.claimId ? { claimId: objection.claimId, role: "objection" as const } : undefined).filter((ref): ref is { claimId: string; role: "objection" } => Boolean(ref)),
+    ]
+    const challengedClaimIds = [...new Set(challengedClaimRefs.map((ref) => ref.claimId))]
     slides.push({
       index: slides.length + 1,
       title: "Risks And Objections",
@@ -136,6 +164,8 @@ function buildSlides(narrative: NarrativeStateV1): SlideSpec[] {
       layout: "two-col",
       qa: true,
       components: ["card"],
+      claimIds: challengedClaimIds,
+      claimRefs: dedupeClaimRefs(challengedClaimRefs),
       content: {
         headline: "What could break the recommendation",
         bullets: [
@@ -176,6 +206,9 @@ function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvi
     layout: "two-col",
     qa: true,
     components: ["card"],
+    claimIds: [claim.id],
+    claimRefs: [{ claimId: claim.id, role: "primary" }],
+    evidenceBindingIds: bindings.map((binding) => binding.id),
     content: {
       headline: claim.text,
       bullets: [claim.supportedScope, claim.unsupportedScope ? `Unsupported scope: ${claim.unsupportedScope}` : undefined, ...(claim.caveats ?? [])].filter((item): item is string => Boolean(item)),
@@ -185,6 +218,16 @@ function claimSlide(index: number, claim: NarrativeClaim, bindings: NarrativeEvi
   }
 }
 
+function dedupeClaimRefs<T extends { claimId: string; role: "risk" | "objection" }>(refs: T[]): T[] {
+  const seen = new Set<string>()
+  return refs.filter((ref) => {
+    const key = `${ref.claimId}:${ref.role}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
 function evidenceRefFromBinding(binding: NarrativeEvidenceBinding): EvidenceRef {
   return {
     source: binding.source,

package/lib/narrative-state/research-gaps.ts

@@ -0,0 +1,191 @@
+import type { DecksState } from "../decks-state"
+import { recordWorkspaceAction } from "../workspace-state/actions"
+import { stableResearchGapId } from "./hash"
+import { normalizeNarrativeState } from "./normalize"
+import { reviewNarrativeState } from "./readiness"
+import type {
+  NarrativeReadinessIssue,
+  NarrativeResearchGap,
+  NarrativeResearchGapStatus,
+  NarrativeResearchGapTargetType,
+  NarrativeStateV1,
+} from "./types"
+
+export interface UpsertResearchGapInput {
+  id?: string
+  targetType?: NarrativeResearchGapTargetType
+  targetId?: string
+  question: string
+  status?: NarrativeResearchGapStatus
+  priority?: "high" | "medium" | "low"
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  createdFromIssueType?: NarrativeReadinessIssue["type"]
+  notes?: string
+}
+
+export interface UpdateResearchGapInput {
+  id: string
+  status?: NarrativeResearchGapStatus
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  notes?: string
+}
+
+export interface ResearchGapMutationResult {
+  created: NarrativeResearchGap[]
+  updated: NarrativeResearchGap[]
+  skipped: Array<{ id?: string; question?: string; reason: string }>
+  gaps: NarrativeResearchGap[]
+}
+
+export interface CloseResearchGapResult {
+  closed: boolean
+  skipped: boolean
+  reason?: string
+  gap?: NarrativeResearchGap
+}
+
+export function deriveResearchGapsFromReadiness(state: DecksState, options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const reviewed = reviewNarrativeState(state, { now: options.now })
+  return upsertResearchGapsInState(reviewed.state, gapsFromIssues(reviewed.state.narrative!, reviewed.result.issues), options)
+}
+
+export function upsertResearchGapsInState(state: DecksState, inputs: UpsertResearchGapInput[], options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const now = options.now ?? new Date().toISOString()
+  const narrative = ensureNarrative(state)
+  const existing = new Map((narrative.researchGaps ?? []).map((gap) => [gap.id, gap]))
+  const created: NarrativeResearchGap[] = []
+  const updated: NarrativeResearchGap[] = []
+  const skipped: ResearchGapMutationResult["skipped"] = []
+
+  for (const input of inputs) {
+    const question = clean(input.question)
+    if (!question) {
+      skipped.push({ reason: "question is required" })
+      continue
+    }
+    const targetType = input.targetType ?? "narrative"
+    const targetId = clean(input.targetId)
+    const id = input.id?.trim() || stableResearchGapId([targetType, targetId, question].filter(Boolean).join("|"))
+    const prior = existing.get(id)
+    if (prior?.status === "closed") {
+      skipped.push({ id, question, reason: "matching research gap is already closed" })
+      continue
+    }
+
+    const next: NarrativeResearchGap = {
+      id,
+      targetType,
+      targetId,
+      question,
+      status: input.status ?? prior?.status ?? "open",
+      priority: input.priority ?? prior?.priority ?? "medium",
+      findingsFile: clean(input.findingsFile) || prior?.findingsFile,
+      evidenceBindingIds: mergeIds(prior?.evidenceBindingIds, input.evidenceBindingIds),
+      createdFromIssueType: input.createdFromIssueType ?? prior?.createdFromIssueType,
+      notes: clean(input.notes) || prior?.notes,
+      createdAt: prior?.createdAt ?? now,
+      updatedAt: now,
+      closedAt: input.status === "closed" ? now : prior?.closedAt,
+    }
+    existing.set(id, next)
+    if (prior) updated.push(next)
+    else created.push(next)
+  }
+
+  const gaps = [...existing.values()].sort((a, b) => gapSortValue(a) - gapSortValue(b) || a.question.localeCompare(b.question))
+  state.narrative = { ...narrative, researchGaps: gaps, updatedAt: now }
+  if (created.length > 0) recordResearchGapAction(state, "research.gap_created", created, now)
+  if (updated.length > 0) recordResearchGapAction(state, "research.gap_updated", updated, now)
+  return { state, result: { created, updated, skipped, gaps } }
+}
+
+export function updateResearchGapInState(state: DecksState, input: UpdateResearchGapInput, options: { now?: string } = {}): { state: DecksState; result: ResearchGapMutationResult } {
+  const narrative = ensureNarrative(state)
+  const gap = (narrative.researchGaps ?? []).find((item) => item.id === input.id)
+  if (!gap) return { state, result: { created: [], updated: [], skipped: [{ id: input.id, reason: "research gap not found" }], gaps: narrative.researchGaps ?? [] } }
+  return upsertResearchGapsInState(state, [{ ...gap, ...input, question: gap.question, targetType: gap.targetType, targetId: gap.targetId }], options)
+}
+
+export function closeResearchGapInState(state: DecksState, id: string, reason?: string, options: { now?: string } = {}): { state: DecksState; result: CloseResearchGapResult } {
+  const now = options.now ?? new Date().toISOString()
+  const narrative = ensureNarrative(state)
+  const gaps = narrative.researchGaps ?? []
+  const gap = gaps.find((item) => item.id === id)
+  if (!gap) return { state, result: { closed: false, skipped: true, reason: "research gap not found" } }
+  const closed: NarrativeResearchGap = { ...gap, status: "closed", notes: clean(reason) || gap.notes, updatedAt: now, closedAt: now }
+  state.narrative = { ...narrative, researchGaps: gaps.map((item) => item.id === id ? closed : item), updatedAt: now }
+  recordResearchGapAction(state, "research.gap_closed", [closed], now)
+  return { state, result: { closed: true, skipped: false, gap: closed } }
+}
+
+function gapsFromIssues(narrative: NarrativeStateV1, issues: NarrativeReadinessIssue[]): UpsertResearchGapInput[] {
+  return issues.flatMap((issue) => {
+    if (!researchableIssue(issue)) return []
+    const target = targetForIssue(narrative, issue)
+    return [{
+      targetType: target.type,
+      targetId: target.id,
+      question: questionForIssue(issue),
+      priority: issue.severity === "blocker" ? "high" : "medium",
+      status: "open",
+      createdFromIssueType: issue.type,
+      notes: issue.suggestedAction,
+      findingsFile: issue.source?.startsWith("researches/") ? issue.source : undefined,
+    }]
+  })
+}
+
+function researchableIssue(issue: NarrativeReadinessIssue): boolean {
+  return issue.type === "missing_evidence" || issue.type === "weak_evidence" || issue.type === "unsupported_scope" || issue.type === "unhandled_objection" || issue.type === "missing_risk"
+}
+
+function targetForIssue(narrative: NarrativeStateV1, issue: NarrativeReadinessIssue): { type: NarrativeResearchGapTargetType; id?: string } {
+  if (issue.claimId) return { type: "claim", id: issue.claimId }
+  const objection = narrative.objections.find((item) => item.text === issue.claimText)
+  if (objection) return { type: "objection", id: objection.id }
+  if (issue.type === "missing_risk") return { type: "decision", id: narrative.decision.action ? stableResearchGapId(`decision:${narrative.decision.action}`) : undefined }
+  return { type: "narrative", id: narrative.id }
+}
+
+function questionForIssue(issue: NarrativeReadinessIssue): string {
+  if (issue.claimText && issue.type === "missing_evidence") return `Find evidence for claim: ${issue.claimText}`
+  if (issue.claimText && issue.type === "weak_evidence") return `Strengthen evidence for claim: ${issue.claimText}`
+  if (issue.claimText && issue.type === "unsupported_scope") return `Resolve unsupported scope for claim: ${issue.claimText}`
+  if (issue.type === "unhandled_objection") return `Find response or evidence for objection: ${issue.claimText ?? issue.message}`
+  if (issue.type === "missing_risk") return "Identify risk, assumption, caveat, or tradeoff handling for the recommendation."
+  return issue.message
+}
+
+function ensureNarrative(state: DecksState): NarrativeStateV1 {
+  state.narrative = normalizeNarrativeState(state)
+  return state.narrative
+}
+
+function recordResearchGapAction(state: DecksState, type: "research.gap_created" | "research.gap_updated" | "research.gap_closed", gaps: NarrativeResearchGap[], timestamp: string): void {
+  recordWorkspaceAction(state, {
+    type,
+    actor: "revela-decks",
+    timestamp,
+    inputs: { narrativeId: state.narrative?.id },
+    outputs: { gaps: gaps.map((gap) => ({ id: gap.id, status: gap.status, targetType: gap.targetType, targetId: gap.targetId, findingsFile: gap.findingsFile, evidenceBindingIds: gap.evidenceBindingIds })) },
+    status: "success",
+    summary: `${type === "research.gap_created" ? "Created" : type === "research.gap_closed" ? "Closed" : "Updated"} ${gaps.length} research gap${gaps.length === 1 ? "" : "s"}.`,
+    nodeIds: gaps.map((gap) => gap.id),
+  })
+}
+
+function gapSortValue(gap: NarrativeResearchGap): number {
+  const statusValue: Record<NarrativeResearchGapStatus, number> = { open: 0, in_progress: 1, findings_saved: 2, attached: 3, evidence_bound: 4, closed: 5 }
+  const priorityValue = gap.priority === "high" ? 0 : gap.priority === "medium" ? 1 : 2
+  return statusValue[gap.status] * 10 + priorityValue
+}
+
+function mergeIds(existing: string[] | undefined, next: string[] | undefined): string[] {
+  return [...new Set([...(existing ?? []), ...(next ?? [])].map(clean).filter(Boolean))].sort()
+}
+
+function clean(value: string | undefined): string {
+  return value?.trim() ?? ""
+}

package/lib/narrative-state/types.ts

@@ -4,6 +4,12 @@ export type NarrativeClaimKind = "context" | "problem" | "opportunity" | "eviden
 
 export type NarrativeEvidenceStatus = "supported" | "partial" | "weak" | "missing" | "not_required"
 
+export type NarrativeResearchGapStatus = "open" | "in_progress" | "findings_saved" | "attached" | "evidence_bound" | "closed"
+
+export type NarrativeResearchGapTargetType = "claim" | "objection" | "risk" | "decision" | "narrative"
+
+export type NarrativeClaimRelationType = "leads_to" | "supports" | "depends_on" | "contrasts_with" | "constrains" | "answers"
+
 export interface NarrativeStateV1 {
   version: 1
   id: string
@@ -12,9 +18,11 @@ export interface NarrativeStateV1 {
   decision: DecisionIntent
   thesis?: NarrativeThesis
   claims: NarrativeClaim[]
+  claimRelations?: NarrativeClaimRelation[]
   evidenceBindings: NarrativeEvidenceBinding[]
   objections: NarrativeObjection[]
   risks: NarrativeRisk[]
+  researchGaps?: NarrativeResearchGap[]
   approvals: NarrativeApproval[]
   updatedAt: string
 }
@@ -55,6 +63,14 @@ export interface NarrativeClaim {
   caveats?: string[]
 }
 
+export interface NarrativeClaimRelation {
+  id: string
+  fromClaimId: string
+  toClaimId: string
+  relation: NarrativeClaimRelationType
+  rationale?: string
+}
+
 export interface NarrativeEvidenceBinding {
   id: string
   claimId: string
@@ -86,6 +102,22 @@ export interface NarrativeRisk {
   mitigation?: string
 }
 
+export interface NarrativeResearchGap {
+  id: string
+  targetType: NarrativeResearchGapTargetType
+  targetId?: string
+  question: string
+  status: NarrativeResearchGapStatus
+  priority: "high" | "medium" | "low"
+  findingsFile?: string
+  evidenceBindingIds?: string[]
+  createdFromIssueType?: NarrativeReadinessIssueType
+  notes?: string
+  createdAt: string
+  updatedAt: string
+  closedAt?: string
+}
+
 export interface NarrativeApproval {
   id: string
   narrativeHash: string
@@ -112,6 +144,7 @@ export type NarrativeReadinessIssueType =
   | "approval_stale"
   | "artifact_stale"
   | "research_findings_unattached"
+  | "research_gap_open"
 
 export interface NarrativeReadinessIssue {
   type: NarrativeReadinessIssueType

package/lib/refine/server.ts

@@ -459,6 +459,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
   }
 
   const snapshot = normalizeSnapshot(body?.snapshot ?? body)
+  const language = normalizeInspectLanguage(body?.language)
   const requestId = typeof body?.requestId === "string" && body.requestId.trim() ? body.requestId.trim() : randomBytes(10).toString("base64url")
   const version = readDeckVersion(session).version
   const staleReason = typeof body?.deckVersion === "string" && body.deckVersion !== version
@@ -480,6 +481,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
           text: buildInspectionPrompt({
             requestId,
             file: session.file,
+            language,
             projection: staleReason
               ? { ...projection, stale: { stale: true, reason: staleReason } } as any
               : projection,
@@ -491,7 +493,7 @@ async function handleInspect(req: Request, session: EditSession): Promise<Respon
       failInspectRequest(requestId, message)
     })
 
-    return jsonResponse({ ok: true, requestId, deckVersion: version, status: "pending", preprocess })
+    return jsonResponse({ ok: true, requestId, deckVersion: version, status: "pending", language, preprocess })
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
     failInspectRequest(requestId, message)
@@ -510,6 +512,11 @@ function handleInspectResult(requestId: string | null, session: EditSession): Re
   return jsonResponse({ ok: true, requestId, status: request.status, deckVersion: request.deckVersion })
 }
 
+function normalizeInspectLanguage(input: unknown): string {
+  const value = typeof input === "string" ? input.trim() : ""
+  return value || "Auto"
+}
+
 function normalizeSnapshot(input: any): InspectionElementSnapshot {
   return {
     scope: input?.scope === "selection" || input?.scope === "slide" || input?.scope === "element" ? input.scope : undefined,
@@ -657,6 +664,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     .comment-bubble.stale .comment-bubble-state { color: #a16207; }
     .comment-bubble.failed .comment-bubble-state { color: #b91c1c; }
     .inspect-actions { display: flex; flex-direction: column; gap: 8px; }
+    .inspect-options { display: flex; flex-direction: column; gap: 5px; }
+    .inspect-options label { color: #64748b; font-size: 11px; font-weight: 800; text-transform: uppercase; letter-spacing: .05em; }
+    .inspect-select { width: 100%; padding: 10px 11px; border: 1px solid #d7e0ea; border-radius: 12px; background: #fff; color: #0f172a; font-weight: 700; }
     .inspect-cards { display: flex; flex-direction: column; gap: 12px; }
     .inspect-card { border: 1px solid #d7e0ea; border-radius: 16px; background: #fff; padding: 13px; box-shadow: 0 10px 24px rgba(15,23,42,.05); }
     .inspect-card-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 8px; }
@@ -681,7 +691,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
     <aside>
       <div>
         <h1><span class="wordmark">REVELA</span> Refine</h1>
-        <p class="hint">Cmd/Ctrl-click slide elements once, then use Edit for fast changes or Inspect for Source/Purpose review.</p>
+        <p class="hint">Cmd/Ctrl-click slide elements once, then use Edit for fast changes or Inspect for Narrative Reading, Exploratory Reading, Source, and Purpose review.</p>
       </div>
       <div id="selectionSummary" class="selection-summary"><strong>Selection</strong><span>No references selected.</span><div id="selectionChips" class="selection-chips"></div></div>
       <div class="tabs" role="tablist" aria-label="Refine mode">
@@ -698,10 +708,11 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       </div>
       <div id="inspectPanel" class="tab-panel">
         <div class="inspect-actions">
+          <div class="inspect-options"><label for="inspectLanguage">Display Language</label><select id="inspectLanguage" class="inspect-select"><option>Auto</option><option>English</option><option>简体中文</option><option>繁體中文</option><option>日本語</option><option>Deutsch</option><option>Français</option><option>Español</option><option>Português</option><option>Arabic</option></select></div>
           <button id="inspectButton" disabled>Inspect Selection</button>
           <div id="inspectStale"></div>
         </div>
-        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select one or more deck elements, then inspect them for Source and Purpose. This does not edit the deck.</div></div>
+        <div id="inspectCards" class="inspect-cards"><div class="inspect-empty">Select one or more deck elements, then inspect them for Narrative Reading, Exploratory Reading, Source, and Purpose. This does not edit the deck.</div></div>
       </div>
       <div id="status" class="status"></div>
     </aside>
@@ -744,6 +755,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         mode: defaultMode === 'inspect' ? 'inspect' : 'edit',
         inspecting: false,
         activeInspectRequestId: '',
+        inspectLanguage: 'Auto',
+        inspectFallback: null,
       };
       const els = {
         frame: null,
@@ -759,6 +772,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         commentThread: null,
         send: null,
         inspectButton: null,
+        inspectLanguage: null,
         inspectCards: null,
         inspectStale: null,
         status: null,
@@ -792,7 +806,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           els.inspectStale = document.getElementById('inspectStale');
           els.status = document.getElementById('status');
 
-          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectButton || !els.inspectCards || !els.inspectStale || !els.status) {
+          els.inspectLanguage = document.getElementById('inspectLanguage');
+
+          if (!els.frame || !els.hitbox || !els.resizeHandle || !els.selectionSummary || !els.selectionChips || !els.editTab || !els.inspectTab || !els.editPanel || !els.inspectPanel || !els.comment || !els.commentThread || !els.send || !els.inspectButton || !els.inspectLanguage || !els.inspectCards || !els.inspectStale || !els.status) {
             throw new Error('Editor boot failed: required DOM nodes are missing.');
           }
 
@@ -840,6 +856,9 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         els.resizeHandle.addEventListener('dblclick', resetEditorWidth);
         els.send.addEventListener('click', sendComment);
         els.inspectButton.addEventListener('click', inspectCurrentSelection);
+        els.inspectLanguage.addEventListener('change', () => {
+          state.inspectLanguage = els.inspectLanguage.value || 'Auto';
+        });
         els.editTab.addEventListener('click', () => setMode('edit'));
         els.inspectTab.addEventListener('click', () => setMode('inspect'));
       }
@@ -1075,7 +1094,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         renderReferenceOutlines();
         updateSendState();
         renderSelectionSummary();
-        resetInspectCards('References ready. Open Inspect and click Inspect Selection when you want Source/Purpose review.');
+        resetInspectCards('References ready. Open Inspect and click Inspect Selection when you want Narrative Reading, Exploratory Reading, Source, and Purpose review.');
         setStatus('Inserted @' + label + '. ' + state.references.length + ' reference' + (state.references.length === 1 ? '' : 's') + ' will be sent.');
       }
 
@@ -1286,22 +1305,28 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         updateSendState();
         setMode('inspect');
         els.inspectStale.innerHTML = '';
-        els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Preparing inspection...</b><br>Deterministic Source/Purpose appears first; generated cards update lazily.</div>';
+        state.inspectFallback = null;
+        els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Reading selection...</b><br>Sending grounded selection context to OpenCode. Deterministic context is kept as fallback if generation fails.</div>';
         try {
           const res = await fetch('/api/inspect?token=' + encodeURIComponent(token), {
             method: 'POST',
             headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ snapshot, deckVersion: state.deckVersion }),
+            body: JSON.stringify({ snapshot, deckVersion: state.deckVersion, language: state.inspectLanguage }),
           });
           const body = await res.json().catch(() => ({}));
           if (!res.ok || !body.ok) throw new Error(body.error || 'Inspection failed');
           state.deckVersion = body.deckVersion || state.deckVersion;
           state.activeInspectRequestId = body.requestId;
-          if (body.preprocess) renderInspectResult(body.preprocess, 'Preprocessed');
-          els.inspectCards.insertAdjacentHTML('beforeend', '<div class="inspect-loading"><b>Generating lazy inspection...</b><br>Waiting for structured result from OpenCode.</div>');
+          state.inspectFallback = body.preprocess || null;
+          els.inspectCards.innerHTML = '<div class="inspect-loading"><b>Reading selection...</b><br>Waiting for localized structured reading cards.</div>';
           await pollInspectResult(body.requestId);
         } catch (error) {
-          resetInspectCards(error && error.message ? error.message : String(error));
+          if (state.inspectFallback) {
+            renderInspectResult(state.inspectFallback, 'Deterministic fallback');
+            els.inspectCards.insertAdjacentHTML('afterbegin', '<div class="inspect-warning">Generated inspection failed or timed out. Showing deterministic fallback context only.</div>');
+          } else {
+            resetInspectCards(error && error.message ? error.message : String(error));
+          }
         } finally {
           state.inspecting = false;
           updateSendState();
@@ -1309,7 +1334,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       async function pollInspectResult(requestId) {
-        for (;;) {
+        for (let attempt = 0; attempt < 80; attempt++) {
           await delay(900);
           const res = await fetch('/api/inspect-result?token=' + encodeURIComponent(token) + '&requestId=' + encodeURIComponent(requestId));
           const body = await res.json().catch(() => ({}));
@@ -1321,6 +1346,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
           }
           if (body.status === 'failed' || body.status === 'expired') throw new Error(body.error || 'Inspection failed');
         }
+        throw new Error('Inspection timed out while waiting for OpenCode result');
       }
 
       function collectReferenceSnapshot() {
@@ -1351,6 +1377,8 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         else els.inspectStale.innerHTML = '';
         els.inspectCards.innerHTML = [
           '<div class="status">' + escapeHtml(phase || 'Inspection') + '</div>',
+          result.cards.reading ? renderInspectCard('Narrative Reading', result.cards.reading.status, result.cards.reading.rationale, renderReading(result.cards.reading)) : '',
+          result.cards.exploratory ? renderInspectCard('Exploratory Reading', result.cards.exploratory.status, result.cards.exploratory.rationale, renderExploratory(result.cards.exploratory)) : '',
           renderInspectCard('Purpose', result.cards.purpose.status, result.cards.purpose.rationale, renderPurpose(result.cards.purpose)),
           renderInspectCard('Source', result.cards.source.status, result.cards.source.rationale, renderSource(result.cards.source)),
         ].join('');
@@ -1364,6 +1392,49 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         return '<div class="inspect-item">' + field('Role', card.role) + field('Why it matters', card.whyItMatters) + '</div>';
       }
 
+      function renderReading(card) {
+        return '<div class="inspect-item">'
+          + field('Claim ID', card.claimId)
+          + field('Canonical claim ID', card.canonicalClaimId)
+          + field('Claim', card.claimText)
+          + field('Evidence status', card.evidenceStatus)
+          + field('Evidence bindings', card.evidenceBindingIds && card.evidenceBindingIds.length ? card.evidenceBindingIds.join(', ') : '')
+          + field('Supported scope', card.supportedScope)
+          + field('Unsupported scope', card.unsupportedScope)
+          + '</div>'
+          + renderSectionList('Caveats', card.caveats)
+          + renderSectionList('Objections', card.relatedObjections)
+          + renderSectionList('Risks', card.relatedRisks)
+          + renderArtifactCoverage(card.artifactCoverage);
+      }
+
+      function renderArtifactCoverage(items) {
+        if (!items || !items.length) return '';
+        return '<div class="label">Artifact Coverage</div>' + items.map((item) => {
+          const title = (item.type || 'artifact') + (item.outputPath ? ' · ' + item.outputPath : '');
+          const status = (item.coverageStatus || 'unknown') + (item.containsClaim ? ' · contains claim' : ' · claim not rendered');
+          return '<div class="inspect-item"><b>' + escapeHtml(title) + '</b>'
+            + field('Coverage', status)
+            + field('Stale', item.stale ? (item.staleReason || 'stale') : '')
+            + field('Note', item.note)
+            + renderSectionList('Locations', item.locations)
+            + '</div>';
+        }).join('');
+      }
+
+      function renderExploratory(card) {
+        return '<div class="inspect-item"><b>Non-official reading aid</b>'
+          + field('Official artifact content', card.official === false ? 'No' : '')
+          + field('Audience', card.audience)
+          + field('Claim focus', card.claimFocus)
+          + field('Audience reframe boundary', card.audienceReframe)
+          + '</div>'
+          + renderSectionList('Objection Prep', card.objectionPrompts)
+          + renderSectionList('Appendix Leads', card.appendixLeads)
+          + renderSectionList('Meeting Prep', card.meetingPrep)
+          + renderSectionList('Boundaries', card.boundaries);
+      }
+
       function renderSource(card) {
         return renderSources(card.sources) + renderWarnings(card.warnings) + renderSectionList('Gaps', card.gaps) + renderSectionList('Caveats', card.caveats);
       }
@@ -1422,7 +1493,7 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
         state.references = [];
         if (removeChips) els.comment.querySelectorAll('.ref-chip').forEach((chip) => chip.remove());
         renderSelectionSummary();
-        resetInspectCards('Select one or more deck elements, then inspect them for Source and Purpose. This does not edit the deck.');
+        resetInspectCards('Select one or more deck elements, then inspect them for Narrative Reading, Exploratory Reading, Source, and Purpose. This does not edit the deck.');
       }
 
       function getCommentText() {
@@ -1525,10 +1596,17 @@ export function renderRefineShell(token: string, defaultMode: RefineMode = "edit
       }
 
       function findSlide(node) {
-        return node.closest('.slide, [slide-qa], .slide-canvas, .page');
+        if (!node || !node.closest) return null;
+        return node.closest('.slide[data-slide-index]')
+          || node.closest('.slide')
+          || node.closest('[slide-qa]')
+          || node.closest('.slide-canvas')
+          || node.closest('.page');
       }
 
       function getSlides(doc) {
+        const canonicalSlides = Array.from(doc.querySelectorAll('.slide[data-slide-index]'));
+        if (canonicalSlides.length) return canonicalSlides;
         const slides = Array.from(doc.querySelectorAll('.slide'));
         if (slides.length) return slides;
         const qaSlides = Array.from(doc.querySelectorAll('[slide-qa]'));

package/lib/workspace-state/evidence-status.ts

@@ -40,15 +40,25 @@ export interface EvidenceStatusMatch {
   slideIndex?: number
   slideTitle?: string
   claimId?: string
+  canonicalClaimId?: string
   claimText?: string
   claimEvidenceSensitive?: boolean
   claimEvidenceSupport?: string
+  evidenceBindingIds: string[]
+  supportedScope?: string
+  unsupportedScope?: string
+  caveats: string[]
 }
 
 export interface EvidenceStatusEvidence extends EvidenceRef {
   slideIndex: number
   slideTitle: string
   hasDetail: boolean
+  evidenceBindingId?: string
+  claimId?: string
+  supportScope?: string
+  unsupportedScope?: string
+  strength?: "strong" | "partial" | "weak"
 }
 
 export interface EvidenceStatusGap {
@@ -159,9 +169,14 @@ function projectMatch(match: InspectionElementMatch): EvidenceStatusMatch {
     slideIndex: match.slide?.index,
     slideTitle: match.slide?.title,
     claimId: match.claim?.id,
+    canonicalClaimId: match.claim?.canonicalClaimId,
     claimText: match.claim?.text,
     claimEvidenceSensitive: match.claim?.evidenceSensitive,
     claimEvidenceSupport: match.claim?.evidenceSupport,
+    evidenceBindingIds: match.claim?.evidenceBindingIds ?? [],
+    supportedScope: match.claim?.supportedScope,
+    unsupportedScope: match.claim?.unsupportedScope,
+    caveats: match.claim?.caveats ?? [],
   }
 }
 
@@ -235,7 +250,12 @@ function relevantSearchDiagnostics(issues: ReadinessIssue[], match: InspectionEl
 
 function actionTraceForMatch(actions: WorkspaceAction[], match: InspectionElementMatch): EvidenceStatusActionTrace[] {
   const slideNodeId = match.slide ? `slide:${match.slide.index}` : undefined
-  const evidenceKeys = new Set(match.evidence.flatMap((item) => [item.source, item.sourcePath, item.findingsFile].filter((value): value is string => Boolean(value))))
+  const evidenceKeys = new Set([
+    match.claim?.id,
+    match.claim?.canonicalClaimId,
+    ...(match.claim?.evidenceBindingIds ?? []),
+    ...match.evidence.flatMap((item) => [item.source, item.sourcePath, item.findingsFile, item.evidenceBindingId, item.claimId]),
+  ].filter((value): value is string => Boolean(value)))
   return actions
     .filter((action) => actionRelevantToMatch(action, slideNodeId, evidenceKeys))
     .slice(-12)