@cyber-dash-tech/revela 0.17.0 → 0.17.1

package/lib/commands/narrative.ts

@@ -147,7 +147,7 @@ export function buildNarrativeViewPrompt(options: { workspaceRoot: string; langu
     relations: map.claimRelations.map((relation) => ({ id: relation.id, fromClaimId: relation.fromClaimId, toClaimId: relation.toClaimId, relation: relation.relation, rationale: relation.rationale, inferred: relation.inferred })),
     objections: map.objections.map((objection) => ({ id: objection.id, claimId: objection.claimId, priority: objection.priority, text: objection.text, response: objection.response })),
     risks: map.risks.map((risk) => ({ id: risk.id, claimId: risk.claimId, severity: risk.severity, text: risk.text, mitigation: risk.mitigation })),
-    researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question })),
+    researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question, findingsFile: gap.findingsFile, evidenceBindingIds: gap.evidenceBindingIds, notes: gap.notes })),
     artifactCoverage: map.artifactCoverage.map((artifact) => ({ type: artifact.type, outputPath: artifact.outputPath, stale: artifact.stale, coverageStatus: artifact.coverageStatus, affectedClaimIds: artifact.affectedClaimIds, missingClaimIds: artifact.missingClaimIds, slideRefs: artifact.slideRefs.map((ref) => ({ claimId: ref.claimId, slideIndex: ref.slideIndex, role: ref.role, match: ref.match, location: ref.location })) })),
   }
 
@@ -165,18 +165,27 @@ Hard rules:
 - Do not invent new claims, evidence, relations, slide coverage, source paths, findings files, quotes, or caveats.
 - Preserve every claimId exactly.
 - Preserve every relation endpoint exactly: fromClaimId, toClaimId, relation.
-- You may only organize and localize display copy for the UI: pageTitle, summaryLine, section labels, claim card displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, relation displayLabel, and relation displayRationale.
+- You may only organize and localize display copy for the UI: pageTitle, summaryLine, section labels, claim card displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, research gap displayQuestion, relation displayLabel, and relation displayRationale.
 - For inferred relations, do not provide relation displayLabel or displayRationale; inferred relations are unconfirmed order notes, not causal/support/dependency judgments.
 - relation displayRationale may only localize or clarify an existing canonical relation rationale. If relation.rationale is missing or the relation is inferred, do not provide displayRationale; the UI will show the missing or inferred status.
 - Keep source paths, findings files, claim IDs, narrative hash, and numbers unchanged.
-- Translate normal UI/display text into the target language request: pageTitle, summaryLine, labels, claim displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, relation displayLabel, and relation displayRationale.
+- Translate normal UI/display text into the target language request: pageTitle, summaryLine, labels, claim displayTitle, roleLabel, narrativeJob, evidenceSummary, supportRationale, supportedScope, unsupportedScope, objectionsSummary, risksSummary, riskOrGapSummary, researchGapsSummary, research gap displayQuestion, relation displayLabel, and relation displayRationale.
 - For every claim in a non-English target language, provide displayTitle so the selected-claim panel does not fall back to canonical English claim text.
-- For every selected-claim detail field that has canonical user-facing text, provide the matching localized display field when it exists: supportedScope for supported scope, unsupportedScope for evidence boundaries, supportRationale for why the evidence supports the claim, objectionsSummary for objections, risksSummary for risks, and researchGapsSummary for research gaps.
+- For every evidence/detail field that has canonical user-facing text, provide the matching localized display field when it exists: supportedScope for supported scope, unsupportedScope for evidence boundaries, supportRationale for why the evidence supports the claim, objectionsSummary for objections, risksSummary for risks, and researchGapsSummary for canonical research gaps.
 - Do not translate claim IDs, relation endpoints, narrative hash, source paths, findings files, URLs, numbers, or quoted/source facts.
+- For every canonical research gap in a non-English target language, provide researchGapCards[].displayQuestion so gap cards do not fall back to canonical English question text. Preserve gapId exactly and do not change the gap meaning.
 - Use natural business and manufacturing terminology in the target language, not word-by-word machine translation.
 - If a fact is missing, describe it as missing instead of filling it in.
 - If vaultDiagnostics.blockers is present in the compact map, keep Story read-only but surface the blocker state in summaryLine and the relevant claim card riskOrGapSummary when applicable. Include diagnostic file/nodeId/code/message/suggestedAction in display copy; do not invent missing evidence, source trace, quotes, or caveats to hide the blocker.
 - Do not turn Story into a workflow dashboard: diagnostic copy is for reading context only, not command suggestions or mutation planning.
+- Story UI is evidence-first: clicking a claim shows evidence/gap cards; evidence cards must carry the evidence description, why it supports the claim, and source trace; clicking evidence shows only canonical gaps linked to that evidence.
+- The selected-claim panel is only an evidence/research-gap card list. Do not repeat canonical claim text there; the claim itself is already visible in Claim Flow.
+- Claim cards should not explain gaps or risks through riskOrGapSummary when the same topic belongs in evidence/gap cards. Keep claim cards focused on role, narrative job, and evidence summary.
+- Do not make evidence detail a schema dump. Do not default to unsupportedScope, caveat, IDs, target fields, or evidenceBindingIds for evidence cards; evidence cards should explain what the source says, why it supports the claim, and where it came from.
+- Do not invent, infer, or soften new gaps in display copy. Show research gaps only when they exist in compactMap.researchGaps; do not turn unsupportedScope, weak evidence, caveats, objections, risks, or your own judgment into a gap.
+- researchGapsSummary and riskOrGapSummary may only summarize existing canonical research gaps or diagnostics. If no canonical gap exists for the claim, leave gap-specific display copy empty instead of implying a gap.
+- Localize new Story labels when useful: selectedEvidence, evidenceList, gap, gaps, noEvidence, selectEvidencePrompt, sourceTrace, evidenceSource, whyThisSupports, linkedGaps, selectedGap, and noLinkedGaps.
+- Gap detail may only use canonical research gap fields from the compact map: id, targetType, targetId, status, priority, question, findingsFile, evidenceBindingIds, and notes.
 
 Chinese localization rules when the target language request is Chinese, zh, zh-CN, --cn, 中文, or Simplified Chinese:
 - Use natural business/manufacturing Chinese, not word-by-word machine translation.

package/lib/commands/review.ts

@@ -94,15 +94,16 @@ Workflow:
 3. If the read summary returned \`markdownQa.blockers\` or \`vaultDiagnostics.blockers\`, stop before deck planning and report Markdown QA repair cards separately from compile diagnostics with file/node/code/message and smallest repair or suggested next action. If narrative readiness is \`approved\`, continue. If it is \`ready_for_approval\`, ask the user for explicit approval before continuing. If it is blocked, stale, or needs research, stop and report the smallest next action. Do not call \`approveNarrative\` unless the user explicitly approves or requests a render override.
 4. After approval or explicit render override exists, call \`revela-decks\` action \`compileDeckPlan\`. This projects canonical narrative claims and evidence bindings into compatibility \`slides[]\` and \`slides[].evidence[]\`; it must not write HTML.
 5. If \`compileDeckPlan\` returns \`skipped\`, stop and report the reason. Do not invent slide specs manually to bypass approval.
-6. Present the compiled deck plan to the user and include a low-fidelity layout sketch for every slide. The plan must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. The sketch is ASCII/text structure only; do not generate visual images or HTML mockups.
-7. Stop after presenting the plan. Ask the user to confirm or request changes. Do not call \`revela-decks review\`, do not fetch design context, and do not write HTML in the same turn unless the user had already explicitly confirmed the current plan before this command.
-8. Only after explicit user confirmation of the current slide plan, call \`revela-decks\` action \`confirmDeckPlan\` with \`approvalBy=user\` and a compact \`approvalNote\`.
-9. After confirmation is recorded, ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
-10. Update only deck/artifact metadata through \`revela-decks upsertDeck\` / \`upsertSlides\` when required by confirmed design/layout choices. Do not change canonical narrative claims unless the user asks to revise the narrative.
-11. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing. If it reports \`slide_plan_unconfirmed\`, stop and ask for explicit deck-plan confirmation.
-12. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
-13. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
-14. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Review.
+6. Treat each compiled slide's \`visuals[]\` and \`content.data.visualIntent\` as required render instructions, not optional decoration. Do not downgrade a planned chart, metric card, evidence table, comparison grid, risk matrix, steps view, or media brief into generic bullets unless the plan is revised and reconfirmed.
+7. Present the compiled deck plan to the user and include a low-fidelity layout sketch for every slide. The plan must identify the chapter structure first: 3-5 chapter headings, each chapter's slide range, and which non-structural slides belong to each chapter. The sketch is ASCII/text structure only; do not generate visual images or HTML mockups.
+8. Stop after presenting the plan. Ask the user to confirm or request changes. Do not call \`revela-decks review\`, do not fetch design context, and do not write HTML in the same turn unless the user had already explicitly confirmed the current plan before this command.
+9. Only after explicit user confirmation of the current slide plan, call \`revela-decks\` action \`confirmDeckPlan\` with \`approvalBy=user\` and a compact \`approvalNote\`.
+10. After confirmation is recorded, ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
+11. Update only deck/artifact metadata through \`revela-decks upsertDeck\` / \`upsertSlides\` when required by confirmed design/layout choices. Do not change canonical narrative claims unless the user asks to revise the narrative.
+12. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing. If it reports \`slide_plan_unconfirmed\`, stop and ask for explicit deck-plan confirmation.
+13. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. Generate the artifact chapter by chapter instead of drafting all content slides in one broad pass. Keep the HTML file valid after every write, preserve already-written slides, and update one chapter's slide sections at a time.
+14. For each chapter, make every content slide carry a distinct claim, evidence item, comparison, risk, or action. If a chapter lacks enough substance for its allocated slides, merge weak slides or reduce the slide count instead of creating sparse filler.
+15. After each HTML write, the system automatically runs artifact QA before opening Review. If post-write artifact QA reports hard errors, fix them and let QA run again. Review opens only after hard errors pass. Density warnings about thin claim/evidence substance should be reported and improved when useful, but they do not block Review.
 
 Deck plan report format:
 - Start with \`Deck plan: awaiting confirmation\` when a plan was compiled and has not yet been confirmed.
@@ -111,7 +112,7 @@ Deck plan report format:
 - Include whether \`compileDeckPlan\` compiled or skipped.
 - Include \`Required structure: Cover + Table of Contents + Closing\` and do not omit any of those slides.
 - Include a \`Chapters\` section before the slide list. It must list 3-5 TOC headings, their slide ranges, and the non-structural slides assigned to each chapter.
-- For every slide, include: slide index, title, purpose, narrative role, low-fidelity layout sketch, layout, components, primary/supporting claim ids, evidence binding ids or source summary, visual intent, and caveats/unsupported scope.
+- For every slide, include: slide index, title, purpose, narrative role, low-fidelity layout sketch, layout, components, primary/supporting claim ids, evidence binding ids or source summary, visual intent from \`content.data.visualIntent\`, visual brief from \`visuals[]\`, and caveats/unsupported scope.
 - Use this sketch style or similarly simple ASCII boxes:
 
 \`\`\`text
@@ -133,6 +134,8 @@ Components:
 Primary claim:
 Supporting claims:
 Evidence bindings:
+Visual intent:
+Visual brief:
 Caveats / unsupported scope:
 \`\`\`
 - End by asking the user to confirm the deck plan or request changes.
@@ -146,6 +149,7 @@ Report format before any HTML write after confirmation:
 
 Rules:
 - \`compileDeckPlan\` is the canonical narrative-to-deck planning path. Do not manually invent slide specs to avoid it.
+- Visual intent is part of the confirmed plan. During HTML generation, satisfy the planned component/visual brief using fetched design components; do not collapse planned visuals into prose-only bullets.
 - Deck slide specs are render-target projections. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, risks, and approval.
 - Cover, Table of Contents, and Closing are mandatory deck structure. TOC chapter headings must match the chapter grouping used for generation.
 - Do not generate the complete deck content in one broad pass after confirmation. Work chapter by chapter while keeping the artifact valid after each write.

package/lib/media/download.ts

@@ -12,6 +12,10 @@ const MIME_TO_EXT: Record<string, string> = {
 
 const ALLOWED_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".svg", ".webp", ".gif", ".ico"])
 const DEFAULT_DOWNLOAD_TIMEOUT_MS = 10_000
+const PRODUCT_USER_AGENT = "Revela/0.17 asset-save"
+const BROWSER_USER_AGENT =
+  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+  "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
 
 function normalizeExtension(ext: string): string {
   const value = ext.toLowerCase()
@@ -47,6 +51,24 @@ export async function downloadImageFromUrl(
     throw new Error("INVALID_URL")
   }
 
+  const userAgents = [PRODUCT_USER_AGENT, BROWSER_USER_AGENT]
+  let lastError: unknown
+  for (const userAgent of userAgents) {
+    try {
+      return await downloadWithUserAgent(parsed, userAgent, options)
+    } catch (error) {
+      lastError = error
+    }
+  }
+
+  throw lastError instanceof Error ? lastError : new Error(String(lastError))
+}
+
+async function downloadWithUserAgent(
+  parsed: URL,
+  userAgent: string,
+  options: { timeoutMs?: number },
+): Promise<{ buffer: Buffer; contentType: string | null; extension: string }> {
   const controller = new AbortController()
   let timedOut = false
   const timer = setTimeout(() => {
@@ -60,9 +82,7 @@ export async function downloadImageFromUrl(
     response = await fetch(parsed, {
       headers: {
         Accept: "image/avif,image/webp,image/apng,image/svg+xml,image/*,*/*;q=0.8",
-        "User-Agent":
-          "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
-          "(KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
+        "User-Agent": userAgent,
       },
       signal: controller.signal,
     })

package/lib/media/save.ts

@@ -141,6 +141,7 @@ function saveFailureResult(
     path: null,
     manifestPath: relative(workspaceDir, manifestPath),
     updated: true,
+    failureReason,
   }
 }
 

package/lib/media/types.ts

@@ -59,6 +59,7 @@ export type MediaSaveResult =
     path: string | null
     manifestPath: string
     updated: boolean
+    failureReason?: string
   }
   | {
     ok: false

package/lib/narrative-state/display.ts

@@ -9,6 +9,7 @@ export interface NarrativeDisplayModel {
   summaryLine?: string
   labels?: Partial<NarrativeDisplayLabels>
   claimCards?: NarrativeDisplayClaimCard[]
+  researchGapCards?: NarrativeDisplayResearchGapCard[]
   relations?: NarrativeDisplayRelation[]
 }
 
@@ -17,6 +18,18 @@ export interface NarrativeDisplayLabels {
   claimFlow: string
   flowNote: string
   selectedClaim: string
+  selectedEvidence: string
+  evidenceList: string
+  gap: string
+  gaps: string
+  noEvidence: string
+  selectEvidencePrompt: string
+  sourceTrace: string
+  evidenceSource: string
+  whyThisSupports: string
+  linkedGaps: string
+  selectedGap: string
+  noLinkedGaps: string
   claim: string
   claimId: string
   status: string
@@ -48,6 +61,11 @@ export interface NarrativeDisplayClaimCard {
   researchGapsSummary?: string
 }
 
+export interface NarrativeDisplayResearchGapCard {
+  gapId: string
+  displayQuestion?: string
+}
+
 export interface NarrativeDisplayRelation {
   fromClaimId: string
   toClaimId: string
@@ -63,6 +81,7 @@ export interface ValidatedNarrativeDisplayModel {
   summaryLine?: string
   labels: NarrativeDisplayLabels
   claimCards: Map<string, NarrativeDisplayClaimCard>
+  researchGapCards: Map<string, NarrativeDisplayResearchGapCard>
   relations: Map<string, NarrativeDisplayRelation>
 }
 
@@ -71,8 +90,20 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
     return {
       eyebrow: "只读主张流",
       claimFlow: "主张推进",
-      flowNote: "点击主张查看证据、关系、风险、缺口和已覆盖页面。",
+      flowNote: "点击主张查看论据和真实存在的缺口；点击论据查看它关联的缺口。",
       selectedClaim: "当前主张",
+      selectedEvidence: "当前论据",
+      evidenceList: "论据",
+      gap: "缺口",
+      gaps: "缺口",
+      noEvidence: "没有绑定论据",
+      selectEvidencePrompt: "选择一条论据或缺口查看详情",
+      sourceTrace: "来源追踪",
+      evidenceSource: "来源",
+      whyThisSupports: "为什么支撑论点",
+      linkedGaps: "这条论据关联的缺口",
+      selectedGap: "当前缺口",
+      noLinkedGaps: "这条论据没有关联缺口",
       claim: "主张",
       claimId: "主张 ID",
       status: "状态",
@@ -93,8 +124,20 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
     return {
       eyebrow: "読み取り専用クレームフロー",
       claimFlow: "クレームフロー",
-      flowNote: "クレームをクリックすると、根拠、関係、リスク、ギャップ、該当スライドを確認できます。",
+      flowNote: "クレームをクリックして根拠と実在するギャップを確認し、根拠をクリックして紐づくギャップを確認します。",
       selectedClaim: "選択中のクレーム",
+      selectedEvidence: "選択中の根拠",
+      evidenceList: "根拠",
+      gap: "ギャップ",
+      gaps: "ギャップ",
+      noEvidence: "紐づいた根拠はありません",
+      selectEvidencePrompt: "根拠またはギャップを選択して詳細を確認してください",
+      sourceTrace: "出典トレース",
+      evidenceSource: "出典",
+      whyThisSupports: "この根拠がクレームを支える理由",
+      linkedGaps: "この根拠に紐づくギャップ",
+      selectedGap: "選択中のギャップ",
+      noLinkedGaps: "この根拠に紐づくギャップはありません",
       claim: "クレーム",
       claimId: "クレーム ID",
       status: "ステータス",
@@ -114,8 +157,20 @@ export function defaultNarrativeDisplayLabels(language: NarrativeViewLanguage):
   return {
     eyebrow: "Read-only claim flow board",
     claimFlow: "Claim Flow",
-    flowNote: "Click a claim to inspect support, relation context, gaps, and covered slides.",
+    flowNote: "Click a claim to read its evidence and real gaps; click evidence to see gaps linked to that evidence.",
     selectedClaim: "Selected claim",
+    selectedEvidence: "Selected evidence",
+    evidenceList: "Evidence",
+    gap: "Gap",
+    gaps: "Gaps",
+    noEvidence: "No evidence bound",
+    selectEvidencePrompt: "Select evidence or a gap to inspect details.",
+    sourceTrace: "Source trace",
+    evidenceSource: "Source",
+    whyThisSupports: "Why this supports the claim",
+    linkedGaps: "Gaps linked to evidence",
+    selectedGap: "Selected gap",
+    noLinkedGaps: "No gaps linked to this evidence.",
     claim: "Claim",
     claimId: "Claim ID",
     status: "Status",
@@ -140,6 +195,7 @@ export function validateNarrativeDisplayModel(map: NarrativeMap, input: Narrativ
   if (input.language !== language) throw new Error(`Narrative display model language must be ${language}.`)
 
   const claimIds = new Set(map.claimFlow.map((claim) => claim.id))
+  const gapIds = new Set(map.researchGaps.map((gap) => gap.id))
   const relationByKey = new Map(map.claimRelations.map((relation) => [relationKey(relation), relation]))
   const claimCards = new Map<string, NarrativeDisplayClaimCard>()
   for (const card of input.claimCards ?? []) {
@@ -147,6 +203,12 @@ export function validateNarrativeDisplayModel(map: NarrativeMap, input: Narrativ
     claimCards.set(card.claimId, cleanClaimCard(card))
   }
 
+  const researchGapCards = new Map<string, NarrativeDisplayResearchGapCard>()
+  for (const card of input.researchGapCards ?? []) {
+    if (!gapIds.has(card.gapId)) throw new Error(`Unknown display gapId: ${card.gapId}`)
+    researchGapCards.set(card.gapId, cleanResearchGapCard(card))
+  }
+
   const relations = new Map<string, NarrativeDisplayRelation>()
   for (const relation of input.relations ?? []) {
     const key = relationKey(relation)
@@ -162,12 +224,13 @@ export function validateNarrativeDisplayModel(map: NarrativeMap, input: Narrativ
     summaryLine: clean(input.summaryLine),
     labels: mergeLabels(defaults, input.labels),
     claimCards,
+    researchGapCards,
     relations,
   }
 }
 
 export function emptyDisplayModel(language: NarrativeViewLanguage, labels = defaultNarrativeDisplayLabels(language)): ValidatedNarrativeDisplayModel {
-  return { version: 1, language, labels, claimCards: new Map(), relations: new Map() }
+  return { version: 1, language, labels, claimCards: new Map(), researchGapCards: new Map(), relations: new Map() }
 }
 
 export function relationKey(relation: Pick<NarrativeDisplayRelation, "fromClaimId" | "toClaimId" | "relation">): string {
@@ -210,6 +273,13 @@ function cleanClaimCard(card: NarrativeDisplayClaimCard): NarrativeDisplayClaimC
   }
 }
 
+function cleanResearchGapCard(card: NarrativeDisplayResearchGapCard): NarrativeDisplayResearchGapCard {
+  return {
+    gapId: card.gapId,
+    displayQuestion: clean(card.displayQuestion),
+  }
+}
+
 function cleanRelation(relation: NarrativeDisplayRelation, canonical: NarrativeMapClaimRelation): NarrativeDisplayRelation {
   const displayLabel = clean(relation.displayLabel)
   const displayRationale = clean(relation.displayRationale)