@buildinternet/uploads 0.43.0 → 0.45.0

package/dist/comment-config.generated.d.ts

@@ -13,6 +13,7 @@ export interface RepoCommentConfig {
     note?: string;
     ingestGithubAttachments?: boolean;
     ingestBotAttachments?: boolean;
+    adoptLinkedFiles?: boolean;
 }
 export interface WorkspaceCommentDefaults {
     imageWidth?: "full" | number;
@@ -22,6 +23,7 @@ export interface WorkspaceCommentDefaults {
     note?: string;
     ingestGithubAttachments?: boolean;
     ingestBotAttachments?: boolean;
+    adoptLinkedFiles?: boolean;
 }
 export interface ResolvedCommentOptions {
     imageWidth: "auto" | "full" | number;
@@ -32,6 +34,7 @@ export interface ResolvedCommentOptions {
     note: string | null;
     ingestGithubAttachments: boolean;
     ingestBotAttachments: boolean;
+    adoptLinkedFiles: boolean;
 }
 export type OptionSource = "repo" | "workspace" | "auto";
 export declare const AUTO_COMMENT_OPTIONS: ResolvedCommentOptions;

package/dist/comment-config.generated.js

@@ -14,6 +14,9 @@ export const AUTO_COMMENT_OPTIONS = {
     note: null,
     ingestGithubAttachments: true,
     ingestBotAttachments: false,
+    // Default ON for bound repos (issue #701) — binding is already an
+    // explicit opt-in relationship, same posture as ingestGithubAttachments.
+    adoptLinkedFiles: true,
 };
 export const NOTE_MAX_CHARS = 500;
 const WIDTH_MIN = 160;
@@ -81,6 +84,14 @@ export function parseRepoCommentConfig(text, format) {
         else
             warnings.push(`ingestBotAttachments: expected a boolean; dropped`);
     }
+    // adoptLinkedFiles: boolean
+    if ("adoptLinkedFiles" in c) {
+        const v = c.adoptLinkedFiles;
+        if (typeof v === "boolean")
+            config.adoptLinkedFiles = v;
+        else
+            warnings.push(`adoptLinkedFiles: expected a boolean; dropped`);
+    }
     // meta.path / meta.state: booleans nested under `meta`
     if ("meta" in c) {
         const v = c.meta;
@@ -139,6 +150,7 @@ export function resolveCommentOptions(repo, ws) {
         ...(ws?.ingestBotAttachments !== undefined
             ? { ingestBotAttachments: ws.ingestBotAttachments }
             : {}),
+        ...(ws?.adoptLinkedFiles !== undefined ? { adoptLinkedFiles: ws.adoptLinkedFiles } : {}),
     };
     const options = { ...AUTO_COMMENT_OPTIONS };
     const source = Object.fromEntries(Object.keys(AUTO_COMMENT_OPTIONS).map((k) => [k, "auto"]));
@@ -151,6 +163,7 @@ export function resolveCommentOptions(repo, ws) {
             "linkToFilePage",
             "ingestGithubAttachments",
             "ingestBotAttachments",
+            "adoptLinkedFiles",
         ]) {
             if (cfg[key] !== undefined && source[key] === "auto") {
                 options[key] = cfg[key];

package/dist/comment-render.generated.d.ts

@@ -147,5 +147,8 @@ export declare function attachmentImageWidth(filename: string, density?: Attachm
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
+ *
+ * `target` is optional so goldens, the settings preview, and other callers
+ * without a PR/issue stay on the generic `--pr <N>` hint.
  */
-export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[], marker?: string, options?: CommentRenderOptions): string;
+export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[], marker?: string, options?: CommentRenderOptions, target?: Pick<GhTarget, "kind" | "num">): string;

package/dist/comment-render.generated.js

@@ -390,11 +390,24 @@ function countInlinableMedia(sorted, maxInlineImages) {
     }
     return count;
 }
+/**
+ * Quiet add-media footer. When `target` is a real PR/issue, the command
+ * uses that number (`--pr 12` / `--issue 45`) so anyone reading the comment
+ * can copy it. Without a target the generic `--pr <N>` placeholder stays.
+ */
+function addMediaFooter(target) {
+    const flag = target?.kind === "issues" ? "--issue" : "--pr";
+    const n = target && Number.isInteger(target.num) && target.num > 0 ? String(target.num) : "&lt;N&gt;";
+    return `<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> · add media: <code>uploads put &lt;file&gt; ${flag} ${n}</code> · <a href="https://uploads.sh/docs/github-app">docs</a></sub>`;
+}
 /**
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
+ *
+ * `target` is optional so goldens, the settings preview, and other callers
+ * without a PR/issue stay on the generic `--pr <N>` hint.
  */
-export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMENTS_MARKER, options = AUTO_RENDER_OPTIONS) {
+export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMENTS_MARKER, options = AUTO_RENDER_OPTIONS, target) {
     // Non-mutating sort (equivalent to Array#toSorted) — the api worker's
     // tsconfig targets lib ES2022, which predates Array#toSorted (ES2023);
     // packages/uploads/src/github.ts uses toSorted directly.
@@ -529,6 +542,6 @@ export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMEN
     // Footer condensed to a single quiet line — the old two-line explainer
     // ("re-uploading updates everywhere", full add-media flags) repeats on
     // every PR and lost value with each appearance; details live in the docs.
-    lines.push('<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> · add media: <code>uploads put &lt;file&gt; --pr &lt;N&gt;</code> · <a href="https://uploads.sh/docs/github-app">docs</a></sub>');
+    lines.push(addMediaFooter(target));
     return lines.join("\n");
 }

package/dist/config-file.d.ts

@@ -1,7 +1,7 @@
 import type { UploadsClientConfig } from "./config.js";
 export declare const UPLOADS_CONFIG_KEYS: readonly ["UPLOADS_API_URL", "UPLOADS_WORKSPACE", "UPLOADS_TOKEN", 
 /** Better Auth device-flow session bearer — keeps session.cliVersion fresh. */
-"UPLOADS_SESSION_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"];
+"UPLOADS_SESSION_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", "UPLOADS_NO_AUTO_PR"];
 export type UploadsConfigKey = (typeof UPLOADS_CONFIG_KEYS)[number];
 export type UploadsConfigValues = Partial<Record<UploadsConfigKey, string>>;
 export interface PutDefaults {
@@ -18,6 +18,9 @@ export interface PutDefaults {
     noAutoMeta?: boolean;
     /** When true, `put` never prints the bare-put --pr/attach nudge (issue #393). */
     noNudge?: boolean;
+    /** When true, a bare put/screenshot never auto-assumes an unambiguous open
+     * PR's context (issue #700) — falls back to the #403/#469 staging default. */
+    noAutoPr?: boolean;
 }
 declare const PUT_DEFAULT_KEY_MAP: Record<keyof PutDefaults, UploadsConfigKey>;
 export declare function putDefaultsToConfigValues(defaults: PutDefaults): UploadsConfigValues;

package/dist/config-file.js

@@ -17,6 +17,7 @@ export const UPLOADS_CONFIG_KEYS = [
     "UPLOADS_NO_AUTO_META",
     "UPLOADS_SCREENSHOT_VIA",
     "UPLOADS_NO_NUDGE",
+    "UPLOADS_NO_AUTO_PR",
 ];
 const PUT_DEFAULT_KEY_MAP = {
     prefix: "UPLOADS_DEFAULT_PREFIX",
@@ -28,6 +29,7 @@ const PUT_DEFAULT_KEY_MAP = {
     keepExif: "UPLOADS_KEEP_EXIF",
     noAutoMeta: "UPLOADS_NO_AUTO_META",
     noNudge: "UPLOADS_NO_NUDGE",
+    noAutoPr: "UPLOADS_NO_AUTO_PR",
 };
 function isTruthyConfigFlag(value) {
     if (!value)
@@ -55,6 +57,8 @@ export function putDefaultsToConfigValues(defaults) {
         out.UPLOADS_NO_AUTO_META = "1";
     if (defaults.noNudge)
         out.UPLOADS_NO_NUDGE = "1";
+    if (defaults.noAutoPr)
+        out.UPLOADS_NO_AUTO_PR = "1";
     return out;
 }
 function parsePutDefaultsFromRaw(raw) {
@@ -80,6 +84,8 @@ function parsePutDefaultsFromRaw(raw) {
         out.noAutoMeta = true;
     if (isTruthyConfigFlag(raw.UPLOADS_NO_NUDGE))
         out.noNudge = true;
+    if (isTruthyConfigFlag(raw.UPLOADS_NO_AUTO_PR))
+        out.noAutoPr = true;
     return out;
 }
 function parsePutDefaultsFromEnv() {
@@ -102,6 +108,8 @@ function parsePutDefaultsFromEnv() {
         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;
+    if (process.env.UPLOADS_NO_AUTO_PR)
+        raw.UPLOADS_NO_AUTO_PR = process.env.UPLOADS_NO_AUTO_PR;
     return parsePutDefaultsFromRaw(raw);
 }
 /** XDG default shared across buildinternet skills (github-screenshots, uploads, …). */
@@ -175,6 +183,8 @@ export function mergePutDefaults(...layers) {
             out.noAutoMeta = layer.noAutoMeta;
         if (layer.noNudge != null)
             out.noNudge = layer.noNudge;
+        if (layer.noAutoPr != null)
+            out.noAutoPr = layer.noAutoPr;
     }
     return out;
 }

package/dist/github-gh.d.ts

@@ -98,3 +98,30 @@ export declare function upsertAttachmentsComment(target: GhTarget, body: string,
 }): {
     action: "created" | "updated" | "skipped";
 };
+/** Cheap, regex-only reject: no http(s) URL at all means nothing to scan for.
+ * Mirrors `hasLinkCandidate` in apps/api/src/github-link-adopt.ts. */
+export declare function hasLinkCandidate(text: string): boolean;
+/**
+ * Distinct http(s) URLs found in `text`, trailing prose punctuation
+ * stripped, order preserved, first occurrence wins on duplicates. Ported
+ * verbatim from apps/api/src/github-link-adopt.ts's `extractCandidateUrls`
+ * so the two paths recognize the same URL spellings — resolution itself
+ * (storage host / embed host / `/f/` page → key, and the bound-workspace
+ * check) happens server-side inside `POST .../github/attach`, so this file
+ * doesn't need its own copy of that logic.
+ */
+export declare function extractCandidateUrls(text: string): string[];
+/**
+ * Best-effort concatenation of a PR/issue's current body plus every comment's
+ * current body, for link-adoption scanning. Returns "" on any `gh` failure
+ * (not authenticated, network, repo/number not found) — adoption degrades to
+ * a no-op rather than blocking the comment sync it rides along with.
+ *
+ * Unlike the webhook path (which re-scans one specific body/comment ref per
+ * event), the CLI has no per-event ref to key off of — `uploads comment` is
+ * one ad-hoc invocation — so this scans the PR/issue body and every comment
+ * on the thread in one pass every time it runs. That's a documented
+ * divergence: harmless (adoption is idempotent) but does mean a link posted
+ * in comment #1 gets rescanned on every later `uploads comment` run too.
+ */
+export declare function fetchAdoptionCandidateText(target: GhTarget, run: CommandRunner): string;

package/dist/github-gh.js

@@ -344,6 +344,72 @@ function reconcileAfterCreate(target, body, run, marker, createdRaw) {
         return null;
     }
 }
+// --- link adoption (issue #708, local-gh fallback parity with the bot's
+// #701/apps/api/src/github-link-adopt.ts) ---
+/** Cheap, regex-only reject: no http(s) URL at all means nothing to scan for.
+ * Mirrors `hasLinkCandidate` in apps/api/src/github-link-adopt.ts. */
+export function hasLinkCandidate(text) {
+    return /https?:\/\//i.test(text);
+}
+const URL_RE = /https?:\/\/[^\s)"'<>\]]+/gi;
+/**
+ * Distinct http(s) URLs found in `text`, trailing prose punctuation
+ * stripped, order preserved, first occurrence wins on duplicates. Ported
+ * verbatim from apps/api/src/github-link-adopt.ts's `extractCandidateUrls`
+ * so the two paths recognize the same URL spellings — resolution itself
+ * (storage host / embed host / `/f/` page → key, and the bound-workspace
+ * check) happens server-side inside `POST .../github/attach`, so this file
+ * doesn't need its own copy of that logic.
+ */
+export function extractCandidateUrls(text) {
+    const seen = new Set();
+    const out = [];
+    for (const m of text.matchAll(URL_RE)) {
+        const url = m[0].replace(/[.,;:]+$/, "");
+        if (seen.has(url))
+            continue;
+        seen.add(url);
+        out.push(url);
+    }
+    return out;
+}
+/**
+ * Best-effort concatenation of a PR/issue's current body plus every comment's
+ * current body, for link-adoption scanning. Returns "" on any `gh` failure
+ * (not authenticated, network, repo/number not found) — adoption degrades to
+ * a no-op rather than blocking the comment sync it rides along with.
+ *
+ * Unlike the webhook path (which re-scans one specific body/comment ref per
+ * event), the CLI has no per-event ref to key off of — `uploads comment` is
+ * one ad-hoc invocation — so this scans the PR/issue body and every comment
+ * on the thread in one pass every time it runs. That's a documented
+ * divergence: harmless (adoption is idempotent) but does mean a link posted
+ * in comment #1 gets rescanned on every later `uploads comment` run too.
+ */
+export function fetchAdoptionCandidateText(target, run) {
+    let body = "";
+    try {
+        body = run("gh", ["api", `repos/${target.repo}/issues/${target.num}`, "--jq", '.body // ""']);
+    }
+    catch {
+        // Not found / no access — fall through with an empty body; comments may
+        // still be readable.
+    }
+    let comments = "";
+    try {
+        comments = run("gh", [
+            "api",
+            `repos/${target.repo}/issues/${target.num}/comments?per_page=100`,
+            "--paginate",
+            "--jq",
+            '[.[].body] | join("\\n")',
+        ]);
+    }
+    catch {
+        // Same degrade — an empty comments blob just means nothing more to scan.
+    }
+    return `${body}\n${comments}`;
+}
 /** PATCH one comment's body via stdin, so the body is never shell-interpolated. */
 function patchComment(target, run, id, body) {
     run("gh", ["api", `repos/${target.repo}/issues/comments/${id}`, "-X", "PATCH", "-F", "body=@-"], body);

package/dist/mcp/output-schemas.js

@@ -43,6 +43,25 @@ const promoteResultSchema = objectSchema({
         ]),
     },
 }, ["promoted", "skipped"]);
+/** Hosted `promote` tool's `attached[]` entry (issue #702, `AttachExistingResponse`). */
+const attachExistingResultSchema = objectSchema({
+    key: { type: "string" },
+    url: nullableString,
+    embedUrl: nullableString,
+    pageUrl: { type: "string" },
+    moved: { type: "boolean" },
+    source: objectSchema({ key: { type: "string" } }, ["key"]),
+    comment: commentResultSchema,
+}, ["key", "url", "embedUrl", "moved", "source", "comment"]);
+/** Hosted `promote` tool's `attachFailures[]` entry — one per bad `keys` source. */
+const attachFailureSchema = objectSchema({
+    key: { type: "string" },
+    error: objectSchema({
+        message: { type: "string" },
+        code: { type: "string" },
+        status: { type: "number" },
+    }, ["message"]),
+}, ["key", "error"]);
 const putObjectFields = {
     key: { type: "string" },
     url: nullableString,
@@ -209,10 +228,14 @@ export const healthResultSchema = objectSchema({
     apiUrl: { type: "string" },
 });
 export const promoteToolResultSchema = objectSchema({
+    // `promotion` is optional (issue #702): a `keys`-only call (no `branch`)
+    // never runs the branch sweep, so there's nothing to report under it.
     promotion: promoteResultSchema,
+    attached: { type: "array", items: attachExistingResultSchema },
+    attachFailures: { type: "array", items: attachFailureSchema },
     comment: commentResultSchema,
     commentError: { type: "string" },
-}, ["promotion"]);
+});
 const galleryItemSchema = objectSchema({
     id: { type: "string" },
     objectKey: { type: "string" },

package/dist/mcp/tools.js

@@ -1,5 +1,5 @@
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveGhPrefixSafe, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
+import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeStagingMeta, resolveAutoPrTarget, resolveGhPrefixSafe, resolvePutNudgeContext, resolvePutStagingTarget, resolveStaged, syncAttachmentsComment, autoPrNoteText, putNudgeText, uploadAttachments, uploadPreparedImage, uploadPuts, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
@@ -345,9 +345,13 @@ export function createUploadsMcpTools(opts) {
                     },
                     ...frameProps,
                     noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
+                    noPr: {
+                        type: "boolean",
+                        description: "Skip auto-PR context (issue #700): without pr/issue/key/ref/prefix/destination, a call on a branch mapping to exactly one open PR otherwise behaves as if pr had been passed (stable key + managed comment sync when comment is set). Also opts out via UPLOADS_NO_AUTO_PR=1.",
+                    },
                     comment: {
                         type: "boolean",
-                        description: "With pr/issue: create or update the managed attachments comment. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth (best-effort).",
+                        description: "With pr/issue (or auto-detected PR context): create or update the managed attachments comment. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth (best-effort).",
                     },
                     dryRun: {
                         type: "boolean",
@@ -431,16 +435,39 @@ export function createUploadsMcpTools(opts) {
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
                 const noGit = optBool(args, "noGit") || defaults.noGit === true;
+                const noAutoPr = optBool(args, "noPr") || defaults.noAutoPr === true;
                 const alt = optString(args, "alt");
                 const width = optPosInt(args, "width") ?? defaults.width;
                 const contentType = optString(args, "contentType");
+                // Auto-PR context (issue #700): local stdio MCP put mirrors the CLI
+                // default — no pr/issue/key/ref/prefix/destination, not noGit/noPr,
+                // on a branch that maps to exactly one open PR behaves as if `pr`
+                // had been passed (stable key + managed comment sync) instead of
+                // the #403 staging default below. Never throws — see
+                // resolveAutoPrTarget.
+                const autoPrTarget = target
+                    ? undefined
+                    : resolveAutoPrTarget({
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        refArg,
+                        prefixArg,
+                        destinationArg: destArg,
+                        noGit,
+                        noAutoPr,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const effectiveTarget = target ?? autoPrTarget;
                 // 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.
+                // effectiveTarget (explicit pr/issue OR the #700 auto-PR match)
+                // wins over staging, same as it wins over the dated layout.
                 const stagingTarget = resolvePutStagingTarget({
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     keyHint: keyArg,
                     refArg,
                     prefixArg,
@@ -449,6 +476,21 @@ export function createUploadsMcpTools(opts) {
                     repoArg: optString(args, "repo") ?? defaults.repo,
                     run,
                 });
+                // Bare-put nudge context (issue #393/#700): only relevant when
+                // neither auto-PR nor staging took over. Finished into a hint once
+                // upload keys exist, below.
+                const nudgeCtx = effectiveTarget || stagingTarget
+                    ? undefined
+                    : resolvePutNudgeContext({
+                        quiet: false,
+                        noNudge: defaults.noNudge === true,
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        noGit,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const autoPrHint = autoPrTarget ? autoPrNoteText(autoPrTarget.num) : undefined;
                 // Derived `repo` metadata (spec: 2026-08-11-screenshots-project-grouping-design.md).
                 // Same derivation the CLI does; MCP always derives (no --no-auto), so
                 // this is only suppressed by noGit. metadataProp's contract: omitting
@@ -468,7 +510,7 @@ export function createUploadsMcpTools(opts) {
                     : metadataWithRepo;
                 const putShared = {
                     client,
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     ghBranchTarget: stagingTarget,
                     prefix: resolvedPrefix ?? defaults.prefix,
                     repo: optString(args, "repo") ?? defaults.repo,
@@ -496,11 +538,15 @@ export function createUploadsMcpTools(opts) {
                     if (uploads.length === 0 && failures.length > 0) {
                         throw new ToolBatchError(batchFailureMessage(failures), { uploads, failures });
                     }
-                    if (wantComment && target && uploads.length > 0) {
-                        const { comment, commentError } = await syncComment(client, target, config.workspace);
-                        return { uploads, failures, comment, commentError };
+                    const hint = autoPrHint ??
+                        (nudgeCtx && uploads.length > 0
+                            ? putNudgeText(nudgeCtx.branch, nudgeCtx.pr, uploads.map((u) => u.key))
+                            : undefined);
+                    if (wantComment && effectiveTarget && uploads.length > 0) {
+                        const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
+                        return { uploads, failures, comment, commentError, ...(hint ? { hint } : {}) };
                     }
-                    return { uploads, failures };
+                    return { uploads, failures, ...(hint ? { hint } : {}) };
                 }
                 // Single-file: contentBase64 still supported; paths go through uploadPuts.
                 if (contentBase64 !== undefined) {
@@ -509,7 +555,7 @@ export function createUploadsMcpTools(opts) {
                     const { result, prepared, markdown } = await uploadPreparedImage(client, bytes, sourceName, {
                         frame: frameOpts,
                         optimize: optimizeOpts,
-                        ghTarget: target,
+                        ghTarget: effectiveTarget,
                         ghBranchTarget: stagingTarget,
                         key: keyArg,
                         prefix: resolvedPrefix ?? defaults.prefix,
@@ -531,9 +577,19 @@ export function createUploadsMcpTools(opts) {
                         outputBytes: prepared.outputBytes,
                         filename: prepared.filename,
                     };
-                    if (wantComment && target) {
-                        const { comment, commentError } = await syncComment(client, target, config.workspace);
-                        return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
+                    const hint = autoPrHint ??
+                        (nudgeCtx ? putNudgeText(nudgeCtx.branch, nudgeCtx.pr, [result.key]) : undefined);
+                    if (wantComment && effectiveTarget) {
+                        const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
+                        return {
+                            ...result,
+                            markdown,
+                            optimize,
+                            frame: prepared.frame,
+                            comment,
+                            commentError,
+                            ...(hint ? { hint } : {}),
+                        };
                     }
                     return {
                         ...result,
@@ -541,6 +597,7 @@ export function createUploadsMcpTools(opts) {
                         optimize,
                         frame: prepared.frame,
                         ...(dryRun ? { dryRun: true } : {}),
+                        ...(hint ? { hint } : {}),
                     };
                 }
                 const { uploads, failures, firstError } = await uploadPuts({
@@ -553,6 +610,8 @@ export function createUploadsMcpTools(opts) {
                     throw firstError instanceof Error ? firstError : new Error(String(firstError));
                 }
                 const u = uploads[0];
+                const hint = autoPrHint ??
+                    (nudgeCtx ? putNudgeText(nudgeCtx.branch, nudgeCtx.pr, [u.key]) : undefined);
                 const flat = {
                     workspace: u.workspace,
                     key: u.key,
@@ -566,9 +625,10 @@ export function createUploadsMcpTools(opts) {
                     optimize: u.optimize,
                     frame: u.frame,
                     ...(dryRun ? { dryRun: true } : {}),
+                    ...(hint ? { hint } : {}),
                 };
-                if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target, config.workspace);
+                if (wantComment && effectiveTarget) {
+                    const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;
@@ -673,9 +733,13 @@ export function createUploadsMcpTools(opts) {
                     keepExif: { type: "boolean", description: "Keep EXIF/XMP/ICC when optimizing." },
                     ...frameProps,
                     noGit: { type: "boolean", description: "Don't derive the repo segment from git." },
+                    noPr: {
+                        type: "boolean",
+                        description: "Skip auto-PR context (issue #700): without pr/issue/key/ref/prefix/destination, a call on a branch mapping to exactly one open PR otherwise behaves as if pr had been passed. Also opts out via UPLOADS_NO_AUTO_PR=1.",
+                    },
                     comment: {
                         type: "boolean",
-                        description: "With pr/issue: create/update the managed attachments comment (best-effort).",
+                        description: "With pr/issue (or auto-detected PR context): create/update the managed attachments comment (best-effort).",
                     },
                     galleryId: {
                         type: "string",
@@ -741,16 +805,38 @@ export function createUploadsMcpTools(opts) {
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
                 const noGit = optBool(args, "noGit") || defaults.noGit === true;
+                const noAutoPr = optBool(args, "noPr") || defaults.noAutoPr === true;
                 const alt = optString(args, "alt");
                 const width = optPosInt(args, "width") ?? defaults.width;
+                // Auto-PR context (issue #700): mirrors the CLI screenshot command
+                // and the put tool above — no pr/issue/key/ref/prefix/destination,
+                // not noGit/noPr, on a branch that maps to exactly one open PR
+                // behaves as if `pr` had been passed (stable key + managed comment
+                // sync) instead of the #469 auto-staging default below. Never
+                // throws — see resolveAutoPrTarget.
+                const autoPrTarget = target
+                    ? undefined
+                    : resolveAutoPrTarget({
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        refArg,
+                        prefixArg,
+                        destinationArg: destArg,
+                        noGit,
+                        noAutoPr,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const effectiveTarget = target ?? autoPrTarget;
                 // Auto branch staging (issue #469 lever 1): mirrors the CLI screenshot
                 // command and the put tool above (issue #403) — 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 `screenshots/<repo>/<date>/...` layout. Never
-                // throws — see resolvePutStagingTarget.
+                // throws — see resolvePutStagingTarget. effectiveTarget (explicit
+                // pr/issue OR the #700 auto-PR match) wins over staging.
                 const stagingTarget = resolvePutStagingTarget({
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     keyHint: keyArg,
                     refArg,
                     prefixArg,
@@ -759,13 +845,27 @@ export function createUploadsMcpTools(opts) {
                     repoArg: optString(args, "repo") ?? defaults.repo,
                     run,
                 });
+                // Bare-screenshot nudge context (issue #393/#700): only relevant
+                // when neither auto-PR nor staging took over.
+                const nudgeCtx = effectiveTarget || stagingTarget
+                    ? undefined
+                    : resolvePutNudgeContext({
+                        quiet: false,
+                        noNudge: defaults.noNudge === true,
+                        ghTarget: target,
+                        keyHint: keyArg,
+                        noGit,
+                        repoArg: optString(args, "repo") ?? defaults.repo,
+                        run,
+                    });
+                const autoPrHint = autoPrTarget ? autoPrNoteText(autoPrTarget.num) : undefined;
                 let resolvedPrefix;
                 try {
                     resolvedPrefix = resolvePutPrefix({
                         destination: destArg,
                         prefix: prefixArg,
                         key: keyArg,
-                        ghAttachment: Boolean(target) || stagingTarget !== undefined,
+                        ghAttachment: Boolean(effectiveTarget) || stagingTarget !== undefined,
                     });
                 }
                 catch (err) {
@@ -837,10 +937,10 @@ export function createUploadsMcpTools(opts) {
                 }
                 // Resolved once (issue #631), only now that upload is actually
                 // about to happen — never per file (screenshot uploads exactly one).
-                const ghPrefix = target
+                const ghPrefix = effectiveTarget
                     ? await resolveGhPrefixSafe(client, {
-                        repo: target.repo,
-                        target: { kind: target.kind, num: target.num },
+                        repo: effectiveTarget.repo,
+                        target: { kind: effectiveTarget.kind, num: effectiveTarget.num },
                     })
                     : stagingTarget
                         ? await resolveGhPrefixSafe(client, {
@@ -851,7 +951,7 @@ export function createUploadsMcpTools(opts) {
                 const { result, prepared, markdown } = await uploadPreparedImage(client, captured.png, captured.filename, {
                     frame: frameOpts,
                     optimize: optimizeOpts,
-                    ghTarget: target,
+                    ghTarget: effectiveTarget,
                     ghBranchTarget: stagingTarget,
                     ghPrefix,
                     key: keyArg,
@@ -897,14 +997,19 @@ export function createUploadsMcpTools(opts) {
                     frame: prepared.frame,
                     gallery,
                     ...(dryRun ? { dryRun: true } : {}),
-                    // Full-page height cap note (issue #652), mirrors the CLI's stderr
-                    // note + `hint` field.
+                    // Hint precedence (mirrors the CLI): the full-page height cap note
+                    // (issue #652) is about the just-captured image itself, more
+                    // immediately actionable than the #700 auto-PR/nudge notes below.
                     ...(captured.capped?.clipped
                         ? { hint: screenshotModule.clipHintText(captured.capped.maxHeightPx, "maxHeight") }
-                        : {}),
+                        : autoPrHint
+                            ? { hint: autoPrHint }
+                            : nudgeCtx
+                                ? { hint: putNudgeText(nudgeCtx.branch, nudgeCtx.pr, [result.key]) }
+                                : {}),
                 };
-                if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target, config.workspace);
+                if (wantComment && effectiveTarget) {
+                    const { comment, commentError } = await syncComment(client, effectiveTarget, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;

package/package.json

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