@cyber-dash-tech/revela 0.15.1 → 0.15.3

package/README.md

@@ -17,8 +17,8 @@ Its first render target is still the HTML slide deck: start a Revela workflow co
 
 ## What It Does
 
-- injects one-shot workflow instructions for explicit commands such as `/revela init`, `/revela story`, and `/revela make deck`
-- switches into deck-render prompt mode only when you explicitly start `/revela make deck`
+- injects one-shot workflow instructions for explicit commands such as `/revela init`, `/revela story`, and `/revela make --deck`
+- switches into deck-render prompt mode only when you explicitly start `/revela make --deck`
 - supports workspace document discovery, transparent text extraction for `.pdf`, `.docx`, `.pptx`, and `.xlsx`, and cached embedded-material extraction for those formats
 - keeps `DECKS.json` as the current workspace state engine for sources, research actions, findings, claims, evidence, narrative intent, render targets, and readiness
 - reviews narrative readiness before artifact rendering, then separately gates deck HTML writes through deck/artifact readiness
@@ -95,8 +95,8 @@ Optionally switch design or domain:
 
 ```text
 /revela design
-/revela design use summit
-/revela domains deeptech-investment
+/revela design --use summit
+/revela domain --use deeptech-investment
 ```
 
 Then shape, research, or review the story. When the narrative is ready and approved, make the deck:
@@ -104,32 +104,14 @@ Then shape, research, or review the story. When the narrative is ready and appro
 ```text
 /revela story
 /revela research
-/revela make deck
-```
-
-If you need to check only the deck/artifact gate before HTML writing, use:
-
-```text
-/revela make deck --review
+/revela make --deck
 ```
 
 Export when needed, either manually or by asking the agent to export:
 
 ```text
-/revela pdf decks/humanoid-robotics.html
-/revela pptx decks/humanoid-robotics.html
-```
-
-If you want normal chat messages to stay in Revela narrative mode between explicit commands, enable optional ambient mode:
-
-```text
-/revela enable
-```
-
-Disable ambient mode when done:
-
-```text
-/revela disable
+/revela export --deck pdf decks/humanoid-robotics.html
+/revela export --deck pptx decks/humanoid-robotics.html
 ```
 
 ---
@@ -137,64 +119,49 @@ Disable ambient mode when done:
 ## Commands
 
 ```text
-/revela                          show status and help
-/revela enable                   optional ambient narrative mode for normal chat
-/revela disable                  disable ambient Revela mode
+/revela                          show REVELA help
 
 /revela init                     initialize or refresh narrative workspace state
 /revela research                 research, bind evidence, and reduce story gaps/caveats
 /revela story                    open the read-only story workspace UI
-/revela make deck                make a deck from approved story state
-/revela make deck --review       review deck/artifact readiness before writing HTML
-/revela make brief [file.md]     render executive brief from approved story
-/revela remember <text>          save an explicit user/workflow preference
-/revela refine                   open unified reading, inspection, and editing workspace
-/revela inspect                  deprecated shim to /revela refine Inspect mode
-
-/revela review                   legacy readiness report for story state
-/revela narrative                compatibility alias for /revela story
-/revela deck                     compatibility alias for /revela make deck
-/revela brief [file.md]          compatibility alias for /revela make brief
+/revela make --deck              make a deck from approved story state
+/revela make --brief [file.md]   render executive brief from approved story
+/revela refine --deck            open unified deck reading, inspection, and editing workspace
+/revela export --deck pdf [file] export an HTML deck to PDF in the same directory
+/revela export --deck pptx [file] [--notes] export an HTML deck to editable PPTX
 
 /revela design                   list installed designs
-/revela design use <name>        activate a design
-/revela design new <name>        create a custom design with AI
-/revela design edit <name>       refine an existing custom design with AI
-/revela design preview [name]    open a design preview in the browser
-/revela design add <source>      install a design from URL, local path, or github:user/repo
-/revela design rm <name>         remove an installed design
-/revela designs                  list installed designs
-/revela designs <name>           activate a design
-/revela designs-new <name>       create a custom design with AI
-/revela designs-edit <name>      refine an existing custom design with AI
-/revela designs-preview [name]   open a design preview in the browser
-/revela designs-add <source>     install a design from URL, local path, or github:user/repo
-/revela designs-rm <name>        remove an installed design
-
-/revela domains                  list installed domains
-/revela domains <name>           activate a domain
-/revela domains-add <source>     install a domain from URL, local path, or github:user/repo
-/revela domains-rm <name>        remove an installed domain
-
-/revela pdf <file>               export an HTML deck to PDF in the same directory
-/revela pptx <file>              export an HTML deck to editable PPTX in the same directory
+/revela design --use <name>      activate a design
+/revela design --new <name>      create a custom design with AI
+/revela design --edit <name>     refine an existing custom design with AI
+/revela design --preview [name]  open a design preview in the browser
+/revela design --add <source>    install a design from URL, local path, or github:user/repo
+/revela design --rm <name>       remove an installed design
+
+/revela domain                   list installed domains
+/revela domain --use <name>      activate a domain
+/revela domain --add <source>    install a domain from URL, local path, or github:user/repo
+/revela domain --rm <name>       remove an installed domain
 ```
 
-Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela research`, `/revela story`, `/revela review`, `/revela make deck`, `/revela remember`, `/revela design new`, and `/revela design edit` start AI-assisted workflows because they need to read or update project files. These workflow commands keep the visible chat message short and inject their detailed instructions through a one-shot system-prompt command intent. `/revela refine` is the unified post-artifact workspace. It opens a local browser workspace with Edit and Inspect tabs that share the same Cmd/Ctrl-click element references. Edit sends targeted comments back into the current OpenCode session; Inspect sends grounded selection context to the current OpenCode session and renders localized Narrative Reading, Exploratory Reading, Source, and Purpose cards, has no chat box, and does not edit the deck. Deterministic preprocessing is kept as fallback context rather than the normal first UI. If a generated result omits newer reading cards, Refine keeps the deterministic Narrative Reading and Exploratory Reading cards instead of dropping context. Narrative Reading also shows artifact coverage for the selected canonical claim, including whether each recorded artifact contains the claim and whether coverage is current, stale, partial, or missing. Exploratory Reading is explicitly non-official and bounded to recorded claims, evidence, caveats, objections, risks, and artifact coverage. `/revela edit` has been removed; use `/revela refine` instead. `/revela inspect` remains only as a deprecated compatibility shim to Refine.
+Most `/revela` commands run locally with zero LLM cost. `/revela init`, `/revela research`, `/revela story`, `/revela make --deck`, `/revela design --new`, `/revela design --edit`, and `/revela export --deck pptx --notes` start AI-assisted workflows because they need to read or update project files. These workflow commands keep the visible chat message short and inject their detailed instructions through a one-shot system-prompt command intent. `/revela refine --deck` is the unified post-artifact workspace. It opens a local browser workspace with Edit and Inspect tabs that share the same Cmd/Ctrl-click element references. Edit sends targeted comments back into the current OpenCode session; Inspect sends grounded selection context to the current OpenCode session and renders localized Narrative Reading, Exploratory Reading, Source, and Purpose cards, has no chat box, and does not edit the deck. Deterministic preprocessing is kept as fallback context rather than the normal first UI. If a generated result omits newer reading cards, Refine keeps the deterministic Narrative Reading and Exploratory Reading cards instead of dropping context. Narrative Reading also shows artifact coverage for the selected canonical claim, including whether each recorded artifact contains the claim and whether coverage is current, stale, partial, or missing. Exploratory Reading is explicitly non-official and bounded to recorded claims, evidence, caveats, objections, risks, and artifact coverage. `/revela edit` and `/revela inspect` are no longer public commands; use `/revela refine --deck` instead.
 
 ---
 
 ## How It Works
 
-Explicit Revela workflow commands append one-shot command instructions to the current agent's system prompt. `/revela enable` is optional ambient mode for keeping normal chat in Revela narrative mode between explicit commands.
+Explicit Revela workflow commands append one-shot command instructions to the current agent's system prompt and choose the needed prompt mode automatically.
 
-The default prompt is narrative-first: it follows `Init -> Research -> Story -> Make -> Refine` and focuses on audience belief shift, decision/action, thesis, claims, evidence boundaries, objections, risks, research gaps, and approval. Active design CSS, layout catalogs, component indexes, chart rules, and deck HTML skeletons are intentionally omitted until `/revela make deck` switches the session into deck-render mode or `/revela design` starts explicit design work.
+The default prompt is narrative-first: it follows `Init -> Research -> Story -> Make -> Refine -> Export` and focuses on audience belief shift, decision/action, thesis, claims, evidence boundaries, objections, risks, research gaps, and approval. Active design CSS, layout catalogs, component indexes, chart rules, and deck HTML skeletons are intentionally omitted until `/revela make --deck` switches the session into deck-render mode or `/revela design` starts explicit design work.
 
-Deck-render mode is built from 3 layers:
+Deck-render mode is built from 2 layers:
 
 1. `skill/SKILL.md` - the core deck-render workflow
-2. active domain - domain-specific report structure and terminology
-3. active design - visual system, layouts, components, and chart rules
+2. active design - visual system, layouts, components, and chart rules
+
+Active domain guidance is narrative-only. It helps `init`, `research`, and `story`
+shape the canonical narrative; `make --deck` renders that approved narrative
+without injecting the full domain prompt again.
 
 Persistent preferences live in `~/.config/revela/config.json`.
 The ambient enabled or disabled state is session-level only.
@@ -211,7 +178,7 @@ The state records:
 - render targets such as the active HTML deck plus derived PDF and PPTX artifacts
 - review snapshots with input hashes so old readiness results become stale after meaningful state changes
 
-Existing root `DECKS.json` workspaces remain compatible. Running `/revela init` or `/revela review` on an older project can normalize canonical narrative state and refresh projection fields without requiring a manual migration, moving files, or replacing `DECKS.json` with a database. `writeReadiness.status: "ready"` is deck/artifact readiness only; it is never narrative approval.
+Existing root `DECKS.json` workspaces remain compatible. Running `/revela init` or `/revela story` on an older project can normalize canonical narrative state and refresh projection fields without requiring a manual migration, moving files, or replacing `DECKS.json` with a database. `writeReadiness.status: "ready"` is deck/artifact readiness only; it is never narrative approval.
 
 Decks remain the primary authored artifact, but they are now treated as render targets from the same workspace state that can later support briefs, appendix material, Evidence Inspector views, Q&A, and interactive reading layers without duplicating source/evidence logic.
 
@@ -225,26 +192,16 @@ Use Revela as a narrative-first artifact workflow:
 2. Use `/revela research` when story gaps or unsupported central claims need external evidence; it should loop through research, evidence binding, claim/relation narrowing, and re-review until public research stops improving the state.
 3. Use `/revela story` to open the story workspace UI and inspect claim flow, evidence, caveats, research gaps, approval state, and artifact coverage.
 4. Approve the narrative or request revisions. If you intentionally render before full strategic approval, record an explicit render override.
-5. Run `/revela make deck` to compile the approved narrative into deck slide specs and enter deck-render mode, or `/revela make brief` to render an executive brief.
-6. Choose or confirm design only during deck handoff, then run the deck/artifact gate with `/revela make deck --review` or the handoff workflow.
+5. Run `/revela make --deck` to compile the approved narrative into deck slide specs and enter deck-render mode, or `/revela make --brief` to render an executive brief.
+6. Choose or confirm design only during deck handoff; `/revela make --deck` runs the deck/artifact gate after plan confirmation.
 7. Let the agent write the HTML deck under `decks/` only after the artifact gate is ready.
-8. Use `/revela refine` for visual comments, targeted revisions, read-only Narrative Reading, bounded Exploratory Reading, Source, and Purpose inspection, and claim-to-artifact coverage for selected deck elements.
-9. Use `/revela refine` for post-artifact changes; `/revela edit` has been removed and `/revela inspect` remains only for old scripts or habits.
-10. Export with `/revela pdf <file>` or `/revela pptx <file>`.
-
-Use `/revela enable` only when you want ordinary chat messages, not just explicit `/revela ...` commands, to stay in Revela narrative mode.
-
-`/revela story` opens the read-only story workspace UI. `/revela review` produces the legacy readiness report for unclear audience, missing belief shift, missing decision/action, weak thesis, unsupported central claims, weak evidence, unsupported scope, unhandled objections, missing risk/assumption handling, stale approval, or missing approval. Neither command reviews design/layout readiness or writes the final deck.
+8. Use `/revela refine --deck` for visual comments, targeted revisions, read-only Narrative Reading, bounded Exploratory Reading, Source, and Purpose inspection, and claim-to-artifact coverage for selected deck elements.
+9. Use `/revela refine --deck` for post-artifact changes; `/revela edit` and `/revela inspect` are no longer public commands.
+10. Export with `/revela export --deck pdf <file>` or `/revela export --deck pptx <file>`.
 
-If Revela blocks a deck write, ask the agent to run `/revela make deck --review`, resolve the reported artifact gaps, and try again. This protects the deck file from being overwritten before the slide specs, evidence projection, design/layout readiness, review snapshot, and deck HTML contract are ready.
-
-To remember long-term preferences, use:
-
-```text
-/revela remember Prefer concise Chinese consulting-style decks.
-```
+`/revela story` opens the read-only story workspace UI for unclear audience, missing belief shift, missing decision/action, weak thesis, unsupported central claims, weak evidence, unsupported scope, unhandled objections, missing risk/assumption handling, stale approval, or missing approval. It does not review design/layout readiness or write the final deck.
 
-Do not use `remember` for temporary checklist state; use it only for durable user or workflow preferences.
+If Revela blocks a deck write, ask the agent to continue `/revela make --deck`, resolve the reported artifact gaps, and try again. This protects the deck file from being overwritten before the slide specs, evidence projection, design/layout readiness, review snapshot, and deck HTML contract are ready.
 
 ---
 
@@ -329,7 +286,7 @@ You can also run QA manually with the `revela-qa` tool.
 
 ## Designs And Domains
 
-Use `/revela design` and `/revela domains` to inspect what is installed in your environment. Older `/revela designs*` commands remain compatibility aliases.
+Use `/revela design` and `/revela domain` to inspect what is installed in your environment. Older `/revela designs*` commands now show migration help.
 
 Bundled domains in this repository:
 
@@ -356,8 +313,7 @@ unless the installer infers another name from the source.
 You can ask Revela to create a new local design interactively:
 
 ```text
-/revela designs-new my-design
-/revela design new my-design
+/revela design --new my-design
 ```
 
 The agent will interview you for visual references, summarize a design brief for confirmation, then save `DESIGN.md` and `preview.html` into your local Revela designs directory. For AI-authored designs, `preview.html` is required: it must include cover and closing slides, and it must showcase every `@component:*` before `revela-designs-author` will accept the package. The default structural base is an internal neutral `starter` design, which is hidden from the normal design list. Use `--base summit` or `--base monet` only when you want to derive from those specific styles.
@@ -365,8 +321,7 @@ The agent will interview you for visual references, summarize a design brief for
 Refine an existing local design:
 
 ```text
-/revela designs-edit my-design
-/revela design edit my-design
+/revela design --edit my-design
 ```
 
 The agent will ask what to change, inspect the current design, confirm an edit brief, then overwrite the local design package through the controlled authoring tool.
@@ -374,8 +329,7 @@ The agent will ask what to change, inspect the current design, confirm an edit b
 Open a design preview in your browser:
 
 ```text
-/revela designs-preview my-design
-/revela design preview my-design
+/revela design --preview my-design
 ```
 
 Omit the name to preview the active design. If a design has no `preview.html`, Revela will report that no preview is available.
@@ -583,9 +537,9 @@ If a design has no markers, Revela falls back to injecting the full `DESIGN.md`
 Install a custom design:
 
 ```text
-/revela design add github:your-org/your-design
-/revela design add https://example.com/my-design.zip
-/revela design add ./path/to/local/design-folder
+/revela design --add github:your-org/your-design
+/revela design --add https://example.com/my-design.zip
+/revela design --add ./path/to/local/design-folder
 ```
 
 ---
@@ -595,7 +549,7 @@ Install a custom design:
 A custom domain is a folder containing `INDUSTRY.md`.
 
 ```text
-/revela domains-add github:your-org/your-domain
+/revela domain --add github:your-org/your-domain
 ```
 
 `INDUSTRY.md` is a legacy filename kept for compatibility.
@@ -607,10 +561,10 @@ A custom domain is a folder containing `INDUSTRY.md`.
 Use the unified refinement workspace for normal post-write review and revision:
 
 ```text
-/revela refine
+/revela refine --deck
 ```
 
-`/revela refine` opens the active HTML deck with two tabs. Use `Ctrl`/`Cmd` + click once to reference deck elements, then choose Edit for fast natural-language change comments or Inspect for read-only Narrative Reading, bounded Exploratory Reading, Source, Purpose, and artifact coverage review. Inspect does not mutate the deck; Edit remains the mutation path. This is the recommended entry for post-artifact reading, inspection, and editing.
+`/revela refine --deck` opens the active HTML deck with two tabs. Use `Ctrl`/`Cmd` + click once to reference deck elements, then choose Edit for fast natural-language change comments or Inspect for read-only Narrative Reading, bounded Exploratory Reading, Source, Purpose, and artifact coverage review. Inspect does not mutate the deck; Edit remains the mutation path. This is the recommended entry for post-artifact reading, inspection, and editing.
 
 Removed command:
 
@@ -618,25 +572,25 @@ Removed command:
 /revela edit
 ```
 
-`/revela edit` has been removed. Use `/revela refine` for the unified reading, inspection, and editing workspace.
+`/revela edit` has been removed. Use `/revela refine --deck` for the unified reading, inspection, and editing workspace.
 
 Use `Ctrl`/`Cmd` + click to reference deck elements, write a natural-language comment in the Edit tab, then send it back to OpenCode. Revela sends a structured edit prompt that includes the deck file, slide context, selected element metadata, and your comment.
 
 LLM tool equivalent: `revela-edit` with no target. The tool remains a compatibility shim and opens Refine in Edit mode when you say things like “I want to edit the deck”.
 
-For existing decks, `/revela refine` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
+For existing decks, `/revela refine --deck` prepares whatever minimal project context is needed so targeted edits can still use the normal safety checks.
 
 ---
 
 ## Evidence Inspector
 
-Use `/revela refine` for evidence inspection and narrative reading. Deprecated compatibility command:
+Use `/revela refine --deck` for evidence inspection and narrative reading. Removed compatibility command:
 
 ```text
 /revela inspect
 ```
 
-`/revela inspect` no longer opens a separate inspector shell. It opens `/revela refine` in Inspect mode. The Inspect tab shows Narrative Reading and Exploratory Reading cards alongside the fixed Source and Purpose cards. Narrative Reading preserves canonical claim ids, evidence binding ids, supported scope, unsupported scope, caveats, objections, risks, and artifact coverage when the selected element maps to canonical narrative state. Coverage shows whether the selected claim appears in recorded deck/brief/export artifacts and whether those artifacts are current, stale, partial, or missing against the current narrative hash. Exploratory Reading provides non-official objection prep, audience reframing boundaries, appendix leads, and meeting-prep cues from the same recorded context only. Use `Ctrl`/`Cmd` + click to reference deck elements, then click `Inspect Selection`. Selection is locked while the request is being processed.
+`/revela inspect` no longer opens a separate inspector shell. Use `/revela refine --deck` and the Inspect tab. The Inspect tab shows Narrative Reading and Exploratory Reading cards alongside the fixed Source and Purpose cards. Narrative Reading preserves canonical claim ids, evidence binding ids, supported scope, unsupported scope, caveats, objections, risks, and artifact coverage when the selected element maps to canonical narrative state. Coverage shows whether the selected claim appears in recorded deck/brief/export artifacts and whether those artifacts are current, stale, partial, or missing against the current narrative hash. Exploratory Reading provides non-official objection prep, audience reframing boundaries, appendix leads, and meeting-prep cues from the same recorded context only. Use `Ctrl`/`Cmd` + click to reference deck elements, then click `Inspect Selection`. Selection is locked while the request is being processed.
 
 The inspector is not chat and has no freeform prompt. It does not mutate `DECKS.json` or the deck HTML. It uses recorded slide specs, narrative state, and slide-level evidence trace as grounded context. Inspect is LLM-first in the UI: it shows a reading/loading state, then renders structured generated cards. Deterministic preprocessing remains internal fallback context and is shown only if generation fails or times out. The Inspect tab includes a fixed display-language selector; language changes affect card copy only and never alter claim ids, evidence ids, source paths, URLs, numbers, quotes, or canonical facts. When an older or partial generated result only returns Source/Purpose, Refine preserves the deterministic reading cards so generated inspection cannot silently remove claim, evidence-boundary, artifact-coverage, or exploratory context.
 
@@ -649,7 +603,7 @@ Refine uses the active HTML deck render target recorded in workspace state. The
 PDF export:
 
 ```text
-/revela pdf decks/my-deck.html
+/revela export --deck pdf decks/my-deck.html
 ```
 
 LLM tool equivalent: `revela-pdf` with `{ "file": "decks/my-deck.html" }`.
@@ -657,12 +611,12 @@ LLM tool equivalent: `revela-pdf` with `{ "file": "decks/my-deck.html" }`.
 Editable PPTX export:
 
 ```text
-/revela pptx decks/my-deck.html
+/revela export --deck pptx decks/my-deck.html
 ```
 
 LLM tool equivalent: `revela-pptx` with `{ "file": "decks/my-deck.html" }`.
 
-Both commands and tools write output beside the source HTML deck. Use the tools when you want the agent to run export as part of the deck workflow instead of asking the user to invoke `/revela pdf` or `/revela pptx` manually.
+Both commands and tools write output beside the source HTML deck. Use the tools when you want the agent to run export as part of the deck workflow instead of asking the user to invoke `/revela export --deck pdf` or `/revela export --deck pptx` manually.
 
 ---