@cyber-dash-tech/revela 0.7.8 → 0.8.1

package/skill/SKILL.md

@@ -49,31 +49,35 @@ If the brief is unclear, ask 1–3 targeted clarification questions. Do not forc
 the user to provide a research topic command; the working topic emerges from the
 conversation.
 
-### Phase 1.5 — Project State, Working Slug & Active Deck
+### Phase 1.5 — Project State, Output File & Current Deck
 
 Before research, use the `revela-decks` tool with action `read` or `init` to
 inspect `DECKS.json`. Treat it as the source of truth for project context,
-source material index, explicit user preferences, prior deck history, active
+source material index, explicit user preferences, current deck state, active
 deck specs, per-slide content/layout/components, write readiness, and open
 questions. Do not write or patch `DECKS.json` directly.
 
-Derive a **working slug** from the Research Brief: lowercase, hyphens, no spaces
-(e.g. "AI Investment Shift" → `ai-investment-shift`). The slug is only a file
-path handle for this deck/research cache; the user does not need to supply it as
-a command. Tell the user: "I'll save this deck as `decks/{slug}.html`." They can
-correct the name at this point.
+Treat the workspace folder as the deck project boundary. The `revela-decks` tool
+derives its internal deck key from the workspace folder name; this key is not
+user-facing.
+
+Derive an **output file** for the current deck. Default to
+`decks/{workspace-name}.html` using the normalized workspace folder name unless
+the user explicitly asks for a different filename. Tell the user: "I'll save this
+deck as `decks/<filename>.html`." They can correct the filename at this point.
 
 Check whether this deck has been worked on before:
-1. Run `glob researches/{slug}/*.md`.
-2. If research files already exist, list them and ask whether to reuse, supplement,
+1. Use the workspace-derived internal key from `DECKS.json.activeDeck` when available; otherwise use the normalized workspace folder name for `researches/{workspace-key}/`.
+2. Run `glob researches/{workspace-key}/*.md`.
+3. If research files already exist, list them and ask whether to reuse, supplement,
    or replace the existing research.
-3. If the user chooses reuse, read the existing files before Phase 4.
-4. If the user chooses supplement or replace, use the existing files to avoid
+4. If the user chooses reuse, read the existing files before Phase 4.
+5. If the user chooses supplement or replace, use the existing files to avoid
    duplicate work and proceed through Phase 3 only for missing or stale axes.
 
-All subsequent file paths in this session use the working slug:
-- Slides file: `decks/{slug}.html`
-- Research dir: `researches/{slug}/`
+All subsequent file paths in this session use the current workspace deck:
+- Slides file: the confirmed `decks/*.html` output path
+- Research dir: `researches/{workspace-key}/`
 
 Create or update the active deck in `DECKS.json` through `revela-decks` actions
 `upsertDeck` and `upsertSlides`. Keep the deck spec current as work progresses:
@@ -132,14 +136,14 @@ user 1–3 focused questions before launching agents.
 #### Research Brief Before Agents
 
 Before starting research agents, write a brief for yourself with:
-- working slug for `researches/{slug}/`
+- workspace-derived research key for `researches/{workspace-key}/`
 - user goal and audience
 - thesis or decision the deck should support
 - key questions and time period
 - relevant `DECKS.json` sourceMaterials or user-provided files
 - axes to research and desired output for each axis
 
-You do not need to ask the user to approve the slug unless the filename matters.
+You do not need to ask the user to approve an internal key. Ask only if the visible output filename matters.
 
 #### Deep Research via `revela-research` Subagents
 
@@ -152,14 +156,14 @@ axis gets one focused subagent brief. When multiple axes are needed, launch all
 agents in a single message with parallel Task tool calls.
 
 Each subagent brief must specify:
-- shared working slug for `researches/{slug}/`
+- shared workspace-derived research key for `researches/{workspace-key}/`
 - axis filename, such as `market-data`, `competitor-profile`, or `technology-trends`
 - the research question, time period, geography, and evidence standard
 - relevant `DECKS.json` sourceMaterials or user files to prioritize
 - whether web research is needed and what types of sources are preferred
 
 The subagent writes exactly one file through `revela-research-save`:
-`researches/{slug}/{axis-name}.md`.
+`researches/{workspace-key}/{axis-name}.md`.
 
 #### Workspace Memory and Freshness
 
@@ -177,7 +181,7 @@ deep-read files that are relevant to the current Research Brief.
 
 #### After Agents Complete
 
-List and read the findings files in `researches/{slug}/`. Each file contains
+List and read the findings files in `researches/{workspace-key}/`. Each file contains
 structured `## Data`, `## Cases`, `## Images`, and `## Gaps` sections. Use these
 directly as slide material, cross-reference them with workspace documents, and
 flag contradictions.
@@ -202,7 +206,7 @@ already checked and what specific missing information is needed.
 - **NEVER** call `revela-research` as a tool; use Task with `subagent_type: "revela-research"`
 - **NEVER** collapse distinct research axes into one broad agent brief when parallel focused briefs would be clearer
 - **ALWAYS** use `revela-decks` action `read` before deciding what research is needed
-- **ALWAYS** read each `researches/{slug}/{axis}.md` after agents complete
+- **ALWAYS** read each `researches/{workspace-key}/{axis}.md` after agents complete
 - Use the `read` tool for all file types — binary formats are handled transparently
 ---
 
@@ -302,7 +306,7 @@ After the user confirms the slide plan, update `DECKS.json` through `revela-deck
 3. Call `revela-designs` tool with `action: "read"` and `component` set to ALL component
    names you plan to use (comma-separated, e.g. `component: "card,stat-card,evidence-list"`).
 4. Use `revela-decks` action `upsertDeck` to mark `requiredInputs.designLayoutsFetched` complete.
-5. Run `/revela review {slug}` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
+5. Run `/revela review` or call `revela-decks` action `review` yourself. The tool must compute readiness from `DECKS.json`.
 6. Use `revela-decks` action `read` and confirm `writeReadiness.status` is `ready` with no blockers.
 7. Generate HTML that **exactly matches** the fetched examples — copy the HTML structure verbatim.
 
@@ -313,7 +317,7 @@ Once the fetch is complete, generate the complete HTML file in one shot.
 
 - Output **only** the raw HTML — no markdown fences, no explanation before or after
 - Create a `decks/` directory in the current working directory if it doesn't already exist
-- Write the file to `decks/{slug}.html` using the deck slug confirmed in Phase 1.5
+- Write the file to the `decks/*.html` output path confirmed in Phase 1.5
 - The file must be completely self-contained (all CSS and JS inline)
 
 ### Phase 6 — Iterate
@@ -323,11 +327,12 @@ After generating, briefly tell the user:
 - How to navigate (arrow keys / swipe)
 - One line invitation to request changes
 
-Then use `revela-decks` to record written status when available. Preserve
-stable decisions in deck memory when useful.
+Keep `DECKS.json` focused on the current slide specs, research/read state,
+output path, and explicit preferences. The HTML file is the source of truth for
+the produced artifact.
 
 For change requests: re-generate the **entire** file (don't patch). Apply the
-change and silently overwrite the same `decks/{slug}.html` filename.
+change and silently overwrite the confirmed `decks/*.html` output file.
 
 ---
 
@@ -402,7 +407,7 @@ element selector list, and `window.getEditedHTML()` definition.
 
 - When research findings contain image leads that should appear in the final deck,
   first call `revela-research-images-list` to inspect structured candidates from
-  `researches/{slug}/*.md`. When multiple images are needed, prefer
+  `researches/{workspace-key}/*.md`. When multiple images are needed, prefer
   `revela-media-batch-save` to save the selected candidates in one call. Use
   `revela-media-save` for one-off cases. Then reference the returned local file
   path in HTML. Do not use remote image URLs directly in final slides.

package/tools/decks.ts

@@ -2,11 +2,13 @@ import { tool } from "@opencode-ai/plugin"
 import {
   createDeckSpec,
   DECKS_STATE_FILE,
+  normalizeWorkspaceDeckState,
   readOrCreateDecksState,
   reviewDeckState,
   upsertDeck,
   upsertSlides,
   writeDecksState,
+  workspaceDeckSlug,
   type DeckSpec,
   type RequiredInputs,
   type ResearchAxis,
@@ -22,13 +24,12 @@ export default tool({
     action: tool.schema
       .enum(["read", "init", "upsertDeck", "upsertSlides", "review", "remember"])
       .describe("Action to perform on DECKS.json."),
-    slug: tool.schema.string().optional().describe("Deck slug for read/upsert/review actions."),
     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."),
     audience: tool.schema.string().optional().describe("For upsertDeck: deck audience."),
     language: tool.schema.string().optional().describe("For upsertDeck: deck language."),
     slideCount: tool.schema.number().optional().describe("For upsertDeck: expected slide count."),
-    outputPath: tool.schema.string().optional().describe("For upsertDeck: target output path, normally decks/{slug}.html."),
+    outputPath: tool.schema.string().optional().describe("For upsertDeck: target output path, normally decks/{workspace-name}.html."),
     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."),
@@ -84,7 +85,8 @@ export default tool({
   async execute(args, context) {
     try {
       const workspaceRoot = context.directory ?? process.cwd()
-      const state = readOrCreateDecksState(workspaceRoot)
+      let state = normalizeWorkspaceDeckState(readOrCreateDecksState(workspaceRoot), workspaceRoot)
+      const defaultSlug = workspaceDeckSlug(workspaceRoot)
 
       if (args.action === "init") {
         writeDecksState(workspaceRoot, state)
@@ -92,20 +94,20 @@ export default tool({
       }
 
       if (args.action === "read") {
-        const slug = args.slug || state.activeDeck
+        const deckKey = state.activeDeck
         if (args.summary) {
-          const deck = slug ? state.decks[slug] : undefined
+          const deck = deckKey ? state.decks[deckKey] : undefined
           return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, activeDeck: state.activeDeck, deck }, null, 2)
         }
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, state }, null, 2)
       }
 
       if (args.action === "upsertDeck") {
-        if (!args.slug) return JSON.stringify({ ok: false, error: "slug is required for upsertDeck" })
-        const existing = state.decks[args.slug]
+        const deckKey = defaultSlug
+        const existing = state.decks[deckKey]
         const deckInput: Partial<DeckSpec> & { slug: string } = {
           ...existing,
-          slug: args.slug,
+          slug: deckKey,
           goal: args.goal ?? existing?.goal ?? "",
           audience: args.audience ?? existing?.audience,
           language: args.language ?? existing?.language,
@@ -127,15 +129,15 @@ export default tool({
       }
 
       if (args.action === "upsertSlides") {
-        if (!args.slug) return JSON.stringify({ ok: false, error: "slug is required for upsertSlides" })
+        const deckKey = state.activeDeck || defaultSlug
         if (!args.slides) return JSON.stringify({ ok: false, error: "slides are required for upsertSlides" })
-        const next = upsertSlides(state, args.slug, args.slides as SlideSpec[])
+        const next = upsertSlides(state, deckKey, args.slides as SlideSpec[])
         writeDecksState(workspaceRoot, next)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, deck: next.activeDeck ? next.decks[next.activeDeck] : undefined }, null, 2)
       }
 
       if (args.action === "review") {
-        const reviewed = reviewDeckState(state, args.slug)
+        const reviewed = reviewDeckState(state)
         writeDecksState(workspaceRoot, reviewed.state)
         return JSON.stringify({ ok: true, path: DECKS_STATE_FILE, result: reviewed.result }, null, 2)
       }

package/tools/edit.ts

@@ -12,16 +12,12 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
     description:
       "Open Revela's visual comment editor for an existing slide deck. " +
       "Use this when the user asks to edit, revise, annotate, or visually comment on a deck, " +
-      "including when they reference a decks/*.html file with @. " +
-      "Accepts either a deck slug from DECKS.json or a workspace-relative decks/*.html path. " +
+      "including when they reference the current deck. " +
+      "Revela 0.8 opens the only HTML deck in decks/. " +
       "This opens a local browser editor where the user can Ctrl/Cmd-click deck elements, write comments, " +
       "and send precise edit requests back to the current OpenCode session.",
-    args: {
-      target: tool.schema
-        .string()
-        .describe("Deck slug or workspace-relative deck HTML path, e.g. investor-update or decks/investor-update.html."),
-    },
-    async execute({ target }, context: any) {
+    args: {},
+    async execute(_args, context: any) {
       const sessionID = context?.sessionID ?? context?.session?.id ?? ""
       if (!sessionID) {
         return JSON.stringify({
@@ -31,7 +27,7 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
       }
 
       try {
-        const result = openEditableDeck(target, {
+        const result = openEditableDeck("", {
           client: options.client,
           sessionID,
           workspaceRoot: options.workspaceRoot,
@@ -40,7 +36,7 @@ export function createEditTool(options: { client: any; workspaceRoot: string; op
 
         return JSON.stringify({
           ok: true,
-          deck: result.deck.slug,
+          deckKey: result.deck.slug,
           file: result.deck.file,
           source: result.source,
           url: result.url,

package/tools/media-batch-save.ts

@@ -6,7 +6,7 @@ export default tool({
     "Save a selected batch of research-found image leads into workspace assets and update the media manifest. " +
     "Use this after the primary agent has chosen multiple images from researches/{topic}/*.md.",
   args: {
-    topic: tool.schema.string().describe("Topic slug shared by one presentation, e.g. 'ev-market'."),
+    topic: tool.schema.string().describe("Topic key shared by one presentation, e.g. 'ev-market'."),
     items: tool.schema.array(tool.schema.object({
       candidateId: tool.schema.string().describe("Stable candidate id returned by revela-research-images-list."),
       description: tool.schema.string().describe("Candidate description from research findings."),

package/tools/media-save.ts

@@ -7,7 +7,7 @@ export default tool({
     "Supports either a sourceUrl or a sourcePath. Records both success and failure states. " +
     "Use this when a research-found image or an existing local image should become a formal project asset.",
   args: {
-    topic: tool.schema.string().describe("Topic slug shared by one presentation, e.g. 'ev-market'."),
+    topic: tool.schema.string().describe("Topic key shared by one presentation, e.g. 'ev-market'."),
     id: tool.schema.string().describe("Stable asset id within the topic, e.g. 'tesla-logo-01'."),
     type: tool.schema.enum(["image"]).describe("Asset type. Stage 1 only supports 'image'."),
     purpose: tool.schema

package/tools/research-images-list.ts

@@ -6,7 +6,7 @@ export default tool({
     "List structured image leads from researches/{topic}/*.md. " +
     "Parses ## Images sections and returns candidate image records for the primary agent to review.",
   args: {
-    topic: tool.schema.string().describe("Topic slug shared by one presentation, e.g. 'ev-market'."),
+    topic: tool.schema.string().describe("Topic key shared by one presentation, e.g. 'ev-market'."),
     uses: tool.schema
       .array(tool.schema.enum(["logo", "portrait", "screenshot", "unknown"]))
       .optional()

package/tools/research-save.ts

@@ -10,9 +10,9 @@ function today(): string {
 }
 
 /**
- * Sanitize a slug: lowercase, alphanumeric + hyphens only.
+ * Sanitize a key: lowercase, alphanumeric + hyphens only.
  */
-function slugify(s: string): string {
+function keyify(s: string): string {
   return s
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, "-")
@@ -49,8 +49,8 @@ export default tool({
     topic: tool.schema
       .string()
       .describe(
-        "Topic slug in kebab-case, e.g. 'ev-battery-market' or 'saas-competitive-analysis'. " +
-        "All files for the same presentation share the same topic slug.",
+        "Topic key in kebab-case, e.g. 'ev-battery-market' or 'saas-competitive-analysis'. " +
+        "All files for the same presentation share the same topic key.",
       ),
     filename: tool.schema
       .string()
@@ -74,17 +74,17 @@ export default tool({
   },
   async execute(args, context) {
     try {
-      const topicSlug = slugify(args.topic || "research")
-      const fileSlug = slugify(args.filename || "findings")
+      const topicKey = keyify(args.topic || "research")
+      const fileKey = keyify(args.filename || "findings")
       const workspaceDir = context.directory ?? process.cwd()
-      const topicDir = join(workspaceDir, "researches", topicSlug)
+      const topicDir = join(workspaceDir, "researches", topicKey)
 
       mkdirSync(topicDir, { recursive: true })
 
-      const frontmatter = buildFrontmatter(args.topic, fileSlug, args.sources ?? [])
+      const frontmatter = buildFrontmatter(args.topic, fileKey, args.sources ?? [])
       const fileContent = `${frontmatter}\n\n${args.content ?? ""}\n`
-      const filePath = join(topicDir, `${fileSlug}.md`)
-      const relPath = `researches/${topicSlug}/${fileSlug}.md`
+      const filePath = join(topicDir, `${fileKey}.md`)
+      const relPath = `researches/${topicKey}/${fileKey}.md`
 
       writeFileSync(filePath, fileContent, "utf-8")