@cyber-dash-tech/revela 0.11.0 → 0.13.0

package/lib/commands/narrative.ts

@@ -0,0 +1,160 @@
+import { mkdirSync, writeFileSync } from "fs"
+import { tmpdir } from "os"
+import { join } from "path"
+import { openUrl as defaultOpenUrl } from "../edit/open"
+import { hasDecksState, readDecksState } from "../decks-state"
+import { buildNarrativeMap, formatNarrativeMap } from "../narrative-state/map"
+import { renderNarrativeMapHtmlWithDisplay } from "../narrative-state/map-html"
+import { emptyDisplayModel, type NarrativeViewLanguage, type ValidatedNarrativeDisplayModel } from "../narrative-state/display"
+
+export interface NarrativeArgs {
+  language: NarrativeViewLanguage
+  raw: boolean
+}
+
+export type ParseNarrativeArgsResult = { ok: true; args: NarrativeArgs } | { ok: false; error: string }
+
+export function parseNarrativeArgs(param: string): ParseNarrativeArgsResult {
+  const tokens = param.trim().split(/\s+/).filter(Boolean)
+  let language: NarrativeViewLanguage = "en"
+  let raw = false
+  const languageParts: string[] = []
+  for (const token of tokens) {
+    const normalized = token.toLowerCase()
+    if (normalized === "--raw") {
+      raw = true
+      continue
+    }
+    if (token.startsWith("--") && token.length > 2) {
+      language = normalizeLanguageRequest(token.slice(2))
+      continue
+    }
+    languageParts.push(token)
+  }
+  if (languageParts.length > 0) language = normalizeLanguageRequest(languageParts.join(" "))
+  return { ok: true, args: { language, raw } }
+}
+
+function normalizeLanguageRequest(value: string): NarrativeViewLanguage {
+  const trimmed = value.trim()
+  const normalized = trimmed.toLowerCase()
+  if (["en", "eng", "english"].includes(normalized)) return "en"
+  if (["cn", "zh", "zh-cn", "chinese"].includes(normalized)) return "zh-CN"
+  if (["jp", "ja", "ja-jp", "japanese"].includes(normalized)) return "ja-JP"
+  return trimmed || "en"
+}
+
+export async function handleNarrative(
+  options: { workspaceRoot: string; openBrowser?: boolean; openUrl?: (url: string) => void; language?: NarrativeViewLanguage; display?: ValidatedNarrativeDisplayModel },
+  send: (text: string) => Promise<void>,
+): Promise<void> {
+  try {
+    if (!hasDecksState(options.workspaceRoot)) {
+      await send("No `DECKS.json` found. Run `/revela init` first to initialize the narrative workspace.")
+      return
+    }
+
+    const state = readDecksState(options.workspaceRoot)
+    const map = buildNarrativeMap(state)
+    const markdown = formatNarrativeMap(map)
+
+    if (options.openBrowser) {
+      const htmlPath = writeNarrativeMapHtml(map, options.display ?? emptyDisplayModel(options.language ?? "en"))
+      const url = `file://${htmlPath}`
+      try {
+        ;(options.openUrl ?? defaultOpenUrl)(url)
+        await send(`Opened read-only narrative workspace: ${url}\n\n${markdown}`)
+      } catch (e: any) {
+        await send(`Read-only narrative workspace generated but could not open automatically: ${url}\n\n${e.message || String(e)}\n\n${markdown}`)
+      }
+      return
+    }
+
+    await send(markdown)
+  } catch (e: any) {
+    await send(`**Narrative map failed:** ${e.message || String(e)}`)
+  }
+}
+
+export function buildNarrativeViewPrompt(options: { workspaceRoot: string; language: NarrativeViewLanguage }): string {
+  if (!hasDecksState(options.workspaceRoot)) {
+    return "No `DECKS.json` found. Tell the user to run `/revela init` before opening the narrative view. Do not call any tool."
+  }
+
+  const map = buildNarrativeMap(readDecksState(options.workspaceRoot))
+  const projection = {
+    narrativeHash: map.snapshot.narrativeHash,
+    language: options.language,
+    snapshot: map.snapshot,
+    claims: map.claimFlow.map((claim) => ({
+      id: claim.id,
+      kind: claim.kind,
+      importance: claim.importance,
+      evidenceStatus: claim.evidenceStatus,
+      text: claim.text,
+      supportedScope: claim.supportedScope,
+      unsupportedScope: claim.unsupportedScope,
+      evidence: claim.evidence.map((evidence) => ({ source: evidence.source, strength: evidence.strength, findingsFile: evidence.findingsFile, location: evidence.location, quote: evidence.quote, caveat: evidence.caveat, unsupportedScope: evidence.unsupportedScope })),
+    })),
+    relations: map.claimRelations.map((relation) => ({ id: relation.id, fromClaimId: relation.fromClaimId, toClaimId: relation.toClaimId, relation: relation.relation, rationale: relation.rationale, inferred: relation.inferred })),
+    researchGaps: map.researchGaps.map((gap) => ({ id: gap.id, targetType: gap.targetType, targetId: gap.targetId, status: gap.status, priority: gap.priority, question: gap.question })),
+    artifactCoverage: map.artifactCoverage.map((artifact) => ({ type: artifact.type, outputPath: artifact.outputPath, stale: artifact.stale, slideRefs: artifact.slideRefs.map((ref) => ({ claimId: ref.claimId, slideIndex: ref.slideIndex, role: ref.role, match: ref.match, location: ref.location })) })),
+  }
+
+  return `Prepare the read-only Revela narrative UI display model.
+
+Target language request: ${options.language}
+- The language value is passed from the user's /revela narrative arguments. Interpret it as the desired UI/display language.
+- Examples: --cn maps to zh-CN, --jp maps to ja-JP, while --fr, --de, --es, --ko, --Arabic, --Portuguese-BR, or a written language name should be localized normally into that requested language.
+- Default /revela narrative language is en when the user provides no language request.
+
+You must call the \`revela-narrative-view\` tool exactly once.
+
+Hard rules:
+- Do not mutate DECKS.json, deck HTML, evidence, claims, relations, approvals, or artifacts.
+- 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, riskOrGapSummary, 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, riskOrGapSummary, relation displayLabel, and relation displayRationale.
+- Do not translate claim IDs, relation endpoints, narrative hash, source paths, findings files, URLs, numbers, or quoted/source facts.
+- 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.
+
+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.
+- In manufacturing, industrial AI, automation, and autonomous systems context, translate "autonomy" as "自主化", "自主能力", or "自主系统". Do not translate it as "自治".
+- Translate "autonomous" as "自主的" / "自主化的" where appropriate, not "自治的".
+- Translate "architectural" as "架构层面的", "架构性", or "架构问题" according to context.
+- Slug-like or kebab-case claim text such as "autonomy-is-architectural" should become a readable displayTitle such as "自主化是架构问题" or "自主化必须作为架构问题处理", not a literal token-by-token translation.
+- If the canonical claim text is only a slug, preserve the claimId exactly but write displayTitle as a readable claim title.
+
+Call \`revela-narrative-view\` with:
+- language: ${options.language}
+- narrativeHash: ${map.snapshot.narrativeHash}
+- displayModel.version: 1
+- displayModel.language: ${options.language}
+- displayModel.claimCards only for claim IDs listed below
+- displayModel.relations only for relations listed below
+
+Compact deterministic narrative map:
+
+\`\`\`json
+${JSON.stringify(projection, null, 2)}
+\`\`\``
+}
+
+export function writeNarrativeMapHtml(map: ReturnType<typeof buildNarrativeMap>, display: ValidatedNarrativeDisplayModel = emptyDisplayModel("en")): string {
+  const dir = join(tmpdir(), "revela-narrative")
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, `${safeFilePart(map.snapshot.narrativeId)}-${map.snapshot.narrativeHash}.html`)
+  writeFileSync(file, renderNarrativeMapHtmlWithDisplay(map, display), "utf-8")
+  return file
+}
+
+function safeFilePart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "narrative"
+}

package/lib/commands/review.ts

@@ -6,15 +6,129 @@ export function buildReviewPrompt({
 }: {
   exists: boolean
   workspaceRoot?: string
+}): string {
+  const state = exists
+    ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
+    : `${DECKS_STATE_FILE} does not exist yet. Create or normalize it through the revela-decks tool only if there is enough workspace narrative context.`
+
+  return `Review Revela narrative readiness.
+
+Goal:
+- Use ${DECKS_STATE_FILE} as the compatibility workspace-state file, but review the canonical narrative state first: audience, belief shift, decision/action, thesis, central claims, evidence boundaries, objections, risks, and approval state.
+- Treat this as a narrative readiness review, not a deck HTML write-readiness review.
+- Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
+- Call \`revela-decks\` action \`reviewNarrative\` as the authoritative deterministic readiness engine.
+- Do not call \`revela-decks\` action \`review\` here. That action is the deck/artifact gate and belongs to \`/revela deck --review\`.
+- Do not treat legacy \`writeReadiness.status\`, old review snapshots, or an existing HTML deck as narrative approval.
+- Do not write or overwrite \`decks/*.html\` during narrative review.
+- If the narrative is \`ready_for_approval\`, ask whether the user wants to approve it or revise it. Do not approve automatically.
+- Only call \`revela-decks\` action \`approveNarrative\` when the user explicitly asks to approve or override.
+
+Current state:
+- ${state}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workspace boundary rules:
+- Stay strictly inside the current workspace root for every scan, glob, read, and write.
+- Do not search parent directories, home directories, or unrelated absolute directories.
+- Do not use \`~\`, \`..\`, or parent-directory traversal to discover files.
+- For Glob/file searches, use the current workspace as the search root. Do not set the search root to a parent directory or home directory.
+
+Workflow:
+1. Call \`revela-decks\` with action \`read\` to inspect the current workspace state.
+2. If ${DECKS_STATE_FILE} is missing or empty, do not invent a deck plan, slide count, design, output path, or visual style. Report the smallest narrative inputs needed, usually audience, belief-before, belief-after, decision/action, thesis, central claims, evidence availability, objections, and risks.
+3. If legacy deck state exists, let the tool-normalized canonical narrative derived from \`narrativeBrief\`, slide roles, slide content, and slide evidence be reviewed. Do not assume old deck readiness means approval.
+4. Call \`revela-decks\` action \`reviewNarrative\`. Use its returned \`status\`, \`blockers\`, \`warnings\`, \`issues\`, \`narrativeHash\`, \`approval\`, and \`nextActions\` as authoritative.
+5. If research findings have been saved but not attached or evidence-bound, report them as unattached research state, not proof.
+6. If central claims lack required evidence, report the named claim and the exact next action: attach findings, bind evidence, run targeted research, narrow unsupported scope, or rewrite the claim.
+7. If approval is missing or stale, clearly distinguish \`ready_for_approval\`, \`approved\`, and render override.
+
+Report format:
+- Start with \`Narrative readiness: <status>\`.
+- Include \`Narrative hash: <hash>\` when returned.
+- If blocked or needs research, list each blocker with issue type, claim text when available, and suggested next action.
+- If warnings exist, list them after blockers as residual risks.
+- If approval is missing, ask whether the user wants to approve the narrative or revise it.
+- If approval is stale, say the prior approval no longer matches the current narrative hash.
+- Keep deck/artifact readiness separate. If the user wants to review slide-writing readiness, tell them to run \`/revela deck --review\`.
+
+Rules:
+- Do not write or overwrite \`decks/*.html\` during narrative review.
+- Do not call \`revela-decks review\` during narrative review.
+- Do not apply evidence candidates, bind evidence, or rewrite slide text unless the user explicitly asks.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+- Do not add inferred user preferences to long-term preference state.
+
+Start now by reading ${DECKS_STATE_FILE} through \`revela-decks\`, then call \`revela-decks\` action \`reviewNarrative\`.`
+}
+
+export function buildDeckPrompt({
+  exists,
+  workspaceRoot,
+}: {
+  exists: boolean
+  workspaceRoot?: string
+}): string {
+  const state = exists
+    ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
+    : `${DECKS_STATE_FILE} does not exist yet. Do not invent a deck; initialize narrative state first with /revela init.`
+
+  return `Begin Revela deck render handoff.
+
+Goal:
+- Treat this as the explicit transition from approved narrative state to deck render planning.
+- Use the deck-render prompt mode for design, layout, component, HTML, QA, and deck artifact rules.
+- Do not write or overwrite \`decks/*.html\` until the narrative handoff and deck/artifact gate are both satisfied.
+- Do not treat legacy \`writeReadiness.status\`, old review snapshots, or existing HTML decks as narrative approval.
+- Do not bypass the deck HTML contract, review snapshot freshness, source-trace expectations, or export preflight protections.
+
+Current state:
+- ${state}
+${workspaceRoot ? `- Current workspace root: \`${workspaceRoot}\`` : ""}
+
+Workflow:
+1. Call \`revela-decks\` action \`read\`.
+2. Call \`revela-decks\` action \`reviewNarrative\` before planning deck slides.
+3. 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. Ask for or confirm visual design only after the narrative deck plan exists. Fetch required design layouts/components with \`revela-designs read\` as needed.
+7. 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.
+8. Call \`revela-decks\` action \`review\` as the artifact gate. It computes \`writeReadiness\` and review snapshots for deck HTML writing.
+9. Write \`decks/*.html\` only if the deck/artifact gate is ready and all deck HTML contract requirements can be satisfied. If not ready, report blockers and stop.
+
+Report format before any HTML write:
+- Start with \`Deck handoff: <status>\`.
+- Include narrative readiness status and narrative hash when available.
+- Include whether \`compileDeckPlan\` compiled or skipped.
+- If deck/artifact review is blocked, list blockers separately from narrative blockers.
+- If proceeding to HTML writing, state which approved narrative hash and deck review snapshot authorized the artifact work.
+
+Rules:
+- \`compileDeckPlan\` is the canonical narrative-to-deck planning path. Do not manually invent slide specs to avoid it.
+- Deck slide specs are render-target projections. Canonical narrative remains the authority for audience, decision, claims, evidence boundaries, objections, risks, and approval.
+- Applying evidence candidates, rewriting canonical claims, or approving narratives requires explicit user instruction.
+- Do not store secrets, credentials, tokens, or sensitive personal information.
+
+Start now by reading ${DECKS_STATE_FILE}, reviewing narrative readiness, and then compiling the deck plan only if approval or explicit render override is current.`
+}
+
+export function buildDeckReviewPrompt({
+  exists,
+  workspaceRoot,
+}: {
+  exists: boolean
+  workspaceRoot?: string
 }): string {
   const state = exists
     ? `${DECKS_STATE_FILE} exists. Read it through the revela-decks tool.`
     : `${DECKS_STATE_FILE} does not exist yet. Create it through the revela-decks tool if there is enough deck context.`
 
-  return `Review Revela deck write readiness.
+  return `Review Revela deck/artifact write readiness.
 
 Goal:
 - Use ${DECKS_STATE_FILE} as the source of truth for whether the current workspace deck is ready to be written to \`decks/*.html\`.
+- Treat this as an artifact gate for deck rendering, not strategic narrative approval. Narrative readiness is reviewed by \`/revela review\`.
 - Preserve the deck spec for future sessions: every slide's content, layout, components, evidence, visuals, production status, and the 0.9 narrative compiler brief when available.
 - Do not write, patch, or directly edit ${DECKS_STATE_FILE}. Use the \`revela-decks\` tool for all state changes.
 - Let \`revela-decks\` action \`review\` compute writeReadiness; do not manually set readiness to ready.

package/lib/decks-state.ts

@@ -17,6 +17,8 @@ import {
   latestReviewSnapshotForTarget,
 } from "./workspace-state/review-snapshots"
 import { WORKSPACE_STATE_FILE, type RenderTarget, type ReviewSnapshot, type WorkspaceAction } from "./workspace-state/types"
+import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "./narrative-state/normalize"
+import type { NarrativeStateV1 } from "./narrative-state/types"
 
 export const DECKS_STATE_FILE = WORKSPACE_STATE_FILE
 
@@ -24,10 +26,12 @@ export type DeckProductionStatus = "planning" | "blocked" | "ready" | "written"
 export type SlideProductionStatus = "planned" | "ready" | "written" | "qa_passed" | "qa_failed"
 export type WriteReadinessStatus = "blocked" | "ready" | "written"
 export type NarrativeRole = "context" | "tension" | "evidence" | "recommendation" | "risk" | "ask" | "appendix" | "close"
+export type SlideClaimRefRole = "primary" | "supporting" | "evidence" | "risk" | "objection"
 
 export interface DecksState {
   version: 1
   activeDeck?: string
+  narrative?: NarrativeStateV1
   workspace: {
     brief?: string
     sourceMaterials: SourceMaterial[]
@@ -132,6 +136,9 @@ export interface SlideSpec {
   layout: string
   qa?: boolean
   components: string[]
+  claimIds?: string[]
+  claimRefs?: SlideClaimRef[]
+  evidenceBindingIds?: string[]
   content: {
     headline?: string
     body?: string[]
@@ -145,6 +152,12 @@ export interface SlideSpec {
   notes?: string
 }
 
+export interface SlideClaimRef {
+  claimId: string
+  role: SlideClaimRefRole
+  note?: string
+}
+
 export interface EvidenceRef {
   source: string
   quote?: string
@@ -349,15 +362,15 @@ export function createDeckSpec(input: Partial<DeckSpec> & { slug: string }): Dec
 }
 
 export function readDecksState(workspaceRoot: string): DecksState {
-  return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
+  return readWorkspaceState(workspaceRoot, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
 }
 
 export function writeDecksState(workspaceRoot: string, state: DecksState): void {
-  writeWorkspaceState(workspaceRoot, state, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
+  writeWorkspaceState(workspaceRoot, state, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
 }
 
 export function readOrCreateDecksState(workspaceRoot: string): DecksState {
-  return readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksState })
+  return readOrCreateWorkspaceState(workspaceRoot, createEmptyDecksState, { fileName: DECKS_STATE_FILE, normalize: normalizeDecksStateWithNarrative })
 }
 
 export function upsertDeck(state: DecksState, input: Partial<DeckSpec> & { slug: string }): DecksState {
@@ -717,6 +730,7 @@ function normalizeDecksState(input: DecksState): DecksState {
   const state: DecksState = {
     version: 1,
     activeDeck: input.activeDeck ? normalizeSlug(input.activeDeck) : undefined,
+    narrative: normalizeCanonicalNarrativeState(input.narrative, input.activeDeck || "workspace"),
     workspace: {
       brief: input.workspace?.brief,
       sourceMaterials: input.workspace?.sourceMaterials ?? [],
@@ -745,6 +759,12 @@ function normalizeDecksState(input: DecksState): DecksState {
   return state
 }
 
+function normalizeDecksStateWithNarrative(input: DecksState): DecksState {
+  const state = normalizeDecksState(input)
+  if (!state.narrative && currentDeckKey(state)) state.narrative = normalizeNarrativeState(state)
+  return state
+}
+
 function currentDeckKey(state: DecksState): string | undefined {
   if (state.activeDeck && state.decks[state.activeDeck]) return state.activeDeck
   const keys = Object.keys(state.decks)
@@ -1468,6 +1488,9 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
       title: slide.title ?? "",
       layout: slide.layout ?? "",
       components: slide.components ?? [],
+      claimIds: normalizeTextList(slide.claimIds),
+      claimRefs: normalizeSlideClaimRefs(slide.claimRefs),
+      evidenceBindingIds: normalizeTextList(slide.evidenceBindingIds),
       content: slide.content ?? {},
       evidence: slide.evidence ?? [],
       status: slide.status ?? "planned",
@@ -1475,6 +1498,26 @@ function normalizeSlides(slides: SlideSpec[]): SlideSpec[] {
     .sort((a, b) => a.index - b.index)
 }
 
+function normalizeSlideClaimRefs(refs: SlideClaimRef[] | undefined): SlideClaimRef[] {
+  const seen = new Set<string>()
+  const out: SlideClaimRef[] = []
+  for (const ref of refs ?? []) {
+    const claimId = cleanOptionalText(ref.claimId)
+    if (!claimId) continue
+    const role = isSlideClaimRefRole(ref.role) ? ref.role : "supporting"
+    const key = `${claimId}:${role}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    const note = cleanOptionalText(ref.note)
+    out.push({ claimId, role, ...(note ? { note } : {}) })
+  }
+  return out
+}
+
+function isSlideClaimRefRole(value: string | undefined): value is SlideClaimRefRole {
+  return value === "primary" || value === "supporting" || value === "evidence" || value === "risk" || value === "objection"
+}
+
 function normalizeNarrativeBrief(brief: NarrativeBrief | undefined): NarrativeBrief | undefined {
   if (!brief) return undefined
   const normalized: NarrativeBrief = {

package/lib/edit/prompt.ts

@@ -71,6 +71,9 @@ Instructions:
 - Make the smallest targeted change that satisfies the user's comment.
 - If there are multiple comments, apply them as one coherent edit pass and avoid changes from one comment overwriting another.
 - Each comment may reference one or more selected elements. Treat the elements in a single comment as a group.
+- Preserve the narrative boundary: if the requested edit changes audience framing, belief shift, decision/action, thesis, recommendation, claim wording, evidence scope, caveat, risk, objection, or decision ask, do not patch the HTML directly. Explain that the canonical narrative must be updated first through ${"`revela-decks`"} action ${"`upsertNarrative`"}, then reviewed/approved or explicitly overridden before updating the deck projection.
+- Pure artifact polish such as layout, spacing, typography, alignment, color, image crop, animation, export fidelity, or deck HTML contract fixes may remain an artifact-level edit.
+- If the request mixes content meaning and visual polish, treat it as narrative-impacting unless the user clarifies otherwise.
 - Preserve the existing deck structure, active design language, typography, spacing system, animations, and slide count unless the comment explicitly asks otherwise.
 - Do not rewrite unrelated slides or broad sections of the deck.
 - Locate each target primarily with slideIndex, slideTitle, selected text, nearbyText, and outerHTMLExcerpt. Use selector/domPath as hints; they may be approximate.