@cyber-dash-tech/revela 0.18.7 → 0.18.9

package/plugins/revela/mcp/revela-server.ts

@@ -289,12 +289,12 @@ const tools = [
   },
   {
     name: "revela_research_save",
-    description: "Save source-linked research findings under researches/{topic}/{filename}.md for deck-plan use.",
+    description: "Save source-linked research findings under researches/{topic}/{filename}.md for deck-plan use. Prefer structured blocks: ## Finding: <stable-id> for evidence, ## Synthesis: <stable-id> for interpretation across findings, ## Analysis: <stable-id> for analytical frameworks, ## Implementation Note: <stable-id> for render/data/API contracts, ## Asset Lead: <stable-id> for media leads, and ## Gaps for missing support.",
     inputSchema: objectSchema({
       workspaceRoot: stringProp("Optional workspace root."),
       topic: requiredStringProp("Research topic key."),
       filename: requiredStringProp("Findings filename without extension."),
-      content: requiredStringProp("Structured Markdown findings content."),
+      content: requiredStringProp("Structured Markdown findings content. Evidence findings should preserve source, quote/snippet, support scope or Supports, Evidence boundary or unsupported scope, Strength, Deck use, and optional Display note. Synthesis entries should preserve Basis, Interpretation, So what, Decision implication, Confidence, Alternative reading, Evidence boundary, and Deck use. Analysis and Implementation Note entries may support planning or rendering but are not external factual proof."),
       sources: arrayProp("Source URLs or workspace files for YAML frontmatter."),
     }, ["topic", "filename", "content"]),
   },

package/plugins/revela/skills/revela/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: revela
+description: Route Revela requests to the right specialist workflow based on user intent and workspace state. Use when the user asks generally to use Revela, start or continue a Revela workflow, inspect next steps, or decide what to do from existing spec.md, researches/, deck-plan.md, or deck artifacts.
+---
+
+# Revela Router
+
+Use this skill as the main Revela entrypoint in Codex. It should inspect intent and file-native workspace state, then route to the narrow specialist skill that owns the next action.
+
+## Contract
+
+- This is a non-mutating router.
+- It may inspect runtime, active design/domain, and workspace artifact status.
+- It must not write `spec.md`, save research findings, write `deck-plan.md`, generate deck HTML, open Review UI, or export artifacts.
+- Route quickly once the next workflow is clear.
+
+## Required Tools
+
+1. Call `revela_doctor` to inspect runtime and workspace status.
+2. Call `revela_design_list` to identify the active design.
+3. Call `revela_domain_list` to identify the active domain.
+4. Read files only as needed to distinguish `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/` state.
+
+## Routing Rules
+
+- Custom visual system, design package, layout, component, or activation request: use `revela-design`.
+- Custom narrative domain, industry guidance, evidence standard, or domain activation request: use `revela-domain`.
+- No `spec.md`, unclear objective, missing audience, missing output target, or missing acceptance criteria: use `revela-spec`.
+- `spec.md` exists but source support, material review, or findings are missing: use `revela-research`.
+- `spec.md` and sufficient findings exist but `deck-plan.md` is missing or needs normal authoring: use `revela-research` Planning Handoff.
+- Valid `deck-plan.md` exists and the user asks to make, generate, render, or update a deck: use `revela-make-deck`.
+- Existing deck artifact and the user asks to review, diagnose, QA, or refine: use `revela-review`.
+- Existing deck artifact and the user asks for PDF, PPTX, or PNG output: use `revela-export`.
+- If the next step is still ambiguous after inspection, ask the smallest missing question and recommend the safest next specialist skill.
+
+## Output
+
+Report:
+
+- Current workflow state: `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/`.
+- Active design and active domain.
+- The selected specialist skill and why.
+- Any missing input that prevents routing.
+
+## Must Not
+
+- Do not write or patch files.
+- Do not do external web research.
+- Do not create or repair `spec.md` or `deck-plan.md`.
+- Do not generate, review, patch, or export deck artifacts.
+- Do not install or activate designs or domains; route those requests to `revela-design` or `revela-domain`.

package/plugins/revela/skills/revela-helper/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: revela-helper
-description: Explain Revela, inspect the current Revela workspace status, and report active design/domain guidance in Codex.
+description: Explain Revela, inspect the current Revela workspace status, and report active design/domain guidance in Codex. Use the revela router for workflow routing when the user wants to start or continue work.
 ---
 
 # Revela Helper
@@ -10,8 +10,9 @@ Use this skill when the user asks what Revela is, what the current workspace sta
 ## Contract
 
 - This is a read-only helper and orientation surface.
+- `revela` is the main workflow router; this skill explains status and capabilities.
 - It may inspect runtime, design, domain, and workspace artifact status.
-- It must not perform research, write files, create `deck-plan.md`, generate decks, open Review UI, or export artifacts.
+- It must not perform research, write files, create `spec.md`, create `deck-plan.md`, generate decks, open Review UI, or export artifacts.
 - Keep the answer short and operational.
 
 ## Preconditions
@@ -21,7 +22,7 @@ Use this skill when the user asks what Revela is, what the current workspace sta
 ## Inputs
 
 - User questions about Revela, current status, active design/domain, or next workflow step.
-- Optional workspace context such as existing `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/`.
+- Optional workspace context such as existing `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/`.
 
 ## Required Tools
 
@@ -37,11 +38,12 @@ Report:
 - What Revela does: trusted, traceable, deck-first decision artifacts from local materials, research, data, and user intent.
 - Runtime/version status from `revela_doctor`.
 - Active design and active domain.
-- Workspace artifact status: whether `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/` appear available.
+- Workspace artifact status: whether `spec.md`, `researches/`, `deck-plan.md`, `decks/*.html`, and `assets/` appear available.
 - Recommended next step:
   - Custom visual system requested: use `revela-design`.
   - Custom narrative domain guidance requested: use `revela-domain`.
-  - No `researches/`: run `revela-research`.
+  - No `spec.md` or unclear objective: run `revela-spec`.
+  - `spec.md` exists but no `researches/`: run `revela-research`.
   - Research exists but no `deck-plan.md`: continue `revela-research` to the Planning Handoff.
   - Valid `deck-plan.md` but no deck artifact: run `revela-make-deck`.
   - Existing deck artifact: run `revela-review` or `revela-export` depending on the user goal.
@@ -50,6 +52,7 @@ Report:
 
 - Do not write or patch files.
 - Do not do external web research.
+- Do not generate or repair `spec.md`.
 - Do not generate or repair `deck-plan.md`.
 - Do not generate, review, patch, or export deck artifacts.
 - Do not create, install, or activate designs or domains; route those requests to `revela-design` or `revela-domain`.

package/plugins/revela/skills/revela-make-deck/SKILL.md

@@ -11,6 +11,7 @@ Use this skill when the user asks to make, generate, render, or update a Revela
 
 - Deck execution planning comes from canonical `deck-plan.md`.
 - Local materials, material reviews, `researches/`, `assets/`, and user intent provide source context.
+- Slide argument copy comes from `deck-plan.md` `Claim`, `Reasoning`, and `Audience takeaway` fields when present; raw findings are evidence/source context, not default body copy.
 - Active/requested design tools define valid layouts, slots, components, nesting hints, and HTML writing rules.
 - Active/requested domain guidance may inform communication framing, but it is not source evidence.
 - Generated artifacts live under `decks/*.html`.
@@ -22,7 +23,7 @@ Use this skill when the user asks to make, generate, render, or update a Revela
 
 - Required: readable `deck-plan.md`.
 - An active or user-requested design must be readable.
-- If `deck-plan.md` is missing, stop and tell the user to run `revela-research` or continue `revela-research` to the Planning Handoff.
+- If `deck-plan.md` is missing, stop and tell the user to run `revela` for routing, `revela-spec` for missing requirements, or `revela-research` for the Planning Handoff.
 - If `deck-plan.md` is structurally invalid, only repair technical plan diagnostics reported during render preflight.
 
 ## Inputs
@@ -61,7 +62,9 @@ Allowed plan repairs are limited to technical diagnostics from `revela_read_deck
 - Layout, slot, component, or `children` names that do not match `revela_design_inventory`.
 - Component nesting fixes such as using `box.children` when the selected component model requires nested semantic groups.
 
-Do not redesign the argument structure, add new slides, remove supported slides, rewrite claims, or add source links that were not reviewed or saved by `revela-research`. If normal plan authoring is needed, stop and send the user back to `revela-research` Planning Handoff.
+Do not redesign the argument structure, add new slides, remove supported slides, rewrite claims, or add source links that were not reviewed or saved by `revela-research`. If normal plan authoring is needed, stop and send the user back to `revela` routing or `revela-research` Planning Handoff.
+
+If a non-structural slide plan has source links but lacks `Claim`, `Reasoning`, or `Audience takeaway`, treat it as synthesis-thin: do not fill the gap by copying raw findings into slide body copy. Report that the plan needs `revela-research` Planning Handoff repair.
 
 ## Render Phase
 
@@ -70,14 +73,15 @@ Use this phase when the user asks to make, generate, render, or update an HTML d
 1. Call `revela_read_deck_plan` before HTML generation and follow the current projection.
 2. Read `htmlWritingBatches` before any HTML write. `revela_read_deck_plan` is QA/diagnostics, not a writer.
 3. For new HTML files, call `revela_create_deck_foundation`.
-4. Generate one `htmlWritingBatches` entry at a time.
-5. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
-6. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
-7. Patch slides into the foundation between Revela slide markers.
-8. Preserve positive 1-based `data-slide-index` values.
-9. Every slide must have exactly one direct `.slide-canvas` child.
-10. Keep the HTML valid after each write.
-11. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing, review, or export.
+4. Use the deck-plan's `Claim`, `Reasoning`, and `Audience takeaway` as the primary slide copy. Keep finding text in source notes, captions, evidence charts, or speaker notes unless the plan explicitly calls for a direct evidence quote.
+5. Generate one `htmlWritingBatches` entry at a time.
+6. A single HTML write/edit/apply_patch may add or rewrite at most 5 slide sections.
+7. If a chapter is longer than 5 slides, use the consecutive batch parts returned by `revela_read_deck_plan`.
+8. Patch slides into the foundation between Revela slide markers.
+9. Preserve positive 1-based `data-slide-index` values.
+10. Every slide must have exactly one direct `.slide-canvas` child.
+11. Keep the HTML valid after each write.
+12. After every HTML write, call `revela_run_deck_qa` and repair hard errors before continuing, review, or export.
 
 ## Outputs
 

package/plugins/revela/skills/revela-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: revela-research
-description: Research workspace materials and public sources for a Revela deck objective, using active domain/design guidance to save source-linked findings and hand off deck-plan.md.
+description: Research from an existing or emerging Revela spec.md and public/workspace sources, using active domain/design guidance to save source-linked findings and hand off deck-plan.md.
 ---
 
 # Revela Research
@@ -10,6 +10,7 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 ## Contract
 
 - Research is the source-preparation workflow for Codex Revela.
+- Prefer root-level `spec.md` as the demand contract. If it is missing or the objective is unclear, route to `revela-spec` unless the user gave enough intent to research immediately.
 - Research output is saved under `researches/**/*.md` and, when the user goal is a deck and materials are sufficient, handed off as `deck-plan.md`.
 - Local materials are only usable after direct text review or extracted read-view review.
 - Active/requested domain guidance informs audience, decision framing, claim standards, evidence expectations, objection/risk interpretation, and research-gap priority.
@@ -21,11 +22,12 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 
 ## Preconditions
 
-- The user provides at least one of: objective, topic, audience, decision/action, source materials, or deck intent.
+- The user provides at least one of: existing `spec.md`, objective, topic, audience, decision/action, source materials, or deck intent.
 - If intent is unclear, inspect the workspace first and ask only the smallest missing high-impact questions.
 
 ## Inputs
 
+- Root-level `spec.md` when present.
 - User objective, constraints, audience, decision/action, and language preference when available.
 - Workspace materials, extracted material read views, existing `researches/**/*.md`, existing `deck-plan.md`, and `assets/`.
 - Active or user-requested domain guidance.
@@ -35,14 +37,15 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 
 1. Call `revela_domain_list`.
 2. Call `revela_domain_read` for the active domain or user-requested domain.
-3. Call `revela_prepare_local_materials`.
-4. For Office/PDF sources, read the provided `allowedReadPath` / `read_view_path`; if missing, call `revela_extract_document_materials`.
-5. Read original text/Markdown/CSV files or extracted read views before treating a material as usable.
-6. Call `revela_record_material_review` for each reviewed Office/PDF source.
-7. Call `revela_check_material_intake` before reporting research readiness.
-8. Use external research only for public facts, user-authorized questions, or gaps not covered by local materials.
-9. Save useful findings with `revela_research_save`.
-10. For deck goals with sufficient materials, run Planning Handoff:
+3. Read `spec.md` when present and use it to scope material review, findings, and deck-plan handoff.
+4. Call `revela_prepare_local_materials`.
+5. For Office/PDF sources, read the provided `allowedReadPath` / `read_view_path`; if missing, call `revela_extract_document_materials`.
+6. Read original text/Markdown/CSV files or extracted read views before treating a material as usable.
+7. Call `revela_record_material_review` for each reviewed Office/PDF source.
+8. Call `revela_check_material_intake` before reporting research readiness.
+9. Use external research only for public facts, user-authorized questions, or gaps not covered by local materials or `spec.md`.
+10. Save useful findings with `revela_research_save`.
+11. For deck goals with sufficient materials, run Planning Handoff:
     - Call `revela_design_list`.
     - Call `revela_design_read` with `section: "rules"` for the active/requested design.
     - Call `revela_design_inventory`.
@@ -52,17 +55,55 @@ Use this skill when the user asks to start from a goal, inspect local materials,
 
 ## Finding Requirements
 
-Each saved finding should include:
+Saved research should use stable, reusable Markdown blocks. Evidence findings use:
+
+```md
+## Finding: <stable-id>
+
+Source: <source name and date when known>
+URL: <source URL when available>
+Location: <page/slide/sheet/section when known>
+Quote/Snippet: <short exact quote or compact snippet; note when no exact quote is available>
+Supports: <narrow support scope or intended slide/source context>
+Evidence boundary: <internal guardrail; what this finding does not prove>
+Strength: <strong|directional|weak|context-only>
+Deck use: <where this belongs in deck planning>
+Display note: <optional short user-facing scope note for captions/source notes>
+```
+
+Use synthesis blocks to turn multiple findings into decision-relevant interpretation before deck planning:
+
+```md
+## Synthesis: <stable-id>
+
+Question answered: <research question this synthesis resolves>
+Basis: <finding ids, source files, or URLs used>
+Interpretation: <what the evidence means when read together>
+So what: <why this matters for the audience or decision>
+Decision implication: <what should change in the recommendation, story, or slide argument>
+Confidence: <high|medium|low>
+Alternative reading: <plausible competing interpretation or contradiction>
+Evidence boundary: <internal guardrail; what this synthesis must not overclaim>
+Deck use: <where this belongs in deck planning>
+Display note: <optional short user-facing scope note>
+```
+
+Use `## Analysis: <stable-id>` for user/LLM analytical frameworks, `## Implementation Note: <stable-id>` for render/data/API contracts, `## Asset Lead: <stable-id>` for image/logo/media leads, and `## Gaps` for missing or insufficient source support.
+
+Each saved evidence finding should include:
 
 - Source URL or workspace path.
 - Quote/snippet or explicit note when no exact quote is available.
 - What it supports.
-- What it does not support.
-- Caveat or limitation.
+- `Evidence boundary` for internal support limits, unsupported scope, or uncertainty.
+- `Deck use` for likely planning placement.
+- Optional `Display note` for short audience-facing scope text.
 - Date checked.
 - Optional image/logo/screenshot leads with known source and license/attribution status.
 
-If a finding is context only, label it as context and do not present it as proof.
+If a finding is context only, label it as context and do not present it as proof. Internal boundaries must not be mechanically copied into deck text; use `Display note` for default visible caption/source-note scope, and expose `Evidence boundary` only when needed to avoid a misleading audience conclusion.
+
+Do not use raw findings as the default deck argument. For deck goals, synthesize findings first; findings provide evidence basis, while `Synthesis` provides the interpretation, decision implication, and audience takeaway that should drive `deck-plan.md`.
 
 ## Outputs
 
@@ -82,12 +123,17 @@ Each non-structural slide block must include:
 
 - Slide title and role when relevant.
 - `#### Content Plan`
-- `#### Source Links` for materials, findings, assets, URLs, and caveats.
+- In `#### Content Plan`: `Claim`, `Reasoning`, `Audience takeaway`, `Evidence basis`, and `Boundary handling`.
+- `#### Source Links` for materials, finding-level references when available, assets, URLs, and caveats.
 - `#### Design Plan`
 - Selected layout from design inventory.
 - Component plan using component names from design inventory.
 - Valid slots from the selected layout.
 - Valid component nesting hints, including `box.children` when multiple child components support one semantic idea.
+- Base slide arguments on `Synthesis` blocks when available; use finding text as evidence/source context, not as default body copy.
+- Use `Display note` for short visible caption/source-note scope.
+- Keep `Evidence boundary` internal unless it is required to avoid a misleading audience conclusion.
+- `Analysis` and `Implementation Note` entries may support deck structure or rendering, but must not be cited as external factual proof.
 - Unresolved inputs, source limitations, and user review notes instead of AI-authored caveat/risk judgement.
 
 Do not duplicate the same child as both nested and top-level. Do not add source links that were not reviewed or saved during research.
@@ -95,6 +141,7 @@ Do not duplicate the same child as both nested and top-level. Do not add source
 ## Must Not
 
 - Do not generate `revela-narrative/`.
+- Do not write `spec.md`; route demand changes to `revela-spec`.
 - Do not write `decks/*.html`.
 - Do not bind findings into a Narrative Vault or canonical evidence graph.
 - Do not treat domain guidance as source evidence.

package/plugins/revela/skills/revela-spec/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: revela-spec
+description: Discover Revela artifact requirements and write a root-level spec.md before research or deck planning. Use when the user goal, audience, output type, constraints, acceptance criteria, or next workflow step is unclear or not yet captured.
+---
+
+# Revela Spec
+
+Use this skill to turn user intent and available workspace context into a concise root-level `spec.md` demand contract.
+
+## Contract
+
+- `spec.md` is the canonical demand and task specification for Codex Revela.
+- The spec answers what to build, for whom, why it matters, what constraints apply, and how success will be judged.
+- Local materials may be inspected only to ground scope and identify available inputs.
+- This skill does not own research findings, deck planning, deck rendering, Review, or Export.
+- Ask the smallest missing high-impact questions after local inspection.
+
+## Preconditions
+
+- The user provides at least one of: objective, topic, audience, decision/action, source material, desired artifact, or open problem.
+- If no local workspace exists, write the spec from user intent and mark material gaps explicitly.
+
+## Inputs
+
+- User objective, audience, decision/action, output type, language, style, constraints, and deadline when available.
+- Existing workspace context: local materials, `researches/`, `deck-plan.md`, `decks/*.html`, `assets/`, active design, and active domain.
+
+## Workflow
+
+1. Call `revela_doctor` to inspect workspace state.
+2. Call `revela_domain_list` to capture active narrative guidance.
+3. Call `revela_design_list` to capture active design guidance.
+4. Call `revela_prepare_local_materials` when local material awareness is needed for scope.
+5. For Office/PDF sources, do not treat them as reviewed evidence unless extracted/read in a later `revela-research` workflow.
+6. Ask only for missing information that materially changes the spec or next step.
+7. Write or update root-level `spec.md`.
+8. End by recommending the next specialist skill:
+   - `revela-research` when sources or findings are needed.
+   - `revela-make-deck` only when a valid `deck-plan.md` already exists and the spec does not require new source work.
+   - `revela-design` or `revela-domain` when the spec requires custom guidance first.
+
+## spec.md Requirements
+
+`spec.md` must include these sections:
+
+- `# Spec`
+- `## Objective`
+- `## Audience`
+- `## Decision Or Action`
+- `## Output`
+- `## Constraints`
+- `## Available Materials`
+- `## Known Gaps`
+- `## Acceptance Criteria`
+- `## Recommended Next Step`
+
+Use explicit `Unknown` or `Pending user input` entries instead of inventing requirements.
+
+## Outputs
+
+- Root-level `spec.md`.
+- A short summary of open questions, source limitations, and the recommended next skill.
+
+## Must Not
+
+- Do not write `researches/**/*.md`.
+- Do not write `deck-plan.md`.
+- Do not write `decks/*.html`.
+- Do not bind findings into a Narrative Vault or canonical evidence graph.
+- Do not treat domain guidance or unreviewed local files as source evidence.
+- Do not invent requirements, constraints, citations, source paths, URLs, numbers, licenses, or acceptance criteria.

package/tools/research-save.ts

@@ -6,7 +6,8 @@ export default tool({
     "Save a research findings file to the workspace researches/ directory. " +
     "Creates researches/{topic}/{filename}.md with YAML frontmatter. " +
     "Each research axis gets its own file (e.g. 'market-data', 'catl-profile'). " +
-    "Content should use ## Data / ## Cases / ## Images / ## Gaps sections.",
+    "Content should use structured blocks such as ## Finding: <stable-id>, ## Synthesis: <stable-id>, ## Analysis: <stable-id>, " +
+    "## Implementation Note: <stable-id>, ## Asset Lead: <stable-id>, and ## Gaps.",
   args: {
     topic: tool.schema
       .string()
@@ -23,10 +24,12 @@ export default tool({
     content: tool.schema
       .string()
       .describe(
-        "Structured markdown findings. Use these sections (omit empty ones):\n" +
-        "## Data — key stats and data points, each with [Source: url]\n" +
-        "## Cases — company/entity profiles, 1-2 sentences each with [Source: url]\n" +
-        "## Images — image URLs: '{description}: {url} | Alt: {text} | Use: logo|screenshot|portrait'\n" +
+        "Structured markdown findings. Prefer stable cards:\n" +
+        "## Finding: <stable-id> — evidence with Source, URL/path, Quote/Snippet, Supports, Evidence boundary, Strength, Deck use, and optional Display note\n" +
+        "## Synthesis: <stable-id> — interpretation across findings with Basis, Interpretation, So what, Decision implication, Confidence, Alternative reading, Evidence boundary, Deck use, and optional Display note\n" +
+        "## Analysis: <stable-id> — LLM/user analytical frameworks; not external factual proof\n" +
+        "## Implementation Note: <stable-id> — render/data/API contracts; not market evidence\n" +
+        "## Asset Lead: <stable-id> — image/logo/media leads with source, license/attribution status, alt text, and deck use\n" +
         "## Gaps — topics not found or insufficiently covered",
       ),
     sources: tool.schema