@buildinternet/uploads 0.26.1 → 0.28.0

package/README.md

@@ -98,6 +98,11 @@ explicit deletes. Promotion (auto or `--promote`) does skip files staged
 more than 30 days before the PR opens, though; they're still there, just no
 longer auto-promoted.
 
+**Metadata edits re-sync the comment too:** `uploads meta set` on a `gh/…`-keyed
+object refreshes the managed comment automatically when it touches `path` or
+`state` — best-effort, so backfilled metadata shows up without waiting on the
+next `attach`.
+
 **Bare `put` stages too, by default (issue #403):** on a non-default git
 branch, a `put` with none of
 `--pr`/`--issue`/`--key`/`--ref`/`--prefix`/`--destination` set

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

@@ -60,6 +60,7 @@ export const SCREENSHOT_FLAGS = [
     "--light",
     "--wait",
     "--out",
+    "--no-sidecar",
     "--no-upload",
     "--destination",
     "--prefix",
@@ -187,6 +188,11 @@ export const ROOT_COMMANDS = [
             { name: "all", summary: "Install skills and MCP (default)" },
         ],
     },
+    {
+        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

@@ -16,6 +16,7 @@ const ESSENTIAL_ORDER = [
     "delete",
     "doctor",
     "install",
+    "update",
 ];
 /** Day-to-day commands shown on bare `uploads` / `uploads help`. */
 const ESSENTIALS = ESSENTIAL_ORDER.map((name) => {

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 { 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 +269,9 @@ export async function runCli(argv) {
             case "install":
                 code = await runInstall(cmdArgs, { globals: parsed.globals, json }, 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/install.d.ts

@@ -1,6 +1,14 @@
 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;

package/dist/commands/install.js

@@ -46,7 +46,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 };

package/dist/commands/screenshot.js

@@ -2,15 +2,16 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
+import { branchFromFlags, derivedMetaEnabled, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, stateAppMetaFromFlags, warnNearMissMeta, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, resolvePutStagingTarget, putStagingNoteText, resolveStageBindingWarning, mergeStagingMeta, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveRepo, } from "../github-gh.js";
-import { ghBranchAttachmentKey, ghMetadataForBranch } from "../github.js";
+import { ghBranchAttachmentKey } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
+import { writeSidecarMeta } from "../sidecar.js";
 import { writeJson, writeStdout } from "../io.js";
 import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
 const SCREENSHOT_HELP = `uploads screenshot <target> [options]
@@ -33,6 +34,15 @@ fail fast with a clear error instead of sending a doomed request.
 After capture, screenshots share the put upload pipeline: optional --frame,
 optimize-by-default, --pr/--issue attachment + --comment, --gallery, --meta.
 
+Branch staging by default (pre-PR): with no --pr/--issue/--branch/--key/--ref/
+--prefix/--destination, a screenshot taken on a non-default git branch stages
+under gh/<owner>/<repo>/branch/<branch>/<name> instead of the dated
+screenshots/<repo>/<date>/... layout — same key/metadata as an explicit
+--branch, carrying every derived fact (path/url/env/viewport, --state) along.
+Staged files auto-attach with full metadata the first time you attach to that
+branch's PR once it opens (or run "uploads attach --promote"). Use --no-git,
+or an explicit --ref/--prefix, to opt back into the dated layout.
+
 Options:
   --via auto|local|remote   Capture backend (default: auto, or UPLOADS_SCREENSHOT_VIA)
   --browser <path>          Explicit local browser executable (or UPLOADS_CHROME_PATH / CHROME_PATH)
@@ -51,7 +61,12 @@ Options:
                             on --via remote — neutralizes animations via injected CSS)
   --eval <js>               Run JS in the page after settle, before capture (--via local only)
   --init-script <file>      Inject a JS file before navigation (--via local only)
-  --out <file>              Also write the PNG to a local file
+  --out <file>              Also write the PNG to a local file. Also writes a sidecar manifest,
+                            <file>.uploads.json, recording this capture's derived metadata
+                            (path/url/env/viewport, plus --state if given) with a content hash; a
+                            later \`put\`/\`attach\` of this exact file picks the metadata back up
+                            automatically (explicit --meta/--state still win). See --no-sidecar.
+  --no-sidecar              Don't write the <file>.uploads.json sidecar alongside --out
   --no-upload                Skip hosting; requires --out (local file only)
   --destination <id>        Typed root: screenshots | gh | f
   --prefix <path>           Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
@@ -171,6 +186,9 @@ captureImpl = captureScreenshot) {
     const noUpload = flagBool(parsed.flags, "--no-upload");
     if (noUpload && !outFile)
         throw new UsageError("--no-upload requires --out");
+    const noSidecar = flagBool(parsed.flags, "--no-sidecar");
+    if (noSidecar && !outFile)
+        throw new UsageError("--no-sidecar requires --out");
     const keyHint = flagString(parsed.flags, "--key");
     const destFlag = flagString(parsed.flags, "--destination");
     const prefixFlag = flagString(parsed.flags, "--prefix");
@@ -210,14 +228,38 @@ captureImpl = captureScreenshot) {
         if (noUpload)
             throw new UsageError("--dry-run cannot be combined with --no-upload");
     }
+    const putDefaults = resolvePutDefaults({ envFile: ctx.envFile }, rawDefaults);
+    const noGit = flagBool(parsed.flags, "--no-git") || putDefaults.noGit === true;
     const branchRepo = branchArg !== undefined ? resolveRepo(flagString(parsed.flags, "--repo"), run) : undefined;
+    // Auto branch staging (issue #469 lever 1): mirrors bare `put`'s auto-staging
+    // (issue #403). When no --branch/--pr/--issue/--key/--ref/--prefix/--destination
+    // is given and git use isn't disabled, a screenshot taken on a non-default
+    // git branch stages the same way explicit `--branch`/bare `put` do — same
+    // key shape, same gh.* metadata — instead of landing on the dated
+    // `screenshots/<repo>/<date>/...` layout. This is what lets derived
+    // metadata (path/url/env/viewport, --state) ride through to PR-open
+    // promotion when the capture happens before the PR exists. Skipped
+    // entirely when --branch was given explicitly (already handled above).
+    const autoStagingTarget = branchArg === undefined
+        ? resolvePutStagingTarget({
+            ghTarget,
+            keyHint,
+            refArg: flagString(parsed.flags, "--ref"),
+            prefixArg: prefixFlag,
+            destinationArg: destFlag,
+            noGit,
+            repoArg: flagString(parsed.flags, "--repo") ?? putDefaults.repo,
+            run,
+        })
+        : undefined;
+    const stagingTarget = branchArg !== undefined ? { repo: branchRepo, branch: branchArg } : autoStagingTarget;
     let resolvedPrefix;
     try {
         resolvedPrefix = resolvePutPrefix({
             destination: destFlag,
             prefix: prefixFlag,
             key: keyHint,
-            ghAttachment: Boolean(ghTarget) || branchArg !== undefined,
+            ghAttachment: Boolean(ghTarget) || stagingTarget !== undefined,
         });
     }
     catch (err) {
@@ -233,7 +275,6 @@ captureImpl = captureScreenshot) {
                 return raw;
             throw new UsageError(`invalid --format: ${raw}`);
         })();
-    const putDefaults = resolvePutDefaults({ envFile: ctx.envFile }, rawDefaults);
     const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, putDefaults);
     const frameOpts = frameOptionsFromFlags(parsed.flags);
     const altFlag = flagString(parsed.flags, "--alt");
@@ -248,9 +289,8 @@ captureImpl = captureScreenshot) {
         metadata = { ...withFacts, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(metadata);
     }
-    else if (branchArg !== undefined) {
-        metadata = { ...withFacts, ...ghMetadataForBranch(branchRepo, branchArg) };
-        validateMetaMap(metadata);
+    else if (stagingTarget !== undefined) {
+        metadata = mergeStagingMeta(withFacts, stagingTarget);
     }
     else if (Object.keys(withFacts).length > 0) {
         validateMetaMap(withFacts);
@@ -282,6 +322,8 @@ captureImpl = captureScreenshot) {
         writeFileSync(outFile, captured.png);
         if (logHuman)
             process.stderr.write(`>> wrote ${outFile}\n`);
+        if (!noSidecar)
+            writeSidecarMeta(outFile, captured.png, withFacts);
     }
     if (noUpload) {
         if (ctx.json) {
@@ -294,8 +336,8 @@ captureImpl = captureScreenshot) {
     }
     const repo = flagString(parsed.flags, "--repo") ?? putDefaults.repo;
     const ref = flagString(parsed.flags, "--ref") ?? putDefaults.ref;
-    const branchKey = branchArg !== undefined
-        ? ghBranchAttachmentKey(branchRepo, branchArg, captured.filename)
+    const branchKey = stagingTarget !== undefined
+        ? ghBranchAttachmentKey(stagingTarget.repo, stagingTarget.branch, captured.filename)
         : undefined;
     const alt = altFlag ?? basename(captured.filename);
     const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, captured.png, captured.filename, {
@@ -306,13 +348,26 @@ captureImpl = captureScreenshot) {
         prefix: resolvedPrefix ?? putDefaults.prefix,
         repo,
         ref,
-        deriveRepoFromGit: !(flagBool(parsed.flags, "--no-git") || putDefaults.noGit === true),
+        deriveRepoFromGit: !noGit,
         dryRun,
         metadata,
         provenanceClient: "uploads-cli-screenshot",
         alt: () => alt,
         width,
     });
+    // Staging note (issue #469 lever 1, mirrors #403's bare-put note): only for
+    // the auto-staged case — explicit `--branch` keeps its own "staged: these
+    // auto-attach..." wording below. Same suppression as put's note (--quiet,
+    // UPLOADS_NO_NUDGE=1).
+    const stagingNote = autoStagingTarget && !ctx.quiet && !putDefaults.noNudge
+        ? putStagingNoteText(autoStagingTarget.branch)
+        : undefined;
+    // Stage-time binding warning (issue #398), same check bare put/attach
+    // --branch run, now also reachable from screenshot's staging paths
+    // (explicit --branch and auto-staging alike).
+    const bindingWarning = stagingTarget !== undefined
+        ? await resolveStageBindingWarning({ ctx, defaults: putDefaults, repo: stagingTarget.repo })
+        : undefined;
     let gallery;
     if (galleryId) {
         try {
@@ -347,8 +402,25 @@ captureImpl = captureScreenshot) {
         if (prepared.optimized) {
             process.stderr.write(`>> optimized ${prepared.originalBytes} → ${prepared.outputBytes} bytes\n`);
         }
-        process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n\n`);
+        process.stderr.write(`>> key: ${result.key}${dryRun ? " (dry run — not uploaded)" : ""}\n`);
+        if (stagingTarget !== undefined) {
+            process.stderr.write(`>> find these later: uploads find gh.branch=${stagingTarget.branch.toLowerCase()}\n`);
+            if (autoStagingTarget) {
+                if (stagingNote)
+                    process.stderr.write(`${stagingNote}\n`);
+            }
+            else {
+                process.stderr.write(`>> staged: these auto-attach to this branch's PR when it opens ` +
+                    `(or run \`uploads attach --promote\` after opening)\n`);
+            }
+        }
+        if (bindingWarning)
+            process.stderr.write(`${bindingWarning}\n`);
+        process.stderr.write("\n");
     }
+    // One JSON `hint` slot (mirrors bare put): the binding warning is more
+    // actionable than the generic staging note, so it wins when both fire.
+    const jsonHint = bindingWarning ?? stagingNote;
     switch (format) {
         case "json":
             await writeJson({
@@ -363,6 +435,7 @@ captureImpl = captureScreenshot) {
                 backend: captured.backend,
                 gallery,
                 ...(dryRun ? { dryRun: true } : {}),
+                ...(jsonHint ? { hint: jsonHint } : {}),
             });
             break;
         case "url":

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,31 @@ 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
+ * (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,
+ * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ */
+export declare function pathMetaHintFor(uploads: {
+    contentType: string;
+    metadata?: Record<string, string>;
+}[]): string | undefined;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -355,6 +379,14 @@ export declare function resolvePutStagingTarget(opts: {
     repoArg: string | undefined;
     run: CommandRunner;
 }): BranchTarget | undefined;
+/**
+ * Merges a staging target's `gh.*` branch metadata over `base` and validates
+ * the result (same builder, same contract as `attach --branch`) — the one
+ * merge+validate step shared by every staging call site: `runPut`,
+ * `runScreenshot`, and both the local stdio MCP `put` and `screenshot`
+ * tools.
+ */
+export declare function mergeStagingMeta(base: Record<string, string> | undefined, target: BranchTarget): Record<string, string>;
 /**
  * The bare-put staging note's wording (issue #403): replaces the #393 nudge
  * for the (now default) case where a bare put on a non-default branch stages