feat(mofa-slides): list_styles tool + discourage auto_layout + skill-output-aligned paths (#62)

* feat(mofa-slides): add mofa_list_styles tool and discourage auto_layout default

* New mofa_list_styles tool scans find_styles_dir for any skill, returns
  live catalog (name, description, variants, tags). Lets the LLM see
  what's actually installed instead of relying on a hardcoded table
  that drifts every release.
* plugin_slides no longer silently swaps in nb-pro.toml when a style
  file is missing — it bails with the available-style list. The silent
  fallback was masking deployment drift and producing purple output for
  styles like lingnan when the deployed copy was stale.
* SKILL.md rewritten:
  * Mode 2 (manual texts) is now the explicit default for "editable PPT".
  * auto_layout (Mode 3) has a "when NOT to use this" section explaining
    it's slow, expensive, and produces output that usually needs heavy
    human cleanup. Only appropriate when user explicitly asks for VQA
    or for PDF-to-PPTX (Mode 4).
  * Hardcoded 17-style table replaced with a directive to call
    mofa_list_styles (deployed dir actually has 20 styles, validating
    the drift).
* manifest.json: declare mofa_list_styles; rewrite style + auto_layout
  descriptions to match.
* Style accessors variant_names() / default_variant_name() / list_style_names()
  added to back the new tool.
* Bump to 0.5.0 (was out of sync between SKILL.md 0.4.2 and manifest 0.4.5).

* docs(mofa-slides): SKILL.md output paths align with octos skill-output rebind

The Octos host rebinds plugin work_dir to <workspace>/skill-output/,
so an LLM that emits `out: "skill-output/mofa-slides-XX/deck.pptx"`
gets a double-prefix (`<workspace>/skill-output/skill-output/...`)
that the workspace contract validator never finds.

Inside an Octos slides workspace (the normal case), the LLM should
pass workspace-relative `slides/<slug>/output/deck.pptx` — the host
rebind places it at `<workspace>/skill-output/slides/<slug>/output/`,
the workspace contract picks it up via files_to_send, and delivery
is automatic.

Standalone use (mofa CLI outside Octos) keeps a unique-per-request
subdir but drops the skill-output prefix.

* docs(mofa-slides): Mode 4 example uses workspace-relative source_image

The Mode 4 (PDF-to-PPTX) example used `source_image: "skill-output/pdf-pages/..."`
which contradicts the rule added two commits ago ("never prefix
skill-output/ yourself"). Inside an Octos slides workspace the host
does NOT rebind input paths (only `out` / `slide_dir`), so the
example was still functionally valid — but the contradiction would
train the LLM to use skill-output prefixes elsewhere and trip the
double-prefix failure on output args.

Switch the example to a slides-project-relative input path
(slides/<slug>/assets/pdf-pages/...) and explicitly note that
input-path semantics differ from output-path semantics.

Codex review of #62 — MINOR.

Author: ymote

mofa-cli/src/main.rs

@@ -353,6 +353,9 @@ fn run_plugin(tool_name: &str, cancel: &std::sync::atomic::AtomicBool) -> Result
             plugin_infographic(&args, &mofa_root, &cfg).map(|s| (s.into(), serde_json::Value::Null))
         }
         "mofa_video" => plugin_video(&args, &mofa_root, &cfg).map(|s| (s.into(), serde_json::Value::Null)),
+        "mofa_list_styles" => {
+            plugin_list_styles(&args, &mofa_root).map(|(s, v)| (s.into(), v))
+        }
         _ => Err(eyre::eyre!("unknown tool: {tool_name}")),
     };
 
@@ -525,7 +528,10 @@ fn plugin_slides(
     }
 
     // Check workspace styles first (agent-created), then built-in styles.
-    // If neither exists, fall back to nb-pro so generation never fails on style.
+    // If neither exists, bail loudly so the caller can pick a real style —
+    // a silent swap to a different theme hides deployment drift (e.g. an
+    // older skill snapshot missing a style) and produces output that looks
+    // like the LLM picked the wrong color scheme on purpose.
     let style_filename = format!("{style_name}.toml");
     let builtin_dir = find_styles_dir(mofa_root, "slides");
     let cwd_style = std::env::current_dir()
@@ -538,8 +544,17 @@ fn plugin_slides(
     } else if builtin_style.exists() {
         builtin_style
     } else {
-        eprintln!("style '{}' not found, falling back to nb-pro", style_name);
-        builtin_dir.join("nb-pro.toml")
+        let available = style::list_style_names(&builtin_dir);
+        let list = if available.is_empty() {
+            format!("(none found in {})", builtin_dir.display())
+        } else {
+            available.join(", ")
+        };
+        eyre::bail!(
+            "style '{style_name}' not found under {}. Available: {list}. \
+             Call the `mofa_list_styles` tool to inspect variants and descriptions.",
+            builtin_dir.display()
+        );
     };
     let loaded_style = style::load_style(&style_file)?;
 
@@ -902,6 +917,112 @@ fn plugin_video(
     ))
 }
 
+/// Scan the styles dir for a given skill and return the live catalog.
+/// Reads each `*.toml`, extracts `[meta]` + variant names, and returns a JSON object.
+/// The LLM should call this BEFORE picking a style so it never asks for one
+/// that isn't on the deployed copy.
+fn plugin_list_styles(
+    args: &serde_json::Value,
+    mofa_root: &std::path::Path,
+) -> Result<(String, serde_json::Value)> {
+    let skill = args
+        .get("skill")
+        .and_then(|v| v.as_str())
+        .unwrap_or("slides");
+    let styles_dir = find_styles_dir(mofa_root, skill);
+    let names = style::list_style_names(&styles_dir);
+
+    let mut styles_json: Vec<serde_json::Value> = Vec::with_capacity(names.len());
+    for name in &names {
+        let path = styles_dir.join(format!("{name}.toml"));
+        let entry = match style::load_style(&path) {
+            Ok(s) => {
+                let meta = s
+                    .meta
+                    .clone()
+                    .unwrap_or(toml::Value::Table(Default::default()));
+                // Surface common meta fields as first-class JSON keys; everything else
+                // (tags, category, etc.) ends up under `meta`.
+                let display_name = meta
+                    .get("display_name")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or(name)
+                    .to_string();
+                let description = meta
+                    .get("description")
+                    .and_then(|v| v.as_str())
+                    .unwrap_or("")
+                    .to_string();
+                let category = meta
+                    .get("category")
+                    .and_then(|v| v.as_str())
+                    .map(str::to_string);
+                let tags: Vec<String> = meta
+                    .get("tags")
+                    .and_then(|v| v.as_array())
+                    .map(|arr| {
+                        arr.iter()
+                            .filter_map(|v| v.as_str().map(str::to_string))
+                            .collect()
+                    })
+                    .unwrap_or_default();
+                serde_json::json!({
+                    "name": name,
+                    "display_name": display_name,
+                    "description": description,
+                    "category": category,
+                    "tags": tags,
+                    "variants": s.variant_names(),
+                    "default_variant": s.default_variant_name(),
+                })
+            }
+            Err(e) => serde_json::json!({
+                "name": name,
+                "error": format!("{e:#}"),
+            }),
+        };
+        styles_json.push(entry);
+    }
+
+    let summary = serde_json::json!({
+        "skill": skill,
+        "styles_dir": styles_dir.to_string_lossy(),
+        "count": names.len(),
+        "styles": styles_json,
+    });
+
+    let human = if names.is_empty() {
+        format!(
+            "No styles found under {} (skill={skill})",
+            styles_dir.display()
+        )
+    } else {
+        let mut lines = vec![format!(
+            "{} {skill} styles available (from {}):",
+            names.len(),
+            styles_dir.display()
+        )];
+        for s in &summary["styles"].as_array().cloned().unwrap_or_default() {
+            let name = s.get("name").and_then(|v| v.as_str()).unwrap_or("?");
+            let display = s.get("display_name").and_then(|v| v.as_str()).unwrap_or("");
+            let variants = s
+                .get("variants")
+                .and_then(|v| v.as_array())
+                .map(|arr| {
+                    arr.iter()
+                        .filter_map(|v| v.as_str())
+                        .collect::<Vec<_>>()
+                        .join(", ")
+                })
+                .unwrap_or_default();
+            lines.push(format!("  • {name} — {display} [variants: {variants}]"));
+        }
+        lines.join("\n")
+    };
+
+    Ok((human, summary))
+}
+
 fn main() -> Result<()> {
     color_eyre::install()?;
 

mofa-cli/src/openai.rs

@@ -88,8 +88,7 @@ impl OpenAIImageClient {
             {
                 Ok(resp) => {
                     if let Ok(data) = resp.json::<Value>() {
-                        if let Some(b64) =
-                            data.pointer("/data/0/b64_json").and_then(|v| v.as_str())
+                        if let Some(b64) = data.pointer("/data/0/b64_json").and_then(|v| v.as_str())
                         {
                             if let Ok(bytes) = base64::Engine::decode(
                                 &base64::engine::general_purpose::STANDARD,

mofa-cli/src/pipeline/slides.rs

@@ -4,11 +4,11 @@ use crate::config::MofaConfig;
 use crate::dashscope::DashscopeClient;
 use crate::deepseek_ocr::DeepSeekOcrClient;
 use crate::gemini::{BatchImageRequest, GeminiClient};
-use crate::openai::OpenAIImageClient;
 use crate::layout::{
     extract_text_layout, extract_text_layout_deepseek, refine_text_layout, ANTI_LEAK_RULES,
     NO_TEXT_INSTRUCTION, SH, SW,
 };
+use crate::openai::OpenAIImageClient;
 use crate::pptx::{self, ImageOverlay, SlideData, TextOverlay};
 use crate::style::Style;
 use eyre::Result;
@@ -152,7 +152,14 @@ fn generate_image(
     if model.starts_with("gpt-image") {
         if let Some(ref oa) = openai {
             return oa
-                .gen_image(prompt, out_file, image_size, Some("16:9"), Some(model), Some(label))
+                .gen_image(
+                    prompt,
+                    out_file,
+                    image_size,
+                    Some("16:9"),
+                    Some(model),
+                    Some(label),
+                )
                 .ok()
                 .flatten()
                 .inspect(|path| {

mofa-cli/src/style.rs

@@ -23,6 +23,37 @@ impl Style {
             .map(|s| s.as_str())
             .unwrap_or("")
     }
+
+    /// Variant names declared in this style (excludes the synthetic `default` key).
+    pub fn variant_names(&self) -> Vec<String> {
+        let mut names: Vec<String> = self.variants.keys().cloned().collect();
+        names.sort();
+        names
+    }
+
+    /// Name of the default variant (the one used when no `style` is specified).
+    pub fn default_variant_name(&self) -> &str {
+        &self.default_variant
+    }
+}
+
+/// Scan a styles directory and return the list of style names (file stems of `*.toml`)
+/// without parsing the prompt bodies. Returns an empty vec if the dir is missing.
+pub fn list_style_names(dir: &Path) -> Vec<String> {
+    let mut names = Vec::new();
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return names;
+    };
+    for entry in entries.flatten() {
+        let path = entry.path();
+        if path.extension().map(|e| e == "toml").unwrap_or(false) {
+            if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {
+                names.push(stem.to_string());
+            }
+        }
+    }
+    names.sort();
+    names
 }
 
 /// Load a single TOML style file.