@buildinternet/uploads 0.45.0 → 0.46.1

package/README.md

@@ -204,7 +204,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env mcp`.
 
-For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP with whichever of Claude Code, Codex, and Grok are on PATH (a missing CLI is skipped) + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use
 

package/dist/cli-catalog.js

@@ -212,7 +212,7 @@ export const ROOT_COMMANDS = [
         essential: true,
         subcommands: [
             { name: "skill", summary: "Install the agent skills only" },
-            { name: "mcp", summary: "Register the remote MCP server only" },
+            { name: "mcp", summary: "Register the remote MCP server (skips missing agent CLIs)" },
             { name: "hooks", summary: "Install PR screenshot hooks for Grok/Cursor" },
             { name: "all", summary: "Install skills, MCP, and hooks (default)" },
         ],

package/dist/cli-help.js

@@ -167,9 +167,10 @@ ${section(style, "Examples:")}
   ${style.command("uploads logout")}
   ${style.command("uploads --version")}
 
-${section(style, "Agent/MCP:")} ${style.body("`uploads install` sets up skills, hosted MCP, and hooks for")}
-${style.body("Grok/Cursor. Claude and Codex use their plugins for the same PR-screenshot")}
-${style.body("hook. Run `uploads mcp` for local stdio.")}
+${section(style, "Agent/MCP:")} ${style.body("`uploads install` sets up skills, hosted MCP (Claude/Codex/Grok;")}
+${style.body("skips any CLI that is not on PATH), and hooks for Grok/Cursor. Claude and")}
+${style.body("Codex use their plugins for the same PR-screenshot hook. Run `uploads mcp`")}
+${style.body("for local stdio.")}
 
 ${style.muted("Tip: uploads help          essentials only")}
 ${style.muted("     uploads help --all    this full listing")}

package/dist/commands/install.d.ts

@@ -1,10 +1,21 @@
 import { type GlobalFlags } from "../cli-args.js";
 import { type CommandRunner } from "../github-gh.js";
 export declare const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
+type McpClientId = "claude" | "codex" | "grok";
+interface McpClient {
+    id: McpClientId;
+    label: string;
+    command: (name: string, url: string, bearer: string) => string[];
+}
+/**
+ * Agent CLIs that can register the hosted MCP server. Each is attempted
+ * independently; a missing binary is skipped so the others can still install.
+ */
+export declare const MCP_CLIENTS: readonly McpClient[];
 export interface StepResult {
     command: string[];
     ok: boolean;
-    skipped?: "dry-run" | "sign-in" | "already-configured";
+    skipped?: "dry-run" | "sign-in" | "already-configured" | "missing-cli";
     error?: string;
     output?: string;
 }
@@ -27,3 +38,4 @@ export declare function runInstall(args: string[], opts: {
     /** Override home for hook installs (tests). */
     home?: string;
 }, help?: boolean): Promise<number>;
+export {};

package/dist/commands/install.js

@@ -6,20 +6,62 @@ import { HOOK_COMMAND, HOOK_INVOCATION, installHookManifests, } from "../hooks-i
 export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
 const SKILL_SOURCE = "buildinternet/uploads";
 const SKILL_NAMES = ["uploads-cli", "github-screenshots", "annotate-screenshots"];
+/** `mcp add --transport http` with an Authorization header. */
+function httpMcpAdd(binary, name, url, bearer) {
+    return [
+        binary,
+        "mcp",
+        "add",
+        "--transport",
+        "http",
+        name,
+        url,
+        "--header",
+        `Authorization: Bearer ${bearer}`,
+    ];
+}
+/**
+ * Agent CLIs that can register the hosted MCP server. Each is attempted
+ * independently; a missing binary is skipped so the others can still install.
+ */
+export const MCP_CLIENTS = [
+    {
+        id: "claude",
+        label: "Claude Code",
+        command: (name, url, bearer) => httpMcpAdd("claude", name, url, bearer),
+    },
+    {
+        id: "codex",
+        label: "Codex",
+        // Codex HTTP MCP has no --header; auth is OAuth on first use (same as the
+        // plugin's .mcp.json). Passing --bearer-token-env-var UPLOADS_TOKEN would
+        // break machines that signed in via `uploads login` (token lives in the
+        // config file, not the environment).
+        command: (name, url) => ["codex", "mcp", "add", name, "--url", url],
+    },
+    {
+        id: "grok",
+        label: "Grok",
+        command: (name, url, bearer) => httpMcpAdd("grok", name, url, bearer),
+    },
+];
+const MCP_CLIENT_BINARIES = MCP_CLIENTS.map((c) => c.id).join(", ");
 const INSTALL_HELP = `uploads install — set up agent integrations (skills + remote MCP + hooks)
 
 Installs the github-screenshots, uploads-cli, and annotate-screenshots agent
-skills, registers the
-hosted MCP server with Claude Code, and installs the PR screenshot reminder
-hook for Grok / Cursor when those tools are present. The remote MCP endpoint
-infers your workspace from the bearer token, so only the token is needed.
+skills, registers the hosted MCP server with whichever of Claude Code, Codex,
+and Grok are on PATH, and installs the PR screenshot reminder hook for
+Grok / Cursor when those tools are present. A missing agent CLI is skipped —
+it does not fail the rest of the install. The remote MCP endpoint infers your
+workspace from the bearer token, so only the token is needed.
 
 Claude Code and Codex ship the same reminder via their plugins (same command:
 \`${HOOK_INVOCATION}\`) — install those plugins instead of relying on this step.
 
 Safe to re-run. An MCP server already registered under this name is reported
 as \`already configured\` and left as-is — including the token it was created
-with. To point it at a new token: \`claude mcp remove <name>\` first.
+with. To point it at a new token: \`<cli> mcp remove <name>\` first
+(e.g. \`claude mcp remove uploads\`).
 
 Usage:
   uploads install [skill|mcp|hooks|all]     (default: all)
@@ -28,7 +70,8 @@ What it does:
   skill   Agent skills (via npx skills) — github-screenshots: visuals into
           PRs/issues; uploads-cli: full CLI reference; annotate-screenshots:
           hand-drawn callouts and redaction on screenshots
-  mcp     Hosted MCP server in Claude Code — put, list, attach, galleries
+  mcp     Hosted MCP server in Claude Code, Codex, and Grok — each CLI that
+          is installed is registered; missing ones are skipped
   hooks   PR screenshot reminder for Grok / Cursor (user-global manifests)
 
 What runs under the hood:
@@ -37,7 +80,10 @@ What runs under the hood:
           with npx on PATH — missing tooling fails once with install guidance)
   mcp     claude mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
             --header "Authorization: Bearer <token>"
-          (needs the Claude Code CLI on PATH)
+          codex mcp add uploads --url ${DEFAULT_MCP_URL}
+          grok mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
+            --header "Authorization: Bearer <token>"
+          (each is skipped when that CLI is not on PATH)
   hooks   write/merge ~/.grok/hooks/… and ~/.cursor/hooks.json when present
 
 Options:
@@ -76,9 +122,15 @@ export function missingBinaryHint(binary) {
                 `Install Node 22+ from https://nodejs.org (or your package manager), open a new shell, ` +
                 `confirm \`${binary} --version\` works, then re-run \`uploads install skill\`.`);
         case "claude":
-            return (`claude not found on PATH — MCP install needs the Claude Code CLI. ` +
+            return (`claude not found on PATH — MCP install for Claude Code needs the Claude Code CLI. ` +
                 `Install it from https://docs.anthropic.com/en/docs/claude-code, ensure \`claude\` is on PATH, ` +
-                `then re-run \`uploads install mcp\`. Skills and hooks still work without Claude Code.`);
+                `then re-run \`uploads install mcp\`. Other agent CLIs (and skills/hooks) still work without it.`);
+        case "codex":
+            return (`codex not found on PATH — MCP install for Codex needs the Codex CLI. ` +
+                `Install it, ensure \`codex\` is on PATH, then re-run \`uploads install mcp\`.`);
+        case "grok":
+            return (`grok not found on PATH — MCP install for Grok needs the Grok CLI. ` +
+                `Install it, ensure \`grok\` is on PATH, then re-run \`uploads install mcp\`.`);
         default:
             return `${binary} not found on PATH — install it and ensure it is available in this shell.`;
     }
@@ -131,28 +183,59 @@ function skillCommand(skill) {
     // -g global, -y non-interactive, -a '*' every agent (skips the multi-select TUI)
     return ["npx", "-y", "skills", "add", SKILL_SOURCE, "--skill", skill, "-g", "-y", "-a", "*"];
 }
-/**
- * `claude mcp add` refuses to overwrite an existing entry and exits non-zero
- * ("MCP server uploads already exists in local config"). That is the steady
- * state for anyone re-running `uploads install`, not a failure — recognize it
- * so the run stays green and the footer tells them how to re-add if they want
- * a fresh token in the header.
- */
-function alreadyConfigured(result) {
-    return !result.ok && /already exists/i.test(result.error ?? "");
+/** `mcp add` exits non-zero when the name is already registered; treat that as success. */
+function isAlreadyConfigured(error) {
+    return /already exists|already (configured|registered|present)|duplicate/i.test(error);
 }
-function mcpCommand(name, url, bearer) {
-    return [
-        "claude",
-        "mcp",
-        "add",
-        "--transport",
-        "http",
-        name,
-        url,
-        "--header",
-        `Authorization: Bearer ${bearer}`,
-    ];
+function mcpStepKey(client) {
+    return `mcp:${client.id}`;
+}
+function mcpClientForStep(step) {
+    return MCP_CLIENTS.find((c) => mcpStepKey(c) === step);
+}
+function stepFamily(key) {
+    if (key.startsWith("skill:"))
+        return "skills";
+    if (key.startsWith("mcp:"))
+        return "mcp";
+    return key;
+}
+function partitionSteps(results) {
+    const skills = [];
+    const mcp = [];
+    const other = [];
+    for (const entry of Object.entries(results)) {
+        const key = entry[0];
+        if (key.startsWith("skill:"))
+            skills.push(entry);
+        else if (key.startsWith("mcp:"))
+            mcp.push(entry);
+        else
+            other.push(entry);
+    }
+    return { skills, mcp, other };
+}
+/** Run one client's `mcp add`; missing binaries skip, duplicates are already-configured. */
+function runMcpClientStep(run, command) {
+    try {
+        const output = run(command[0], command.slice(1)).trim();
+        return { command, ok: true, output: output || undefined };
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            return {
+                command,
+                ok: true,
+                skipped: "missing-cli",
+                error: `${command[0]} not found on PATH`,
+            };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        if (isAlreadyConfigured(message)) {
+            return { command, ok: true, skipped: "already-configured", output: message };
+        }
+        return { command, ok: false, error: message };
+    }
 }
 function peekToken(globals) {
     try {
@@ -171,27 +254,35 @@ function peekToken(globals) {
 }
 function printOneHumanStep(step, r, redact, verbose, mcpName) {
     const cmd = redact(r.command.join(" "));
-    if (r.skipped === "dry-run") {
-        process.stdout.write(`${step}: would run — ${cmd}\n`);
-    }
-    else if (r.skipped === "sign-in") {
-        process.stdout.write(`${step}: skipped — ${redact(r.error ?? "needs sign-in")}\n`);
-    }
-    else if (r.skipped === "already-configured") {
-        process.stdout.write(`${step}: already configured — "${mcpName}" is registered in Claude Code (nothing to do)\n` +
-            `  To re-register (e.g. with a new token): claude mcp remove ${mcpName} && uploads install mcp\n`);
+    switch (r.skipped) {
+        case "dry-run":
+            process.stdout.write(`${step}: would run — ${cmd}\n`);
+            return;
+        case "sign-in":
+            process.stdout.write(`${step}: skipped — ${redact(r.error ?? "needs sign-in")}\n`);
+            return;
+        case "missing-cli":
+            process.stdout.write(`${step}: skipped — ${r.error ?? `${r.command[0]} not found on PATH`}\n`);
+            return;
+        case "already-configured": {
+            const client = mcpClientForStep(step);
+            const label = client?.label ?? "the client";
+            const remove = `${client?.id ?? "<cli>"} mcp remove ${mcpName}`;
+            process.stdout.write(`${step}: already configured — "${mcpName}" is registered in ${label} (nothing to do)\n` +
+                `  To re-register (e.g. with a new token): ${remove} && uploads install mcp\n`);
+            return;
+        }
     }
-    else if (r.ok) {
+    if (r.ok) {
         process.stdout.write(`${step}: ok\n`);
         if (verbose && r.output) {
             process.stdout.write(`  ${redact(r.output).split("\n").join("\n  ")}\n`);
         }
+        return;
     }
-    else {
-        process.stderr.write(`${step}: failed — ${redact(r.error ?? "")}\n`);
-        if (verbose)
-            process.stderr.write(`  command: ${cmd}\n`);
-    }
+    process.stderr.write(`${step}: failed — ${redact(r.error ?? "")}\n`);
+    if (verbose)
+        process.stderr.write(`  command: ${cmd}\n`);
 }
 /** Shared error when every skill step failed identically; otherwise undefined. */
 function identicalSkillFailure(skillEntries) {
@@ -203,27 +294,41 @@ function identicalSkillFailure(skillEntries) {
     const allSame = skillEntries.every(([, r]) => !r.ok && !r.skipped && r.error === error);
     return allSame ? error : undefined;
 }
+function printMcpHumanSteps(mcp, redact, verbose, mcpName) {
+    const first = mcp[0];
+    if (!first)
+        return;
+    if (mcp.every(([, r]) => r.skipped === "sign-in")) {
+        printOneHumanStep("mcp", first[1], redact, verbose, mcpName);
+        return;
+    }
+    if (mcp.every(([, r]) => r.skipped === "missing-cli")) {
+        process.stdout.write(`mcp: skipped — no agent CLI on PATH (${MCP_CLIENT_BINARIES}). Skills and hooks still work.\n`);
+        return;
+    }
+    for (const [step, r] of mcp) {
+        printOneHumanStep(step, r, redact, verbose, mcpName);
+    }
+}
 /** Collapse identical skill failures to one `skills:` line (missing npx, old npm, …). */
 function printHumanSteps(results, redact, verbose, mcpName) {
-    const entries = Object.entries(results);
-    const skillEntries = entries.filter(([step]) => step.startsWith("skill:"));
-    const sharedError = identicalSkillFailure(skillEntries);
+    const { skills, mcp, other } = partitionSteps(results);
+    const sharedError = identicalSkillFailure(skills);
     if (sharedError !== undefined) {
         process.stderr.write(`skills: failed — ${redact(sharedError)}\n`);
         if (verbose) {
-            for (const [step, r] of skillEntries) {
+            for (const [step, r] of skills) {
                 process.stderr.write(`  ${step}: ${redact(r.command.join(" "))}\n`);
             }
         }
     }
     else {
-        for (const [step, r] of skillEntries) {
+        for (const [step, r] of skills) {
             printOneHumanStep(step, r, redact, verbose, mcpName);
         }
     }
-    for (const [step, r] of entries) {
-        if (step.startsWith("skill:"))
-            continue;
+    printMcpHumanSteps(mcp, redact, verbose, mcpName);
+    for (const [step, r] of other) {
         printOneHumanStep(step, r, redact, verbose, mcpName);
     }
 }
@@ -288,24 +393,27 @@ export async function runInstall(args, opts, help = false) {
         }
     }
     if (target === "mcp" || target === "all") {
-        if (!dryRun && !token) {
-            results.mcp = {
-                command: mcpCommand(name, url, "<token>"),
-                ok: false,
-                skipped: "sign-in",
-                error: "needs sign-in — run `uploads login`, then `uploads install mcp`",
-            };
-        }
-        else {
-            const command = mcpCommand(name, url, token || "<token>");
-            if (human)
-                process.stdout.write("Installing MCP server…\n");
-            const step = dryRun
-                ? { command, ok: true, skipped: "dry-run" }
-                : runStep(run, command);
-            results.mcp = alreadyConfigured(step)
-                ? { command, ok: true, skipped: "already-configured", output: step.error }
-                : step;
+        const bearer = token || "<token>";
+        const skipSignIn = !dryRun && !token;
+        if (human && !skipSignIn)
+            process.stdout.write("Installing MCP server…\n");
+        for (const client of MCP_CLIENTS) {
+            const command = client.command(name, url, bearer);
+            const key = mcpStepKey(client);
+            if (skipSignIn) {
+                results[key] = {
+                    command,
+                    ok: false,
+                    skipped: "sign-in",
+                    error: "needs sign-in — run `uploads login`, then `uploads install mcp`",
+                };
+            }
+            else if (dryRun) {
+                results[key] = { command, ok: true, skipped: "dry-run" };
+            }
+            else {
+                results[key] = runMcpClientStep(run, command);
+            }
         }
     }
     if (target === "hooks" || target === "all") {
@@ -345,28 +453,25 @@ export async function runInstall(args, opts, help = false) {
         (dryRun || (human && (verbose || hookWrites.some((w) => w.action !== "skipped"))))) {
         printHookResults(hookWrites);
     }
-    const skillResults = Object.entries(results)
-        .filter(([step]) => step.startsWith("skill:"))
-        .map(([, r]) => r);
+    const { skills: skillEntries, mcp: mcpEntries } = partitionSteps(results);
+    const skillResults = skillEntries.map(([, r]) => r);
     const skillsOk = skillResults.length > 0 && skillResults.every((r) => r.ok);
     const skillsFailed = skillResults.some((r) => !r.ok);
+    const mcpResults = mcpEntries.map(([, r]) => r);
+    const mcpFailed = mcpResults.some((r) => !r.ok);
     if (!failed && !dryRun) {
         const stepLabels = [
-            ...new Set(Object.keys(results).map((k) => (k.startsWith("skill:") ? "skills" : k))),
+            ...new Set(Object.entries(results)
+                .filter(([, r]) => r.ok && r.skipped !== "missing-cli" && r.skipped !== "sign-in")
+                .map(([k]) => stepFamily(k))),
         ];
-        printSuccessFooter(stepLabels, signedIn);
+        if (stepLabels.length > 0)
+            printSuccessFooter(stepLabels, signedIn);
     }
-    else if (failed && !dryRun && skillsOk && results.mcp && !results.mcp.ok) {
-        let next;
-        if (results.mcp.skipped === "sign-in") {
-            next = "Sign in with `uploads login`, then re-run `uploads install mcp`.";
-        }
-        else if (results.mcp.error?.includes("not found on PATH")) {
-            next = "Install the Claude Code CLI (or skip MCP), then re-run `uploads install mcp`.";
-        }
-        else {
-            next = "Fix the MCP step above, then re-run `uploads install mcp`.";
-        }
+    else if (failed && !dryRun && skillsOk && mcpFailed) {
+        const next = mcpResults.every((r) => r.skipped === "sign-in")
+            ? "Sign in with `uploads login`, then re-run `uploads install mcp`."
+            : "Fix the MCP step above, then re-run `uploads install mcp`.";
         process.stdout.write(`\nSkills are installed. ${next}\n`);
     }
     else if (failed && !dryRun && skillsFailed) {

package/dist/commands/login.js

@@ -459,7 +459,7 @@ export async function runLogin(args, opts, help = false, deviceIo = defaultDevic
         process.stdout.write(`saved credentials to ${path}\napi: ${savedApiUrl}\nworkspace: ${result.workspace}\ntoken: ${redactToken(result.token)}\n`);
         process[doctor.ok ? "stdout" : "stderr"].write(`doctor: ${checked ? (doctor.ok ? "ok" : `failed — ${doctor.error}`) : "skipped"}\n`);
         if (doctor.ok)
-            process.stdout.write("\nusing a coding agent? run `uploads install` to add the uploads skill + MCP server to Claude Code\n");
+            process.stdout.write("\nusing a coding agent? run `uploads install` to add the uploads skill + MCP server\n");
     }
     return doctor.ok ? 0 : 1;
 }

package/dist/commands/screenshot.js

@@ -82,7 +82,16 @@ Options:
   --no-hide-dev-tools       Don't auto-hide framework dev toolbars (auto-hidden on localhost/private)
   --reduced-motion          Emulate prefers-reduced-motion: reduce so animations settle (best-effort
                             on --via remote — neutralizes animations via injected CSS)
-  --eval <js>               Run JS in the page after settle, before capture (--via local only)
+  --wait-for <js>           Poll this JS expression in the page until truthy before --eval and
+                            capture (--via local only). Bridges framework hydration: load/
+                            networkidle settle before React/Next attach handlers, so a synthetic
+                            click in --eval hits the inert server-rendered DOM. Express the app's
+                            own "interactive" signal, e.g. --wait-for 'window.__hydrated===true' or
+                            --wait-for 'document.querySelector("[data-hydrated]")'. Times out with
+                            the capture timeout if it never becomes truthy.
+  --eval <js>               Run JS in the page after settle, before capture (--via local only).
+                            Note: synthetic events (el.click()) won't reach framework handlers
+                            until the app hydrates — pair with --wait-for on React/Next apps.
   --init-script <file>      Inject a JS file before navigation (--via local only)
   --annotate <file|->       Bake hand-drawn boxes, arrows, labels, and redactions from a JSON
                             annotation spec onto the capture before upload (file path or - for
@@ -216,6 +225,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     // lets captureScreenshot apply its localhost-aware default.
     const hideDevTools = flagBool(parsed.flags, "--no-hide-dev-tools") ? false : undefined;
     const reducedMotion = flagBool(parsed.flags, "--reduced-motion");
+    const waitForExpr = flagString(parsed.flags, "--wait-for");
     const evalJs = flagString(parsed.flags, "--eval");
     const initScriptPath = flagString(parsed.flags, "--init-script");
     let initScript;
@@ -445,6 +455,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         hide,
         hideDevTools,
         reducedMotion,
+        waitForExpr,
         evalJs,
         initScript,
         // Skip folding when an explicit --key was given — --key sets the whole

package/dist/commands/update.js

@@ -11,8 +11,9 @@ const UPDATE_HELP = `uploads update — update the CLI and refresh agent integra
 Upgrades the globally installed npm package, then re-runs \`uploads install\` so
 the agent skills match the new version. Skills drift on their own, so this
 refreshes them even when the CLI is already current. An MCP server already
-registered is left as-is (\`already configured\`) — \`claude mcp add\` never
-overwrites an existing entry.
+registered is left as-is (\`already configured\`) — \`claude mcp add\` (and the
+Codex/Grok equivalents) never overwrite an existing entry. A missing agent CLI
+is skipped so it does not fail the rest of the refresh.
 
 Usage:
   uploads update [options]

package/dist/screenshot-local.d.ts

@@ -62,6 +62,15 @@ export interface LocalCaptureOptions {
     hide?: string[];
     /** Emulate prefers-reduced-motion: reduce so animations settle deterministically. */
     reducedMotion?: boolean;
+    /**
+     * JS expression polled in the page (page.waitForFunction) after settle and
+     * before `evalJs`/capture — the caller's "app is interactive" signal. Lets a
+     * synthetic click in `evalJs` land after a framework (React/Next/…) has
+     * hydrated and attached its handlers, instead of firing on the still-inert
+     * server-rendered DOM. Throws `RENDER_FAILED` if it never becomes truthy
+     * within the capture timeout.
+     */
+    waitForExpr?: string;
     /** JS run via page.evaluate after settle, before capture. */
     evalJs?: string;
     /** JS injected via addInitScript before navigation. */

package/dist/screenshot-local.js

@@ -346,9 +346,28 @@ export async function captureLocal(opts) {
             }
         }
         const waitUntil = typeof opts.waitUntil === "string" ? opts.waitUntil : "load";
-        await page.goto(opts.url, { waitUntil, timeout: opts.timeoutMs ?? 30_000 });
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        await page.goto(opts.url, { waitUntil, timeout: timeoutMs });
         if (typeof opts.waitUntil === "number")
             await page.waitForTimeout(opts.waitUntil);
+        // Hydration-aware gate (issue #715): poll the caller's "app is interactive"
+        // predicate before running any eval or capturing. The load/networkidle
+        // settle strategies fire before a framework hydrates, so a synthetic
+        // click in `evalJs` would hit the inert server-rendered DOM with no
+        // handler attached. Waiting for the caller's own signal (e.g.
+        // `window.__hydrated === true`, or a class/attribute the app sets once
+        // interactive) closes that gap. A timeout means the predicate never
+        // became truthy — surface it clearly rather than capturing the un-ready
+        // page silently.
+        if (opts.waitForExpr) {
+            try {
+                await page.waitForFunction(opts.waitForExpr, undefined, { timeout: timeoutMs });
+            }
+            catch (err) {
+                throw new UploadsError(`--wait-for expression never became truthy within ${timeoutMs}ms: ${opts.waitForExpr}` +
+                    ` (${err instanceof Error ? err.message : String(err)})`, "RENDER_FAILED");
+            }
+        }
         // Hide overlays first, then run any user eval (which may depend on, or
         // deliberately override, the hidden state).
         if (opts.hide && opts.hide.length > 0) {

package/dist/screenshot.d.ts

@@ -99,6 +99,13 @@ export interface CaptureScreenshotOptions {
     hideDevTools?: boolean;
     /** Emulate prefers-reduced-motion: reduce so CSS/JS animations settle. */
     reducedMotion?: boolean;
+    /**
+     * JS expression polled in the page until truthy after settle, before
+     * `evalJs` and capture — the caller's "app is interactive" signal so a
+     * synthetic click in `evalJs` lands after framework hydration (issue #715).
+     * Local backend only — throws if the resolved backend is remote.
+     */
+    waitForExpr?: string;
     /** Run this JS in the page after settle, before capture (local backend only). */
     evalJs?: string;
     /** Inject this JS as an init script before navigation (local backend only). */
@@ -127,6 +134,7 @@ export interface CaptureScreenshotOptions {
         waitUntil: WaitUntil;
         hide?: string[];
         reducedMotion?: boolean;
+        waitForExpr?: string;
         evalJs?: string;
         initScript?: string;
         measureSelectors?: string[];

package/dist/screenshot.js

@@ -290,6 +290,12 @@ export async function captureScreenshot(opts) {
     if (backend === "remote" && (opts.evalJs !== undefined || opts.initScript !== undefined)) {
         throw new UploadsError("--eval and --init-script are local-only — use --via local", "USAGE");
     }
+    // --wait-for polls a JS predicate via the live local page (page.waitForFunction);
+    // the remote renderer has no eval escape hatch to evaluate it. Fail fast
+    // rather than silently ignore the caller's readiness signal.
+    if (backend === "remote" && opts.waitForExpr !== undefined) {
+        throw new UploadsError("--wait-for is local-only — use --via local", "USAGE");
+    }
     // Selector-based annotation measurement needs a live local page — the
     // remote render endpoint has no eval escape hatch to run
     // getBoundingClientRect. Covers both explicit --via remote and auto
@@ -315,6 +321,7 @@ export async function captureScreenshot(opts) {
             waitUntil,
             hide,
             reducedMotion: opts.reducedMotion,
+            waitForExpr: opts.waitForExpr,
             evalJs: opts.evalJs,
             initScript: opts.initScript,
             measureSelectors: opts.measureSelectors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.45.0",
+  "version": "0.46.1",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,