markupr 2.6.5 → 2.6.8

package/README.md

@@ -18,7 +18,8 @@
 
 <p align="center">
   <a href="#quick-start">Quick Start</a> &middot;
-  <a href="#why-markupR">Why markupR</a> &middot;
+  <a href="#context-aware-capture-what-your-agent-actually-gets">Context-Aware Capture</a> &middot;
+  <a href="#why-markupr">Why markupR</a> &middot;
   <a href="#mcp-server">MCP Server</a> &middot;
   <a href="#cli">CLI</a> &middot;
   <a href="#integrations">Integrations</a> &middot;
@@ -27,7 +28,11 @@
 
 ---
 
-<!-- hero-screenshot: Replace with an actual screenshot or GIF of markupR in action -->
+<p align="center">
+  <img src="assets/demo-cli.gif" alt="markupR desktop-to-report workflow demo" width="800">
+</p>
+
+Desktop app workflow is the default: record + narrate + stop, then ship context-rich markdown (frames + cursor/window/focus hints when available) directly to your agent.
 
 ## The Problem
 
@@ -35,11 +40,12 @@ AI coding agents can't see your screen. When you find a bug, you context-switch
 
 ## The Solution
 
-markupR records your screen while you narrate what's wrong. When you stop, it runs an intelligent pipeline that correlates your transcript timestamps with the video to extract the right frames at the right moments -- then stitches everything into structured Markdown your AI agent can act on immediately.
+markupR is a desktop capture app first. You hit a hotkey, narrate what you see, and stop. Then it runs a post-session pipeline that aligns transcript timestamps with the recording, extracts the right frames, and outputs structured Markdown your agent can execute against immediately.
 
 - **Record** -- press a hotkey, talk through what you see
 - **Process** -- Whisper transcribes, ffmpeg extracts frames at the exact moments you described
-- **Output** -- structured Markdown with screenshots placed exactly where they belong
+- **Enrich** -- capture context is attached to shot markers (cursor position, active window/app, focused element hints when available)
+- **Output** -- structured Markdown with screenshots and context your agent can trust
 
 ```
 Cmd+Shift+F  -->  talk  -->  Cmd+Shift+F  -->  Cmd+V into your agent
@@ -47,31 +53,49 @@ Cmd+Shift+F  -->  talk  -->  Cmd+Shift+F  -->  Cmd+V into your agent
 
 ## Quick Start
 
-### CLI (zero install)
+### Desktop App (recommended)
+
+Download from [markupr.com](https://markupr.com) or [GitHub Releases](https://github.com/eddiesanjuan/markupr/releases).
+
+> **macOS install note:** Apple notarization is currently rolling out. If macOS warns on first launch, use **Right-click -> Open** once to trust the app. If needed, run: `xattr -dr com.apple.quarantine /Applications/markupR.app`
+
+1. Press `Cmd+Shift+F` (macOS) or `Ctrl+Shift+F` (Windows) to start
+2. Narrate what you see and mark shots when needed
+3. Press the hotkey again to stop
+4. Paste the generated report path into Claude Code, Cursor, Windsurf, or any coding agent
+
+### MCP Server (for AI coding agents)
 
 ```bash
-npx markupr analyze ./recording.mov
+npx -p markupr markupr-mcp
 ```
 
-### MCP Server (for AI coding agents)
+### CLI (for existing recordings / CI / automation)
 
 ```bash
-npx markupr-mcp
+npx markupr analyze ./recording.mov
 ```
 
-### Desktop App
+Use this when you already have a video file. The desktop app remains the primary capture workflow.
 
-Download from [markupr.com](https://markupr.com) or [GitHub Releases](https://github.com/eddiesanjuan/markupr/releases). Available for macOS and Windows.
+## Context-Aware Capture: What Your Agent Actually Gets
 
-No API keys required. Local Whisper transcription works out of the box.
+Every important frame can carry extra machine-usable context, not just pixels.
+
+- **Cursor coordinates** at capture time
+- **Active app + window title** (best-effort from OS context)
+- **Focused element hints** (role/text/title hints when available)
+- **Trigger metadata** (`manual`, `pause`, or `voice-command`)
+
+This makes the report a high-signal liaison between you and your agent: what you said, what you saw, and where your attention was.
 
 ## Why markupR?
 
 **Local-first.** Whisper runs on your device. Your recordings, transcripts, and screenshots never leave your machine. No cloud dependency, no account required.
 
-**AI-native output.** The Markdown output is structured for LLM consumption -- headings, categories, severity levels, and inline screenshots. Not a raw transcript with random images. Every screenshot shows exactly what you were describing when you said it.
+**AI-native output.** The Markdown output is structured for LLM consumption -- headings, categories, severity levels, inline screenshots, and capture-context hints. Not a raw transcript with random images.
 
-**Works everywhere.** Desktop app for daily use. CLI for scripts and CI/CD. MCP server for agent integration. GitHub Action for PR feedback. Same pipeline, four interfaces.
+**Works everywhere.** Desktop app for daily flow. CLI for scripts and CI/CD. MCP server for agent integration. GitHub Action for PR feedback. Same pipeline, four interfaces.
 
 **Open source.** MIT licensed. No telemetry, no tracking, no analytics. Read the source, fork it, ship it.
 
@@ -95,7 +119,7 @@ There's a visible layout shift -- the sidebar jumps left by about
 ![Screenshot at 1:12](screenshots/fb-002.png)
 ```
 
-Each screenshot is extracted from the exact video frame matching your narration timestamp. See full examples in [`examples/`](examples/).
+Each screenshot is extracted from the exact video frame matching your narration timestamp, with context hints attached when available. See full examples in [`examples/`](examples/).
 
 ## MCP Server
 
@@ -110,7 +134,7 @@ Give your AI coding agent eyes and ears. Add markupR as an MCP server and it can
   "mcpServers": {
     "markupR": {
       "command": "npx",
-      "args": ["-y", "markupr-mcp"]
+      "args": ["-y", "-p", "markupr", "markupr-mcp"]
     }
   }
 }
@@ -122,9 +146,9 @@ Give your AI coding agent eyes and ears. Add markupR as an MCP server and it can
 
 | Tool | Description |
 |------|-------------|
-| `capture_screenshot` | Grab the current screen. Your agent sees what you see. |
+| `capture_screenshot` | Grab the current screen and attach context metadata (cursor + active app/window + focus hints when available). |
 | `capture_with_voice` | Record screen + mic for a set duration. Returns a structured report. |
-| `analyze_video` | Process any `.mov` or `.mp4` into Markdown with extracted frames. |
+| `analyze_video` | Process any existing `.mov` or `.mp4` into Markdown with extracted frames (fallback path for externally captured recordings). |
 | `analyze_screenshot` | Run a screenshot through the AI analysis pipeline. |
 | `start_recording` | Begin an interactive recording session. |
 | `stop_recording` | End the session and run the full pipeline. |
@@ -141,7 +165,7 @@ Agent: [calls capture_screenshot]
        [fixes the code]
 ```
 
-No copy-pasting screenshots. No describing the bug in text. The agent looks at your screen and acts.
+No copy-pasting screenshots. No rewriting what you already know. The agent gets structured report context and acts.
 
 Full MCP documentation: [README-MCP.md](README-MCP.md)
 
@@ -159,7 +183,7 @@ npm install -g markupr
 
 ### Commands
 
-**`markupR analyze <video>`** -- Process a screen recording into structured Markdown.
+**`markupR analyze <video>`** -- Process an existing screen recording into structured Markdown.
 
 ```bash
 markupR analyze ./bug-demo.mov
@@ -209,10 +233,10 @@ Run markupR in CI to get visual feedback on pull requests:
     github-token: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-### Desktop App Workflow
+### Desktop App Workflow (Primary)
 
 1. Press `Cmd+Shift+F` (macOS) or `Ctrl+Shift+F` (Windows)
-2. Narrate what you see -- screenshots capture automatically during pauses
+2. Narrate what you see and mark shots as needed
 3. Press the hotkey again to stop
 4. Paste the file path from your clipboard into Claude Code, Cursor, or any AI agent
 
@@ -238,6 +262,8 @@ Run markupR in CI to get visual feedback on pull requests:
 
 The pipeline degrades gracefully. No ffmpeg? Transcript-only output. No Whisper model? Timer-based screenshots. No API keys? Everything runs locally.
 
+Desktop app capture remains the default path. CLI/MCP `analyze_video` remains available when you need to process an existing recording.
+
 For architecture details, see [CLAUDE.md](CLAUDE.md).
 
 ## Development

package/dist/cli/index.mjs

@@ -3623,7 +3623,7 @@ async function runInit(options) {
 }
 
 // src/cli/index.ts
-var VERSION = true ? "2.6.5" : "0.0.0-dev";
+var VERSION = true ? "2.6.8" : "0.0.0-dev";
 var SYMBOLS = {
   check: "\u2714",
   // checkmark

package/dist/main/index.mjs

@@ -7445,6 +7445,7 @@ class AutoUpdaterManager {
   updaterAvailable = false;
   autoCheckEnabled = true;
   isChecking = false;
+  activeCheckUserInitiated = false;
   startupCheckTimer = null;
   periodicCheckTimer = null;
   STARTUP_CHECK_DELAY_MS = 5e3;
@@ -7497,10 +7498,10 @@ class AutoUpdaterManager {
       return;
     }
     this.startupCheckTimer = setTimeout(() => {
-      void this.checkForUpdates();
+      void this.checkForUpdates({ userInitiated: false });
     }, this.STARTUP_CHECK_DELAY_MS);
     this.periodicCheckTimer = setInterval(() => {
-      void this.checkForUpdates();
+      void this.checkForUpdates({ userInitiated: false });
     }, this.PERIODIC_CHECK_INTERVAL_MS);
   }
   clearAutoCheckTimers() {
@@ -7554,14 +7555,14 @@ class AutoUpdaterManager {
       });
     });
     autoUpdater.on("error", (error) => {
-      if (this.shouldSuppressUpdateError(error)) {
+      if (this.shouldSuppressUpdateError(error, this.activeCheckUserInitiated)) {
         log$1.warn("[AutoUpdater] Suppressing expected updater error:", error.message);
-        this.updateState("not-available");
+        this.updateState(this.activeCheckUserInitiated ? "not-available" : "idle");
         return;
       }
       log$1.error("[AutoUpdater] Error:", error);
       this.sendStatus("error", {
-        message: error.message
+        message: this.getUserFacingUpdateErrorMessage(error)
       });
     });
   }
@@ -7570,7 +7571,7 @@ class AutoUpdaterManager {
    */
   setupIPCHandlers() {
     ipcMain.handle(IPC_CHANNELS.UPDATE_CHECK, async () => {
-      return this.checkForUpdates();
+      return this.checkForUpdates({ userInitiated: true });
     });
     ipcMain.handle(IPC_CHANNELS.UPDATE_DOWNLOAD, async () => {
       return this.downloadUpdate();
@@ -7592,7 +7593,8 @@ class AutoUpdaterManager {
   /**
    * Check for available updates
    */
-  async checkForUpdates() {
+  async checkForUpdates(options = {}) {
+    const userInitiated = options.userInitiated ?? true;
     if (!this.updaterAvailable) {
       this.updateState("not-available");
       return null;
@@ -7600,27 +7602,29 @@ class AutoUpdaterManager {
     if (this.isChecking) {
       return null;
     }
-    if (this.state.status === "downloading") {
+    if (this.state.status === "downloading" || !userInitiated && this.state.status === "ready") {
       return null;
     }
     try {
       this.isChecking = true;
+      this.activeCheckUserInitiated = userInitiated;
       log$1.info("[AutoUpdater] Checking for updates");
       const result = await autoUpdater.checkForUpdates();
       return result;
     } catch (error) {
-      if (error instanceof Error && this.shouldSuppressUpdateError(error)) {
+      if (error instanceof Error && this.shouldSuppressUpdateError(error, userInitiated)) {
         log$1.warn("[AutoUpdater] Update check skipped:", error.message);
-        this.updateState("not-available");
+        this.updateState(userInitiated ? "not-available" : "idle");
         return null;
       }
       log$1.error("[AutoUpdater] Check for updates failed:", error);
       this.sendStatus("error", {
-        message: error instanceof Error ? error.message : "Failed to check for updates"
+        message: this.getUserFacingUpdateErrorMessage(error)
       });
       return null;
     } finally {
       this.isChecking = false;
+      this.activeCheckUserInitiated = false;
     }
   }
   /**
@@ -7638,7 +7642,7 @@ class AutoUpdaterManager {
     } catch (error) {
       log$1.error("[AutoUpdater] Download failed:", error);
       this.sendStatus("error", {
-        message: error instanceof Error ? error.message : "Failed to download update"
+        message: this.getUserFacingUpdateErrorMessage(error)
       });
     }
   }
@@ -7700,9 +7704,28 @@ class AutoUpdaterManager {
   /**
    * Suppress known local-install update errors (not actionable for users).
    */
-  shouldSuppressUpdateError(error) {
+  shouldSuppressUpdateError(error, userInitiated) {
     const message = error.message.toLowerCase();
-    return message.includes("app-update.yml") || message.includes("latest.yml") || message.includes("enoent");
+    const isLocalBuildMetadataError = message.includes("app-update.yml") || message.includes("latest.yml") || message.includes("enoent");
+    if (isLocalBuildMetadataError) {
+      return true;
+    }
+    if (!userInitiated && this.isTransientNetworkError(message)) {
+      return true;
+    }
+    return false;
+  }
+  isTransientNetworkError(message) {
+    return message.includes("err_internet_disconnected") || message.includes("err_network_changed") || message.includes("err_name_not_resolved") || message.includes("econnrefused") || message.includes("eai_again") || message.includes("enotfound") || message.includes("timed out") || message.includes("timeout") || message.includes("network request failed") || message.includes("failed to fetch");
+  }
+  getUserFacingUpdateErrorMessage(error) {
+    if (!(error instanceof Error)) {
+      return "Unable to check for updates right now. Please try again.";
+    }
+    if (this.isTransientNetworkError(error.message.toLowerCase())) {
+      return "No internet connection detected. Reconnect and try again.";
+    }
+    return error.message;
   }
   /**
    * Get current update state
@@ -12498,7 +12521,7 @@ function handleMenuAction(action, data) {
       mainWindow?.webContents.send(IPC_CHANNELS.SHOW_SHORTCUTS);
       break;
     case "check-updates":
-      autoUpdaterManager.checkForUpdates();
+      void autoUpdaterManager.checkForUpdates({ userInitiated: true });
       break;
     case "open-session":
       showWindow();

package/dist/mcp/index.mjs

@@ -4524,7 +4524,7 @@ function registerResources(server) {
 }
 
 // src/mcp/server.ts
-var VERSION = true ? "2.6.5" : "0.0.0-dev";
+var VERSION = true ? "2.6.8" : "0.0.0-dev";
 function createServer() {
   const server = new McpServer2({
     name: "markupR",
@@ -4544,7 +4544,7 @@ function createServer() {
 }
 
 // src/mcp/index.ts
-var VERSION2 = true ? "2.6.5" : "0.0.0-dev";
+var VERSION2 = true ? "2.6.8" : "0.0.0-dev";
 log(`markupR MCP server v${VERSION2} starting...`);
 process.on("uncaughtException", (error) => {
   log(`Uncaught exception: ${error instanceof Error ? error.message : String(error)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "markupr",
-  "version": "2.6.5",
+  "version": "2.6.8",
   "description": "Record your screen, narrate feedback, get structured Markdown with screenshots. Desktop app, CLI, and MCP server for AI coding agents like Claude Code, Cursor, and Windsurf.",
   "type": "module",
   "main": "dist/main/index.mjs",
@@ -99,7 +99,7 @@
     "prebuild:win": "npm run generate:installer-images",
     "build:cli": "node scripts/build-cli.mjs",
     "build:mcp": "node scripts/build-mcp.mjs",
-    "prepublishOnly": "npm run build:cli"
+    "prepublishOnly": "npm run build:cli && npm run build:mcp"
   },
   "devDependencies": {
     "@electron/notarize": "^3.1.1",