@buildinternet/uploads 0.27.0 → 0.29.0

package/README.md

@@ -175,7 +175,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 (short progress; `--verbose` for underlying output). 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 + 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-brand.js

@@ -156,7 +156,10 @@ function boxLines(lines, options = {}) {
     ].join("\n");
 }
 export function formatUpdateBanner(options) {
-    return boxLines([`Update available  ${options.current} → ${options.latest}`, `npm i -g @buildinternet/uploads`], { color: options.color, tone: BRAND.accent });
+    return boxLines([`Update available  ${options.current} → ${options.latest}`, `uploads update`], {
+        color: options.color,
+        tone: BRAND.accent,
+    });
 }
 export function formatAuthBanner(options = {}) {
     return boxLines(["Sign in via browser", "uploads login"], {

package/dist/cli-catalog.js

@@ -180,14 +180,30 @@ export const ROOT_COMMANDS = [
     { name: "setup", summary: "Inspect/configure advanced CLI settings" },
     {
         name: "install",
-        summary: "Install the agent skills + register the remote MCP server",
+        summary: "Install agent skills, remote MCP, and harness hooks",
         essential: true,
         subcommands: [
             { name: "skill", summary: "Install the agent skills only" },
             { name: "mcp", summary: "Register the remote MCP server only" },
-            { name: "all", summary: "Install skills and MCP (default)" },
+            { name: "hooks", summary: "Install PR screenshot hooks for Grok/Cursor" },
+            { name: "all", summary: "Install skills, MCP, and hooks (default)" },
         ],
     },
+    {
+        name: "hook",
+        summary: "Agent harness hook handlers (stdin → advisory JSON)",
+        subcommands: [
+            {
+                name: "pre-pr-screenshot",
+                summary: "Remind to stage screenshots before gh pr create",
+            },
+        ],
+    },
+    {
+        name: "update",
+        summary: "Update the CLI, then refresh the agent skills + MCP registration",
+        essential: true,
+    },
     {
         name: "login",
         summary: "Sign in via browser (or an enrollment code) and save credentials",

package/dist/cli-help.js

@@ -6,24 +6,44 @@ const CMD_WIDTH = 22;
 function toRow(c) {
     return [c.usage ?? c.name, c.summary];
 }
-/** Preferred order for the short essentials help (subset of ROOT_COMMANDS). */
+/**
+ * Display order for the short essentials help. Membership is *not* declared
+ * here — it comes from `essential: true` in cli-catalog.ts, the one source of
+ * truth (issue #491: this array used to decide membership too, and had already
+ * drifted, silently keeping `screenshot` out of short help). This list only
+ * says what order the essential commands appear in; the check below fails the
+ * build-time module load if the two ever disagree in either direction.
+ */
 const ESSENTIAL_ORDER = [
     "put",
     "attach",
+    "screenshot",
     "login",
     "whoami",
     "list",
     "delete",
     "doctor",
     "install",
+    "update",
 ];
 /** Day-to-day commands shown on bare `uploads` / `uploads help`. */
-const ESSENTIALS = ESSENTIAL_ORDER.map((name) => {
-    const cmd = ROOT_COMMANDS.find((c) => c.name === name);
-    if (!cmd)
-        throw new Error(`cli-catalog missing essential command: ${name}`);
-    return toRow(cmd);
-});
+const ESSENTIALS = (() => {
+    const essential = ROOT_COMMANDS.filter((c) => c.essential);
+    const rank = new Map(ESSENTIAL_ORDER.map((name, i) => [name, i]));
+    const unordered = essential.filter((c) => !rank.has(c.name));
+    if (unordered.length > 0) {
+        throw new Error(`cli-help ESSENTIAL_ORDER missing essential command(s): ${unordered.map((c) => c.name).join(", ")}`);
+    }
+    const names = new Set(essential.map((c) => c.name));
+    const stale = ESSENTIAL_ORDER.filter((name) => !names.has(name));
+    if (stale.length > 0) {
+        throw new Error(`cli-help ESSENTIAL_ORDER names non-essential command(s): ${stale.join(", ")}`);
+    }
+    return essential
+        .slice()
+        .sort((a, b) => rank.get(a.name) - rank.get(b.name))
+        .map(toRow);
+})();
 /** Full catalog (same surface as before, still discoverable via help --all). */
 const ALL_COMMANDS = ROOT_COMMANDS.map(toRow);
 function rows(style, items) {
@@ -147,10 +167,9 @@ ${section(style, "Examples:")}
   ${style.command("uploads logout")}
   ${style.command("uploads --version")}
 
-${section(style, "Agent/MCP:")} ${style.body("`uploads install` sets up the agent skills and the hosted MCP server")}
-${style.body("(https://agents.uploads.sh/mcp, workspace inferred from the token). Run")}
-${style.body("`uploads mcp` for local stdio, or use createUploadsWorkerFileTools()")}
-${style.body("from @buildinternet/uploads/agent on the Worker.")}
+${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.")}
 
 ${style.muted("Tip: uploads help          essentials only")}
 ${style.muted("     uploads help --all    this full listing")}

package/dist/cli.js

@@ -12,6 +12,8 @@ import { runInvite } from "./commands/invite.js";
 import { runAdmin } from "./commands/admin-enrollment.js";
 import { runMcp } from "./commands/mcp.js";
 import { runInstall } from "./commands/install.js";
+import { runHook } from "./commands/hook.js";
+import { runUpdate } from "./commands/update.js";
 import { runCompletion } from "./commands/completion.js";
 import { runLogout, runWhoami } from "./commands/session.js";
 import { runTelemetry } from "./commands/telemetry.js";
@@ -268,6 +270,13 @@ export async function runCli(argv) {
             case "install":
                 code = await runInstall(cmdArgs, { globals: parsed.globals, json }, showHelp);
                 break;
+            case "hook":
+                // Fail-open harness hooks — no token required, no telemetry noise.
+                code = await runHook(cmdArgs, showHelp);
+                break;
+            case "update":
+                code = await runUpdate(cmdArgs, { globals: parsed.globals }, showHelp);
+                break;
             case "completion":
             case "completions":
                 code = await runCompletion(cmdArgs, showHelp);

package/dist/client.d.ts

@@ -519,10 +519,18 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         id: string;
     }>;
     findGalleriesByReference(opts: FindGalleriesByReferenceOptions): Promise<GalleryListResult>;
+    /**
+     * Upsert the managed attachments comment. `resync: true` marks an
+     * explicit "make the comment state correct" call (`uploads comment`), so
+     * the server hunts for the marker — and collapses any duplicate — instead
+     * of patching its cached comment id (issue #480). Older servers ignore
+     * the field.
+     */
     upsertGithubComment(opts: {
         repo: string;
         num: number;
         kind: "pull" | "issues";
+        resync?: boolean;
     }): Promise<GithubCommentResult>;
     /**
      * Promote a workspace's branch-staged attachments into a PR's stable

package/dist/client.js

@@ -479,6 +479,13 @@ export function createUploadsClient(config) {
                 params.set("cursor", opts.cursor);
             return request("GET", galleriesBase(config) + "/by-reference?" + params);
         },
+        /**
+         * Upsert the managed attachments comment. `resync: true` marks an
+         * explicit "make the comment state correct" call (`uploads comment`), so
+         * the server hunts for the marker — and collapses any duplicate — instead
+         * of patching its cached comment id (issue #480). Older servers ignore
+         * the field.
+         */
         async upsertGithubComment(opts) {
             return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/comment`, {
                 body: new TextEncoder().encode(JSON.stringify(opts)),

package/dist/commands/hook.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `uploads hook pre-pr-screenshot` — agent PreToolUse / beforeShellExecution
+ * handler. When the shell command is `gh pr create`, the branch touches UI
+ * files, and nothing is staged on uploads.sh, emit a non-blocking advisory.
+ *
+ * Always fail-open. Disable with UPLOADS_HOOK_DISABLE=1.
+ */
+export type HookDeps = {
+    stdin: string;
+    testFiles?: string;
+    cwd?: string;
+    countStaged?: (branch: string) => Promise<number | null>;
+    isFork?: () => boolean | null;
+    git?: {
+        isRepo: () => boolean;
+        branch: () => string | null;
+        changedFiles: () => string[];
+    };
+};
+/** Claude/Codex: tool_input.command · Grok: toolInput.command · Cursor: command */
+export declare function shellCommandFromHookInput(raw: unknown): string;
+export declare function isCursorHookInput(raw: unknown): boolean;
+export declare function looksLikeGhPrCreate(command: string): boolean;
+export declare function isVisualPath(filePath: string): boolean;
+export declare function anyVisual(files: string[]): boolean;
+export declare function formatAdvisory(message: string, cursor: boolean): string;
+/** Returns advisory JSON, or null when silent. Never throws for product paths. */
+export declare function runPrePrScreenshot(deps: HookDeps): Promise<string | null>;
+export declare function runHook(args: string[], help?: boolean): Promise<number>;

package/dist/commands/hook.js

@@ -0,0 +1,204 @@
+/**
+ * `uploads hook pre-pr-screenshot` — agent PreToolUse / beforeShellExecution
+ * handler. When the shell command is `gh pr create`, the branch touches UI
+ * files, and nothing is staged on uploads.sh, emit a non-blocking advisory.
+ *
+ * Always fail-open. Disable with UPLOADS_HOOK_DISABLE=1.
+ */
+import { execFileSync } from "node:child_process";
+import { createUploadsClient } from "../client.js";
+import { resolveConfig } from "../config.js";
+import { writeCommandHelp } from "../cli-style.js";
+const HOOK_CMD = "pre-pr-screenshot";
+const VISUAL_EXT = /\.(astro|tsx|jsx|vue|svelte|html|css|scss|less)$/i;
+const EMAIL_PATH = /(?:^|\/)email\//i;
+const FIND_TIMEOUT_MS = 5_000;
+const HOOK_HELP = `uploads hook <name> — agent harness hook handlers (stdin JSON → stdout JSON)
+
+Usage:
+  uploads hook pre-pr-screenshot
+
+Invoked by Claude Code / Codex / Grok / Cursor hooks. Never blocks.
+
+  pre-pr-screenshot
+    If the shell command is \`gh pr create\`, the branch touches UI files, and
+    no screenshots are staged for the branch, emit an advisory to stage with
+    \`uploads attach … --branch\`.
+
+Disable with UPLOADS_HOOK_DISABLE=1.
+`;
+/** Claude/Codex: tool_input.command · Grok: toolInput.command · Cursor: command */
+export function shellCommandFromHookInput(raw) {
+    if (!raw || typeof raw !== "object")
+        return "";
+    const o = raw;
+    const toolInput = (o.tool_input ?? o.toolInput);
+    if (toolInput && typeof toolInput.command === "string")
+        return toolInput.command;
+    if (typeof o.command === "string")
+        return o.command;
+    return "";
+}
+export function isCursorHookInput(raw) {
+    if (!raw || typeof raw !== "object")
+        return false;
+    const o = raw;
+    return "conversation_id" in o || "workspace_roots" in o || "cursor_version" in o;
+}
+export function looksLikeGhPrCreate(command) {
+    return command.includes("gh pr create");
+}
+export function isVisualPath(filePath) {
+    return VISUAL_EXT.test(filePath) || EMAIL_PATH.test(filePath);
+}
+export function anyVisual(files) {
+    return files.some(isVisualPath);
+}
+export function formatAdvisory(message, cursor) {
+    if (cursor) {
+        return JSON.stringify({ additional_context: message, agentMessage: message });
+    }
+    return JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            additionalContext: message,
+        },
+        systemMessage: message,
+    });
+}
+function runGit(args, cwd, timeoutMs = 5_000) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            timeout: timeoutMs,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function defaultGit(cwd) {
+    return {
+        isRepo: () => runGit(["rev-parse", "--is-inside-work-tree"], cwd) === "true",
+        branch: () => {
+            const b = runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
+            return !b || b === "HEAD" ? null : b;
+        },
+        changedFiles: () => {
+            const defaultBranch = runGit(["remote", "show", "origin"], cwd, 8_000)
+                .split("\n")
+                .map((l) => l.match(/HEAD branch:\s*(.+)/)?.[1]?.trim())
+                .find(Boolean) || "main";
+            const mergeBase = runGit(["merge-base", `origin/${defaultBranch}`, "HEAD"], cwd) ||
+                runGit(["merge-base", defaultBranch, "HEAD"], cwd);
+            const diff = mergeBase
+                ? runGit(["diff", "--name-only", mergeBase, "HEAD"], cwd)
+                : runGit(["diff", "--name-only", "HEAD"], cwd);
+            return diff ? diff.split("\n").filter(Boolean) : [];
+        },
+    };
+}
+async function defaultCountStaged(branch) {
+    try {
+        const config = resolveConfig({ requireToken: false });
+        if (!config.token)
+            return null;
+        const client = createUploadsClient(config);
+        const result = await Promise.race([
+            client.findFiles({ "gh.branch": branch.toLowerCase() }, { limit: 1 }),
+            new Promise((_, reject) => {
+                setTimeout(() => reject(new Error("find timeout")), FIND_TIMEOUT_MS);
+            }),
+        ]);
+        return Array.isArray(result.items) ? result.items.length : 0;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultIsFork(cwd) {
+    try {
+        const out = execFileSync("gh", ["repo", "view", "--json", "isFork", "-q", ".isFork"], {
+            cwd,
+            encoding: "utf8",
+            timeout: 3_000,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (out === "true")
+            return true;
+        if (out === "false")
+            return false;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns advisory JSON, or null when silent. Never throws for product paths. */
+export async function runPrePrScreenshot(deps) {
+    if (process.env.UPLOADS_HOOK_DISABLE === "1")
+        return null;
+    let raw;
+    try {
+        raw = deps.stdin.trim() ? JSON.parse(deps.stdin) : null;
+    }
+    catch {
+        return null;
+    }
+    const command = shellCommandFromHookInput(raw);
+    if (!command || !looksLikeGhPrCreate(command))
+        return null;
+    const cwd = deps.cwd ?? process.cwd();
+    const git = deps.git ?? defaultGit(cwd);
+    if (!git.isRepo())
+        return null;
+    const branch = git.branch();
+    if (!branch)
+        return null;
+    const testFiles = deps.testFiles ?? process.env.UPLOADS_HOOK_TEST_FILES;
+    const changed = testFiles ? testFiles.split("\n").filter(Boolean) : git.changedFiles();
+    if (!anyVisual(changed))
+        return null;
+    const staged = await (deps.countStaged ?? defaultCountStaged)(branch);
+    // null = error/unconfigured → fail open; >0 = already staged
+    if (staged === null || staged > 0)
+        return null;
+    const fork = (deps.isFork ?? (() => defaultIsFork(cwd)))();
+    const forkNote = fork === true
+        ? " Note: this looks like a fork branch, so staged screenshots won't auto-promote into the PR comment yet (see issue #317) — attach them manually if you use uploads."
+        : "";
+    const message = `This PR touches UI files (astro/tsx/jsx/vue/svelte/html/css/scss/less or an /email/ path) but no screenshots are staged for branch '${branch}' on uploads.sh. ` +
+        `Consider running \`uploads attach <shot.png> --branch --state after\` (and a --state before if useful) before or after opening the PR — the managed attachments comment assembles from staged files automatically.${forkNote}`;
+    return formatAdvisory(message, isCursorHookInput(raw));
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+export async function runHook(args, help = false) {
+    const name = args[0];
+    if (help || !name || name === "--help" || name === "-h") {
+        writeCommandHelp(HOOK_HELP);
+        return 0;
+    }
+    if (name !== HOOK_CMD) {
+        process.stderr.write(`unknown hook: ${name} (expected ${HOOK_CMD})\n`);
+        return 2;
+    }
+    try {
+        const out = await runPrePrScreenshot({ stdin: await readStdin() });
+        if (out)
+            process.stdout.write(out);
+    }
+    catch {
+        // fail-open
+    }
+    return 0;
+}

package/dist/commands/install.d.ts

@@ -1,8 +1,18 @@
 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";
+export interface StepResult {
+    command: string[];
+    ok: boolean;
+    skipped?: "dry-run" | "sign-in";
+    error?: string;
+    output?: string;
+}
+export declare function runStep(run: CommandRunner, command: string[]): StepResult;
 export declare function runInstall(args: string[], opts: {
     globals: GlobalFlags;
     json?: boolean;
     runner?: CommandRunner;
+    /** Override home for hook installs (tests). */
+    home?: string;
 }, help?: boolean): Promise<number>;

package/dist/commands/install.js

@@ -2,28 +2,35 @@ import { flagBool, flagString, parseCommandArgs, UsageError, } from "../cli-args
 import { resolveConfig } from "../config.js";
 import { execRunner } from "../github-gh.js";
 import { writeCommandHelp } from "../cli-style.js";
+import { HOOK_COMMAND, installHookManifests } from "../hooks-install.js";
 export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
 const SKILL_SOURCE = "buildinternet/uploads";
 const SKILL_NAMES = ["uploads-cli", "github-screenshots"];
-const INSTALL_HELP = `uploads install — set up agent integrations (skills + remote MCP)
+const INSTALL_HELP = `uploads install — set up agent integrations (skills + remote MCP + hooks)
 
-Installs the github-screenshots and uploads-cli agent skills and registers
-the hosted MCP server with Claude Code. The remote MCP endpoint infers your
-workspace from the bearer token, so only the token is needed.
+Installs the github-screenshots and uploads-cli 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.
+
+Claude Code and Codex ship the same reminder via their plugins (same command:
+\`${HOOK_COMMAND}\`) — install those plugins instead of relying on this step.
 
 Usage:
-  uploads install [skill|mcp|all]     (default: all)
+  uploads install [skill|mcp|hooks|all]     (default: all)
 
 What it does:
   skill   Agent skills (via npx skills) — github-screenshots: visuals into
           PRs/issues; uploads-cli: full CLI reference
   mcp     Hosted MCP server in Claude Code — put, list, attach, galleries
+  hooks   PR screenshot reminder for Grok / Cursor (user-global manifests)
 
 What runs under the hood:
   skill   npx -y skills add ${SKILL_SOURCE} --skill <name> -g -y -a '*'
           (once per skill: ${SKILL_NAMES.join(", ")})
   mcp     claude mcp add --transport http uploads ${DEFAULT_MCP_URL} \\
             --header "Authorization: Bearer <token>"
+  hooks   write/merge ~/.grok/hooks/… and ~/.cursor/hooks.json when present
 
 Options:
   --url <endpoint>    Remote MCP endpoint (default: ${DEFAULT_MCP_URL})
@@ -35,6 +42,7 @@ Examples:
   uploads install
   uploads install skill
   uploads install mcp
+  uploads install hooks
   uploads install --dry-run
 `;
 /** Mask Bearer credentials and the configured token in any printed text. */
@@ -46,7 +54,7 @@ function redactor(token) {
         return out;
     };
 }
-function runStep(run, command) {
+export function runStep(run, command) {
     try {
         const output = run(command[0], command.slice(1)).trim();
         return { command, ok: true, output: output || undefined };
@@ -123,6 +131,18 @@ function printSuccessFooter(steps, signedIn) {
         process.stdout.write("\nNot signed in yet? Run `uploads login` once so put/attach/MCP can authenticate.\n");
     }
 }
+function printHookResults(writes) {
+    if (writes.length === 0) {
+        process.stdout.write("hooks: nothing to do (no ~/.grok or ~/.cursor; Claude/Codex use their plugins)\n");
+        return;
+    }
+    for (const w of writes) {
+        if (w.error)
+            process.stderr.write(`hooks:${w.path}: skipped — ${w.error}\n`);
+        else
+            process.stdout.write(`hooks:${w.path}: ${w.action}\n`);
+    }
+}
 export async function runInstall(args, opts, help = false) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
@@ -130,8 +150,8 @@ export async function runInstall(args, opts, help = false) {
         return 0;
     }
     const target = parsed.positionals[0] ?? "all";
-    if (!["skill", "mcp", "all"].includes(target)) {
-        throw new UsageError(`unknown install target: ${target} (expected skill, mcp, or all)`);
+    if (!["skill", "mcp", "hooks", "all"].includes(target)) {
+        throw new UsageError(`unknown install target: ${target} (expected skill, mcp, hooks, or all)`);
     }
     const url = flagString(parsed.flags, "--url") ?? DEFAULT_MCP_URL;
     const name = flagString(parsed.flags, "--name") ?? "uploads";
@@ -143,6 +163,7 @@ export async function runInstall(args, opts, help = false) {
     const signedIn = Boolean(token);
     const redact = redactor(token);
     const results = {};
+    let hookWrites = [];
     if (target === "skill" || target === "all") {
         if (human)
             process.stdout.write("Installing skills…\n");
@@ -169,6 +190,22 @@ export async function runInstall(args, opts, help = false) {
             results.mcp = dryRun ? { command, ok: true, skipped: "dry-run" } : runStep(run, command);
         }
     }
+    if (target === "hooks" || target === "all") {
+        if (human)
+            process.stdout.write("Installing agent hooks…\n");
+        hookWrites = installHookManifests({ home: opts.home, dryRun });
+        // Surface as a synthetic step so --json / failure accounting stay simple.
+        const hookErrors = hookWrites.filter((w) => w.error);
+        results.hooks = {
+            command: [HOOK_COMMAND],
+            ok: hookErrors.length === 0,
+            skipped: dryRun ? "dry-run" : undefined,
+            output: hookWrites
+                .map((w) => `${w.path}: ${w.action}${w.error ? ` (${w.error})` : ""}`)
+                .join("\n"),
+            error: hookErrors.length > 0 ? hookErrors.map((w) => w.error).join("; ") : undefined,
+        };
+    }
     const failed = Object.values(results).some((r) => !r.ok);
     if (opts.json) {
         const steps = Object.fromEntries(Object.entries(results).map(([key, r]) => [
@@ -185,6 +222,11 @@ export async function runInstall(args, opts, help = false) {
         return failed ? 1 : 0;
     }
     printHumanSteps(results, redact, verbose);
+    // Path-level detail for hooks (printHumanSteps only shows the synthetic step).
+    if ((target === "hooks" || target === "all") &&
+        (dryRun || (human && (verbose || hookWrites.some((w) => w.action !== "skipped"))))) {
+        printHookResults(hookWrites);
+    }
     const skillResults = Object.entries(results)
         .filter(([step]) => step.startsWith("skill:"))
         .map(([, r]) => r);

package/dist/commands/update.d.ts

@@ -0,0 +1,14 @@
+import { type GlobalFlags } from "../cli-args.js";
+import { type CommandRunner } from "../github-gh.js";
+import { type InstallSource } from "../install-source.js";
+import { type UpdateStatus } from "../update-check.js";
+export interface RunUpdateOptions {
+    globals: GlobalFlags;
+    /** Injected in tests. */
+    runner?: CommandRunner;
+    /** Injected in tests; defaults to detection from this module's path. */
+    source?: InstallSource;
+    /** Injected in tests; defaults to a cache-bypassing registry check. */
+    check?: () => Promise<UpdateStatus>;
+}
+export declare function runUpdate(args: string[], opts: RunUpdateOptions, help?: boolean): Promise<number>;

package/dist/commands/update.js

@@ -0,0 +1,125 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { flagBool, parseCommandArgs, UsageError } from "../cli-args.js";
+import { execRunner } from "../github-gh.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { detectInstallSource } from "../install-source.js";
+import { checkForUpdate } from "../update-check.js";
+import { runInstall, runStep } from "./install.js";
+const UPDATE_HELP = `uploads update — update the CLI and refresh agent integrations
+
+Upgrades the globally installed npm package, then re-runs \`uploads install\` so
+the agent skills and the MCP registration match the new version. Skills and the
+MCP registration drift on their own, so this refreshes them even when the CLI is
+already current.
+
+Usage:
+  uploads update [options]
+
+Options:
+  --dry-run        Print the plan without running anything
+  --skip-install   Upgrade the npm package only; leave skills and MCP alone
+  --verbose        Show the output of the underlying commands
+
+Examples:
+  uploads update
+  uploads update --dry-run
+  uploads update --skip-install
+`;
+/** Why an upgrade was skipped, phrased for the user. */
+const SKIP_REASON = {
+    workspace: "this is a workspace checkout, not a global install",
+    npx: "this ran from an npx cache, which is discarded after the run",
+    unknown: "this is a local project dependency, not a global install",
+};
+function thisModulePath() {
+    const path = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+function isPermissionError(message) {
+    return /EACCES|EPERM|permission denied/i.test(message);
+}
+export async function runUpdate(args, opts, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(UPDATE_HELP);
+        return 0;
+    }
+    if (parsed.positionals.length > 0) {
+        throw new UsageError(`update takes no arguments (got ${parsed.positionals[0]})`);
+    }
+    const dryRun = flagBool(parsed.flags, "--dry-run");
+    const verbose = flagBool(parsed.flags, "--verbose");
+    const skipInstall = flagBool(parsed.flags, "--skip-install");
+    const run = opts.runner ?? execRunner;
+    const source = opts.source ?? detectInstallSource(thisModulePath());
+    // ttlMs 0 bypasses the once-a-day cache: `update` must not trust yesterday's read.
+    const status = await (opts.check ?? (() => checkForUpdate({ ttlMs: 0 })))();
+    const willUpgrade = status.updateAvailable && source.kind === "global";
+    // Resolved through PATH: in the normal single-install case this is the
+    // just-upgraded binary, but with multiple `uploads` binaries on PATH it
+    // could resolve to a different, stale one. Accepted risk, not a guarantee.
+    const refreshCommand = ["uploads", "install"];
+    // --- plan ---
+    if (willUpgrade) {
+        process.stdout.write(`CLI ${status.current} → ${status.latest}\n`);
+    }
+    else if (status.updateAvailable) {
+        process.stdout.write(`CLI ${status.current} is behind ${status.latest}, but the upgrade is skipped — ` +
+            `${SKIP_REASON[source.kind] ?? "the install source is not a global install"}.\n` +
+            `Upgrade by hand with: ${source.upgradeCommand.join(" ")}\n`);
+    }
+    else {
+        process.stdout.write(`CLI already at ${status.current}\n`);
+    }
+    if (dryRun) {
+        if (willUpgrade) {
+            process.stdout.write(`upgrade: would run — ${source.upgradeCommand.join(" ")}\n`);
+        }
+        if (!skipInstall) {
+            process.stdout.write(`refresh: would run — ${refreshCommand.join(" ")}\n`);
+        }
+        return 0;
+    }
+    // --- upgrade ---
+    if (willUpgrade) {
+        process.stdout.write("Upgrading the CLI…\n");
+        const result = runStep(run, source.upgradeCommand);
+        if (!result.ok) {
+            const message = result.error ?? "";
+            process.stderr.write(`upgrade: failed — ${message}\n`);
+            if (isPermissionError(message)) {
+                process.stderr.write("The global install directory is not writable by your user. Fix the ownership " +
+                    `of your npm prefix so global installs work without sudo, then re-run \`uploads update\`.\n`);
+            }
+            process.stderr.write(`Run it by hand: ${source.upgradeCommand.join(" ")}\n`);
+            return 1;
+        }
+        process.stdout.write("upgrade: ok\n");
+        if (verbose && result.output)
+            process.stdout.write(`  ${result.output}\n`);
+    }
+    if (skipInstall)
+        return 0;
+    // --- refresh ---
+    // After an upgrade the in-process code is the OLD version, so spawn the newly
+    // installed binary. Its skill list is the one that should be installed.
+    if (willUpgrade) {
+        process.stdout.write("Refreshing skills and MCP…\n");
+        const result = runStep(run, refreshCommand);
+        if (!result.ok) {
+            process.stderr.write(`refresh: failed — ${result.error ?? ""}\n`);
+            process.stderr.write("Run it by hand: uploads install\n");
+            return 1;
+        }
+        process.stdout.write(result.output ? `${result.output}\n` : "refresh: ok\n");
+        return 0;
+    }
+    // Nothing changed, so the in-process install code is already current.
+    return runInstall(verbose ? ["--verbose"] : [], { globals: opts.globals, runner: run });
+}

package/dist/commands.d.ts

@@ -166,7 +166,16 @@ export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]):
  */
 export declare class GithubCommentAuthorizationError extends Error {
 }
-export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner, workspace?: string): Promise<AttachmentsCommentResult>;
+/**
+ * `opts.resync` marks an explicit `uploads comment` invocation rather than a
+ * background sync (attach, screenshot, put --comment). It costs the server one
+ * extra comment listing and in exchange collapses any duplicate managed
+ * comment (issue #480) — worth it on the rare, explicitly-asked-for resync,
+ * not on every attach.
+ */
+export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner, workspace?: string, opts?: {
+    resync?: boolean;
+}): Promise<AttachmentsCommentResult>;
 /**
  * Lever 3 (issue #469): a nudge for when an image lands on a PR/issue with
  * no `path` metadata — `path` is one of the highest-value queryable tags

package/dist/commands.js

@@ -450,13 +450,21 @@ export function commentViaSuffix(via) {
  */
 export class GithubCommentAuthorizationError extends Error {
 }
-export async function syncAttachmentsComment(client, target, run, workspace) {
+/**
+ * `opts.resync` marks an explicit `uploads comment` invocation rather than a
+ * background sync (attach, screenshot, put --comment). It costs the server one
+ * extra comment listing and in exchange collapses any duplicate managed
+ * comment (issue #480) — worth it on the rare, explicitly-asked-for resync,
+ * not on every attach.
+ */
+export async function syncAttachmentsComment(client, target, run, workspace, opts = {}) {
     let bot;
     try {
         bot = await client.upsertGithubComment({
             repo: target.repo,
             num: target.num,
             kind: target.kind,
+            ...(opts.resync ? { resync: true } : {}),
         });
     }
     catch {
@@ -2258,6 +2266,7 @@ async function resyncCommentAfterMetaSet(ctx, key, touchedKeys) {
             repo: target.repo,
             num: target.num,
             kind: target.kind,
+            resync: true,
         });
         if (bot.posted) {
             if (!ctx.quiet && !ctx.json) {
@@ -2336,7 +2345,9 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     const target = ghTargetFromFlags(parsed.flags, run);
     if (!target)
         throw new UsageError("comment requires --pr or --issue");
-    const result = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
+    const result = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace, {
+        resync: true,
+    });
     if (ctx.json) {
         await writeJson({ ...target, ...result });
     }

package/dist/github-gh.d.ts

@@ -55,7 +55,8 @@ export declare function resolveGhTitle(target: GhTarget, run?: CommandRunner): s
 export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: CommandRunner): Record<string, string>;
 /**
  * Create the managed attachments comment, or edit it in place if it already
- * exists. Never touches any other comment. Body is passed via stdin
+ * exists. Never touches any other comment except best-effort deletes of
+ * duplicate marker comments (see below). Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
  *
  * `marker` identifies which comment to hunt for (see `findManagedComment`);
@@ -63,6 +64,27 @@ export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: Co
  * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
  * an adopted legacy comment migrates it to the namespaced marker in place.
  * Defaults to the shared legacy marker for backward compatibility.
+ *
+ * Self-healing dedupe (issue #486, mirroring the bot path's #470/#484 fix):
+ * a create race (two concurrent `uploads attach` runs, neither finding an
+ * existing comment) can leave more than one marker comment on the thread.
+ * This path has no id cache, so unlike the bot path a duplicate here never
+ * heals on its own — every sync just patches the oldest and leaves the rest
+ * stale. After patching (or creating), any extra exact-`marker` hits are
+ * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
+ * and never fails the caller's command, and the next sync retries anyway.
+ *
+ * On why this duplicates the bot path rather than deferring to it: the gh
+ * fallback is a supported path, not a stopgap, so it is held at behavioral
+ * parity deliberately. This file already reimplements the hunt, the legacy
+ * adoption and the create-vs-patch gate against a different transport (the
+ * `gh` subprocess, not the App's token), and #486 existed precisely because
+ * the two drifted. Treat any behavior change to `upsertBotComment`
+ * (apps/api/src/github-comment.ts) as owing a matching change here. Note
+ * this is the one place the CLI deletes a GitHub resource under the
+ * invoking human's own credentials — bounded to comments carrying this
+ * workspace's exact namespaced marker, whose content is always
+ * regenerable.
  */
 export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner, marker?: string, opts?: {
     createIfMissing?: boolean;

package/dist/github-gh.js

@@ -187,7 +187,9 @@ export function ghMetadataFromTargetWithTitle(target, run = execRunner) {
 /**
  * PR comments live on the issues endpoint, so one path covers PRs and issues.
  * `--paginate` follows Link headers and merges every page into one array, so the
- * marker comment is found even on threads past 100 comments.
+ * marker comment is found even on threads past 100 comments. GitHub returns
+ * comments oldest-first, so `hits[0]` (after merging paginated pages, which
+ * preserve that order) is the oldest exact-`marker` hit.
  *
  * Hunts for `marker` (the namespaced, per-workspace marker) first; when none
  * is found, falls back to a comment carrying the shared legacy
@@ -195,6 +197,12 @@ export function ghMetadataFromTargetWithTitle(target, run = execRunner) {
  * migrated in place. When `marker` IS the legacy marker (no workspace to
  * namespace with) this collapses to a single hunt, unchanged from pre-4b
  * behavior.
+ *
+ * Collects EVERY comment carrying `marker` (a create race can leave more
+ * than one — issue #486, mirroring the bot path's #470 fix): the oldest is
+ * `comment`, the rest come back as `extras` for the caller to delete. Only
+ * exact-`marker` hits are ever extras — a legacy (unnamespaced) comment may
+ * belong to a different workspace, so it is adopted at most, never deleted.
  */
 function findManagedComment(target, run, marker) {
     const raw = run("gh", [
@@ -203,16 +211,25 @@ function findManagedComment(target, run, marker) {
         "--paginate",
     ]);
     const comments = JSON.parse(raw);
-    const namespacedHit = comments.find((c) => typeof c.body === "string" && c.body.includes(marker));
-    if (namespacedHit)
-        return namespacedHit;
+    const hits = comments.filter((c) => typeof c.body === "string" && c.body.includes(marker));
+    if (hits.length > 0) {
+        // In legacy mode (no workspace to namespace with) our "exact" marker IS
+        // the shared one, so a second hit is not our own duplicate — it may be
+        // another workspace's comment. Adopt the oldest and never delete: the
+        // adopt-only contract is about the marker being ambiguous, which is just
+        // as true when it is the marker we are hunting on.
+        const extras = marker === ATTACHMENTS_MARKER ? undefined : hits.slice(1);
+        return { comment: hits[0], extras };
+    }
     if (marker === ATTACHMENTS_MARKER)
-        return undefined;
-    return comments.find((c) => typeof c.body === "string" && c.body.includes(ATTACHMENTS_MARKER));
+        return {};
+    const legacyHit = comments.find((c) => typeof c.body === "string" && c.body.includes(ATTACHMENTS_MARKER));
+    return { comment: legacyHit };
 }
 /**
  * Create the managed attachments comment, or edit it in place if it already
- * exists. Never touches any other comment. Body is passed via stdin
+ * exists. Never touches any other comment except best-effort deletes of
+ * duplicate marker comments (see below). Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
  *
  * `marker` identifies which comment to hunt for (see `findManagedComment`);
@@ -220,10 +237,41 @@ function findManagedComment(target, run, marker) {
  * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
  * an adopted legacy comment migrates it to the namespaced marker in place.
  * Defaults to the shared legacy marker for backward compatibility.
+ *
+ * Self-healing dedupe (issue #486, mirroring the bot path's #470/#484 fix):
+ * a create race (two concurrent `uploads attach` runs, neither finding an
+ * existing comment) can leave more than one marker comment on the thread.
+ * This path has no id cache, so unlike the bot path a duplicate here never
+ * heals on its own — every sync just patches the oldest and leaves the rest
+ * stale. After patching (or creating), any extra exact-`marker` hits are
+ * deleted best-effort via `gh api -X DELETE`; a failed delete is swallowed
+ * and never fails the caller's command, and the next sync retries anyway.
+ *
+ * On why this duplicates the bot path rather than deferring to it: the gh
+ * fallback is a supported path, not a stopgap, so it is held at behavioral
+ * parity deliberately. This file already reimplements the hunt, the legacy
+ * adoption and the create-vs-patch gate against a different transport (the
+ * `gh` subprocess, not the App's token), and #486 existed precisely because
+ * the two drifted. Treat any behavior change to `upsertBotComment`
+ * (apps/api/src/github-comment.ts) as owing a matching change here. Note
+ * this is the one place the CLI deletes a GitHub resource under the
+ * invoking human's own credentials — bounded to comments carrying this
+ * workspace's exact namespaced marker, whose content is always
+ * regenerable.
  */
 export function upsertAttachmentsComment(target, body, run = execRunner, marker = ATTACHMENTS_MARKER, opts = {}) {
     const createIfMissing = opts.createIfMissing ?? true;
-    const existing = findManagedComment(target, run, marker);
+    const { comment: existing, extras } = findManagedComment(target, run, marker);
+    const deleteExtras = () => {
+        for (const extra of extras ?? []) {
+            try {
+                run("gh", ["api", `repos/${target.repo}/issues/comments/${extra.id}`, "-X", "DELETE"]);
+            }
+            catch {
+                // Best effort only — a failed delete must never fail the caller's command.
+            }
+        }
+    };
     if (existing) {
         run("gh", [
             "api",
@@ -233,12 +281,15 @@ export function upsertAttachmentsComment(target, body, run = execRunner, marker
             "-F",
             "body=@-",
         ], body);
+        deleteExtras();
         return { action: "updated" };
     }
     // Patch-only (createIfMissing false, i.e. an empty body) with no existing
     // comment: nothing to do — never create one just to say it's empty.
     if (!createIfMissing)
         return { action: "skipped" };
+    // No existing marker hit means `extras` is necessarily empty here (see
+    // `findManagedComment`) — nothing to delete after a create.
     run("gh", ["api", `repos/${target.repo}/issues/${target.num}/comments`, "-F", "body=@-"], body);
     return { action: "created" };
 }

package/dist/hooks-install.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Install thin user-global hook manifests for Grok and Cursor.
+ *
+ * Claude and Codex ship the same PreToolUse hook via their plugins
+ * (`hooks/hooks.json` → `uploads hook pre-pr-screenshot`). Do not also write
+ * ~/.codex/hooks.json here, or the reminder would fire twice.
+ *
+ * Idempotent: skip when our command string is already present.
+ */
+export declare const HOOK_COMMAND = "uploads hook pre-pr-screenshot";
+export type HookWriteResult = {
+    path: string;
+    action: "wrote" | "merged" | "skipped" | "would-write" | "would-merge";
+    error?: string;
+};
+export type InstallHooksOptions = {
+    home?: string;
+    dryRun?: boolean;
+    targets?: Array<"grok" | "cursor">;
+};
+/** User-global manifests for Grok + Cursor only. */
+export declare function installHookManifests(opts?: InstallHooksOptions): HookWriteResult[];

package/dist/hooks-install.js

@@ -0,0 +1,112 @@
+/**
+ * Install thin user-global hook manifests for Grok and Cursor.
+ *
+ * Claude and Codex ship the same PreToolUse hook via their plugins
+ * (`hooks/hooks.json` → `uploads hook pre-pr-screenshot`). Do not also write
+ * ~/.codex/hooks.json here, or the reminder would fire twice.
+ *
+ * Idempotent: skip when our command string is already present.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const HOOK_COMMAND = "uploads hook pre-pr-screenshot";
+const TIMEOUT_SEC = 15;
+const GROK_PAYLOAD = {
+    description: "Advisory reminder to stage screenshots on uploads.sh before opening a PR that touches UI files.",
+    hooks: {
+        PreToolUse: [
+            {
+                matcher: "Bash",
+                hooks: [
+                    {
+                        type: "command",
+                        command: HOOK_COMMAND,
+                        timeout: TIMEOUT_SEC,
+                        statusMessage: "Checking staged screenshots",
+                    },
+                ],
+            },
+        ],
+    },
+};
+function containsCommand(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8").includes(HOOK_COMMAND);
+    }
+    catch {
+        return false;
+    }
+}
+function writeJson(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+function commit(filePath, next, dryRun, existed) {
+    if (containsCommand(filePath))
+        return { path: filePath, action: "skipped" };
+    if (dryRun) {
+        return { path: filePath, action: existed ? "would-merge" : "would-write" };
+    }
+    writeJson(filePath, next);
+    return { path: filePath, action: existed ? "merged" : "wrote" };
+}
+function writeGrok(home, dryRun) {
+    const filePath = path.join(home, ".grok", "hooks", "uploads-pre-pr-screenshot.json");
+    return commit(filePath, GROK_PAYLOAD, dryRun, fs.existsSync(filePath));
+}
+function mergeCursor(home, dryRun) {
+    const filePath = path.join(home, ".cursor", "hooks.json");
+    const existed = fs.existsSync(filePath);
+    let existing = { version: 1, hooks: {} };
+    if (existed) {
+        try {
+            const raw = JSON.parse(fs.readFileSync(filePath, "utf8"));
+            if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+                return { path: filePath, action: "skipped", error: "hooks.json is not an object" };
+            }
+            existing = raw;
+        }
+        catch (err) {
+            return {
+                path: filePath,
+                action: "skipped",
+                error: `could not parse existing hooks.json: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    const hooks = existing.hooks && typeof existing.hooks === "object"
+        ? { ...existing.hooks }
+        : {};
+    const list = Array.isArray(hooks.beforeShellExecution) ? [...hooks.beforeShellExecution] : [];
+    list.push({ command: HOOK_COMMAND, timeout: TIMEOUT_SEC });
+    hooks.beforeShellExecution = list;
+    existing.hooks = hooks;
+    if (existing.version === undefined)
+        existing.version = 1;
+    return commit(filePath, existing, dryRun, existed);
+}
+/** User-global manifests for Grok + Cursor only. */
+export function installHookManifests(opts = {}) {
+    const home = opts.home ?? os.homedir();
+    const dryRun = Boolean(opts.dryRun);
+    const targets = opts.targets ??
+        [
+            fs.existsSync(path.join(home, ".grok")) && "grok",
+            fs.existsSync(path.join(home, ".cursor")) && "cursor",
+        ].filter(Boolean);
+    const results = [];
+    for (const t of targets) {
+        try {
+            results.push(t === "grok" ? writeGrok(home, dryRun) : mergeCursor(home, dryRun));
+        }
+        catch (err) {
+            results.push({
+                path: t,
+                action: "skipped",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return results;
+}

package/dist/install-source.d.ts

@@ -0,0 +1,14 @@
+export type InstallKind = "global" | "workspace" | "npx" | "unknown";
+export type PackageManager = "npm" | "pnpm" | "bun";
+export interface InstallSource {
+    kind: InstallKind;
+    /** Falls back to npm for every non-global kind. */
+    manager: PackageManager;
+    /** Upgrades the global install. Only meaningful when kind is "global". */
+    upgradeCommand: string[];
+}
+/**
+ * @param modulePath Absolute path of a file inside the installed package,
+ *   normally `realpathSync(fileURLToPath(import.meta.url))`.
+ */
+export declare function detectInstallSource(modulePath: string): InstallSource;

package/dist/install-source.js

@@ -0,0 +1,42 @@
+/**
+ * Classify where the running CLI was installed from.
+ *
+ * `uploads update` upgrades the global npm package. That is only safe when the
+ * CLI actually came from a global install — upgrading a workspace checkout
+ * would overwrite a developer's build with the published version.
+ *
+ * Pure and path-only: no filesystem or process access, so it is fully testable.
+ */
+import { PACKAGE_NAME } from "./update-check.js";
+const UPGRADE_COMMANDS = {
+    npm: ["npm", "install", "-g", `${PACKAGE_NAME}@latest`],
+    pnpm: ["pnpm", "add", "-g", `${PACKAGE_NAME}@latest`],
+    bun: ["bun", "add", "-g", `${PACKAGE_NAME}@latest`],
+};
+function classify(path) {
+    // npx is checked first: a cache entry can also contain a global-looking marker.
+    if (path.includes("/_npx/"))
+        return { kind: "npx", manager: "npm" };
+    if (path.includes("/.bun/install/global/"))
+        return { kind: "global", manager: "bun" };
+    if (path.includes("/pnpm/global/"))
+        return { kind: "global", manager: "pnpm" };
+    if (path.includes("/lib/node_modules/"))
+        return { kind: "global", manager: "npm" };
+    // Windows npm globals have no `lib` segment: `<prefix>\npm\node_modules\<pkg>`.
+    if (path.includes("/npm/node_modules/"))
+        return { kind: "global", manager: "npm" };
+    // No node_modules segment at all means we are running out of a source checkout.
+    if (!path.includes("/node_modules/"))
+        return { kind: "workspace", manager: "npm" };
+    return { kind: "unknown", manager: "npm" };
+}
+/**
+ * @param modulePath Absolute path of a file inside the installed package,
+ *   normally `realpathSync(fileURLToPath(import.meta.url))`.
+ */
+export function detectInstallSource(modulePath) {
+    const normalized = modulePath.split("\\").join("/");
+    const { kind, manager } = classify(normalized);
+    return { kind, manager, upgradeCommand: UPGRADE_COMMANDS[manager] };
+}

package/dist/mcp/tools.js

@@ -1158,7 +1158,10 @@ export function createUploadsMcpTools(opts) {
                 if (!target)
                     usage("comment requires pr or issue");
                 const { config, client } = clientFor(args);
-                const result = await syncAttachmentsComment(client, target, run, config.workspace);
+                // Explicit resync, same as `uploads comment` (issue #480).
+                const result = await syncAttachmentsComment(client, target, run, config.workspace, {
+                    resync: true,
+                });
                 return { ...target, ...result };
             },
         },

package/dist/telemetry.js

@@ -28,6 +28,7 @@ const NESTED_COMMANDS = new Set([
     "completions",
     "config",
     "gallery",
+    "hook",
     "install",
     "meta",
     "telemetry",

package/dist/update-check.js

@@ -116,7 +116,7 @@ export async function maybeHintUpdate(opts = {}) {
         if (!status.updateAvailable || !status.latest)
             return;
         const write = opts.write ?? ((text) => process.stderr.write(text));
-        write(`hint: ${PACKAGE_NAME}@${status.latest} is available (you have ${status.current}). Update: npm i -g ${PACKAGE_NAME}\n`);
+        write(`hint: ${PACKAGE_NAME}@${status.latest} is available (you have ${status.current}). Update: uploads update\n`);
     }
     catch {
         // Never surface update-check failures.

package/package.json

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