markupr 2.1.8 → 2.5.0

package/README.md

@@ -1,3 +1,9 @@
+> **This project has moved.** FeedbackFlow has been rebranded and evolved into **[markupr](https://github.com/eddiesanjuan/markupr)** -- with cross-platform support, a CLI, an MCP server for AI coding agents, and an intelligent post-processing pipeline. All future development happens at [github.com/eddiesanjuan/markupr](https://github.com/eddiesanjuan/markupr).
+>
+> **Install:** `npm install -g markupr` | **Download:** [markupr.com](https://markupr.com) | **Releases:** [github.com/eddiesanjuan/markupr/releases](https://github.com/eddiesanjuan/markupr/releases)
+
+---
+
 <p align="center">
   <img src="src/renderer/assets/logo.svg" alt="markupr Logo" width="120" height="120">
 </p>
@@ -13,20 +19,26 @@
   <a href="https://github.com/eddiesanjuan/markupr/actions/workflows/release.yml"><img src="https://github.com/eddiesanjuan/markupr/actions/workflows/release.yml/badge.svg" alt="Release"></a>
   <a href="https://github.com/eddiesanjuan/markupr/releases"><img src="https://img.shields.io/github/v/release/eddiesanjuan/markupr?style=flat-square" alt="Latest Release"></a>
   <a href="https://github.com/eddiesanjuan/markupr/releases"><img src="https://img.shields.io/github/downloads/eddiesanjuan/markupr/total?style=flat-square" alt="Downloads"></a>
+  <a href="https://www.npmjs.com/package/markupr"><img src="https://img.shields.io/npm/v/markupr?style=flat-square" alt="npm version"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License"></a>
   <a href="https://ko-fi.com/eddiesanjuan"><img src="https://img.shields.io/badge/Support-Ko--fi-FF5E5B?style=flat-square&logo=ko-fi" alt="Ko-fi"></a>
 </p>
 
 <p align="center">
-  <a href="#features">Features</a> |
   <a href="#quick-start">Quick Start</a> |
+  <a href="#why-markupr">Why markupr?</a> |
+  <a href="#features">Features</a> |
   <a href="#how-it-works">How It Works</a> |
+  <a href="#example-output">Examples</a> |
   <a href="#installation">Installation</a> |
+  <a href="#cli-usage">CLI Usage</a> |
+  <a href="#mcp-server-for-ai-coding-agents">MCP Server</a> |
   <a href="#usage">Usage</a> |
   <a href="#keyboard-shortcuts">Shortcuts</a> |
   <a href="#export-formats">Export</a> |
   <a href="#development">Development</a> |
-  <a href="#contributing">Contributing</a>
+  <a href="#contributing">Contributing</a> |
+  <a href="CHANGELOG.md">Changelog</a>
 </p>
 
 ---
@@ -35,7 +47,58 @@ markupr is a menu bar app that intelligently captures developer feedback. Press
 
 One hotkey to start. One hotkey to stop. A Markdown file with your words, contextually-placed screenshots, and intelligent structure -- ready to hand to your AI coding agent, paste into a GitHub issue, or drop in a Slack thread.
 
-If markupr saves you hours, consider supporting development on [Ko-fi](https://ko-fi.com/eddiesanjuan) so updates and fixes ship faster.
+## Quick Start
+
+### CLI (for developers and AI agents)
+```bash
+npx markupr analyze ./recording.mov
+```
+
+Or install globally:
+```bash
+npm install -g markupr
+# or
+bun install -g markupr
+```
+
+### Desktop App
+Download from [markupr.com](https://markupr.com) or the [releases page](https://github.com/eddiesanjuan/markupr/releases) -- available for macOS, Windows, and Linux.
+
+**First-time setup:**
+1. Install the application (DMG for macOS, installer for Windows)
+2. Grant required permissions (Microphone, Screen Recording)
+3. Press `Cmd+Shift+F` (macOS) or `Ctrl+Shift+F` (Windows) to start recording
+4. Narrate your feedback while markupr captures screenshots at pause points
+5. Press the hotkey again to stop -- post-processing runs automatically
+6. Paste the file path from your clipboard into your AI coding agent
+
+**No API key required!** markupr uses local Whisper transcription by default.
+
+If markupr saves you hours, consider [supporting development on Ko-fi](https://ko-fi.com/eddiesanjuan).
+
+## See It In Action
+
+<!-- TODO: Replace with actual demo recording -->
+> **Demo video coming soon** -- Record your screen, talk through what you see, get structured Markdown with screenshots your AI coding agent can act on. One hotkey in, one hotkey out.
+
+## Why markupr?
+
+AI coding agents are transforming development, but they're only as good as the context you give them. Typing out bug reports with manual screenshots is slow and lossy -- you lose the flow of what you saw and the nuance of what you meant.
+
+markupr bridges this gap. Record your screen, narrate what you see, and markupr produces a structured Markdown document that AI agents can consume directly. The output isn't a raw transcript with random screenshots -- it's an intelligently structured document where every screenshot is placed at the exact moment you were describing it, every issue is categorized, and the format is optimized for LLM consumption.
+
+**The workflow:**
+1. You see a bug. Press `Cmd+Shift+F`.
+2. Talk through what you see: "This button is hidden on mobile, and the spacing is off here..."
+3. Press the hotkey again to stop.
+4. Paste the file path into Claude Code, Cursor, or any AI agent.
+5. The agent reads your structured feedback -- with screenshots -- and fixes the issues.
+
+**What makes it different:**
+- **Timestamp-correlated frames** -- screenshots are extracted from the exact video frame matching your narration, not taken at arbitrary intervals
+- **Local-first** -- Whisper runs on your machine, your data stays on your machine
+- **AI-native output** -- Markdown structured for LLM consumption, not human-only reading
+- **Zero-friction capture** -- one global hotkey from any app, no context switching
 
 ## Features
 
@@ -77,17 +140,6 @@ If markupr saves you hours, consider supporting development on [Ko-fi](https://k
 - **Dark/light/system theme** support
 - **Onboarding experience** for first-run setup
 
-## Quick Start
-
-1. **Download** the latest release for your platform
-2. **Install** the application (DMG for macOS, installer for Windows)
-3. **Press** `Cmd+Shift+F` (macOS) or `Ctrl+Shift+F` (Windows) to start recording
-4. **Narrate** your feedback while markupr captures screenshots at pause points
-5. **Press** the hotkey again to stop -- the post-processing pipeline runs automatically
-6. **Paste** the file path from your clipboard into your AI coding agent
-
-**No API key required!** markupr uses local Whisper transcription by default. Add your OpenAI API key in Settings for cloud transcription.
-
 ## How It Works
 
 ### The Post-Processing Pipeline
@@ -125,6 +177,14 @@ idle ─→ starting (5s timeout) ─→ recording (30min max) ─→ stopping (
 
 Every state has a maximum duration. A watchdog timer monitors state age and forces recovery if anything gets stuck.
 
+## Example Output
+
+See what markupr produces:
+
+- [Desktop app feedback session](examples/feedback-session-example.md) -- a developer reviewing a dashboard, finding mobile and UX issues
+- [MCP server capture session](examples/mcp-session-example.md) -- an AI coding agent recording a CSS bug via `capture_with_voice`
+- [CLI analysis output](examples/cli-output-example.md) -- `npx markupr analyze` processing a security code review
+
 ## Installation
 
 ### macOS
@@ -198,6 +258,223 @@ Claude analyzes your transcript alongside screenshots to produce an intelligent
 | **Hotkeys** | Toggle Recording | Default: `Cmd/Ctrl+Shift+F` |
 | | Manual Screenshot | Default: `Cmd/Ctrl+Shift+S` |
 
+## CLI Usage
+
+markupr can run as a standalone CLI tool -- no Electron or desktop app required. This is ideal for:
+- CI/CD pipelines processing screen recordings
+- AI coding agents that need to analyze recordings programmatically
+- Developers who prefer the command line
+
+### Installation
+
+```bash
+# Run without installing
+npx markupr analyze ./recording.mov
+
+# Install globally via npm
+npm install -g markupr
+
+# Install globally via bun
+bun install -g markupr
+```
+
+### Commands
+
+#### `markupr analyze <video-file>`
+
+Process a screen recording into a structured Markdown document with extracted frames and transcript.
+
+**Options:**
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--audio <file>` | Separate audio file (if not embedded in video) | Auto-extracted from video |
+| `--output <dir>` | Output directory | `./markupr-output` |
+| `--whisper-model <path>` | Path to local Whisper model file | Auto-detected in `~/.markupr/whisper-models/` |
+| `--no-frames` | Skip frame extraction | `false` |
+| `--template <name>` | Output template (`markdown`, `json`, `github-issue`, `linear`, `jira`, `html`) | `markdown` |
+| `--verbose` | Show detailed progress output | `false` |
+
+**Examples:**
+
+```bash
+# Basic usage - analyze a screen recording
+markupr analyze ./bug-demo.mov
+
+# Use a specific output directory
+markupr analyze ./recording.mov --output ./reports
+
+# Separate audio and video files
+markupr analyze ./screen.mov --audio ./voiceover.wav
+
+# Skip frame extraction (transcript only)
+markupr analyze ./recording.mov --no-frames
+```
+
+#### `markupr watch [directory]`
+
+Watch a directory for new screen recordings and auto-process them as they appear. Ideal for continuous feedback workflows.
+
+```bash
+# Watch the current directory
+markupr watch
+
+# Watch a specific directory with custom output
+markupr watch ./recordings --output ./reports
+
+# Watch with verbose logging
+markupr watch ~/Desktop --verbose
+```
+
+#### `markupr push github <report>`
+
+Create GitHub issues from a markupr feedback report. Each feedback item (FB-001, FB-002, etc.) becomes a separate issue with labels and structured markdown.
+
+```bash
+# Create issues from a report (uses gh CLI auth or GITHUB_TOKEN)
+markupr push github ./markupr-output/report.md --repo myorg/myapp
+
+# Preview what would be created
+markupr push github ./report.md --repo myorg/myapp --dry-run
+
+# Push specific items only
+markupr push github ./report.md --repo myorg/myapp --items FB-001 FB-003
+```
+
+Authentication resolves in order: `--token` flag, `GITHUB_TOKEN` env var, `gh auth token` CLI.
+
+#### `markupr push linear <report>`
+
+Create Linear issues from a markupr feedback report.
+
+```bash
+# Create issues in a Linear team
+markupr push linear ./report.md --team ENG
+
+# Assign to a project with dry run
+markupr push linear ./report.md --team DES --project "Q1 Polish" --dry-run
+```
+
+Set `LINEAR_API_KEY` env var or pass `--token`.
+
+### Output Templates
+
+markupr supports multiple output templates for the `analyze` command:
+
+| Template | Description |
+|----------|-------------|
+| `markdown` | Default structured Markdown (llms.txt-inspired) |
+| `json` | Machine-readable JSON for integrations |
+| `github-issue` | GitHub-flavored Markdown optimized for issues |
+| `linear` | Linear-optimized issue format |
+| `jira` | Jira-compatible markup |
+| `html` | Self-contained HTML document |
+
+```bash
+# Generate JSON output for automation
+markupr analyze ./recording.mov --template json
+
+# Generate GitHub-ready issue format
+markupr analyze ./recording.mov --template github-issue
+```
+
+### GitHub Action
+
+Run markupr in CI to get visual feedback on pull requests. Add the action to your workflow:
+
+```yaml
+- uses: eddiesanjuan/markupr-action@v1
+  with:
+    video-path: ./test-recording.mov
+    output-dir: ./markupr-output
+```
+
+See [markupr-action/README.md](markupr-action/README.md) for full configuration options.
+
+### Requirements
+
+- **Node.js** 18+
+- **ffmpeg** must be installed and on your PATH (for frame extraction and audio processing)
+  - macOS: `brew install ffmpeg`
+  - Ubuntu/Debian: `sudo apt install ffmpeg`
+  - Windows: `choco install ffmpeg` or download from ffmpeg.org
+
+### For AI Agents
+
+markupr is designed to be used by AI coding agents. An agent can:
+
+```bash
+# Install and process a recording in one command
+npx markupr analyze ./recording.mov --output ./feedback
+
+# The output is a structured Markdown file with embedded screenshots
+# Perfect for feeding into Claude, GPT, or any LLM
+cat ./feedback/markupr-report.md
+```
+
+The output Markdown follows the llms.txt convention -- structured, parseable, and optimized for AI consumption.
+
+## MCP Server (for AI Coding Agents)
+
+markupr includes an MCP server that gives AI coding agents direct access to screen capture and voice recording. Your agent can see your screen, hear your narration, and receive structured reports -- all mid-conversation. This is the bridge between "I can see the bug" and "my agent can fix it."
+
+### Setup
+
+Add to your IDE config and your agent gets 6 tools:
+
+**Claude Code** (`~/.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "markupr": {
+      "command": "npx",
+      "args": ["-y", "markupr-mcp"]
+    }
+  }
+}
+```
+
+**Cursor / Windsurf** (MCP settings):
+```json
+{
+  "mcpServers": {
+    "markupr": {
+      "command": "npx",
+      "args": ["-y", "markupr-mcp"]
+    }
+  }
+}
+```
+
+### Available Tools
+
+| Tool | What it does |
+|------|-------------|
+| `capture_screenshot` | Grab the current screen. Your agent sees what you see. |
+| `capture_with_voice` | Record screen + microphone for a set duration. Returns a full structured report. |
+| `analyze_video` | Process any `.mov` or `.mp4` into Markdown with extracted frames. |
+| `analyze_screenshot` | Feed a screenshot through the AI analysis pipeline. |
+| `start_recording` | Begin an interactive recording session. |
+| `stop_recording` | End the session. Full pipeline runs, report returned. |
+
+### Example: Agent Captures and Fixes a Bug
+
+In Claude Code, after adding the MCP config, your agent can do this:
+
+```
+You: "The sidebar is overlapping the main content on mobile. Can you see it?"
+
+Claude: [calls capture_screenshot]
+        "I can see the issue -- the sidebar has position: fixed but no
+         z-index, and it's 280px wide with no responsive breakpoint.
+         Let me fix the CSS..."
+
+        [fixes the code]
+```
+
+No copy-pasting screenshots. No describing the bug in text. The agent looks at your screen and acts.
+
+See **[README-MCP.md](README-MCP.md)** for full setup instructions, all tool parameters, and troubleshooting.
+
 ## Usage
 
 ### Basic Workflow
@@ -358,7 +635,7 @@ markupr/
 │   │   └── hooks/             # React hooks (theme, animation)
 │   ├── preload/               # Electron preload (secure IPC bridge)
 │   └── shared/                # Shared types and constants
-├── tests/                     # Test suite (356 tests)
+├── tests/                     # Test suite
 ├── docs/                      # Documentation
 ├── site/                      # Landing page
 └── package.json