@buildinternet/uploads 0.28.0 → 0.30.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-catalog.js

@@ -180,12 +180,23 @@ 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",
+            },
         ],
     },
     {

package/dist/cli-help.js

@@ -6,10 +6,18 @@ 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",
@@ -19,12 +27,23 @@ const ESSENTIAL_ORDER = [
     "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) {
@@ -148,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,7 @@ 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";
@@ -269,6 +270,10 @@ 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;

package/dist/client.d.ts

@@ -82,6 +82,24 @@ export interface PutResult {
      * non-`gh/` key, existing object, no `replace`) instead of overwriting.
      */
     wouldRefuse?: boolean;
+    /**
+     * The object's R2 provenance bag (`client`, `source-name`,
+     * `content-sha256`) — what the upload was made *by*, not the tags it was
+     * tagged *with*. Absent on a dry run, and on API deployments older than the
+     * split that gave this bag its own name.
+     */
+    provenance?: Record<string, string>;
+    /**
+     * The queryable metadata (D1) this put stored, including server-derived
+     * pairs the client never sent (`gh.uploader`). Absent when the put carried
+     * no metadata — that case leaves any existing tags untouched, so the server
+     * reports nothing rather than implying an empty set. Means the same thing
+     * on `getMetadata`, `patchMetadata`, and `list({ metadata: true })`.
+     *
+     * An API older than the split returns the provenance bag here instead, so a
+     * client that must work against both reads `path`-style tags defensively —
+     * see `pathMetaHintFor` in commands.ts, which prefers what it sent.
+     */
     metadata?: Record<string, string>;
 }
 export interface ListItem {
@@ -106,7 +124,12 @@ export interface HeadResult {
     size: number;
     contentType: string;
     uploaded?: string;
-    metadata?: Record<string, string>;
+    /**
+     * The object's R2 provenance bag — see `PutResult.provenance`. A plain head
+     * returns no queryable metadata at all: that tier lives in a separate store
+     * and takes a separate read, so call `getMetadata(key)` for it.
+     */
+    provenance?: Record<string, string>;
 }
 export interface DeleteResult {
     key: string;

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

@@ -13,4 +13,6 @@ 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. */
@@ -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.d.ts

@@ -123,6 +123,13 @@ export interface UploadPreparedImageResult {
     result: PutResult;
     prepared: PreparedUpload;
     markdown: string;
+    /**
+     * The queryable metadata this upload actually sent — `opts.metadata` after
+     * any derived image facts were merged in. Callers that need to reason about
+     * what was stored (see `pathMetaHintFor`) must read this, not
+     * `result.metadata`, which is the API's R2 provenance echo.
+     */
+    sentMetadata?: Record<string, string>;
 }
 /**
  * Shared bytes-oriented upload tail: frame + optimize the bytes, resolve the
@@ -182,15 +189,22 @@ export declare function syncAttachmentsComment(client: UploadsClient, target: Gh
  * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
  * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
  * already-existing image has nothing to derive it from, so it's easy to
- * forget. Fires once per batch (not per file) — checks the metadata the
- * server actually stored (`PutResult.metadata`), not what was requested, so
- * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * forget. Fires once per batch (not per file). Non-image uploads (zips,
  * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ *
+ * Checks the *resolved* metadata each upload actually sent (`--meta` pairs +
+ * sidecar manifest + derived image facts, index-aligned with `uploads`) —
+ * NOT `PutResult.metadata`. That field is the API's echo of the object's R2
+ * provenance bag (`client`, `source-name`, `content-sha256`, `uploaded-at`),
+ * never the queryable D1 tags, so it can't answer this question: reading it
+ * made the tip fire on every image, including ones uploaded with an explicit
+ * `--meta path=` (PR #509).
  */
-export declare function pathMetaHintFor(uploads: {
+export declare function pathMetaHintFor(uploads: readonly {
     contentType: string;
-    metadata?: Record<string, string>;
-}[]): string | undefined;
+}[], 
+/** Index-aligned with `uploads` — see `uploadPuts`/`uploadAttachments`. */
+sentMetadata: readonly (Record<string, string> | undefined)[]): string | undefined;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -211,6 +225,20 @@ export type AttachFailure = {
         status?: number;
     };
 };
+/** Shared shape of every prepare + put batch (`uploadPuts`/`uploadAttachments`). */
+export interface UploadBatchResult<T> {
+    uploads: T[];
+    failures: AttachFailure[];
+    /** The original cause of the first failure — for rethrowing single-file CLI paths. */
+    firstError?: unknown;
+    /**
+     * Index-aligned with `uploads`: the queryable metadata each upload actually
+     * sent (flags + sidecar + derived image facts). Kept beside the items rather
+     * than on them so it stays out of the `--format json` upload objects, which
+     * spread the item wholesale. See `pathMetaHintFor`.
+     */
+    sentMetadata: (Record<string, string> | undefined)[];
+}
 /**
  * Prepare + put each path as a PR/issue attachment with bounded concurrency.
  * Per-file errors collect in `failures` (does not throw). `firstError` is the
@@ -233,11 +261,7 @@ export declare function uploadAttachments(opts: {
     /** Provenance `client` field (default uploads-cli). */
     provenanceClient?: string;
     concurrency?: number;
-}): Promise<{
-    uploads: AttachUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<AttachUploadItem>>;
 /** A branch to stage attachments against pre-PR (`uploads attach --branch`). */
 export interface BranchTarget {
     repo: string;
@@ -266,11 +290,7 @@ export declare function uploadBranchAttachments(opts: {
     deriveImageFacts?: boolean;
     provenanceClient?: string;
     concurrency?: number;
-}): Promise<{
-    uploads: AttachUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<AttachUploadItem>>;
 export type PutUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -317,11 +337,7 @@ export declare function uploadPuts(opts: {
     alt?: string;
     width?: number;
     concurrency?: number;
-}): Promise<{
-    uploads: PutUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<PutUploadItem>>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 /**
  * One source of truth for the "staged, but not going to auto-attach" advisory

package/dist/commands.js

@@ -410,7 +410,7 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         alt: opts.alt(prepared),
         width: opts.width,
     });
-    return { result, prepared, markdown };
+    return { result, prepared, markdown, sentMetadata: metadata };
 }
 export function frameOptionsFromFlags(flags) {
     const raw = flagString(flags, "--frame");
@@ -647,13 +647,21 @@ Examples:
  * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
  * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
  * already-existing image has nothing to derive it from, so it's easy to
- * forget. Fires once per batch (not per file) — checks the metadata the
- * server actually stored (`PutResult.metadata`), not what was requested, so
- * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * forget. Fires once per batch (not per file). Non-image uploads (zips,
  * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ *
+ * Checks the *resolved* metadata each upload actually sent (`--meta` pairs +
+ * sidecar manifest + derived image facts, index-aligned with `uploads`) —
+ * NOT `PutResult.metadata`. That field is the API's echo of the object's R2
+ * provenance bag (`client`, `source-name`, `content-sha256`, `uploaded-at`),
+ * never the queryable D1 tags, so it can't answer this question: reading it
+ * made the tip fire on every image, including ones uploaded with an explicit
+ * `--meta path=` (PR #509).
  */
-export function pathMetaHintFor(uploads) {
-    const missingPath = uploads.some((u) => u.contentType.startsWith("image/") && !u.metadata?.path);
+export function pathMetaHintFor(uploads, 
+/** Index-aligned with `uploads` — see `uploadPuts`/`uploadAttachments`. */
+sentMetadata) {
+    const missingPath = uploads.some((u, i) => u.contentType.startsWith("image/") && !sentMetadata[i]?.path);
     return missingPath ? "tip: add --meta path=/route so this shot is findable by page" : undefined;
 }
 /**
@@ -697,6 +705,7 @@ async function uploadAttachmentBatch(opts) {
             });
             return {
                 ok: true,
+                sentMetadata: metadata,
                 upload: {
                     ...result,
                     file,
@@ -719,17 +728,21 @@ async function uploadAttachmentBatch(opts) {
         }
     });
     const uploads = [];
+    const sentMetadata = [];
     const failures = [];
     let firstError;
     for (const slot of slots) {
-        if (slot.ok)
+        // Pushed together so the two arrays stay index-aligned across failures.
+        if (slot.ok) {
             uploads.push(slot.upload);
+            sentMetadata.push(slot.sentMetadata);
+        }
         else {
             firstError ??= slot.err;
             failures.push({ file: slot.file, error: errorDetail(slot.err) });
         }
     }
-    return { uploads, failures, firstError };
+    return { uploads, failures, firstError, sentMetadata };
 }
 /**
  * Prepare + put each path as a PR/issue attachment with bounded concurrency.
@@ -786,7 +799,7 @@ export async function uploadPuts(opts) {
             // Sidecar manifest from a prior `screenshot --out` of this exact file
             // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin.
             const metadata = file !== "-" ? mergeSidecarMeta(file, bytes, opts.metadata) : opts.metadata;
-            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, bytes, sourceName, {
+            const { result, prepared, markdown, sentMetadata } = await uploadPreparedImage(opts.client, bytes, sourceName, {
                 frame: opts.frame,
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
@@ -807,6 +820,7 @@ export async function uploadPuts(opts) {
             });
             return {
                 ok: true,
+                sentMetadata,
                 upload: {
                     ...result,
                     file,
@@ -827,17 +841,21 @@ export async function uploadPuts(opts) {
         }
     });
     const uploads = [];
+    const sentMetadata = [];
     const failures = [];
     let firstError;
     for (const slot of slots) {
-        if (slot.ok)
+        // Pushed together so the two arrays stay index-aligned across failures.
+        if (slot.ok) {
             uploads.push(slot.upload);
+            sentMetadata.push(slot.sentMetadata);
+        }
         else {
             firstError ??= slot.err;
             failures.push({ file: slot.file, error: errorDetail(slot.err) });
         }
     }
-    return { uploads, failures, firstError };
+    return { uploads, failures, firstError, sentMetadata };
 }
 /**
  * Best-effort call to `POST /v1/:workspace/github/promote` (server contract,
@@ -931,7 +949,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         const n = parsed.positionals.length;
         process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"}\n`);
     }
-    const { uploads, failures, firstError } = await uploadAttachments({
+    const { uploads, failures, firstError, sentMetadata } = await uploadAttachments({
         client: ctx.client,
         target,
         files: parsed.positionals,
@@ -979,7 +997,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         }
     }
     // Lever 3 (issue #469): tip when an image lands here with no `path` meta.
-    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
+    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads, sentMetadata) : undefined;
     if (ctx.json) {
         await writeJson({
             target,
@@ -1672,7 +1690,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (attachedRef)
             process.stderr.write(`>> attached to ${attachedRef}\n`);
     }
-    const { uploads, failures, firstError } = await uploadPuts({
+    const { uploads, failures, firstError, sentMetadata } = await uploadPuts({
         client: ctx.client,
         files,
         nameOverride: nameFlag,
@@ -1707,7 +1725,9 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     // `path` meta. Only relevant on the ghTarget path — the bare-put paths
     // above (staging/auto/dated) aren't attached to a PR/issue yet, so there's
     // nothing to look up from a page later.
-    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
+    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet
+        ? pathMetaHintFor(uploads, sentMetadata)
+        : undefined;
     // One JSON `hint` slot, shared with the #393 nudge (mutually exclusive with
     // it — nudge is undefined whenever staging took over). When staging fires,
     // prefer the more actionable binding warning over the generic staging note

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/telemetry.js

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

package/package.json

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