@conceptcraft/mindframes 0.3.16 → 0.3.17

package/README.md

@@ -1,6 +1,10 @@
 # Mindframes CLI
 
-Command-line tool for creating AI-powered presentations with [Mindframes](https://www.mindframes.app).
+Command-line tool for [Mindframes](https://www.mindframes.app) — presentations, videos, avatars, audio,
+branding, media and research.
+
+Run `mindframes capabilities` at any time for the full, always-current list of callable
+capabilities, and `mindframes <group> --help` to drill into one.
 
 ## Installation
 
@@ -42,37 +46,57 @@ mindframes create "Q4 Report" --context "Revenue: $10M, Growth: 25%, New custome
 # From a file (markdown, text, or JSON)
 mindframes create "Research Summary" --context-file ./research.md
 
-# Pipe content from another command
+# Pipe content from another command (stdin is read automatically when piped)
 cat notes.md | mindframes create "Meeting Notes"
 
-# Scrape content from URLs
-mindframes create "Competitor Analysis" --sources https://example.com/report
+# Upload source documents (PDF, PPTX, DOCX, images)
+mindframes create "Competitor Analysis" --file ./competitor-report.pdf
+
+# Brand and style the deck
+mindframes create "Board Update" --branding-id <brand-id> --template <template-id>
+```
 
-# Combine multiple sources
-cat data.json | mindframes create "Analysis" --sources https://article.com --context "Focus on Q4"
+To use a web page as context, scrape it first and pipe the text in:
+
+```bash
+mindframes scrape https://example.com/report | mindframes create "Competitor Analysis"
 ```
 
 ### Create Options
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `-n, --slides <count>` | Number of slides (1-20) | 10 |
-| `-m, --mode <mode>` | Quality: best, balanced, fast, ultrafast, instant | balanced |
-| `-t, --tone <tone>` | Tone: creative, professional, educational, formal, casual | professional |
-| `--amount <amount>` | Density: minimal, concise, detailed, extensive | concise |
-| `--audience <text>` | Target audience description | General Audience |
-| `-l, --language <lang>` | Output language code | en |
-| `-b, --brand <id\|url>` | Branding ID or URL | - |
-| `-c, --context <text>` | Direct text context | - |
-| `--context-file <path>` | Read context from file | - |
-| `--sources <urls...>` | URLs to scrape for context | - |
-| `--styling <mode>` | freeform, brand-only, brand-plus-style, style-only, no-styling | freeform |
-| `--reference-url <url>` | Style reference image URL | - |
-| `--thinking-depth <depth>` | AI depth: quick, moderate, deep, profound | moderate |
+| `-n, --slides <count>` | Number of slides (1-20) | server default |
+| `-m, --mode <mode>` | Quality: best, balanced, fast, ultrafast, instant, image-min, image, image-max | fast |
+| `--image-tier <tier>` | Embedded-image quality for HTML modes: smart, fast, balanced, best | smart |
+| `-t, --tone <tone>` | Tone: creative, professional, educational, formal, casual | server default |
+| `--amount <amount>` | Density: minimal, concise, detailed, extensive | server default |
+| `--audience <text>` | Target audience description | - |
+| `-g, --goal <type>` | Goal: inform, persuade, train, learn, entertain, report | - |
+| `-l, --language <lang>` | Output language | - |
+| `--branding-id <id>` | Saved brand profile ID (see `mindframes branding list`) | - |
+| `--brand-domain <url>` | Brand the deck by website/domain of a saved brand | - |
+| `--template <id>` | Slide template ID (see `mindframes templates`) | auto |
+| `-c, --context <text>` | Inline text context | - |
+| `--context-file <path>` | Read context from a file | - |
+| `--stdin` | Read context from stdin (also auto-detected when piped) | - |
+| `-f, --file <paths...>` | Upload source files (PDF, PPTX, DOCX, images) | - |
+| `--styling <mode>` | freeform, brand-only, brand-plus-style, style-only, no-styling | server default |
+| `--reference-url <url>` | Image URL used as a visual style reference | - |
+| `--thinking-depth <depth>` | AI depth: quick, moderate, deep, profound | server default |
+| `--theme <preset>` | *instant mode only* — blue, violet, rose, orange, green | - |
+| `--primary-color <hex>` | *instant mode only* — primary color | - |
+| `--decorations <style>` | *instant mode only* — none, waves-bottom-left, waves-top-right, blob-corners, minimal | - |
+| `--team-id <id>` | Team/workspace override | - |
 | `-o, --output <format>` | Output: human, json, quiet | human |
-| `--no-stream` | Disable progress streaming | - |
+| `--no-stream` | Wait for completion without streaming progress | - |
+| `--wait` | Poll until generation completes | - |
+| `--open` | Open the deck in a browser when done | - |
 | `--debug` | Enable debug logging | - |
 
+`--secondary-color`, `--accent-color`, `--background-color`, `--foreground-color`,
+`--id` and `--studio` are also available; run `mindframes create --help` for the full list.
+
 ### Examples
 
 ```bash
@@ -84,9 +108,9 @@ mindframes create "Series A Pitch" -m best -t formal --slides 12 \
 mindframes create "Weekly Update" -m instant -t casual --slides 5 \
   --context "Shipped 3 features, fixed 12 bugs, 2 new hires joining Monday"
 
-# Educational content with research
+# Educational content built from uploaded research
 mindframes create "AI in Healthcare" -t educational --amount detailed \
-  --sources https://research-paper.pdf https://news-article.com
+  --file ./research-paper.pdf
 
 # JSON output for scripting
 URL=$(mindframes create "Demo" --context "..." -o json | jq -r '.viewUrl')
@@ -129,8 +153,17 @@ mindframes import presentation.zip --dry-run  # Validate only
 ### Branding
 
 ```bash
-mindframes branding list           # List brand profiles
-mindframes branding extract <url>  # Extract branding from website
+mindframes branding list                 # List brand profiles
+mindframes branding find "acme"          # Find a saved brand by name or URL
+mindframes branding get <id>             # Brand profile details
+mindframes branding extract <url>        # Extract a brand profile from a website
+mindframes branding status <run-id>      # Check an extraction run
+mindframes branding set-default <id>     # Make a brand the workspace default
+mindframes branding profile [brand-id]   # Read design tokens
+mindframes branding set [brand-id] ...   # Write design tokens (key=value or design.md)
+mindframes branding logo set ...         # Set logo, dark variant, or favicon
+mindframes branding competitor list|add  # Competitors
+mindframes branding social add ...       # Social handles
 ```
 
 ### Configuration
@@ -140,6 +173,8 @@ mindframes config init             # Interactive setup
 mindframes config show             # Show current config
 mindframes config set api-key KEY  # Set API key
 mindframes config set api-url URL  # Set custom API URL
+mindframes config refresh          # Refresh feature flags (unlocks gated commands)
+mindframes config pull             # Pull workspace config
 mindframes config path             # Show config file path
 mindframes config clear            # Clear all config
 ```
@@ -161,45 +196,139 @@ mindframes skill show              # View skill content
 mindframes skill uninstall         # Remove skill from editors
 ```
 
-Supported editors: Claude Code, Cursor, Codex, OpenCode, Windsurf, Agent
+Supported editors: Claude Code, GitHub Copilot, Cursor, Codex, OpenCode, Windsurf, Agent
+
+## Two different video pipelines
+
+The CLI has **two** unrelated video paths. Picking the wrong one is the most
+common mistake:
+
+| You want | Use |
+|----------|-----|
+| Turn a **finished presentation** into an MP4 with narration, avatar, music and captions | `mindframes presentation video` |
+| Build a **video from a brief/storyboard** with stock + generated footage | `mindframes video` |
+
+They share no state: `presentation video` renders slides you already have,
+`video` produces a new film.
+
+## Presentation → MP4 (`presentation video`)
+
+```bash
+# 1) Create (or reuse) a video project for a deck
+mindframes presentation video prepare <presentation-id> --yes
+
+# 2) Inspect the project and its ordered scene timeline
+mindframes presentation video inspect <project-id>
+
+# 3) Optional: persist render settings for the project
+mindframes presentation video settings <project-id> --settings ./settings.json --yes
+
+# 4) Render the MP4
+mindframes presentation video <presentation-id> --render-engine remotion --yes
+mindframes presentation video <presentation-id> --render-engine hyperframes --yes
+
+# 5) Poll the render
+mindframes presentation video status <run-id>
+```
+
+`prepare` accepts `--force-new`, `--team-id`, `--idempotency-key` and requires `--yes`.
+
+The render itself takes either a `<presentation-id>` argument **or**
+`--project-id <id>` (never both), plus `--settings <json-or-path>`,
+`--force-new`, `--force-rerender`, `--render-engine <remotion|hyperframes>`
+(`remotion` = Standard, `hyperframes` = Premium), `--team-id`,
+`--idempotency-key`, and `--yes` to confirm. `--settings` and `--force-new`
+only work with a presentation id, not `--project-id`.
 
-## Video Generation (Remotion)
+### Editing the video draft
 
-The video workflow is intentionally simple. Run commands **inside the project folder** so you can omit `--project`.
+```bash
+mindframes presentation video edit <project-id> --edit ./edit.json     # one atomic draft edit
+mindframes presentation video refresh <project-id>                     # re-pull slides from the deck
+mindframes presentation video versions <project-id>                    # list saved draft versions
+mindframes presentation video restore <project-id> <version-number>    # restore a version
+mindframes presentation video presenter <project-id> <slide-id> --avatar-id <id>
+mindframes video library list <project-id>                              # reusable clips/recordings
+```
 
-### 1) Create a video project
+`presenter` takes exactly one of `--avatar-id`, `--cast-preset-id` or
+`--inherit`; `--render-tier <basic|standard|premium>` is only valid with
+`--avatar-id`, and `--no-apply-preset-voice` keeps the scene's current voice
+when applying a cast preset. Avatar and voice IDs come from `mindframes avatar options`.
+
+### Narration and speaker notes
 
 ```bash
-mindframes video generate new my-video --type youtube
-cd my-video
+# Regenerate one slide's narration inside a video draft
+mindframes presentation video-narration <project-id> --slide-id <id> --instructions "warmer, shorter"
+mindframes presentation video-narration-status <run-id>
+
+# Persisted deck speaker notes
+mindframes presentation speaker-notes <presentation-id> --mode ensure --style concise
+mindframes presentation speaker-notes <presentation-id> --mode regenerate --slide-id <id> --language de
+mindframes presentation speaker-notes-status <run-id>
 ```
 
-### 2) Generate early assets (voiceover, images, videos)
+Both follow the run by default; pass `--no-follow` (or `-f json`) to get the run ID back immediately.
+
+### PowerPoint import and run status
 
 ```bash
-mindframes video generate assets
+mindframes presentation import --file deck.pptx --mode preserve
+mindframes presentation import --file deck.pptx --mode rebrand --branding-id <id>
+mindframes presentation import transform <import-id>
+mindframes presentation import status <run-id>
+mindframes presentation status <run-id>          # deck generation run
 ```
 
-### 3) Generate the video plan
+## Video from a storyboard (`video`)
+
+The hosted pipeline builds a video from a Markdown storyboard revision.
 
 ```bash
-mindframes video generate plan
+# Optional: analyze a reference video and reuse it as a media binding
+mindframes video reference analyze --file ./ref.mp4 --idempotency-key ref-1
+mindframes video reference status <run-id>
+
+# 1) Create a versioned Markdown storyboard
+mindframes video storyboard create --file ./storyboard.md --duration 30 --aspect 16:9 \
+  --idempotency-key sb-1 --title "Launch teaser"
+
+# 2) Revise it (immutable revisions)
+mindframes video storyboard revise <storyboard-id> --base-revision <rev-id> \
+  --file ./storyboard-v2.md --duration 30 --aspect 16:9 --idempotency-key sb-2
+
+# 3) Read it back
+mindframes video storyboard show <storyboard-id> --json
+
+# 4) Render from a pinned revision (this is the terminal step)
+mindframes video create --storyboard-revision <rev-id> --idempotency-key run-1 --yes
+
+# 5) Poll
+mindframes video status <run-id>
 ```
 
-After TTS durations and the final timeline are known, generate music/SFX with
-the factual `--request` commands below.
+`video create` also accepts `--source-video <id>`, `--draft` (480p),
+`--team-id` and `--approval-receipt`. Omit `--approval-receipt` on the first
+call to get the browser confirmation URL back.
 
-### 4) Export the video (poster embedded by default)
+### Poster frames
+
+To attach a poster frame to a finished MP4:
 
 ```bash
-mindframes video export --out out/video.mp4 --thumb out/thumb.png
-mindframes video export --no-embed-poster
+mindframes video thumbnail inject -i out/video.mp4 -t out/thumb.png -o out/final.mp4
 ```
 
-### Supporting commands
+### Supporting video commands
 
 ```bash
-mindframes video find "city timelapse"  # search stock videos
+mindframes video find "city timelapse"                      # stock/web video search
+mindframes video analyze ./clip.mp4                         # local frame + audio analysis
+mindframes video lipsync --source-video-id <uuid> --audio-url <url> -o out.mp4
+mindframes video translate --source-video-id <uuid> --output-dir ./translated
+mindframes video translate-languages                        # supported target languages
+mindframes video library list <project-id>                  # reusable clips
 ```
 
 ### Video-aware music and SFX
@@ -217,13 +346,43 @@ Both JSON files use `schema_version: 1`, `video_description`, `duration_s`, and
 word timings when TTS provides them. Gemini turns those final facts into the
 provider-ready music or SFX prompt on the backend.
 
-### If you prefer using --project
-
-```bash
-mindframes video generate assets --project my-video
-mindframes video generate plan --project my-video
-mindframes video export --project my-video --out out/video.mp4 --thumb out/thumb.png
-```
+## Command groups
+
+`mindframes capabilities` lists every callable capability with its exact command
+path, and `mindframes <group> --help` drills into any group below. Some groups
+appear only after `mindframes login` + `mindframes config refresh` (feature-flag gated —
+`derive` is the clearest example).
+
+| Group | Purpose |
+|-------|---------|
+| `create` | Create a presentation |
+| `list` / `get` / `delete` | List, inspect and delete presentations |
+| `export` / `import` | Export a deck to ZIP; import one back (`import` is admin-only) |
+| `templates` | List slide design templates for `create --template` |
+| `ideas` | Generate presentation topic ideas |
+| `presentation` | Deck → MP4, speaker notes, PowerPoint import, run status |
+| `video` | Storyboard-driven video generation, stock search, lipsync, translation, analysis |
+| `derive` | Derivative content from a deck (blog, tweets, LinkedIn, red-team questions, cheat sheet) — feature-flag gated |
+| `branding` | Brand profiles, design tokens, logos, competitors, social handles |
+| `avatar` | Presenter clips and looks (`avatar options` lists avatars and voices) |
+| `cast` | The faces and voices your videos can use, incl. saved presets |
+| `tts` / `music` / `sfx` / `mix` | Voiceover, video-aware music, sound effects, audio mixing |
+| `image` | Image search and AI image generation |
+| `search` | Web, news, image and stock-video search |
+| `scrape` / `content` / `transcript` | Extract text from a URL, a file, or a YouTube video |
+| `media` | Ingest and transcribe recordings you already own |
+| `document` | Create, read and edit Library documents (with versions/restore) |
+| `library` | Library folders and filing |
+| `knowledge` | Search the workspace Knowledge Hub and read knowledge bundles |
+| `agent` | Scheduled agents; read, edit or erase agent memory |
+| `poll` | Standalone polls |
+| `microsite` | Shareable multi-section web microsite from a brief |
+| `ad-set` | Ad creatives (hooks, copy, visuals) from a campaign brief |
+| `visual-abstract` | One-page visual abstract graphic from a dense brief |
+| `capabilities` | List every callable capability and its parity state |
+| `config` / `login` / `logout` / `whoami` | Auth and configuration |
+| `skill` | Install the agent skill into Claude Code, Cursor, Codex, … |
+| `runner` | Run agent work locally with your own Claude Code / Codex login |
 
 ## Scripting Examples