@cyber-dash-tech/revela 0.11.0 → 0.13.0

package/tools/decks.ts

@@ -21,15 +21,53 @@ import { recordWorkspaceAction } from "../lib/workspace-state/actions"
 import { applyEvidenceBindings } from "../lib/workspace-state/evidence-status"
 import { attachResearchFindings } from "../lib/workspace-state/research-attachments"
 import { activeReviewTargetId, latestReviewSnapshotForTarget } from "../lib/workspace-state/review-snapshots"
+import {
+  approveNarrativeState,
+  recordNarrativeApprovalAction,
+  recordNarrativeReviewAction,
+  reviewNarrativeState,
+} from "../lib/narrative-state/readiness"
+import { compileDeckPlanFromNarrative } from "../lib/narrative-state/render-plan"
+import { backfillSlideClaimRefsFromCoverage } from "../lib/narrative-state/coverage"
+import { closeResearchGapInState, deriveResearchGapsFromReadiness, updateResearchGapInState, upsertResearchGapsInState } from "../lib/narrative-state/research-gaps"
+import { normalizeCanonicalNarrativeState, normalizeNarrativeState } from "../lib/narrative-state/normalize"
+import { narrativeToBrief } from "../lib/narrative-state/project-compat"
+import type { NarrativeStateV1 } from "../lib/narrative-state/types"
+
+function mergeNarrativeInput(current: NarrativeStateV1, input: Partial<NarrativeStateV1>): Partial<NarrativeStateV1> {
+  return {
+    ...current,
+    ...input,
+    id: current.id,
+    version: 1,
+    audience: {
+      ...current.audience,
+      ...(input.audience ?? {}),
+    },
+    decision: {
+      ...current.decision,
+      ...(input.decision ?? {}),
+    },
+    thesis: input.thesis ? { ...current.thesis, ...input.thesis } as NarrativeStateV1["thesis"] : current.thesis,
+    claims: input.claims ?? current.claims,
+    claimRelations: input.claimRelations ?? current.claimRelations,
+    evidenceBindings: input.evidenceBindings ?? current.evidenceBindings,
+    objections: input.objections ?? current.objections,
+    risks: input.risks ?? current.risks,
+    researchGaps: input.researchGaps ?? current.researchGaps,
+    approvals: current.approvals,
+    updatedAt: new Date().toISOString(),
+  }
+}
 
 export default tool({
   description:
     `Read and update ${DECKS_STATE_FILE}, Revela's workspace deck state file. ` +
     "Use this tool instead of writing or patching the state file directly. " +
-    "It stores active deck specs, per-slide content/layout/components, and computes write readiness.",
+    "It stores workspace narrative state, active deck specs, per-slide content/layout/components, and computes narrative or deck readiness.",
   args: {
     action: tool.schema
-      .enum(["read", "init", "upsertDeck", "upsertSlides", "review", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
+      .enum(["read", "init", "upsertDeck", "upsertSlides", "upsertNarrative", "compileDeckPlan", "backfillClaimRefs", "review", "reviewNarrative", "approveNarrative", "deriveResearchGaps", "upsertResearchGaps", "updateResearchGap", "closeResearchGap", "applyEvidenceCandidates", "attachResearchFindings", "remember"])
       .describe("Action to perform on DECKS.json."),
     summary: tool.schema.boolean().optional().describe("For read: return a compact summary instead of full state."),
     goal: tool.schema.string().optional().describe("For upsertDeck: deck goal."),
@@ -45,6 +83,88 @@ export default tool({
       objections: tool.schema.array(tool.schema.string()).optional().describe("Likely stakeholder objections or questions the narrative should handle."),
       risks: tool.schema.array(tool.schema.string()).optional().describe("Risks, assumptions, caveats, or tradeoffs that should travel with the narrative."),
     }).optional().describe("For upsertDeck: 0.9 Narrative Compiler brief used to review story intent before writing."),
+    narrative: tool.schema.object({
+      status: tool.schema.enum(["draft", "needs_research", "needs_user_confirmation", "ready_for_approval", "approved"]).optional(),
+      audience: tool.schema.object({
+        primary: tool.schema.string().optional(),
+        secondary: tool.schema.array(tool.schema.string()).optional(),
+        beliefBefore: tool.schema.string().optional(),
+        beliefAfter: tool.schema.string().optional(),
+        decisionContext: tool.schema.string().optional(),
+        successCriteria: tool.schema.array(tool.schema.string()).optional(),
+      }).optional(),
+      decision: tool.schema.object({
+        action: tool.schema.string().optional(),
+        owner: tool.schema.string().optional(),
+        deadline: tool.schema.string().optional(),
+        decisionType: tool.schema.enum(["approve", "invest", "prioritize", "align", "choose", "understand", "other"]).optional(),
+        consequenceOfNoDecision: tool.schema.string().optional(),
+      }).optional(),
+      thesis: tool.schema.object({
+        id: tool.schema.string().optional(),
+        statement: tool.schema.string().optional(),
+        confidence: tool.schema.enum(["high", "medium", "low"]).optional(),
+        caveat: tool.schema.string().optional(),
+      }).optional(),
+      claims: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        kind: tool.schema.enum(["context", "problem", "opportunity", "evidence", "recommendation", "risk", "assumption", "ask"]).optional(),
+        text: tool.schema.string().describe("Claim text."),
+        importance: tool.schema.enum(["central", "supporting", "background"]).optional(),
+        evidenceRequired: tool.schema.boolean().optional(),
+        evidenceStatus: tool.schema.enum(["supported", "partial", "weak", "missing", "not_required"]).optional(),
+        supportedScope: tool.schema.string().optional(),
+        unsupportedScope: tool.schema.string().optional(),
+        caveats: tool.schema.array(tool.schema.string()).optional(),
+      })).optional(),
+      claimRelations: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        fromClaimId: tool.schema.string().describe("Canonical claim id the relation starts from."),
+        toClaimId: tool.schema.string().describe("Canonical claim id the relation points to."),
+        relation: tool.schema.enum(["leads_to", "supports", "depends_on", "contrasts_with", "constrains", "answers"]).optional(),
+        rationale: tool.schema.string().optional().describe("Short explanation of why this narrative relation exists."),
+      })).optional().describe("Canonical claim-to-claim narrative progression relationships. These affect narrative approval hash."),
+      evidenceBindings: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        claimId: tool.schema.string().describe("Canonical claim id this evidence supports."),
+        source: tool.schema.string().describe("Source file, URL, research finding, or material name."),
+        sourcePath: tool.schema.string().optional(),
+        findingsFile: tool.schema.string().optional(),
+        quote: tool.schema.string().optional(),
+        location: tool.schema.string().optional(),
+        url: tool.schema.string().optional(),
+        caveat: tool.schema.string().optional(),
+        supportScope: tool.schema.string().optional(),
+        unsupportedScope: tool.schema.string().optional(),
+        strength: tool.schema.enum(["strong", "partial", "weak"]).optional(),
+      })).optional(),
+      objections: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        text: tool.schema.string().describe("Objection text."),
+        claimId: tool.schema.string().optional(),
+        priority: tool.schema.enum(["high", "medium", "low"]).optional(),
+        response: tool.schema.string().optional(),
+      })).optional(),
+      risks: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        text: tool.schema.string().describe("Risk, assumption, caveat, or tradeoff text."),
+        claimId: tool.schema.string().optional(),
+        severity: tool.schema.enum(["high", "medium", "low"]).optional(),
+        mitigation: tool.schema.string().optional(),
+      })).optional(),
+      researchGaps: tool.schema.array(tool.schema.object({
+        id: tool.schema.string().optional(),
+        targetType: tool.schema.enum(["claim", "objection", "risk", "decision", "narrative"]).optional(),
+        targetId: tool.schema.string().optional(),
+        question: tool.schema.string().describe("Research question or gap to resolve."),
+        status: tool.schema.enum(["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]).optional(),
+        priority: tool.schema.enum(["high", "medium", "low"]).optional(),
+        findingsFile: tool.schema.string().optional(),
+        evidenceBindingIds: tool.schema.array(tool.schema.string()).optional(),
+        createdFromIssueType: tool.schema.string().optional(),
+        notes: tool.schema.string().optional(),
+      })).optional(),
+    }).optional().describe("For upsertNarrative: canonical narrative state fields to merge into DECKS.json. Replaces provided arrays, preserves approvals."),
     design: tool.schema.string().optional().describe("For upsertDeck: active design name."),
     domain: tool.schema.string().optional().describe("For upsertDeck: active domain name."),
     memory: tool.schema.string().optional().describe("For remember: explicit user or workflow preference to store."),
@@ -93,6 +213,13 @@ export default tool({
       layout: tool.schema.string().describe("Design layout name."),
       qa: tool.schema.boolean().optional().describe("Whether the slide is marked QA-relevant deck metadata."),
       components: tool.schema.array(tool.schema.string()).describe("Design components used by this slide."),
+      claimIds: tool.schema.array(tool.schema.string()).optional().describe("Canonical narrative claim ids directly expressed by this slide."),
+      claimRefs: tool.schema.array(tool.schema.object({
+        claimId: tool.schema.string().describe("Canonical narrative claim id referenced by this slide."),
+        role: tool.schema.enum(["primary", "supporting", "evidence", "risk", "objection"]).describe("How the slide uses this claim."),
+        note: tool.schema.string().optional().describe("Optional short rationale for this claim-slide relationship."),
+      })).optional().describe("Structured canonical claim references for this slide; preferred over flat claimIds when available."),
+      evidenceBindingIds: tool.schema.array(tool.schema.string()).optional().describe("Canonical narrative evidence binding ids used by this slide."),
       content: tool.schema.object({
         headline: tool.schema.string().optional(),
         body: tool.schema.array(tool.schema.string()).optional(),
@@ -124,6 +251,25 @@ export default tool({
     findingsFile: tool.schema.string().optional().describe("For attachResearchFindings: workspace-relative researches/{topic}/{axis}.md file to attach to researchPlan."),
     researchAxis: tool.schema.string().optional().describe("For attachResearchFindings: researchPlan axis to attach the findings file to. Required when filename matching would be ambiguous."),
     researchStatus: tool.schema.enum(["done", "read"]).optional().describe("For attachResearchFindings: optional explicit status to set on the matched research axis."),
+    approvalNote: tool.schema.string().optional().describe("For approveNarrative: optional note explaining the approval or override."),
+    approvalBy: tool.schema.enum(["user", "override"]).optional().describe("For approveNarrative: use override only for explicit render overrides, not normal strategic approval."),
+    approvalScope: tool.schema.enum(["narrative", "render_override"]).optional().describe("For approveNarrative: narrative approval or explicit render override scope."),
+    gapId: tool.schema.string().optional().describe("For updateResearchGap/closeResearchGap: canonical research gap id."),
+    researchGaps: tool.schema.array(tool.schema.object({
+      id: tool.schema.string().optional(),
+      targetType: tool.schema.enum(["claim", "objection", "risk", "decision", "narrative"]).optional(),
+      targetId: tool.schema.string().optional(),
+      question: tool.schema.string().describe("Research question or gap to resolve."),
+      status: tool.schema.enum(["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]).optional(),
+      priority: tool.schema.enum(["high", "medium", "low"]).optional(),
+      findingsFile: tool.schema.string().optional(),
+      evidenceBindingIds: tool.schema.array(tool.schema.string()).optional(),
+      createdFromIssueType: tool.schema.string().optional(),
+      notes: tool.schema.string().optional(),
+    })).optional().describe("For upsertResearchGaps: explicit canonical research gaps to create or update."),
+    gapStatus: tool.schema.enum(["open", "in_progress", "findings_saved", "attached", "evidence_bound", "closed"]).optional().describe("For updateResearchGap: lifecycle status."),
+    gapNotes: tool.schema.string().optional().describe("For updateResearchGap/closeResearchGap: notes or close reason."),
+    evidenceBindingIds: tool.schema.array(tool.schema.string()).optional().describe("For updateResearchGap: canonical narrative evidence binding ids associated with the gap."),
   },
   async execute(args, context) {
     try {
@@ -194,6 +340,45 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, deck: next.activeDeck ? next.decks[next.activeDeck] : undefined }, null, 2)
       }
 
+      if (args.action === "upsertNarrative") {
+        if (!args.narrative) return JSON.stringify({ ok: false, error: "narrative is required for upsertNarrative" })
+        const current = state.narrative ?? normalizeNarrativeState(state)
+        const merged = mergeNarrativeInput(current, args.narrative as Partial<NarrativeStateV1>)
+        const normalized = normalizeCanonicalNarrativeState(merged, state.activeDeck ?? defaultSlug)
+        if (!normalized) return JSON.stringify({ ok: false, error: "narrative could not be normalized" })
+        state.narrative = normalized
+
+        const deckKey = state.activeDeck
+        if (deckKey && state.decks[deckKey]) {
+          state = upsertDeck(state, {
+            ...state.decks[deckKey],
+            slug: deckKey,
+            audience: normalized.audience.primary || state.decks[deckKey].audience,
+            narrativeBrief: narrativeToBrief(normalized),
+          })
+        }
+
+        recordWorkspaceAction(state, {
+          type: "narrative.upserted",
+          actor: "revela-decks",
+          inputs: { hadExistingNarrative: Boolean(current), providedFields: Object.keys(args.narrative as object) },
+          outputs: {
+            narrativeId: normalized.id,
+            status: normalized.status,
+            claimCount: normalized.claims.length,
+            evidenceBindingCount: normalized.evidenceBindings.length,
+            objectionCount: normalized.objections.length,
+            riskCount: normalized.risks.length,
+          },
+          status: "success",
+          summary: `Updated canonical narrative state with ${normalized.claims.length} claim${normalized.claims.length === 1 ? "" : "s"}.`,
+          nodeIds: [normalized.id],
+        })
+
+        writeDecksState(workspaceRoot, state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, narrative: state.narrative, deck: state.activeDeck ? state.decks[state.activeDeck] : undefined }, null, 2)
+      }
+
       if (args.action === "review") {
         const reviewed = reviewDeckState(state, undefined, { workspaceRoot })
         const targetId = activeReviewTargetId(reviewed.state)
@@ -222,6 +407,84 @@ export default tool({
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result }, null, 2)
       }
 
+      if (args.action === "compileDeckPlan") {
+        const compiled = compileDeckPlanFromNarrative(state)
+        if (compiled.result.compiled) {
+          recordWorkspaceAction(compiled.state, {
+            type: "deck.plan_compiled",
+            actor: "revela-decks",
+            inputs: { narrativeId: compiled.state.narrative?.id, activeDeck: compiled.state.activeDeck },
+            outputs: {
+              narrativeHash: compiled.result.narrativeHash,
+              slideCount: compiled.result.slideCount,
+              outputPath: compiled.state.activeDeck ? compiled.state.decks[compiled.state.activeDeck]?.outputPath : undefined,
+            },
+            status: "success",
+            summary: `Compiled deck plan from canonical narrative with ${compiled.result.slideCount} slide${compiled.result.slideCount === 1 ? "" : "s"}.`,
+            nodeIds: [compiled.state.narrative?.id, compiled.state.activeDeck ? `artifact:${compiled.state.decks[compiled.state.activeDeck]?.outputPath ?? compiled.state.activeDeck}` : undefined].filter((item): item is string => Boolean(item)),
+          })
+        }
+        writeDecksState(workspaceRoot, compiled.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: compiled.result, deck: compiled.state.activeDeck ? compiled.state.decks[compiled.state.activeDeck] : undefined, narrative: compiled.state.narrative }, null, 2)
+      }
+
+      if (args.action === "backfillClaimRefs") {
+        const backfilled = backfillSlideClaimRefsFromCoverage(state)
+        writeDecksState(workspaceRoot, backfilled.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: backfilled.result, deck: backfilled.state.activeDeck ? backfilled.state.decks[backfilled.state.activeDeck] : undefined, narrative: backfilled.state.narrative }, null, 2)
+      }
+
+      if (args.action === "reviewNarrative") {
+        const reviewed = reviewNarrativeState(state)
+        recordNarrativeReviewAction(reviewed.state, reviewed.result)
+        writeDecksState(workspaceRoot, reviewed.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result, narrative: reviewed.state.narrative }, null, 2)
+      }
+
+      if (args.action === "approveNarrative") {
+        const approved = approveNarrativeState(state, {
+          approvedBy: args.approvalBy,
+          scope: args.approvalScope,
+          note: args.approvalNote,
+        })
+        recordNarrativeApprovalAction(approved.state, approved.result)
+        writeDecksState(workspaceRoot, approved.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: approved.result, narrative: approved.state.narrative }, null, 2)
+      }
+
+      if (args.action === "deriveResearchGaps") {
+        const derived = deriveResearchGapsFromReadiness(state)
+        writeDecksState(workspaceRoot, derived.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: derived.result, narrative: derived.state.narrative }, null, 2)
+      }
+
+      if (args.action === "upsertResearchGaps") {
+        if (!args.researchGaps?.length) return JSON.stringify({ ok: false, error: "researchGaps are required for upsertResearchGaps" })
+        const upserted = upsertResearchGapsInState(state, args.researchGaps as any[])
+        writeDecksState(workspaceRoot, upserted.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: upserted.result, narrative: upserted.state.narrative }, null, 2)
+      }
+
+      if (args.action === "updateResearchGap") {
+        if (!args.gapId?.trim()) return JSON.stringify({ ok: false, error: "gapId is required for updateResearchGap" })
+        const updated = updateResearchGapInState(state, {
+          id: args.gapId,
+          status: args.gapStatus as any,
+          findingsFile: args.findingsFile,
+          evidenceBindingIds: args.evidenceBindingIds,
+          notes: args.gapNotes,
+        })
+        writeDecksState(workspaceRoot, updated.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: updated.result, narrative: updated.state.narrative }, null, 2)
+      }
+
+      if (args.action === "closeResearchGap") {
+        if (!args.gapId?.trim()) return JSON.stringify({ ok: false, error: "gapId is required for closeResearchGap" })
+        const closed = closeResearchGapInState(state, args.gapId, args.gapNotes)
+        writeDecksState(workspaceRoot, closed.state)
+        return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: closed.result, narrative: closed.state.narrative }, null, 2)
+      }
+
       if (args.action === "applyEvidenceCandidates") {
         const candidateIds = args.candidateIds ?? []
         if (candidateIds.length === 0) return JSON.stringify({ ok: false, error: "candidateIds are required for applyEvidenceCandidates" })

package/tools/narrative-view.ts

@@ -0,0 +1,84 @@
+import { tool } from "@opencode-ai/plugin"
+import { hasDecksState, readDecksState } from "../lib/decks-state"
+import { buildNarrativeMap } from "../lib/narrative-state/map"
+import { validateNarrativeDisplayModel, type NarrativeDisplayModel, type NarrativeViewLanguage } from "../lib/narrative-state/display"
+import { writeNarrativeMapHtml } from "../lib/commands/narrative"
+import { openUrl } from "../lib/edit/open"
+
+export default tool({
+  description:
+    "Render Revela's read-only narrative claim-flow UI from the current deterministic narrative map plus an optional localized display model. " +
+    "This tool validates display IDs against DECKS.json, opens a local HTML view, and never mutates workspace state.",
+  args: {
+    language: tool.schema.string().describe("UI language request from /revela narrative. May be any language tag or language name, such as en, zh-CN, fr, de, Korean, Arabic, or Portuguese-BR."),
+    narrativeHash: tool.schema.string().optional().describe("Narrative hash from the prompt projection. Used to detect stale display prompts."),
+    displayModel: tool.schema.object({
+      version: tool.schema.number().describe("Must be 1."),
+      language: tool.schema.string().describe("Must exactly match the top-level language request."),
+      pageTitle: tool.schema.string().optional(),
+      summaryLine: tool.schema.string().optional(),
+      labels: tool.schema.object({
+        eyebrow: tool.schema.string().optional(),
+        claimFlow: tool.schema.string().optional(),
+        flowNote: tool.schema.string().optional(),
+        selectedClaim: tool.schema.string().optional(),
+        claim: tool.schema.string().optional(),
+        claimId: tool.schema.string().optional(),
+        status: tool.schema.string().optional(),
+        supportedScope: tool.schema.string().optional(),
+        unsupportedScope: tool.schema.string().optional(),
+        incomingRelations: tool.schema.string().optional(),
+        outgoingRelations: tool.schema.string().optional(),
+        evidence: tool.schema.string().optional(),
+        objections: tool.schema.string().optional(),
+        risks: tool.schema.string().optional(),
+        researchGaps: tool.schema.string().optional(),
+        coveredSlides: tool.schema.string().optional(),
+        noClaims: tool.schema.string().optional(),
+        none: tool.schema.string().optional(),
+      }).optional(),
+      claimCards: tool.schema.array(tool.schema.object({
+        claimId: tool.schema.string().describe("Existing canonical claim id. Must match the deterministic map."),
+        displayTitle: tool.schema.string().optional().describe("Display-only localized claim title in the requested language. For Chinese manufacturing/industrial AI context, translate autonomy as 自主化/自主能力, not 自治; convert slug-like claim text into a readable title."),
+        roleLabel: tool.schema.string().optional(),
+        narrativeJob: tool.schema.string().optional(),
+        evidenceSummary: tool.schema.string().optional(),
+        riskOrGapSummary: tool.schema.string().optional(),
+      })).optional(),
+      relations: tool.schema.array(tool.schema.object({
+        fromClaimId: tool.schema.string(),
+        toClaimId: tool.schema.string(),
+        relation: tool.schema.enum(["leads_to", "supports", "depends_on", "contrasts_with", "constrains", "answers"]),
+          displayLabel: tool.schema.string().optional().describe("Display-only localization of an existing canonical relation label. Omit for inferred relations."),
+        displayRationale: tool.schema.string().optional().describe("Display-only localization of an existing canonical rationale. Omit when canonical rationale is missing or the relation is inferred."),
+      })).optional(),
+    }).optional().describe("Localized and organized display-only projection. It must not add facts or alter IDs."),
+  },
+  async execute(args, context) {
+    const workspaceRoot = context.directory ?? process.cwd()
+    try {
+      if (!hasDecksState(workspaceRoot)) {
+        return JSON.stringify({ ok: false, error: "No DECKS.json found. Run /revela init first." })
+      }
+      const language = args.language as NarrativeViewLanguage
+      const map = buildNarrativeMap(readDecksState(workspaceRoot))
+      const stalePrompt = Boolean(args.narrativeHash && args.narrativeHash !== map.snapshot.narrativeHash)
+      const display = validateNarrativeDisplayModel(map, args.displayModel as NarrativeDisplayModel | undefined, language)
+      const htmlPath = writeNarrativeMapHtml(map, display)
+      const url = `file://${htmlPath}`
+      openUrl(url)
+      return JSON.stringify({ ok: true, url, path: htmlPath, narrativeHash: map.snapshot.narrativeHash, stalePrompt, fallback: false }, null, 2)
+    } catch (e: any) {
+      try {
+        const language = (args.language ?? "en") as NarrativeViewLanguage
+        const map = buildNarrativeMap(readDecksState(workspaceRoot))
+        const htmlPath = writeNarrativeMapHtml(map)
+        const url = `file://${htmlPath}`
+        openUrl(url)
+        return JSON.stringify({ ok: false, fallback: true, url, path: htmlPath, error: e.message || String(e) }, null, 2)
+      } catch (fallbackError: any) {
+        return JSON.stringify({ ok: false, fallback: false, error: e.message || String(e), fallbackError: fallbackError.message || String(fallbackError) })
+      }
+    }
+  },
+})

package/tools/workspace-scan.ts

@@ -18,6 +18,17 @@ const EXCLUDE_DIRS = new Set([
   "designs", "domains",  // Exclude revela plugin assets
 ])
 
+const EXCLUDE_FILENAMES = new Set([
+  "AGENTS.md",
+  "DECKS.md",
+  "README.md",
+  "README.zh-CN.md",
+])
+
+function isExcludedFile(entry: string): boolean {
+  return entry.startsWith("~$") || EXCLUDE_FILENAMES.has(entry)
+}
+
 type FileEntry = {
   path: string
   type: string
@@ -84,6 +95,8 @@ function scanDir(dir: string, rootDir: string, results: FileEntry[], maxDepth: n
     if (stat.isDirectory()) {
       scanDir(fullPath, rootDir, results, maxDepth, depth + 1)
     } else if (stat.isFile()) {
+      if (isExcludedFile(entry)) continue
+
       const ext = extname(entry).toLowerCase()
       if (DOC_EXTENSIONS.has(ext)) {
         const sourceMaterial = sourceMaterialMetadata(fullPath, rootDir)
@@ -104,7 +117,7 @@ export default tool({
     "Scan the current workspace for document and data files that can be used as research input. " +
     "Returns a structured list of all found files with their type and size. " +
     "Searches for: PDF, Word (docx/doc), Excel (xlsx/xls), PowerPoint (pptx/ppt), CSV, Markdown, and text files. " +
-    "Excludes node_modules, .git, dist, and the researches/ output directory. " +
+    "Excludes node_modules, .git, dist, the researches/ output directory, project docs, and Office lock files. " +
     "Use this as the first step before reading workspace documents.",
   args: {
     path: tool.schema