@cyber-dash-tech/revela 0.17.23 → 0.18.2

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

@@ -1,50 +1,31 @@
 ---
 name: revela-make-deck
-description: Plan and generate Revela deck artifacts in Codex from canonical narrative state and deck-plan files.
+description: Plan and generate Revela deck artifacts in Codex from deck-plan files and source-linked materials.
 ---
 
 # Revela Make Deck
 
-Use this skill when the user asks to make, generate, or update a Revela deck.
+Use this skill when the user asks to plan, make, generate, or update a Revela deck.
 
 ## Source Authority
 
-- Canonical meaning comes from `revela-narrative/`.
-- Deck execution planning comes from `deck-plan/`.
+- Deck execution planning comes from canonical `deck-plan.md`.
+- Local materials, material reviews, `researches/`, `assets/`, and user intent provide source context.
 - Generated artifacts live under `decks/*.html`.
-- `DECKS.json.slides[]` is not the slide-count contract.
+- Do not require a Narrative Vault before planning or generating a deck.
 
 ## Workflow
 
-1. Call `revela_compile_narrative` and `revela_markdown_qa`.
-2. Report narrative and Markdown diagnostics, but treat only malformed/unsafe files and technical artifact validity as hard blockers.
-3. Call `revela_design_list`, `revela_design_read` using `section: "rules"`, and `revela_design_inventory` before authoring or repairing `deck-plan/`; deck-plan layout/component names must come from the selected design inventory.
-4. Call `revela_read_deck_plan` as the required deck-plan preflight before any HTML generation.
-5. If `deck-plan/` is missing or incomplete, author or repair `deck-plan/index.md` and `deck-plan/slides/*.md` before calling `revela_create_deck_foundation`; use only inventory-listed layouts/components in slide frontmatter and visual intent.
-6. Report deck-plan diagnostics before artifact generation, including stale narrative hashes, missing slide projections, missing evidence trace, caveats, malformed plan files, or layout/component names outside the active design inventory.
-7. Do not start HTML generation from narrative alone unless the user explicitly asks for a throwaway diagnostic smoke deck.
-8. For new HTML files, call `revela_create_deck_foundation`.
-9. Before patching slide HTML, read the specific layouts/components used by the deck plan with `revela_design_read_layout` and `revela_design_read_component`; fetch `section: "chart-rules"` and the `echart-panel` component before creating or changing ECharts. If the user asks to switch designs persistently, call `revela_design_activate`; if they ask for a one-off design, read that design by name, call `revela_design_inventory` with that name, and pass `designName` to `revela_create_deck_foundation`.
-10. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values. Every slide must use `<section class="slide" ...>` with exactly one direct `.slide-canvas` child.
-11. Generate chapter by chapter. Keep the HTML valid after each write.
-12. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
-
-## Generated Visual Assets
-
-- Codex may use the `imagegen` skill for deck-level visual assets when a slide's visual intent calls for an image or diagram and no suitable workspace/source asset exists.
-- Prefer `imagegen` for flow diagrams, framework diagrams, process visuals, system relationship maps, journey maps, before/after schematics, conceptual illustrations, abstract heroes, chapter dividers, background textures, non-evidence metaphor visuals, and visual drafts.
-- Do not use generated images for source evidence, factual screenshots, real people, real places, real products, logos, data charts, tables, or visuals that need verifiable factual accuracy.
-- If the visual needs exact editable text, precise data, axes, code, tables, or strict structure, build it with HTML/CSS, ECharts, or `data-table` instead of `imagegen`.
-- Generated images are artifact-level visuals only. Do not treat them as evidence, source materials, quote support, or factual proof.
-- If a generated image is referenced by deck HTML, move or copy the final asset into the workspace, preferably under `assets/<topic>/media/` or the project's existing asset directory. Deck HTML must reference a workspace-relative local path, never Codex's default generated-image path.
-
-## QA Repair Loop
-
-- `revela_run_deck_qa` launches a browser. In sandboxed Codex sessions, this may require user-approved command escalation.
-- If QA reports `text_overflow` or `text_clipped`, reduce font size, line length, padding, or line-height before changing narrative meaning.
-- Prefer conservative cover and section-title sizing in smoke or diagnostic decks.
-- If QA reports that a standalone smoke artifact is not the active legacy deck target, treat it as a non-blocking warning when slide identity and canvas checks pass.
+1. For planning requests, inspect local materials/reviews/research, then write or repair `deck-plan.md` directly. Do not use structured upsert tools for normal plan authoring.
+2. Call `revela_design_list`, `revela_design_read` with `section: "rules"`, and `revela_design_inventory` before selecting layouts/components; use the returned layout slots and component nesting hints in `deck-plan.md`.
+3. Call `revela_read_deck_plan` after writing or repairing `deck-plan.md`. If diagnostics report layout, slot, component, `children`, or `sourceLinks` issues, patch the Markdown directly and call `revela_read_deck_plan` again.
+4. Call `revela_read_deck_plan` before HTML generation and follow the current projection. `revela_read_deck_plan` is QA/diagnostics, not a writer.
+5. For new HTML files, call `revela_create_deck_foundation`.
+6. Before patching slide HTML, read the specific layouts/components with `revela_design_read_layout` and `revela_design_read_component`; fetch chart rules before ECharts.
+7. Patch slides into the foundation between Revela slide markers. Preserve positive 1-based `data-slide-index` values. Every slide must have exactly one direct `.slide-canvas` child.
+8. Generate chapter by chapter. Keep the HTML valid after each write.
+9. After every HTML write, call `revela_run_deck_qa` and repair hard errors before review or export.
 
 ## Deck Plan Requirements
 
-Every deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, low-fidelity layout sketches, narrative links, visual intent, evidence trace, and caveats.
+Every normal deck plan should include Cover, Table of Contents, and Closing. Use 3-5 chapter headings, explicit slide ranges, `sourceLinks` for materials/findings/assets/URLs/caveats, visual intent, caveats, and unresolved inputs. Use `box.children` when multiple child components support one semantic idea; do not duplicate the same child as both nested and top-level.

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

@@ -1,38 +1,29 @@
 ---
 name: revela-research
-description: Research Revela story gaps and bind evidence in Codex while preserving explicit source boundaries.
+description: Research source-linked findings for a Revela deck plan while preserving explicit source boundaries.
 ---
 
 # Revela Research
 
-Use this skill when the user asks to research, close evidence gaps, evaluate saved findings, or bind support to current Revela claims.
+Use this skill when the user asks to research missing deck inputs, gather public support, save findings, or find source-linked examples/assets for a deck.
 
 ## Contract
 
-- Saved findings in `researches/**/*.md` are not canonical evidence until specific evidence nodes or bindings preserve source trace, quote/snippet, support scope, unsupported scope, caveat, and strength.
-- Missing evidence must stay visible as a gap.
-- Do not broaden claims to fit a source.
-- Do not write deck artifacts during research.
+- Research output is saved under `researches/**/*.md` for deck-plan use.
+- Do not bind findings into a Narrative Vault or canonical evidence graph.
+- Do not create deck artifacts during research.
+- Do not invent URLs, quotes, page references, numbers, caveats, or licenses.
 
 ## Workflow
 
-1. Call `revela_research_targets` to derive target order, selected target, saved findings diagnostics, and evidence gaps.
-2. For existing saved findings, call `revela_evaluate_research_findings` before deciding whether they can support a claim.
-3. Use external research only when the user allowed or requested it and the gap is publicly researchable.
-4. After external research, call `revela_research_save` with structured Markdown findings and explicit source list.
-5. Bind only when `bindingEval.status === "bindable"` by calling `revela_bind_research_findings`; do not hand-author evidence Markdown for bindable saved findings.
-6. If a finding is incomplete, report missing fields instead of inventing them.
-7. After binding or any narrative edit, call `revela_markdown_qa` and `revela_compile_narrative`.
-8. Report evidence bound, unbound findings, remaining caveats, and the next smallest story action.
-
-## Binding Criteria
-
-Bind only when the supported claim exists and the evidence includes:
-
-- source URL/path/findings file
-- quote or traceable snippet
-- support scope
-- unsupported scope
-- caveat
-- strength
-- explicit supported claim context
+1. Inspect material intake status, material review files, existing `researches/**/*.md`, and `deck-plan.md` when present.
+2. Identify the smallest research tasks needed for the deck objective: market facts, benchmarks, examples, source quotes, images/logos/screenshots, or caveats.
+3. Use external research only for public facts or user-authorized questions.
+4. Save useful findings with `revela_research_save`.
+5. Each finding should include source URL/path, quote/snippet, what it supports, what it does not support, caveat, date checked, and optional image leads.
+6. If a finding is context only, label it as context and do not present it as proof.
+
+## Report
+
+- Start with `Research: completed`.
+- List saved findings paths, source limitations, unresolved inputs, and whether `/revela plan --deck` can proceed.

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

@@ -1,43 +1,25 @@
 ---
 name: revela-review-deck
-description: Review Revela deck artifacts in Codex for technical validity, evidence trace, and narrative alignment.
+description: Review Revela deck artifacts in Codex for technical validity and targeted deck edits.
 ---
 
 # Revela Review Deck
 
-Use this skill when the user asks to review, inspect, diagnose, or refine a generated Revela deck.
+Use this skill when the user asks to review, diagnose, QA, or refine a generated Revela deck.
 
 ## Workflow
 
 1. Resolve the target `decks/*.html` file from the user request or unambiguous workspace state.
-2. For a plain request like `review decks/foo.html`, call `revela_review_deck_open` and let the tool open the browser by default.
-3. Use `revela_review_deck_read`, normally with `format: "markdown"`, only when the user explicitly asks to diagnose, QA, read, check, inspect source alignment, inspect evidence trace, or avoid opening a GUI.
-4. Use the read output as the deterministic diagnostics packet for artifact QA, deck-plan diagnostics, narrative/vault diagnostics, artifact coverage, and evidence trace.
-5. Pass `openBrowser: false` only for tests, no-GUI environments, or when the user explicitly asks for a link instead of opening the page.
-6. Do not call `revela_run_deck_qa`, `revela_compile_narrative`, or `revela_read_deck_plan` separately for a normal Review UI open.
-7. Call `revela_run_deck_qa` separately only for focused low-level artifact QA, after a repair, or when the user explicitly asks for QA detail.
-8. Separate technical blockers from narrative/evidence diagnostics.
-9. Pure visual/layout/export fixes may patch artifacts directly when the user asks for a change, but read active design rules first with `revela_design_read` using `section: "rules"`. Meaning changes must update `revela-narrative/` first.
-
-## Generated Visual Assets
-
-- For Review Comment or Apply Fix requests such as adding an image, replacing a cover visual, creating a concept illustration, making a media block visual, or turning a slide idea into a flow/framework diagram, Codex may use the `imagegen` skill.
-- Prefer `imagegen` for flow diagrams, framework diagrams, process visuals, system relationship maps, journey maps, before/after schematics, conceptual illustrations, abstract heroes, chapter dividers, background textures, non-evidence metaphor visuals, and visual drafts.
-- Do not use generated images for source evidence, factual screenshots, real people, real places, real products, logos, data charts, tables, or visuals that need verifiable factual accuracy. Use workspace/source assets instead, or report the missing asset.
-- If the visual needs exact editable text, precise data, axes, code, tables, or strict structure, patch the deck with HTML/CSS, ECharts, or `data-table` instead of `imagegen`.
-- Generated images are artifact-level visual patches only. Do not add them to evidence, source materials, narrative support, or factual trace.
-- If a generated image is referenced by deck HTML, move or copy the final asset into the workspace, preferably under `assets/<topic>/media/` or the project's existing asset directory. Deck HTML must reference a workspace-relative local path, never Codex's default generated-image path.
+2. For a plain review request, call `revela_review_deck_open` and let the tool open the browser by default.
+3. Use `revela_review_deck_read`, normally with `format: "markdown"`, only when the user explicitly asks for diagnostics, QA details, export readiness, or no-GUI output.
+4. Review UI is QA + Comment/Apply Fix. Insight/Inspect is removed.
+5. Do not call `revela_run_deck_qa` separately for a normal Review UI open.
+6. Pure visual/layout/export fixes may patch artifacts directly when the user asks for a change, but read active design rules first with `revela_design_read` using `section: "rules"`.
+7. Content changes that affect the deck argument should update `deck-plan.md` first, then remake the deck.
 
 ## QA Notes
 
-- `revela_review_deck_read` is read-only: it must not mutate deck HTML, `revela-narrative/`, `deck-plan/`, assets, or compatibility state.
-- `revela_review_deck_open` opens the local Review server from the MCP process and uses the Codex `codex-exec` bridge for Insight and Comment/Apply Fix. It returns URL/token/open state and basic file metadata, not aggregate diagnostics.
-- `revela_run_deck_qa` may need browser-launch permission in Codex sandboxed sessions.
+- `revela_review_deck_read` is read-only: it must not mutate deck HTML, `deck-plan.md`, assets, or compatibility state.
+- `revela_review_deck_open` returns URL/token/open state and basic file metadata.
 - Repair hard QA errors before treating a deck as review-ready.
-- Deck slides must use `<section class="slide" ...>` with exactly one direct `.slide-canvas` child; missing, nested, or duplicate slide canvases are hard artifact failures.
-- Text clipping should usually be fixed with typography and spacing changes, not by deleting evidence or changing claim meaning.
-- A warning that a smoke/development artifact is not the active legacy deck target is non-blocking when the requested file passes hard artifact checks.
-
-## Technical Blockers
-
-Hard blockers are limited to missing or ambiguous files, invalid HTML contract, invalid slide identity, canvas/export failure, malformed Markdown/frontmatter, or unsafe writes.
+- Deck slides must use `<section class="slide" ...>` with exactly one direct `.slide-canvas` child.

package/skill/SKILL.md

@@ -26,7 +26,7 @@ The active design is injected after this prompt. Follow it exactly.
 - Do not create or patch `DECKS.json` as workflow state.
 - Canonical narrative remains the authority for audience, decision, thesis,
   claims, evidence boundaries, objections, risks, and caveats.
-- When present, `deck-plan/` is the deck execution blueprint for slide order,
+- When present, `deck-plan.md` is the deck execution blueprint for slide order,
   chapter batches, visual intent, and evidence trace. It does not replace
   canonical narrative meaning.
 - `DECKS.json.slides[]` is a compatibility/cache projection, not the authority
@@ -59,9 +59,9 @@ handoff exactly:
    deck-plan authoring requirements. It does not write the final slide list.
 4. If target slide count, audience, language, output purpose, or visual style is
    unclear, ask the user for the smallest needed confirmation. Then write
-   `deck-plan/index.md` plus `deck-plan/slides/*.md` from the planning packet
-   and requirements, including low-fidelity sketches and `## Narrative Links`.
-5. Use `readDeckPlan` to inspect the current `deck-plan/` projection before
+   `deck-plan.md` from the planning packet and requirements, including
+   low-fidelity sketches and `sourceLinks`.
+5. Use `readDeckPlan` to inspect the current `deck-plan.md` projection before
    artifact review or HTML generation. Diagnostics are advisory unless they are
    artifact validity errors handled by QA.
 6. For a new deck HTML file, call `revela-deck-foundation` to create the
@@ -73,7 +73,7 @@ handoff exactly:
    user proceeds and the deck contract can be satisfied.
 
 Before any HTML generation, call `revela-decks` action `readDeckPlan` and follow
-the current `deck-plan/`: Source Authority, deck parameters, Chapter Writing
+the current `deck-plan.md`: Source Authority, deck parameters, Chapter Writing
 Batches, slide plan, visual intent, evidence trace, boundaries, and narrative
 links. Do not call `compileDeckPlan` merely to understand an existing plan, and
 do not reinterpret cached `DECKS.json.slides[]` as the render contract.
@@ -116,20 +116,19 @@ the deck's chapter grouping and the order of non-structural slides that follow.
 
 Before writing HTML, the deck-plan projection should include:
 
-- `deck-plan/index.md` with current `narrativeHash` when known and a slide-file
-  inventory.
-- `deck-plan/slides/*.md` files for each planned slide, using `## Narrative
-  Links` for `[[claim-id]]`, `[[evidence-id]]`, `[[risk-id]]`,
-  `[[objection-id]]`, or `[[gap-id]]` references.
+- `deck-plan.md` with `designName`, `outputPath` when known, chapter map, and
+  ordered slide blocks.
+- Each slide block uses `sourceLinks` for materials, findings, assets, URLs,
+  and caveats. Legacy narrative links may be read for compatibility, but new
+  plans should not use them.
 - `Required structure: Cover + Table of Contents + Closing`.
 - A `Chapters` section with 3-5 TOC headings, slide ranges, and the
   non-structural slides assigned to each chapter.
-- One row per slide with title, purpose, narrative role, content summary, layout,
-  components, primary/supporting claim ids, evidence binding ids or source
-  summary, `content.data.visualIntent`, `visuals[]`, and caveats/unsupported
-  scope.
-- Source Authority, Chapter Writing Batches, Evidence Trace, Boundary / Risk
-  Treatment, and HTML Identity Contract sections.
+- One row/block per slide with title, purpose, narrative role, content summary,
+  layout, components, `sourceLinks`, visual intent, visual brief, render notes,
+  and caveats/unsupported scope.
+- Source Authority, Chapter Map, Slides, Unresolved Inputs, and HTML Contract
+  sections.
 - A low-fidelity layout sketch for every slide when requested by the handoff
   prompt.
 
@@ -138,7 +137,11 @@ Rules for the slide plan:
 - Use one lightweight narrative role when clear: `context`, `tension`,
   `evidence`, `recommendation`, `risk`, `ask`, `appendix`, or `close`.
 - Use exact layout names from the Layout Index and exact component names from
-  the Component Index. Do not invent layout or component names.
+  the Component Index. Use only slots returned by the selected layout inventory.
+  Do not invent layout, slot, or component names.
+- Use `box.children` when several child components support one semantic idea.
+  Do not duplicate a child component both inside `box.children` and as a
+  separate top-level component plan entry.
 - Content summaries must be specific: real claims, numbers, evidence, or actions
   from narrative state and bound sources. Avoid vague descriptions like
   "overview of topic".
@@ -157,7 +160,7 @@ Rules for the slide plan:
   count or merge weak slides instead of creating sparse filler.
 
 Do not write any HTML until the user chooses to proceed from the current
-`deck-plan/` projection. `confirmDeckPlan` is compatibility/provenance only, not
+`deck-plan.md` projection. `confirmDeckPlan` is compatibility/provenance only, not
 a required workflow gate.
 
 ---
@@ -251,7 +254,7 @@ Required contract:
   when the HTML remains valid and every written slide satisfies this contract.
   Do not use filler or hidden overflow to make missing chapters appear complete.
 - Do not treat cached `DECKS.json.slides[]` length mismatches as an HTML identity
-  failure; plan completeness belongs to `deck-plan/` projection Markdown and
+  failure; plan completeness belongs to `deck-plan.md` and
   chapter batches when present.
 
 Example slide identity:

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

@@ -1,24 +0,0 @@
----
-name: revela-story
-description: Inspect a Revela narrative graph in Codex without mutating artifacts or canonical meaning.
----
-
-# Revela Story
-
-Use this skill when the user asks to view, inspect, understand, or audit the current Revela story.
-
-## Workflow
-
-1. Call `revela_story_read` first, normally with `format: "markdown"`.
-2. Use the returned deterministic map, diagnostics, narrative hash, and Markdown reading view as the authoritative Story surface.
-3. Call `revela_markdown_qa` or `revela_compile_narrative` only when you need deeper structural diagnostics than `revela_story_read` returned.
-4. If `revela_story_read.ok` is false because `revela-narrative/` is missing, report the init guidance. Do not create files from Story mode.
-5. Present audience, belief shift, decision/action, thesis, central claims, evidence, objections, risks, research gaps, artifact coverage, and diagnostics.
-6. Keep claim ids, evidence ids, source facts, quotes, URLs, numbers, and caveats exact.
-7. Do not write claims, evidence, research gaps, deck HTML, deck-plan files, assets, or artifacts from Story mode.
-
-## Output
-
-Lead with the narrative status, narrative hash, and key diagnostics. Then show the claim flow and evidence boundaries.
-
-Keep the reading evidence-first: for each claim, show source trace, support scope, unsupported scope, caveat, support strength, linked objections/risks, and remaining research gaps. Separate structural Markdown QA from evidence trust. Story is read-only; do not turn it into a mutation workflow.