@buildinternet/uploads 0.22.1 → 0.24.0

package/README.md

@@ -94,6 +94,14 @@ attachments when one opens: automatically via the
 workspace↔repo binding the webhook path uses. Promoted staging is cleaned up
 server-side after ~7 days (~30 for branches that never got a PR).
 
+**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
+(and not `--no-git`) stages exactly like `attach --branch` — same key,
+same `gh.*` metadata. The classic dated layout
+(`<prefix>/<repo>/<ref-or-date>/<name>`) remains the default branch/detached
+HEAD/non-repo/`--no-git` behavior, and the explicit-flags opt-out.
+
 **Screenshot capture:** `uploads screenshot <url|file.html>` renders a page to a
 hosted image in one step — no separate browser tooling needed. `--via auto`
 (default) drives a Chrome/Chromium already on the machine (`playwright-core`

package/dist/cli-catalog.js

@@ -114,6 +114,10 @@ export const ROOT_COMMANDS = [
         summary: "Upload (+ URL + markdown for GitHub)",
         essential: true,
     },
+    {
+        name: "staged",
+        summary: "Show what's staged for a branch, and whether it will auto-attach",
+    },
     {
         name: "screenshot",
         usage: "screenshot <target>",

package/dist/cli.js

@@ -4,7 +4,7 @@ import { UploadsError } from "./errors.js";
 import { commandWorkspace, flagString, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
 import { formatRootHelp, wantsFullHelp } from "./cli-help.js";
 import { colorEnabled, createStyle } from "./cli-style.js";
-import { runPut, runAttach, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { runPut, runAttach, runStaged, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
@@ -269,6 +269,7 @@ export async function runCli(argv) {
                 break;
             case "attach":
             case "put":
+            case "staged":
             case "screenshot":
             case "gallery":
             case "list":
@@ -289,6 +290,9 @@ export async function runCli(argv) {
                     case "put":
                         code = await runPut(ctx, cmdArgs, showHelp);
                         break;
+                    case "staged":
+                        code = await runStaged(ctx, cmdArgs, showHelp);
+                        break;
                     case "screenshot":
                         code = await runScreenshot(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -249,6 +249,16 @@ export interface GithubLinkUnlinkResult {
     unlinked: boolean;
     reason?: "not_linked";
 }
+/**
+ * `GET /v1/:workspace/github/repo-link` result (issue #398). Deliberately
+ * minimal relative to `GithubLinkResult`: never names the owning workspace
+ * when it isn't this one — "self"/"other"/"none" is all the stage-time
+ * warning needs, and anything richer would leak cross-tenant info to a
+ * caller that's just probing a repo it detected from local git context.
+ */
+export interface GithubRepoLinkResult {
+    binding: "self" | "other" | "none";
+}
 export interface HealthResult {
     ok: boolean;
 }
@@ -528,6 +538,14 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
      * server without this route.
      */
     githubLinkClaim(repo: string): Promise<GithubLinkClaimResult>;
+    /**
+     * Tri-state binding status for `repo` relative to this workspace (issue
+     * #398, `attach --branch`'s stage-time warning) — never names another
+     * workspace, unlike `githubLinkStatus` above. Throws `UploadsError`
+     * (status 404) on an older/self-hosted server without this route; the
+     * caller (the stage warning) treats ANY failure here as "stay silent".
+     */
+    githubRepoLinkStatus(repo: string): Promise<GithubRepoLinkResult>;
     /**
      * GitHub App configuration + webhook event subscription check. Throws
      * `UploadsError` (status 404) on an older/self-hosted server without

package/dist/client.js

@@ -516,6 +516,16 @@ export function createUploadsClient(config) {
                 headers: { "Content-Type": "application/json" },
             });
         },
+        /**
+         * Tri-state binding status for `repo` relative to this workspace (issue
+         * #398, `attach --branch`'s stage-time warning) — never names another
+         * workspace, unlike `githubLinkStatus` above. Throws `UploadsError`
+         * (status 404) on an older/self-hosted server without this route; the
+         * caller (the stage warning) treats ANY failure here as "stay silent".
+         */
+        async githubRepoLinkStatus(repo) {
+            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/repo-link?repo=${encodeURIComponent(repo)}`);
+        },
         /**
          * GitHub App configuration + webhook event subscription check. Throws
          * `UploadsError` (status 404) on an older/self-hosted server without

package/dist/commands.d.ts

@@ -82,6 +82,13 @@ export interface UploadPreparedImageOptions {
     optimize: OptimizeImageOptions;
     /** gh attachment key wins over `key` when both are set (matches every call site). */
     ghTarget?: GhTarget;
+    /**
+     * Branch-staged key (issue #403): wins over `key`, loses to `ghTarget` (the
+     * two are mutually exclusive at every call site — a PR/issue target always
+     * implies staging is moot). Produces the exact same key as `attach
+     * --branch` for the same filename via `ghBranchAttachmentKey`.
+     */
+    ghBranchTarget?: BranchTarget;
     key?: string;
     prefix?: string;
     repo?: string;
@@ -258,6 +265,8 @@ export declare function uploadPuts(opts: {
     /** Single-file --key. */
     explicitKey?: string;
     ghTarget?: GhTarget;
+    /** Branch-staged key (issue #403) — see UploadPreparedImageOptions.ghBranchTarget. */
+    ghBranchTarget?: BranchTarget;
     prefix?: string;
     repo?: string;
     ref?: string;
@@ -290,6 +299,106 @@ export declare function uploadPuts(opts: {
     firstError?: unknown;
 }>;
 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
+ * text (issue #398), shared by the `attach --branch`/bare-`put` stage-time
+ * warning below and the `uploads staged` view (issue #405) — both surfaces
+ * must say the exact same thing for the same binding state, verified by
+ * tests on both call sites. Returns undefined for `"self"` (the happy path —
+ * callers each phrase that themselves) and any unrecognized value.
+ */
+export declare function stagingBindingAdvisory(binding: string, repo: string): string | undefined;
+/**
+ * Best-effort stage-time binding warning (issue #398): after `attach
+ * --branch` stages files, checks whether `repo` is bound to THIS workspace —
+ * webhook auto-promotion at PR open only fires for a repo already bound
+ * (#297), and staging alone never binds one. Fires only for `binding: "none"`
+ * (unbound) or `"other"` (bound elsewhere); `"self"` and any failure
+ * (network, non-200, older server without the route, `binding: "unknown"`)
+ * are silent — this is advisory only and must never make staging look like
+ * it failed. Same suppression as the #393 put nudge: `--quiet`,
+ * `UPLOADS_NO_NUDGE=1` (env or config).
+ */
+export declare function resolveStageBindingWarning(opts: {
+    ctx: CliContext;
+    defaults: PutDefaults;
+    repo: string;
+}): Promise<string | undefined>;
+/**
+ * Bare-put branch-staging trigger (issue #403): put on a non-default git
+ * branch stages to the branch prefix by default — the branch becomes the
+ * organizing unit instead of the date, superseding the #393 CLI nudge for
+ * this case (see `putStagingNoteText`). Reuses the same detection stack as
+ * `resolvePutNudge` (`deriveRepoFromGit` / `resolveCurrentBranch` /
+ * `resolveDefaultBranch` / main-master fallback) plus a `resolveRepo` lookup
+ * (needed for the "owner/name" staging key) and an explicit-flag opt-out:
+ * `ghTarget`/`keyHint`/`refArg`/`prefixArg`/`destinationArg` set, or `noGit`,
+ * forces the classic dated (or typed-destination) layout. Never throws — any
+ * failure (not a repo, detached HEAD, gh missing/unauthenticated/timed out,
+ * unresolvable repo) degrades to "no staging", leaving the caller to fall
+ * back to the dated path.
+ *
+ * Plain-params (not CLI `flags`) so both `runPut` and the local stdio MCP
+ * `put` tool — same staging default, issue #403's scope — can call this
+ * without either depending on the other's argument shape.
+ */
+export declare function resolvePutStagingTarget(opts: {
+    ghTarget: GhTarget | undefined;
+    keyHint: string | undefined;
+    refArg: string | undefined;
+    prefixArg: string | undefined;
+    /** Explicit `--destination` (CLI) / `destination` (MCP) also opts out — it
+     * resolves to its own prefix via `resolvePutPrefix`, which staging would
+     * otherwise silently override. */
+    destinationArg: string | undefined;
+    noGit: boolean;
+    repoArg: string | undefined;
+    run: CommandRunner;
+}): BranchTarget | undefined;
+/**
+ * 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
+ * to the branch prefix instead of landing on the dated layout. Used verbatim
+ * for both the human-mode stderr line and the JSON `hint` field.
+ */
+export declare function putStagingNoteText(branch: string): string;
+/** One file currently staged for a branch (issue #405). */
+export interface StagedFile {
+    /** Full object key (`gh/<owner>/<repo>/branch/<branch>/<filename>`). */
+    key: string;
+    /** `key` with the staging prefix stripped. */
+    filename: string;
+    size?: number;
+    /** `gh.staged-at` metadata (ISO 8601 UTC), when present. */
+    stagedAt?: string;
+    url: string | null;
+}
+/** Tri-state binding, folded into a ready-to-render advisory (issue #405/#398). */
+export interface StagedBinding {
+    state: "self" | "other" | "none" | "unknown";
+    /** True only for "self" — the only state where staged files actually auto-attach. */
+    autoAttach: boolean;
+    message: string;
+}
+export interface StagedResult {
+    repo: string;
+    branch: string;
+    files: StagedFile[];
+    binding: StagedBinding;
+}
+/**
+ * Shared core for `uploads staged` (CLI) and the `staged` MCP tool (issue
+ * #405): one `list` call against the branch staging prefix
+ * (`ghBranchKeyPrefix` — never hand-built) plus the #398 binding check. Never
+ * throws on the binding check (see `resolveStagedBinding`); a failed `list`
+ * call still propagates, same as every other read command.
+ */
+export declare function resolveStaged(opts: {
+    client: UploadsClient;
+    repo: string;
+    branch: string;
+}): Promise<StagedResult>;
+export declare function runStaged(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runPut(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runGallery(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runList(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;

package/dist/commands.js

@@ -11,8 +11,9 @@ import { writeJson, writeStdout } from "./io.js";
 import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
 import { mergeDerivedMeta, nearMissMetaWarnings, validateStateValue } from "./metadata-vocab.js";
-import { ghAttachmentKey, ghBranchAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, classifyGhNumber, execRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
+import { ghAttachmentKey, ghBranchAttachmentKey, ghBranchKeyPrefix, ghKeyPrefix, ghMetadataFromTarget, ghMetadataForBranch, attachmentsCommentBody, attachmentsMarker, normalizeGithubCoordinate, } from "./github.js";
+import { resolveRepo, resolveCurrentPullRequest, resolveCurrentBranch, resolveDefaultBranch, classifyGhNumber, execRunner, timedExecRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.js";
+import { deriveRepoFromGit } from "./keys.js";
 import { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
@@ -111,6 +112,10 @@ Options:
   --dry-run             Print key + public URL without uploading; reports if the key would replace
                         (or, on a strict key, be refused). Not with --comment/--gallery
 
+A bare put (no --pr/--issue/--key) on a non-default git branch prints a one-line
+nudge toward --pr/attach --branch (stderr in human mode, a "hint" field in
+--format json). Suppress with --quiet, UPLOADS_NO_NUDGE=1, or config UPLOADS_NO_NUDGE=1.
+
 Exit codes: 0 ok · 2 usage/token/file · 3 auth/policy · 4 network · 1 other (incl. partial multi-file failure).
 Scripted formats (json|url|markdown) also print failures on stdout.
 
@@ -368,7 +373,11 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         frameFit: opts.frame.frameFit,
         optimize: opts.optimize,
     });
-    let key = opts.ghTarget ? ghAttachmentKey(opts.ghTarget, prepared.filename) : opts.key;
+    let key = opts.ghTarget
+        ? ghAttachmentKey(opts.ghTarget, prepared.filename)
+        : opts.ghBranchTarget
+            ? ghBranchAttachmentKey(opts.ghBranchTarget.repo, opts.ghBranchTarget.branch, prepared.filename)
+            : opts.key;
     if (key && prepared.optimized)
         key = rewriteKeyExtension(key, prepared.filename);
     const result = await client.put(prepared.bytes, {
@@ -738,6 +747,7 @@ export async function uploadPuts(opts) {
                 frame: opts.frame,
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
+                ghBranchTarget: opts.ghBranchTarget,
                 key: opts.explicitKey,
                 prefix: opts.prefix,
                 repo: opts.repo,
@@ -1004,8 +1014,17 @@ async function runAttachBranch(ctx, parsed, branch, run) {
     if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
         throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
+    // Stage-time binding warning (issue #398): only worth checking once staging
+    // actually produced something to warn about. Best-effort — see
+    // resolveStageBindingWarning; never affects exit code or the upload itself.
+    const bindingWarning = uploads.length > 0 ? await resolveStageBindingWarning({ ctx, defaults, repo }) : undefined;
     if (ctx.json) {
-        await writeJson({ target, uploads, failures });
+        await writeJson({
+            target,
+            uploads,
+            failures,
+            ...(bindingWarning ? { hint: bindingWarning } : {}),
+        });
     }
     else {
         for (const result of uploads) {
@@ -1029,9 +1048,58 @@ async function runAttachBranch(ctx, parsed, branch, run) {
             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`);
     }
     return failures.length === 0 ? 0 : 1;
 }
+/**
+ * One source of truth for the "staged, but not going to auto-attach" advisory
+ * text (issue #398), shared by the `attach --branch`/bare-`put` stage-time
+ * warning below and the `uploads staged` view (issue #405) — both surfaces
+ * must say the exact same thing for the same binding state, verified by
+ * tests on both call sites. Returns undefined for `"self"` (the happy path —
+ * callers each phrase that themselves) and any unrecognized value.
+ */
+export function stagingBindingAdvisory(binding, repo) {
+    switch (binding) {
+        case "none":
+            return (`staged, but ${repo} isn't linked to your workspace yet — staged files only ` +
+                `auto-attach on PR open for linked repos. Link it once with: uploads attach <file> ` +
+                `(on any PR) or uploads github link. After the PR opens: uploads attach --promote`);
+        case "other":
+            return (`staged, but ${repo} is linked to a different workspace — these files won't ` +
+                `auto-attach from here.`);
+        default:
+            return undefined; // "self", or any unrecognized value
+    }
+}
+/**
+ * Best-effort stage-time binding warning (issue #398): after `attach
+ * --branch` stages files, checks whether `repo` is bound to THIS workspace —
+ * webhook auto-promotion at PR open only fires for a repo already bound
+ * (#297), and staging alone never binds one. Fires only for `binding: "none"`
+ * (unbound) or `"other"` (bound elsewhere); `"self"` and any failure
+ * (network, non-200, older server without the route, `binding: "unknown"`)
+ * are silent — this is advisory only and must never make staging look like
+ * it failed. Same suppression as the #393 put nudge: `--quiet`,
+ * `UPLOADS_NO_NUDGE=1` (env or config).
+ */
+export async function resolveStageBindingWarning(opts) {
+    const { ctx, defaults, repo } = opts;
+    if (ctx.quiet)
+        return undefined;
+    if (defaults.noNudge)
+        return undefined;
+    try {
+        const { binding } = await ctx.client.githubRepoLinkStatus(repo);
+        const advisory = stagingBindingAdvisory(binding, repo);
+        return advisory ? `note: ${advisory}` : undefined;
+    }
+    catch {
+        return undefined; // any failure (network, non-200, older server) — stay silent
+    }
+}
 /**
  * `attach --promote` with zero file arguments: resolve the PR target (same
  * resolution as the default `runAttach` path), promote this workspace's
@@ -1079,6 +1147,263 @@ async function runAttachPromoteOnly(ctx, parsed, run) {
     }
     return 0;
 }
+/** Bounds the best-effort `gh pr view` lookup the put nudge (issue #393) makes
+ * on top of the normal put flow — long enough for a real gh call, short
+ * enough to never be felt as a hang. */
+const PUT_NUDGE_GH_TIMEOUT_MS = 3000;
+/**
+ * The bare-put nudge's wording (issue #393): teaches `--pr`/`attach --branch`
+ * as an upgrade from a targetless `put`. `pr` present → names the PR;
+ * otherwise a generic variant that still points at `--pr <num>`. Used
+ * verbatim for both the human-mode stderr line and the JSON `hint` field.
+ */
+function putNudgeText(branch, pr) {
+    const prClause = pr !== undefined ? ` (PR #${pr} open) — rerun with --pr ${pr}` : ` — rerun with --pr <num>`;
+    return (`note: on branch ${branch}${prClause} for a stable key plus a managed comment ` +
+        `that collects this PR's media, or stage pre-PR files with: uploads attach <file> --branch`);
+}
+/**
+ * Best-effort bare-put nudge (issue #393): fires only when `put` has no
+ * targeting flag at all (`--pr`/`--issue`/`--key`; `--branch` too, though
+ * `put` doesn't currently accept it — defensive parity with `attach`), is
+ * inside a git repo (reusing `deriveRepoFromGit`, the same detection the
+ * default screenshot key's repo segment uses), and the current branch isn't
+ * the default one. Never throws — any failure (not a repo, detached HEAD,
+ * `gh` missing/unauthenticated/timed out) degrades to "no nudge" or, once a
+ * branch is already known, to the generic no-PR wording. Must never affect
+ * put's exit code, stdout, or upload behavior.
+ */
+function resolvePutNudge(opts) {
+    const { ctx, flags, ghTarget, keyHint, noGit, defaults, run } = opts;
+    if (ctx.quiet)
+        return undefined;
+    if (defaults.noNudge)
+        return undefined;
+    if (ghTarget || keyHint || noGit)
+        return undefined;
+    if (flags.has("--branch"))
+        return undefined; // not a real put flag today; defensive only
+    try {
+        if (deriveRepoFromGit(run) === undefined)
+            return undefined; // not a (usable) git repo
+        let branch;
+        try {
+            branch = resolveCurrentBranch(run);
+        }
+        catch {
+            return undefined; // detached HEAD, or git unavailable
+        }
+        const defaultBranch = resolveDefaultBranch(run);
+        const onDefaultBranch = defaultBranch
+            ? branch === defaultBranch
+            : branch === "main" || branch === "master"; // undetermined: err toward not nudging
+        if (onDefaultBranch)
+            return undefined;
+        let pr;
+        try {
+            // Only swap in the bounded runner for the real subprocess path — an
+            // injected `run` (tests, or a future caller) is trusted to already be
+            // fast/fake, and execFileSync's `timeout` option is meaningless
+            // against anything that isn't actually shelling out.
+            const timed = run === execRunner ? timedExecRunner(PUT_NUDGE_GH_TIMEOUT_MS) : run;
+            const repoArg = flagString(flags, "--repo") ?? defaults.repo;
+            const repo = resolveRepo(repoArg, timed);
+            pr = resolveCurrentPullRequest(repo, timed).num;
+        }
+        catch {
+            pr = undefined; // gh missing/unauthenticated/timed out/no open PR — generic wording
+        }
+        return putNudgeText(branch, pr);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Bare-put branch-staging trigger (issue #403): put on a non-default git
+ * branch stages to the branch prefix by default — the branch becomes the
+ * organizing unit instead of the date, superseding the #393 CLI nudge for
+ * this case (see `putStagingNoteText`). Reuses the same detection stack as
+ * `resolvePutNudge` (`deriveRepoFromGit` / `resolveCurrentBranch` /
+ * `resolveDefaultBranch` / main-master fallback) plus a `resolveRepo` lookup
+ * (needed for the "owner/name" staging key) and an explicit-flag opt-out:
+ * `ghTarget`/`keyHint`/`refArg`/`prefixArg`/`destinationArg` set, or `noGit`,
+ * forces the classic dated (or typed-destination) layout. Never throws — any
+ * failure (not a repo, detached HEAD, gh missing/unauthenticated/timed out,
+ * unresolvable repo) degrades to "no staging", leaving the caller to fall
+ * back to the dated path.
+ *
+ * Plain-params (not CLI `flags`) so both `runPut` and the local stdio MCP
+ * `put` tool — same staging default, issue #403's scope — can call this
+ * without either depending on the other's argument shape.
+ */
+export function resolvePutStagingTarget(opts) {
+    const { ghTarget, keyHint, refArg, prefixArg, destinationArg, noGit, repoArg, run } = opts;
+    if (ghTarget || keyHint || noGit)
+        return undefined;
+    if (refArg || prefixArg || destinationArg)
+        return undefined;
+    try {
+        if (deriveRepoFromGit(run) === undefined)
+            return undefined; // not a (usable) git repo
+        let branch;
+        try {
+            branch = resolveCurrentBranch(run);
+        }
+        catch {
+            return undefined; // detached HEAD, or git unavailable
+        }
+        const defaultBranch = resolveDefaultBranch(run);
+        const onDefaultBranch = defaultBranch
+            ? branch === defaultBranch
+            : branch === "main" || branch === "master"; // undetermined: err toward the dated layout
+        if (onDefaultBranch)
+            return undefined;
+        // Same bounded-timeout treatment as the #393 nudge's `gh pr view` call —
+        // this is best-effort, and must never be felt as a hang.
+        const timed = run === execRunner ? timedExecRunner(PUT_NUDGE_GH_TIMEOUT_MS) : run;
+        const repo = resolveRepo(repoArg, timed);
+        return { repo, branch };
+    }
+    catch {
+        return undefined; // gh/git unavailable, or repo unresolvable — dated layout
+    }
+}
+/**
+ * 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
+ * to the branch prefix instead of landing on the dated layout. Used verbatim
+ * for both the human-mode stderr line and the JSON `hint` field.
+ */
+export function putStagingNoteText(branch) {
+    return (`note: staged for branch ${branch} — auto-attaches to this branch's PR when it opens ` +
+        `(or run: uploads attach --promote once it exists). Use --ref/--prefix for a plain dated upload.`);
+}
+/**
+ * Binding lookup for `uploads staged`, folded into a renderable `StagedBinding`.
+ * `"none"`/`"other"` reuse `stagingBindingAdvisory` — the exact #398 wording,
+ * one source of truth. `"self"` gets its own message (the #398 warning stays
+ * silent on "self"; this view is the one place that names the happy path
+ * explicitly). Any failure (network, non-200, older server without the
+ * route) degrades to `"unknown"` rather than throwing — this is a read-only
+ * view and a binding check failing must never make it fail outright.
+ */
+async function resolveStagedBinding(client, repo) {
+    try {
+        const { binding } = await client.githubRepoLinkStatus(repo);
+        switch (binding) {
+            case "self":
+                return {
+                    state: "self",
+                    autoAttach: true,
+                    message: "these auto-attach when this branch's PR opens",
+                };
+            case "none":
+            case "other":
+                return {
+                    state: binding,
+                    autoAttach: false,
+                    // stagingBindingAdvisory is total for "none"/"other" — never undefined here.
+                    message: stagingBindingAdvisory(binding, repo),
+                };
+            default:
+                return { state: "unknown", autoAttach: false, message: "binding status unrecognized" };
+        }
+    }
+    catch {
+        return {
+            state: "unknown",
+            autoAttach: false,
+            message: "could not check binding status (offline, or an older server without this route)",
+        };
+    }
+}
+/**
+ * Shared core for `uploads staged` (CLI) and the `staged` MCP tool (issue
+ * #405): one `list` call against the branch staging prefix
+ * (`ghBranchKeyPrefix` — never hand-built) plus the #398 binding check. Never
+ * throws on the binding check (see `resolveStagedBinding`); a failed `list`
+ * call still propagates, same as every other read command.
+ */
+export async function resolveStaged(opts) {
+    const { client, repo, branch } = opts;
+    const prefix = ghBranchKeyPrefix(repo, branch);
+    const [list, binding] = await Promise.all([
+        client.list({ prefix, metadata: true }),
+        resolveStagedBinding(client, repo),
+    ]);
+    const files = list.items.map((item) => ({
+        key: item.key,
+        filename: item.key.slice(prefix.length),
+        size: item.size,
+        stagedAt: item.metadata?.["gh.staged-at"],
+        url: item.url,
+    }));
+    return { repo, branch, files, binding };
+}
+const STAGED_HELP = `uploads staged [--branch <name>] [--repo <owner/name>] [--format json] [--workspace <name>]
+
+Read-only view of what's staged for a branch (\`attach --branch\` / bare
+\`put\` on a non-default branch, issue #403) and whether it will auto-attach
+once a PR opens. One \`list\` call against the branch staging prefix
+(gh/<owner>/<repo>/branch/<branch>/) plus a binding check — files:read only,
+no new server surface.
+
+Defaults: current git branch (same resolution as \`attach --branch\`, worktree-
+safe), repo from --repo / gh / git remote (same as every other command).
+
+Binding: self means these files auto-attach when this branch's PR opens; none
+or other means they won't (repo unlinked, or linked to a different
+workspace) — same advisory as the attach --branch stage-time warning.
+
+Examples:
+  uploads staged
+  uploads staged --branch feature/thing --repo owner/name
+  uploads staged --format json
+`;
+export async function runStaged(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(STAGED_HELP);
+        return 0;
+    }
+    const format = ctx.json
+        ? "json"
+        : (() => {
+            const raw = flagString(parsed.flags, "--format");
+            if (!raw || raw === "human")
+                return "human";
+            if (raw === "json")
+                return "json";
+            throw new UsageError(`invalid --format: ${raw} (expected: json)`);
+        })();
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    const branch = flagString(parsed.flags, "--branch") ?? resolveCurrentBranch(run);
+    const result = await resolveStaged({ client: ctx.client, repo, branch });
+    if (format === "json") {
+        // Always a valid JSON document, even with zero files — never empty
+        // stdout (issue #405 explicitly calls out find --format json's empty-
+        // stdout-on-no-matches wart as a wrong pattern to avoid here).
+        await writeJson(result);
+        return 0;
+    }
+    if (result.files.length === 0) {
+        await writeStdout(`nothing staged for ${branch} in ${repo}\n`);
+        return 0;
+    }
+    for (const file of result.files) {
+        const size = file.size !== undefined ? formatByteSize(file.size) : "? B";
+        const staged = file.stagedAt ? `  staged ${file.stagedAt}` : "";
+        await writeStdout(`${file.filename}  ${size}${staged}  ${file.url ?? "(no url)"}\n`);
+    }
+    process.stderr.write(`binding: ${result.binding.state} — ${result.binding.message}\n`);
+    // Promote is pointless advice when the repo belongs to another workspace —
+    // the cross-tenant gate (#297) would reject it from here.
+    if (result.binding.state !== "other") {
+        process.stderr.write(`once the PR exists: uploads attach --promote\n`);
+    }
+    return 0;
+}
 export async function runPut(ctx, args, help = false, run = execRunner) {
     if (help) {
         writeCommandHelp(PUT_HELP);
@@ -1197,7 +1522,25 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             })()
             : defaults.width;
     const noGit = flagBool(parsed.flags, "--no-git") || defaults.noGit === true;
-    // gh.* metadata: explicit --pr/--issue target wins over --meta; otherwise
+    // Bare-put branch staging (issue #403): a bare put (no --pr/--issue/--key/
+    // --ref/--prefix/--destination, not --no-git) on a non-default git branch
+    // stages to the branch prefix — identical key/metadata to `attach
+    // --branch` — instead of the dated layout. Computed before gh.* metadata
+    // resolution below since it takes over that resolution entirely (branch
+    // metadata, not PR/issue metadata) and supersedes the #393 nudge for this
+    // case.
+    const stagingTarget = resolvePutStagingTarget({
+        ghTarget,
+        keyHint,
+        refArg: flagString(parsed.flags, "--ref"),
+        prefixArg: prefixFlag,
+        destinationArg: destFlag,
+        noGit,
+        repoArg: flagString(parsed.flags, "--repo") ?? defaults.repo,
+        run,
+    });
+    // gh.* metadata: explicit --pr/--issue target wins over --meta; staging
+    // wins over --meta the same way (matches attach --branch); otherwise
     // best-effort auto resolution (on by default) where --meta wins. --no-git,
     // --no-auto, or UPLOADS_NO_AUTO_META disable auto; --auto forces past the
     // config default but never past --no-git (no repo to resolve).
@@ -1209,6 +1552,14 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         metadata = merged;
         attachedRef = merged["gh.ref"];
     }
+    else if (stagingTarget) {
+        const merged = {
+            ...userMeta,
+            ...ghMetadataForBranch(stagingTarget.repo, stagingTarget.branch),
+        };
+        validateMetaMap(merged); // matches attach --branch's unwrapped call — same builder, same contract
+        metadata = merged;
+    }
     else {
         // gh.* additionally needs git, which the shared derived gate ignores.
         if (!noGit && derivedMetaEnabled(parsed.flags, defaults)) {
@@ -1229,6 +1580,31 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             }
         }
     }
+    // Bare-put nudge (issue #393): only relevant when staging didn't take over
+    // — once `stagingTarget` resolves, staging IS the upgrade the nudge used to
+    // point at, so this is skipped entirely rather than firing redundantly.
+    // Still fires as before for a bare put that lands on the dated layout with
+    // a detectable PR (e.g. an explicit --ref/--prefix opts out of staging).
+    // Computed once, used for both the trailing stderr line (human mode) and
+    // the JSON `hint` field below. Best-effort — see resolvePutNudge; never
+    // affects exit code, stdout, or the upload.
+    const nudge = stagingTarget
+        ? undefined
+        : resolvePutNudge({
+            ctx,
+            flags: parsed.flags,
+            ghTarget,
+            keyHint,
+            noGit,
+            defaults,
+            run,
+        });
+    // Staging note (issue #403): same suppression as the #393 nudge
+    // (--quiet, UPLOADS_NO_NUDGE=1 env/config); staging itself is NOT gated by
+    // either — only whether the note is printed/hinted.
+    const stagingNote = stagingTarget && !ctx.quiet && !defaults.noNudge
+        ? putStagingNoteText(stagingTarget.branch)
+        : undefined;
     const logHuman = !ctx.quiet && format === "human";
     if (logHuman) {
         if (multi) {
@@ -1247,6 +1623,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         nameOverride: nameFlag,
         explicitKey: keyHint,
         ghTarget,
+        ghBranchTarget: stagingTarget,
         prefix: resolvedPrefix ?? defaults.prefix,
         repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
         ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
@@ -1265,6 +1642,19 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     if (uploads.length === 0 && failures.length > 0 && !multi) {
         throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
+    // Stage-time binding warning (issue #398/#400): same check `attach
+    // --branch` runs, now also on the bare-put staging path. Best-effort — see
+    // resolveStageBindingWarning; never affects exit code or the upload.
+    const bindingWarning = stagingTarget && uploads.length > 0
+        ? await resolveStageBindingWarning({ ctx, defaults, repo: stagingTarget.repo })
+        : 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
+    // (mirrors attach --branch, whose only JSON hint content IS the binding
+    // warning); stderr prints the nudge/staging-note and binding-warning lines
+    // independently, below.
+    const jsonHint = nudge ?? bindingWarning ?? stagingNote;
     const galleriesByKey = new Map();
     let galleryHadError = false;
     if (galleryId && uploads.length > 0) {
@@ -1310,6 +1700,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 failures,
                 comment,
                 commentError,
+                ...(jsonHint ? { hint: jsonHint } : {}),
             });
         }
         else {
@@ -1340,6 +1731,12 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
             for (const failure of failures) {
                 process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
             }
+            if (nudge)
+                process.stderr.write(`${nudge}\n`);
+            if (stagingNote)
+                process.stderr.write(`${stagingNote}\n`);
+            if (bindingWarning)
+                process.stderr.write(`${bindingWarning}\n`);
         }
         return failures.length === 0 && !galleryHadError ? 0 : 1;
     }
@@ -1371,6 +1768,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
                 frame: result.frame,
                 gallery,
                 ...(dryRun ? { dryRun: true } : {}),
+                ...(jsonHint ? { hint: jsonHint } : {}),
             });
             break;
         case "url":
@@ -1390,6 +1788,12 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     if (gallery?.error) {
         process.stderr.write(`warning: upload succeeded but adding it to gallery ${gallery.id} failed: ${gallery.error.message}\n`);
     }
+    if (nudge && format !== "json")
+        process.stderr.write(`${nudge}\n`);
+    if (stagingNote && format !== "json")
+        process.stderr.write(`${stagingNote}\n`);
+    if (bindingWarning && format !== "json")
+        process.stderr.write(`${bindingWarning}\n`);
     return gallery?.error ? 1 : 0;
 }
 // --- galleries ---

package/dist/config-file.d.ts

@@ -1,5 +1,5 @@
 import type { UploadsClientConfig } from "./config.js";
-export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF", "UPLOADS_NO_AUTO_META", "UPLOADS_SCREENSHOT_VIA"];
+export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", "UPLOADS_DEFAULT_PREFIX", "UPLOADS_DEFAULT_REPO", "UPLOADS_DEFAULT_REF", "UPLOADS_DEFAULT_WIDTH", "UPLOADS_NO_GIT", "UPLOADS_NO_OPTIMIZE", "UPLOADS_KEEP_EXIF", "UPLOADS_NO_AUTO_META", "UPLOADS_SCREENSHOT_VIA", "UPLOADS_NO_NUDGE"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {
@@ -14,6 +14,8 @@ export interface PutDefaults {
     keepExif?: boolean;
     /** When true, `put` does NOT auto-resolve/stamp gh.* on the default path. */
     noAutoMeta?: boolean;
+    /** When true, `put` never prints the bare-put --pr/attach nudge (issue #393). */
+    noNudge?: boolean;
 }
 declare const PUT_DEFAULT_KEY_MAP: Record<keyof PutDefaults, UploadsConfigKey>;
 export declare function putDefaultsToConfigValues(defaults: PutDefaults): UploadsConfigValues;

package/dist/config-file.js

@@ -14,6 +14,7 @@ export const UPLOADS_CONFIG_KEYS = [
     "UPLOADS_KEEP_EXIF",
     "UPLOADS_NO_AUTO_META",
     "UPLOADS_SCREENSHOT_VIA",
+    "UPLOADS_NO_NUDGE",
 ];
 const PUT_DEFAULT_KEY_MAP = {
     prefix: "UPLOADS_DEFAULT_PREFIX",
@@ -24,6 +25,7 @@ const PUT_DEFAULT_KEY_MAP = {
     noOptimize: "UPLOADS_NO_OPTIMIZE",
     keepExif: "UPLOADS_KEEP_EXIF",
     noAutoMeta: "UPLOADS_NO_AUTO_META",
+    noNudge: "UPLOADS_NO_NUDGE",
 };
 function isTruthyConfigFlag(value) {
     if (!value)
@@ -49,6 +51,8 @@ export function putDefaultsToConfigValues(defaults) {
         out.UPLOADS_KEEP_EXIF = "1";
     if (defaults.noAutoMeta)
         out.UPLOADS_NO_AUTO_META = "1";
+    if (defaults.noNudge)
+        out.UPLOADS_NO_NUDGE = "1";
     return out;
 }
 function parsePutDefaultsFromRaw(raw) {
@@ -72,6 +76,8 @@ function parsePutDefaultsFromRaw(raw) {
         out.keepExif = true;
     if (isTruthyConfigFlag(raw.UPLOADS_NO_AUTO_META))
         out.noAutoMeta = true;
+    if (isTruthyConfigFlag(raw.UPLOADS_NO_NUDGE))
+        out.noNudge = true;
     return out;
 }
 function parsePutDefaultsFromEnv() {
@@ -92,6 +98,8 @@ function parsePutDefaultsFromEnv() {
         raw.UPLOADS_KEEP_EXIF = process.env.UPLOADS_KEEP_EXIF;
     if (process.env.UPLOADS_NO_AUTO_META)
         raw.UPLOADS_NO_AUTO_META = process.env.UPLOADS_NO_AUTO_META;
+    if (process.env.UPLOADS_NO_NUDGE)
+        raw.UPLOADS_NO_NUDGE = process.env.UPLOADS_NO_NUDGE;
     return parsePutDefaultsFromRaw(raw);
 }
 /** XDG default shared across buildinternet skills (github-screenshots, uploads, …). */
@@ -163,6 +171,8 @@ export function mergePutDefaults(...layers) {
             out.keepExif = layer.keepExif;
         if (layer.noAutoMeta != null)
             out.noAutoMeta = layer.noAutoMeta;
+        if (layer.noNudge != null)
+            out.noNudge = layer.noNudge;
     }
     return out;
 }

package/dist/github-gh.d.ts

@@ -2,6 +2,14 @@ import { type GhTarget } from "./github.js";
 /** Runs a command and returns stdout; throws on non-zero exit. Injectable for tests. */
 export type CommandRunner = (cmd: string, args: string[], input?: string) => string;
 export declare const execRunner: CommandRunner;
+/**
+ * A `CommandRunner` bounded by `timeoutMs` (node's native `execFileSync`
+ * `timeout` option). There is no other subprocess-timeout wrapper in this
+ * codebase to reuse, so this is the minimal one: for a best-effort lookup
+ * that must never block its caller for long (e.g. the bare-`put` nudge's `gh
+ * pr view` check, issue #393), pass this instead of the default `execRunner`.
+ */
+export declare const timedExecRunner: (timeoutMs: number) => CommandRunner;
 /**
  * Resolve "owner/name". Order: explicit --repo (validated) → `gh repo view`
  * (fork-aware) → parse the origin remote → UsageError.
@@ -11,6 +19,14 @@ export declare function resolveRepo(explicit: string | undefined, run?: CommandR
 export declare function resolveCurrentPullRequest(repo: string, run?: CommandRunner): GhTarget;
 /** Resolve the current git branch (`--branch` with no value). Throws UsageError on detached HEAD or outside a git repo. */
 export declare function resolveCurrentBranch(run?: CommandRunner): string;
+/**
+ * Best-effort default-branch name via the local `origin/HEAD` ref (no
+ * network call — just reads the ref git already cached from the last
+ * fetch/clone). Returns undefined when it can't be determined (no origin,
+ * `origin/HEAD` never set, not a git repo) — callers should treat that as
+ * "unknown", not "no default branch exists".
+ */
+export declare function resolveDefaultBranch(run?: CommandRunner): string | undefined;
 /**
  * Classify a bare PR/issue number via the GitHub API so the default `put`
  * path can stamp the right `gh.kind`. Returns undefined on any failure (gh

package/dist/github-gh.js

@@ -3,6 +3,19 @@ import { UsageError } from "./cli-args.js";
 import { ATTACHMENTS_MARKER, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
 import { META_VALUE_MAX, isMetaValueSafe } from "./metadata.js";
 export const execRunner = (cmd, args, input) => execFileSync(cmd, args, { encoding: "utf8", input, stdio: ["pipe", "pipe", "pipe"] });
+/**
+ * A `CommandRunner` bounded by `timeoutMs` (node's native `execFileSync`
+ * `timeout` option). There is no other subprocess-timeout wrapper in this
+ * codebase to reuse, so this is the minimal one: for a best-effort lookup
+ * that must never block its caller for long (e.g. the bare-`put` nudge's `gh
+ * pr view` check, issue #393), pass this instead of the default `execRunner`.
+ */
+export const timedExecRunner = (timeoutMs) => (cmd, args, input) => execFileSync(cmd, args, {
+    encoding: "utf8",
+    input,
+    stdio: ["pipe", "pipe", "pipe"],
+    timeout: timeoutMs,
+});
 /**
  * Resolve "owner/name". Order: explicit --repo (validated) → `gh repo view`
  * (fork-aware) → parse the origin remote → UsageError.
@@ -82,6 +95,26 @@ export function resolveCurrentBranch(run = execRunner) {
     }
     return branch;
 }
+/**
+ * Best-effort default-branch name via the local `origin/HEAD` ref (no
+ * network call — just reads the ref git already cached from the last
+ * fetch/clone). Returns undefined when it can't be determined (no origin,
+ * `origin/HEAD` never set, not a git repo) — callers should treat that as
+ * "unknown", not "no default branch exists".
+ */
+export function resolveDefaultBranch(run = execRunner) {
+    try {
+        const out = run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]).trim();
+        if (!out)
+            return undefined;
+        const slash = out.indexOf("/");
+        const branch = slash === -1 ? out : out.slice(slash + 1);
+        return branch || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Classify a bare PR/issue number via the GitHub API so the default `put`
  * path can stamp the right `gh.kind`. Returns undefined on any failure (gh

package/dist/github.d.ts

@@ -86,6 +86,18 @@ export interface AttachmentItem {
         path?: string;
         state?: string;
     };
+    /**
+     * Poster frame for a video (issue #299), server-computed like `embedUrl` —
+     * never taken from client-settable metadata. Absent means "no poster", and
+     * the renderer falls back to the bullet link.
+     */
+    posterUrl?: string | null;
+    /** Derived video facts used for the caption and display width. */
+    videoMeta?: {
+        durationSeconds?: number;
+        width?: number;
+        height?: number;
+    };
 }
 /** A public gallery linked to the PR or issue whose managed comment is syncing. */
 export interface GalleryCommentItem {

package/dist/github.js

@@ -171,6 +171,34 @@ export function attachmentImageWidth(filename) {
     }
     return ATTACHMENT_IMAGE_WIDTH_DEFAULT;
 }
+/** `m:ss` under an hour, `h:mm:ss` at or above one. */
+function formatDuration(seconds) {
+    const total = Math.floor(seconds);
+    const s = total % 60;
+    const m = Math.floor(total / 60) % 60;
+    const h = Math.floor(total / 3600);
+    const ss = String(s).padStart(2, "0");
+    if (h === 0)
+        return `${m}:${ss}`;
+    return `${h}:${String(m).padStart(2, "0")}:${ss}`;
+}
+/**
+ * Display width for a video poster. Real dimensions only *select* among the
+ * width constants — a raw 1920 would blow out the comment column — and the
+ * result is capped at the real width so a small clip is never upscaled.
+ */
+function posterImageWidth(videoMeta, filename) {
+    const w = videoMeta?.width ?? 0;
+    const h = videoMeta?.height ?? 0;
+    if (w <= 0 || h <= 0)
+        return attachmentImageWidth(filename);
+    const chosen = h > w
+        ? ATTACHMENT_IMAGE_WIDTH_PORTRAIT
+        : w / h >= 16 / 9
+            ? ATTACHMENT_IMAGE_WIDTH_WIDE
+            : ATTACHMENT_IMAGE_WIDTH_DEFAULT;
+    return Math.min(chosen, w);
+}
 function escapeHtmlAttr(s) {
     return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
 }
@@ -259,13 +287,29 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
         const src = item.embedUrl ?? item.url;
         const link = item.pageUrl ?? stable; // click-through: file page when known, else raw
         const isImage = Boolean(src) && inferContentType(name).startsWith("image/");
-        if (isImage && inlinedImages >= MAX_INLINE_ATTACHMENT_IMAGES) {
+        const isPosterVideo = Boolean(item.posterUrl) && inferContentType(name).startsWith("video/");
+        const inlines = isImage || isPosterVideo;
+        if (inlines && inlinedImages >= MAX_INLINE_ATTACHMENT_IMAGES) {
             // Cap hit — defer to the collapsed overflow list below rather than
             // embedding every remaining image inline.
             overflowImages.push(item);
             continue;
         }
-        if (isImage) {
+        if (isPosterVideo) {
+            inlinedImages++;
+            const w = posterImageWidth(item.videoMeta, name);
+            const href = escapeHtmlAttr(link ?? item.posterUrl);
+            lines.push(`<a href="${href}"><img width="${w}" alt="${escapeHtmlAttr(name)}" src="${escapeHtmlAttr(item.posterUrl)}"></a>`);
+            // GitHub strips <video>, so a still frame needs an explicit affordance
+            // or it reads as a screenshot.
+            const parts = ["▶ Play video"];
+            if (item.videoMeta?.durationSeconds != null) {
+                parts.push(formatDuration(item.videoMeta.durationSeconds));
+            }
+            parts.push(...metaCaptionParts(item.meta).map(escapeHtmlText));
+            lines.push(`<sub>${parts.join(" · ")}</sub>`, "");
+        }
+        else if (isImage) {
             inlinedImages++;
             // Markdown ![]() has no width control — phone frames become full-column giants.
             // img src uses embed host when available (Camo revalidates); click-through prefers the file page.

package/dist/keys.d.ts

@@ -1,6 +1,13 @@
 export declare function sanitizeKeySegment(s: string): string;
 export declare function sha256Short(bytes: Uint8Array): Promise<string>;
-export declare function deriveRepoFromGit(): string | undefined;
+/**
+ * `run` is optional and structurally matches `CommandRunner` (github-gh.ts)
+ * without importing it — callers that already have an injected runner (e.g.
+ * the put nudge, issue #393) can pass it through for testability; the
+ * default (no `run`) preserves the original direct-`execSync` behavior for
+ * every existing caller.
+ */
+export declare function deriveRepoFromGit(run?: (cmd: string, args: string[], input?: string) => string): string | undefined;
 export declare function buildScreenshotKey(opts: {
     filename: string;
     fileBytes: Uint8Array;

package/dist/keys.js

@@ -9,9 +9,18 @@ export async function sha256Short(bytes) {
         .join("")
         .slice(0, 6);
 }
-export function deriveRepoFromGit() {
+/**
+ * `run` is optional and structurally matches `CommandRunner` (github-gh.ts)
+ * without importing it — callers that already have an injected runner (e.g.
+ * the put nudge, issue #393) can pass it through for testability; the
+ * default (no `run`) preserves the original direct-`execSync` behavior for
+ * every existing caller.
+ */
+export function deriveRepoFromGit(run) {
     try {
-        const url = execSync("git config --get remote.origin.url", { encoding: "utf8" }).trim();
+        const url = run
+            ? run("git", ["config", "--get", "remote.origin.url"]).trim()
+            : execSync("git config --get remote.origin.url", { encoding: "utf8" }).trim();
         const match = url.match(/[/:]([^/]+?)(?:\.git)?$/);
         return match?.[1];
     }

package/dist/mcp/tools.js

@@ -1,13 +1,13 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghKeyPrefix } from "../github.js";
+import { ghKeyPrefix, ghMetadataForBranch } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
-import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
+import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentBranch, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
 import { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, optBool, optPosInt, optString, optStringArray, optStringRecord, stateProp, usage, } from "./args.js";
 import { batchFailureMessage, ToolBatchError } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
@@ -415,9 +415,35 @@ export function createUploadsMcpTools(opts) {
                 const alt = optString(args, "alt");
                 const width = optPosInt(args, "width") ?? defaults.width;
                 const contentType = optString(args, "contentType");
+                // Bare-put branch staging (issue #403): local stdio MCP put mirrors
+                // the CLI default — no pr/issue/key/ref/prefix/destination, not
+                // noGit, on a non-default git branch stages to the branch prefix
+                // (identical key/metadata to `attach --branch`) instead of the
+                // dated layout. Never throws — see resolvePutStagingTarget.
+                const stagingTarget = resolvePutStagingTarget({
+                    ghTarget: target,
+                    keyHint: keyArg,
+                    refArg,
+                    prefixArg,
+                    destinationArg: destArg,
+                    noGit,
+                    repoArg: optString(args, "repo") ?? defaults.repo,
+                    run,
+                });
+                const putMetadata = stagingTarget
+                    ? (() => {
+                        const merged = {
+                            ...metadata,
+                            ...ghMetadataForBranch(stagingTarget.repo, stagingTarget.branch),
+                        };
+                        validateMetaMap(merged); // same builder, same contract as attach --branch
+                        return merged;
+                    })()
+                    : metadata;
                 const putShared = {
                     client,
                     ghTarget: target,
+                    ghBranchTarget: stagingTarget,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
                     ref: refArg ?? defaults.ref,
@@ -427,7 +453,7 @@ export function createUploadsMcpTools(opts) {
                     replace: replaceArg,
                     optimize: optimizeOpts,
                     frame: frameOpts,
-                    metadata,
+                    metadata: putMetadata,
                     // The shared metadata description promises uploads.sh derives these
                     // "automatically where it can" — MCP has no --no-auto, so always on.
                     deriveImageFacts: true,
@@ -458,6 +484,7 @@ export function createUploadsMcpTools(opts) {
                         frame: frameOpts,
                         optimize: optimizeOpts,
                         ghTarget: target,
+                        ghBranchTarget: stagingTarget,
                         key: keyArg,
                         prefix: resolvedPrefix ?? defaults.prefix,
                         repo: optString(args, "repo") ?? defaults.repo,
@@ -466,7 +493,7 @@ export function createUploadsMcpTools(opts) {
                         deriveRepoFromGit: !noGit,
                         dryRun,
                         replace: replaceArg,
-                        metadata,
+                        metadata: putMetadata,
                         provenanceClient: "uploads-mcp",
                         alt: () => alt ?? sourceName,
                         width,
@@ -925,6 +952,31 @@ export function createUploadsMcpTools(opts) {
                 return client.list({ prefix, limit, cursor });
             },
         },
+        {
+            name: "staged",
+            description: "Read-only view of what's staged for a git branch (attach --branch / bare put on a non-default branch) and whether it will auto-attach once a PR opens. One list call against the branch staging prefix plus a repo-binding check (files:read only). Returns { repo, branch, files, binding }; binding.state is self/other/none/unknown and binding.autoAttach is true only for self.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    branch: {
+                        type: "string",
+                        description: "Branch name (default: current git branch, worktree-safe).",
+                    },
+                    repo: {
+                        type: "string",
+                        description: "owner/name repo (default: gh/git remote inference).",
+                    },
+                    workspace: workspaceProp,
+                },
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const { client } = clientFor(args);
+                const repo = resolveRepo(optString(args, "repo"), run);
+                const branch = optString(args, "branch") ?? resolveCurrentBranch(run);
+                return resolveStaged({ client, repo, branch });
+            },
+        },
         {
             name: "delete",
             description: "Delete an uploaded object by key. Set dryRun to preview without deleting.",

package/package.json

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