@buildinternet/uploads 0.14.0 → 0.15.0

package/dist/cli-catalog.js

@@ -25,6 +25,7 @@ export const PUT_LIKE_FLAGS = [
     "--ref",
     "--pr",
     "--issue",
+    "--branch",
     "--comment",
     "--no-comment",
     "--format",
@@ -75,6 +76,7 @@ export const SCREENSHOT_FLAGS = [
     "--no-git",
     "--pr",
     "--issue",
+    "--branch",
     "--comment",
     "--gallery",
     "--meta",
@@ -131,6 +133,11 @@ export const ROOT_COMMANDS = [
         name: "comment",
         summary: "Create/update a PR/issue attachments comment (via gh)",
     },
+    {
+        name: "github",
+        summary: "Claim/inspect this workspace's binding to a GitHub repo",
+        subcommands: [{ name: "link", summary: "Claim or inspect the repo binding" }],
+    },
     {
         name: "list",
         summary: "List objects (--meta k=v filters by queryable metadata)",

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, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { runPut, runAttach, 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";
@@ -278,7 +278,8 @@ export async function runCli(argv) {
             case "reconcile":
             case "purge-expired":
             case "doctor":
-            case "comment": {
+            case "comment":
+            case "github": {
                 const ctx = createContext(parsed.globals, !showHelp, cmdArgs);
                 switch (parsed.command) {
                     case "attach":
@@ -296,6 +297,9 @@ export async function runCli(argv) {
                     case "comment":
                         code = await runComment(ctx, cmdArgs, showHelp);
                         break;
+                    case "github":
+                        code = await runGithub(ctx, cmdArgs, showHelp);
+                        break;
                     case "list":
                         code = await runList(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -73,6 +73,8 @@ export interface ListItem {
     key: string;
     url: string | null;
     embedUrl?: string | null;
+    /** Canonical `/f/` page URL when the API provides it. Absent on older API deployments. */
+    pageUrl?: string;
     size?: number;
     uploaded?: string;
 }
@@ -180,7 +182,36 @@ export type GithubCommentResult = {
 } | {
     posted: false;
     reason: GithubCommentDeclineReason;
+    message?: string;
+    fixUrl?: string;
+    required?: string[];
 };
+/** `POST /v1/:workspace/github/promote` request/response (server contract, PR #310). */
+export interface PromoteBranchAttachmentsOptions {
+    repo: string;
+    num: number;
+    branch: string;
+}
+export interface PromoteSkip {
+    key: string;
+    reason: string;
+}
+export interface PromoteBranchAttachmentsResult {
+    promoted: string[];
+    skipped: PromoteSkip[];
+}
+/** `GET`/`POST /v1/:workspace/github/link` result (server contract, phase 4b). */
+export interface GithubLinkResult {
+    repo: string;
+    linked: boolean;
+    workspace: string | null;
+    source: string | null;
+    createdAt: string | null;
+}
+/** POST-only: whether THIS call's workspace ended up owning the binding. */
+export interface GithubLinkClaimResult extends GithubLinkResult {
+    claimed: boolean;
+}
 export interface HealthResult {
     ok: boolean;
 }
@@ -412,6 +443,25 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         num: number;
         kind: "pull" | "issues";
     }): Promise<GithubCommentResult>;
+    /**
+     * Promote a workspace's branch-staged attachments into a PR's stable
+     * attachment prefix (server contract, PR #310 — degrade-safe callers
+     * treat any failure, including a 404 from an older/self-hosted worker
+     * that doesn't have this route yet, as "nothing promoted").
+     */
+    promoteBranchAttachments(opts: PromoteBranchAttachmentsOptions): Promise<PromoteBranchAttachmentsResult>;
+    /** Current binding for `repo`, or `{ linked: false }` if unclaimed. Throws
+     * `UploadsError` (status 404) on an older/self-hosted server without this
+     * route — callers treat that as "bindings unsupported". */
+    githubLinkStatus(repo: string): Promise<GithubLinkResult>;
+    /**
+     * Explicitly claim `repo` for this workspace (first-claim-wins — see
+     * github-repo-links.ts server-side). `claimed: false` in the result means
+     * the repo is already bound to a DIFFERENT workspace; this call never
+     * steals it. Throws `UploadsError` (status 404) on an older/self-hosted
+     * server without this route.
+     */
+    githubLinkClaim(repo: string): Promise<GithubLinkClaimResult>;
     health(): Promise<HealthResult>;
     /** Workspace storage / upload counters (+ limits when configured). */
     usage(): Promise<UsageResult>;

package/dist/client.js

@@ -458,6 +458,37 @@ export function createUploadsClient(config) {
                 headers: { "Content-Type": "application/json" },
             });
         },
+        /**
+         * Promote a workspace's branch-staged attachments into a PR's stable
+         * attachment prefix (server contract, PR #310 — degrade-safe callers
+         * treat any failure, including a 404 from an older/self-hosted worker
+         * that doesn't have this route yet, as "nothing promoted").
+         */
+        async promoteBranchAttachments(opts) {
+            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/promote`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        /** Current binding for `repo`, or `{ linked: false }` if unclaimed. Throws
+         * `UploadsError` (status 404) on an older/self-hosted server without this
+         * route — callers treat that as "bindings unsupported". */
+        async githubLinkStatus(repo) {
+            return request("GET", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link?repo=${encodeURIComponent(repo)}`);
+        },
+        /**
+         * Explicitly claim `repo` for this workspace (first-claim-wins — see
+         * github-repo-links.ts server-side). `claimed: false` in the result means
+         * the repo is already bound to a DIFFERENT workspace; this call never
+         * steals it. Throws `UploadsError` (status 404) on an older/self-hosted
+         * server without this route.
+         */
+        async githubLinkClaim(repo) {
+            return request("POST", `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/github/link`, {
+                body: new TextEncoder().encode(JSON.stringify({ repo })),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
         async health() {
             return request("GET", `${config.apiUrl}/health`, { auth: false });
         },

package/dist/commands/screenshot.js

@@ -2,11 +2,12 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { basename } from "node:path";
 import { flagBool, flagInt, flagString, flagValues, parseCommandArgs, UsageError, } from "../cli-args.js";
 import { writeCommandHelp } from "../cli-style.js";
-import { frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
+import { branchFromFlags, frameOptionsFromFlags, ghTargetFromFlags, optimizeOptionsFromFlags, syncAttachmentsComment, commentViaSuffix, uploadPreparedImage, } from "../commands.js";
 import { resolvePutDefaults } from "../config.js";
 import { loadDefaultsRaw, resolveScreenshotDefaults } from "../config-file.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { execRunner, ghMetadataFromTargetWithTitle } from "../github-gh.js";
+import { execRunner, ghMetadataFromTargetWithTitle, resolveRepo, } from "../github-gh.js";
+import { ghBranchAttachmentKey, ghMetadataForBranch } from "../github.js";
 import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { writeJson, writeStdout } from "../io.js";
 import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
@@ -66,6 +67,11 @@ Options:
   --keep-exif               Keep EXIF/XMP/ICC when optimizing
   --pr <num>                Attach to a pull request (stable URL, no hash)
   --issue <num>             Attach to an issue
+  --branch [name]           Stage against a branch, pre-PR (default: current git branch):
+                             key gh/<owner>/<repo>/branch/<branch>/<name>; not with
+                             --pr/--issue/--comment/--key/--ref/--prefix. No managed
+                             comment exists yet — promoting into the PR's comment once
+                             one opens ships in a later phase.
   --comment                 With --pr/--issue: update the managed attachments comment.
                              Posts as uploads-sh[bot] when the GitHub App is installed;
                              otherwise via local gh.
@@ -84,6 +90,7 @@ Examples:
   uploads screenshot http://localhost:3000 --via local --full-page
   uploads screenshot https://uploads.sh --pr 128 --comment
   uploads screenshot ./card.html --no-upload --out ./card.png
+  uploads screenshot https://app.example/settings --branch
 `;
 function colorSchemeFromFlags(flags) {
     const dark = flagBool(flags, "--dark");
@@ -164,9 +171,13 @@ captureImpl = captureScreenshot) {
     const destFlag = flagString(parsed.flags, "--destination");
     const prefixFlag = flagString(parsed.flags, "--prefix");
     const ghTarget = ghTargetFromFlags(parsed.flags, run);
+    const branchArg = branchFromFlags(parsed.flags, run);
     const wantComment = parsed.flags.has("--comment");
     const galleryId = flagString(parsed.flags, "--gallery");
     const dryRun = flagBool(parsed.flags, "--dry-run");
+    if (branchArg !== undefined && ghTarget) {
+        throw new UsageError("--branch cannot be combined with --pr/--issue");
+    }
     if (wantComment && !ghTarget)
         throw new UsageError("--comment requires --pr or --issue");
     if (ghTarget) {
@@ -177,6 +188,16 @@ captureImpl = captureScreenshot) {
         if (prefixFlag)
             throw new UsageError("--prefix cannot be combined with --pr/--issue");
     }
+    if (branchArg !== undefined) {
+        if (wantComment)
+            throw new UsageError("--branch cannot be combined with --comment");
+        if (keyHint)
+            throw new UsageError("--key cannot be combined with --branch");
+        if (flagString(parsed.flags, "--ref"))
+            throw new UsageError("--ref cannot be combined with --branch");
+        if (prefixFlag)
+            throw new UsageError("--prefix cannot be combined with --branch");
+    }
     if (dryRun) {
         if (wantComment)
             throw new UsageError("--dry-run cannot be combined with --comment");
@@ -185,13 +206,14 @@ captureImpl = captureScreenshot) {
         if (noUpload)
             throw new UsageError("--dry-run cannot be combined with --no-upload");
     }
+    const branchRepo = branchArg !== undefined ? resolveRepo(flagString(parsed.flags, "--repo"), run) : undefined;
     let resolvedPrefix;
     try {
         resolvedPrefix = resolvePutPrefix({
             destination: destFlag,
             prefix: prefixFlag,
             key: keyHint,
-            ghAttachment: Boolean(ghTarget),
+            ghAttachment: Boolean(ghTarget) || branchArg !== undefined,
         });
     }
     catch (err) {
@@ -218,6 +240,10 @@ captureImpl = captureScreenshot) {
         metadata = { ...metaExtras, ...ghMetadataFromTargetWithTitle(ghTarget, run) };
         validateMetaMap(metadata);
     }
+    else if (branchArg !== undefined) {
+        metadata = { ...metaExtras, ...ghMetadataForBranch(branchRepo, branchArg) };
+        validateMetaMap(metadata);
+    }
     else if (Object.keys(metaExtras).length > 0) {
         validateMetaMap(metaExtras);
     }
@@ -260,12 +286,15 @@ captureImpl = captureScreenshot) {
     }
     const repo = flagString(parsed.flags, "--repo") ?? putDefaults.repo;
     const ref = flagString(parsed.flags, "--ref") ?? putDefaults.ref;
+    const branchKey = branchArg !== undefined
+        ? ghBranchAttachmentKey(branchRepo, branchArg, captured.filename)
+        : undefined;
     const alt = altFlag ?? basename(captured.filename);
     const { result, prepared, markdown } = await uploadPreparedImage(ctx.client, captured.png, captured.filename, {
         frame: frameOpts,
         optimize: optimizeOpts,
         ghTarget,
-        key: keyHint,
+        key: keyHint ?? branchKey,
         prefix: resolvedPrefix ?? putDefaults.prefix,
         repo,
         ref,
@@ -295,7 +324,7 @@ captureImpl = captureScreenshot) {
     let commentError;
     if (wantComment && ghTarget) {
         try {
-            comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
+            comment = await syncAttachmentsComment(ctx.client, ghTarget, run, ctx.config.workspace);
             if (logHuman)
                 process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }

package/dist/commands.d.ts

@@ -28,6 +28,14 @@ export declare function readFileArg(fileArg: string): Uint8Array;
 export declare function makeGhTarget(pr: number | undefined, issue: number | undefined, repoArg: string | undefined, run: CommandRunner): GhTarget | undefined;
 /** Reads --pr/--issue (+ --repo) into a GhTarget; undefined when neither flag is present. */
 export declare function ghTargetFromFlags(flags: CommandFlags["flags"], run: CommandRunner): GhTarget | undefined;
+/**
+ * Reads `--branch [name]` — an optional-value flag: `--branch` alone resolves
+ * the current git branch (`resolveCurrentBranch`); `--branch feature/x` uses
+ * the given name verbatim. Returns undefined when the flag is absent at all
+ * (distinct from an empty/whitespace value, which is rejected). Throws
+ * UsageError if `--branch` is given more than once.
+ */
+export declare function branchFromFlags(flags: CommandFlags["flags"], run: CommandRunner): string | undefined;
 /** Shared put/attach optimize flags + UPLOADS_NO_OPTIMIZE default. */
 export declare function optimizeOptionsFromFlags(flags: CommandFlags["flags"], defaults: PutDefaults): OptimizeImageOptions;
 export type PreparedUpload = OptimizeImageResult & {
@@ -104,7 +112,7 @@ export interface AttachmentsCommentResult {
 }
 /** Human-mode suffix noting who posted the managed comment. */
 export declare function commentViaSuffix(via: AttachmentsCommentResult["via"]): string;
-export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner): Promise<AttachmentsCommentResult>;
+export declare function syncAttachmentsComment(client: UploadsClient, target: GhTarget, run: CommandRunner, workspace?: string): Promise<AttachmentsCommentResult>;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -150,6 +158,37 @@ export declare function uploadAttachments(opts: {
     failures: AttachFailure[];
     firstError?: unknown;
 }>;
+/** A branch to stage attachments against pre-PR (`uploads attach --branch`). */
+export interface BranchTarget {
+    repo: string;
+    branch: string;
+}
+/**
+ * Prepare + put each path as a branch-staged attachment (pre-PR) with
+ * bounded concurrency. Same shape as `uploadAttachments`, keyed under
+ * `gh/<owner>/<repo>/branch/<branch>/<filename>` instead of a PR/issue
+ * number. Never syncs the managed comment — callers must not call
+ * `syncAttachmentsComment` for a branch target.
+ */
+export declare function uploadBranchAttachments(opts: {
+    client: UploadsClient;
+    target: BranchTarget;
+    files: readonly string[];
+    contentType?: string;
+    optimize: OptimizeImageOptions;
+    frame: {
+        frameId?: string;
+        frameUrl?: string;
+        frameFit?: "cover" | "contain";
+    };
+    metadata?: Record<string, string>;
+    provenanceClient?: string;
+    concurrency?: number;
+}): Promise<{
+    uploads: AttachUploadItem[];
+    failures: AttachFailure[];
+    firstError?: unknown;
+}>;
 export type PutUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -199,6 +238,7 @@ export declare function runFind(ctx: CliContext, args: string[], help?: boolean)
 export declare function runMeta(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runDelete(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runComment(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
+export declare function runGithub(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 export declare function runUsage(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runReconcile(ctx: CliContext, args: string[], help?: boolean): Promise<number>;
 export declare function runPurgeExpired(ctx: CliContext, args: string[], help?: boolean): Promise<number>;

package/dist/commands.js

@@ -9,8 +9,8 @@ import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
 import { writeJson, writeStdout } from "./io.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
-import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, attachmentsCommentBody, normalizeGithubCoordinate, } from "./github.js";
-import { resolveRepo, resolveCurrentPullRequest, classifyGhNumber, execRunner, ghMetadataFromTargetWithTitle, upsertAttachmentsComment, } from "./github-gh.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 { resolvePutPrefix } from "./destinations.js";
 import { optimizeImageForUpload, rewriteKeyExtension, } from "./optimize.js";
 import { applyFrame, resolveFrameId } from "./frame.js";
@@ -130,6 +130,25 @@ export function makeGhTarget(pr, issue, repoArg, run) {
 export function ghTargetFromFlags(flags, run) {
     return makeGhTarget(flagInt(flags, "--pr", "--pr"), flagInt(flags, "--issue", "--issue"), flagString(flags, "--repo"), run);
 }
+/**
+ * Reads `--branch [name]` — an optional-value flag: `--branch` alone resolves
+ * the current git branch (`resolveCurrentBranch`); `--branch feature/x` uses
+ * the given name verbatim. Returns undefined when the flag is absent at all
+ * (distinct from an empty/whitespace value, which is rejected). Throws
+ * UsageError if `--branch` is given more than once.
+ */
+export function branchFromFlags(flags, run) {
+    if (!flags.has("--branch"))
+        return undefined;
+    const raw = flags.get("--branch");
+    if (Array.isArray(raw))
+        throw new UsageError("--branch may only be given once");
+    if (raw === true)
+        return resolveCurrentBranch(run);
+    if (typeof raw === "string" && raw.trim().length > 0)
+        return raw;
+    throw new UsageError("--branch requires a non-empty branch name");
+}
 /**
  * Best-effort GitHub target for the default put path (no --pr/--issue). A
  * numeric --ref is classified as pull vs issue; otherwise the current branch's
@@ -278,7 +297,7 @@ export function frameOptionsFromFlags(flags) {
 export function commentViaSuffix(via) {
     return via === "bot" ? " (uploads-sh[bot])" : " (via gh)";
 }
-export async function syncAttachmentsComment(client, target, run) {
+export async function syncAttachmentsComment(client, target, run, workspace) {
     try {
         const bot = await client.upsertGithubComment({
             repo: target.repo,
@@ -287,13 +306,24 @@ export async function syncAttachmentsComment(client, target, run) {
         });
         if (bot.posted)
             return { action: bot.action, count: bot.count, via: "bot" };
+        // Installed-but-unapproved is a fixable misconfiguration, not a silent
+        // degrade: tell the user (and how to fix it) before falling back to gh.
+        if (bot.reason === "forbidden" && bot.message) {
+            process.stderr.write(`note: ${bot.message}${bot.fixUrl ? `\n  ${bot.fixUrl}` : ""}\n` +
+                `Posting via local gh in the meantime.\n`);
+        }
     }
     catch {
         // Endpoint absent/unreachable (self-hosted, network, older worker) — fall
         // through to the gh path below.
     }
     // gh fallback: gather from this workspace's own data and post via local `gh`.
-    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl }) => ({ key, url, embedUrl }));
+    // Note (issue #304): this CLI process has no server-side WorkspaceRecord in
+    // scope, so it cannot honor a workspace's githubCommentLinkToFilePage=false
+    // — it always links to the file page here, matching the default. This only
+    // diverges from the bot-posted comment for a workspace that both sets the
+    // flag false and falls through to this gh-fallback path.
+    const items = (await client.listAll({ prefix: ghKeyPrefix(target) })).map(({ key, url, embedUrl, pageUrl }) => ({ key, url, embedUrl, pageUrl }));
     const galleries = [];
     let cursor;
     do {
@@ -329,8 +359,9 @@ export async function syncAttachmentsComment(client, target, run) {
     }));
     if (items.length === 0 && previewGalleries.length === 0)
         return { action: "skipped", count: 0, via: "gh" };
-    const body = attachmentsCommentBody(items, previewGalleries);
-    const { created } = upsertAttachmentsComment(target, body, run);
+    const marker = attachmentsMarker(workspace);
+    const body = attachmentsCommentBody(items, previewGalleries, marker);
+    const { created } = upsertAttachmentsComment(target, body, run, marker);
     return {
         action: created ? "created" : "updated",
         count: items.length + previewGalleries.length,
@@ -357,9 +388,37 @@ URL and every embed hot-swap. Human mode prints ">> replaced existing object
 Still images are optimized to WebP by default (same as put). Use --no-optimize
 to upload originals. Optional --frame wraps images in device/browser chrome.
 
+Branch staging (pre-PR): --branch [name] stages files against a git branch
+before a pull request exists, e.g. for a coding agent working a branch that
+hasn't opened a PR yet. Key: gh/<owner>/<repo>/branch/<branch>/<filename>
+("/" in the branch name sanitizes to "-", e.g. feature/x -> feature-x).
+With no value, --branch resolves the current git branch. Staged files are
+public like every other attachment — same public-URL caveat applies. There is
+no managed comment for a branch (no PR/issue to comment on yet); --branch
+never runs the comment sync and cannot combine with --pr/--issue/--comment.
+
+Promotion: once a PR exists, staged files for the current branch are picked
+up automatically the first time you attach to that PR (a plain "uploads
+attach <file> --pr <num>", or the inferred-PR default with no target flags) —
+they're copied into the PR's attachment prefix before the managed comment is
+built, so they show up in the same run. Pass --no-promote to skip that. If
+you'd rather promote without attaching a new file (e.g. right after
+"gh pr create" with nothing new to upload), run "uploads attach --promote"
+with no file arguments — it resolves the PR the same way, promotes, and
+refreshes the comment; it exits 0 even if nothing was staged. --promote only
+takes effect with zero files and cannot combine with --branch/--issue/
+--no-promote. Promotion never applies to issues. Staged files stay findable
+with "uploads find gh.branch=<branch>" either way.
+
 Options:
   --pr <num>            Attach to this pull request
   --issue <num>         Attach to this issue
+  --branch [name]       Stage against a branch, pre-PR (default: current git branch);
+                        not with --pr/--issue/--comment
+  --promote             No files: promote branch-staged attachments into the
+                        resolved PR and refresh the comment; not with
+                        --branch/--issue/--no-promote
+  --no-promote          Skip auto-promoting branch-staged attachments (default path only)
   --repo <owner/repo>   Repository (default: gh/git inference)
   --no-comment          Upload only; don't create/update the managed comment
   --content-type <mime> Override Content-Type (applied to every file; ignored when optimize rewrites)
@@ -373,7 +432,8 @@ Options:
   --workspace, -w <name>  Override workspace
   --meta <k=v>          Extra queryable metadata (repeatable; value may contain "=").
                         gh.repo/gh.kind/gh.number/gh.ref are always set from the resolved
-                        target — a --meta pair with the same key is overridden by it.
+                        target (or gh.repo/gh.kind/gh.branch/gh.staged-at with --branch) —
+                        a --meta pair with the same key is overridden by it.
                         Because attach always sends its own gh.* pairs, re-attaching to
                         the same key always replaces that file's entire metadata set
                         (never preserves) — use "uploads meta set" to add to it instead.
@@ -384,13 +444,17 @@ Examples:
   uploads attach ./shot.png --pr 123 --repo myorg/myapp
   uploads attach ./artifact.zip --issue 45 --no-comment
   uploads attach ./shot.png --meta app=myapp --meta page=settings
+  uploads attach ./shot.png --branch
+  uploads attach ./shot.png --branch feature/new-settings
+  uploads attach --promote
 `;
 /**
- * Prepare + put each path as a PR/issue attachment with bounded concurrency.
- * Per-file errors collect in `failures` (does not throw). `firstError` is the
+ * Shared prepare + put loop for both PR/issue attach (`uploadAttachments`)
+ * and branch-staged attach (`uploadBranchAttachments`) — bounded concurrency,
+ * per-file errors collect in `failures` (does not throw). `firstError` is the
  * original cause of the first failure — for rethrowing single-file CLI paths.
  */
-export async function uploadAttachments(opts) {
+async function uploadAttachmentBatch(opts) {
     if (opts.files.some((f) => f === "-")) {
         throw new UsageError("attach does not support stdin; pass one or more file paths");
     }
@@ -403,7 +467,7 @@ export async function uploadAttachments(opts) {
             });
             const result = await opts.client.put(prepared.bytes, {
                 filename: prepared.filename,
-                key: ghAttachmentKey(opts.target, prepared.filename),
+                key: opts.keyFor(prepared.filename),
                 contentType: prepared.optimized ? prepared.contentType : opts.contentType,
                 provenance: buildCliProvenance({
                     sourceName,
@@ -450,6 +514,30 @@ export async function uploadAttachments(opts) {
     }
     return { uploads, failures, firstError };
 }
+/**
+ * Prepare + put each path as a PR/issue attachment with bounded concurrency.
+ * Per-file errors collect in `failures` (does not throw). `firstError` is the
+ * original cause of the first failure — for rethrowing single-file CLI paths.
+ */
+export async function uploadAttachments(opts) {
+    return uploadAttachmentBatch({
+        ...opts,
+        keyFor: (filename) => ghAttachmentKey(opts.target, filename),
+    });
+}
+/**
+ * Prepare + put each path as a branch-staged attachment (pre-PR) with
+ * bounded concurrency. Same shape as `uploadAttachments`, keyed under
+ * `gh/<owner>/<repo>/branch/<branch>/<filename>` instead of a PR/issue
+ * number. Never syncs the managed comment — callers must not call
+ * `syncAttachmentsComment` for a branch target.
+ */
+export async function uploadBranchAttachments(opts) {
+    return uploadAttachmentBatch({
+        ...opts,
+        keyFor: (filename) => ghBranchAttachmentKey(opts.target.repo, opts.target.branch, filename),
+    });
+}
 function errorDetail(err) {
     if (err instanceof UploadsError)
         return { message: err.message, code: err.code, status: err.status };
@@ -527,18 +615,68 @@ export async function uploadPuts(opts) {
     }
     return { uploads, failures, firstError };
 }
+/**
+ * Best-effort call to `POST /v1/:workspace/github/promote` (server contract,
+ * PR #310). Degrade-safe like `syncAttachmentsComment`'s bot path: an older
+ * or self-hosted worker without this route (404), a forbidden token (403),
+ * or a network error all collapse to "nothing promoted" — the caller must
+ * never let this fail the attach. Returns undefined on any failure.
+ */
+async function attemptPromoteBranch(client, target, branch) {
+    try {
+        return await client.promoteBranchAttachments({ repo: target.repo, num: target.num, branch });
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Human-mode note for a promotion that actually promoted something. */
+function promotionNote(promotion, branch) {
+    const n = promotion.promoted.length;
+    const branchSuffix = branch ? ` from branch ${branch}` : "";
+    return `>> promoted ${n} staged attachment${n === 1 ? "" : "s"}${branchSuffix}\n`;
+}
 export async function runAttach(ctx, args, help = false, run = execRunner) {
     const parsed = parseCommandArgs(args);
     if (help || parsed.help) {
         writeCommandHelp(ATTACH_HELP);
         return 0;
     }
+    if (parsed.flags.has("--no-comment") && typeof parsed.flags.get("--no-comment") === "string") {
+        throw new UsageError("--no-comment takes no value — place it after the file arguments");
+    }
+    if (parsed.flags.has("--promote") && typeof parsed.flags.get("--promote") === "string") {
+        throw new UsageError("--promote takes no value — place it after the file arguments");
+    }
+    if (parsed.flags.has("--no-promote") && typeof parsed.flags.get("--no-promote") === "string") {
+        throw new UsageError("--no-promote takes no value — place it after the file arguments");
+    }
+    if (parsed.flags.has("--promote")) {
+        if (parsed.positionals.length > 0) {
+            throw new UsageError("--promote takes no file arguments — attaching a file to a PR already auto-promotes " +
+                "staged files; use `uploads attach <file> --pr <num>` instead");
+        }
+        if (parsed.flags.has("--branch"))
+            throw new UsageError("--promote cannot be combined with --branch");
+        if (parsed.flags.has("--issue"))
+            throw new UsageError("--promote cannot be combined with --issue");
+        if (parsed.flags.has("--no-promote"))
+            throw new UsageError("--promote cannot be combined with --no-promote");
+        return runAttachPromoteOnly(ctx, parsed, run);
+    }
     if (parsed.positionals.length === 0) {
         writeCommandHelp(ATTACH_HELP);
         return 2;
     }
-    if (parsed.flags.has("--no-comment") && typeof parsed.flags.get("--no-comment") === "string") {
-        throw new UsageError("--no-comment takes no value — place it after the file arguments");
+    const branchArg = branchFromFlags(parsed.flags, run);
+    if (branchArg !== undefined) {
+        if (parsed.flags.has("--pr"))
+            throw new UsageError("--branch cannot be combined with --pr");
+        if (parsed.flags.has("--issue"))
+            throw new UsageError("--branch cannot be combined with --issue");
+        if (parsed.flags.has("--comment"))
+            throw new UsageError("--branch cannot be combined with --comment");
+        return runAttachBranch(ctx, parsed, branchArg, run);
     }
     const explicitTarget = ghTargetFromFlags(parsed.flags, run);
     const target = explicitTarget ??
@@ -574,12 +712,33 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
         throw firstError instanceof Error ? firstError : new Error(String(firstError));
     }
+    // Auto-promote: before the comment sync, best-effort promote this
+    // workspace's own branch-staged attachments (from an earlier `attach
+    // --branch` while the PR didn't exist yet) into this PR's attachment
+    // prefix, so the comment gather below sees them in the same invocation.
+    // Never for issues (branch staging only ever targets a future PR), never
+    // with --no-promote, and silently skipped (no client call at all) when the
+    // current git branch can't be resolved (detached HEAD, not a repo) — this
+    // must never fail the attach itself.
+    let promotion;
+    let promotedBranch;
+    if (target.kind === "pull" && !parsed.flags.has("--no-promote")) {
+        try {
+            promotedBranch = resolveCurrentBranch(run);
+        }
+        catch {
+            promotedBranch = undefined;
+        }
+        if (promotedBranch !== undefined) {
+            promotion = await attemptPromoteBranch(ctx.client, target, promotedBranch);
+        }
+    }
     let comment;
     let commentError;
     // Skip comment refresh when every upload failed — nothing new from this batch.
     if (!parsed.flags.has("--no-comment") && uploads.length > 0) {
         try {
-            comment = await syncAttachmentsComment(ctx.client, target, run);
+            comment = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
         }
         catch (err) {
             commentError = err instanceof Error ? err.message : String(err);
@@ -587,7 +746,14 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         }
     }
     if (ctx.json) {
-        await writeJson({ target, uploads, failures, comment, commentError });
+        await writeJson({
+            target,
+            uploads,
+            failures,
+            comment,
+            commentError,
+            promotion: promotion ?? null,
+        });
     }
     else {
         for (const result of uploads) {
@@ -606,6 +772,9 @@ export async function runAttach(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 (!ctx.quiet && promotion && promotion.promoted.length > 0) {
+            process.stderr.write(promotionNote(promotion, promotedBranch));
+        }
         if (!ctx.quiet && comment)
             process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         if (!ctx.quiet && uploads.length > 0) {
@@ -615,6 +784,114 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
     }
     return failures.length === 0 ? 0 : 1;
 }
+/**
+ * `attach --branch` path: stages files under
+ * `gh/<owner>/<repo>/branch/<branch>/<filename>` instead of a PR/issue
+ * number. Never syncs the managed comment (there is no PR/issue to comment
+ * on yet, and the comment-gatherer only lists PR/issue prefixes anyway —
+ * branch-staged keys are invisible to it by construction).
+ */
+async function runAttachBranch(ctx, parsed, branch, run) {
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    const defaults = resolvePutDefaults({ envFile: ctx.envFile });
+    const optimizeOpts = optimizeOptionsFromFlags(parsed.flags, defaults);
+    const frameOpts = frameOptionsFromFlags(parsed.flags);
+    const contentTypeOverride = flagString(parsed.flags, "--content-type");
+    const metaExtras = parseMetaFlags(flagValues(parsed.flags, "--meta"));
+    const metadata = { ...metaExtras, ...ghMetadataForBranch(repo, branch) };
+    validateMetaMap(metadata);
+    const logHuman = !ctx.quiet && !ctx.json;
+    if (logHuman) {
+        const n = parsed.positionals.length;
+        process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"} (staged for branch ${branch})\n`);
+    }
+    const target = { repo, branch };
+    const { uploads, failures, firstError } = await uploadBranchAttachments({
+        client: ctx.client,
+        target,
+        files: parsed.positionals,
+        contentType: contentTypeOverride,
+        optimize: optimizeOpts,
+        frame: frameOpts,
+        metadata,
+    });
+    // Single-file total failure: rethrow so CLI exit codes stay auth/network-aware.
+    if (uploads.length === 0 && failures.length === 1 && parsed.positionals.length === 1) {
+        throw firstError instanceof Error ? firstError : new Error(String(firstError));
+    }
+    if (ctx.json) {
+        await writeJson({ target, uploads, failures });
+    }
+    else {
+        for (const result of uploads) {
+            if (logHuman) {
+                if (result.frame?.framed) {
+                    process.stderr.write(`>> ${basename(result.file)}: framed with ${result.frame.frameId}\n`);
+                }
+                const note = formatOptimizeNote(result.optimize);
+                if (note)
+                    process.stderr.write(`>> ${basename(result.file)}: ${note}\n`);
+                writeReplacedNote(result.replaced, false);
+            }
+            const embedLine = result.embedUrl ? `EMBED: ${result.embedUrl}\n` : "";
+            await writeStdout(`URL: ${result.url}\n${embedLine}MARKDOWN: ${result.markdown}\n`);
+        }
+        for (const failure of failures) {
+            process.stderr.write(`warning: could not upload ${failure.file}: ${failure.error.message}\n`);
+        }
+        if (!ctx.quiet && uploads.length > 0) {
+            process.stderr.write(`>> find these later: uploads find gh.branch=${branch.toLowerCase()}\n`);
+        }
+    }
+    return failures.length === 0 ? 0 : 1;
+}
+/**
+ * `attach --promote` with zero file arguments: resolve the PR target (same
+ * resolution as the default `runAttach` path), promote this workspace's
+ * branch-staged attachments into it, then run the comment sync — useful
+ * right after `gh pr create` when the PR was opened without a fresh attach
+ * (auto-promotion on the default path only fires when you attach a file).
+ * Unlike the default path's best-effort branch resolution, this is an
+ * explicit user action: `resolveCurrentBranch` throwing (detached HEAD, not
+ * a repo) propagates as a UsageError instead of silently skipping. Always
+ * exits 0 — an empty staging prefix is success, not a failure.
+ */
+async function runAttachPromoteOnly(ctx, parsed, run) {
+    const explicitTarget = ghTargetFromFlags(parsed.flags, run);
+    const target = explicitTarget ??
+        resolveCurrentPullRequest(resolveRepo(flagString(parsed.flags, "--repo"), run), run);
+    const branch = resolveCurrentBranch(run);
+    const promotion = await attemptPromoteBranch(ctx.client, target, branch);
+    let comment;
+    let commentError;
+    if (!parsed.flags.has("--no-comment")) {
+        try {
+            comment = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
+        }
+        catch (err) {
+            commentError = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`warning: promotion succeeded but the GitHub comment failed (is gh installed and authenticated?): ${commentError}\n`);
+        }
+    }
+    if (ctx.json) {
+        await writeJson({
+            target,
+            uploads: [],
+            failures: [],
+            comment,
+            commentError,
+            promotion: promotion ?? null,
+        });
+    }
+    else {
+        if (!ctx.quiet && promotion && promotion.promoted.length > 0) {
+            process.stderr.write(promotionNote(promotion, branch));
+        }
+        if (!ctx.quiet && comment)
+            process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
+    }
+    return 0;
+}
 export async function runPut(ctx, args, help = false, run = execRunner) {
     if (help) {
         writeCommandHelp(PUT_HELP);
@@ -815,7 +1092,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     let commentError;
     if (wantComment && ghTarget && uploads.length > 0) {
         try {
-            comment = await syncAttachmentsComment(ctx.client, ghTarget, run);
+            comment = await syncAttachmentsComment(ctx.client, ghTarget, run, ctx.config.workspace);
             if (logHuman)
                 process.stderr.write(`>> attachments comment ${comment.action}${commentViaSuffix(comment.via)}\n`);
         }
@@ -1359,7 +1636,7 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     const target = ghTargetFromFlags(parsed.flags, run);
     if (!target)
         throw new UsageError("comment requires --pr or --issue");
-    const result = await syncAttachmentsComment(ctx.client, target, run);
+    const result = await syncAttachmentsComment(ctx.client, target, run, ctx.config.workspace);
     if (ctx.json) {
         await writeJson({ ...target, ...result });
     }
@@ -1371,6 +1648,62 @@ export async function runComment(ctx, args, help = false, run = execRunner) {
     }
     return 0;
 }
+// --- github link ---
+const GITHUB_HELP = `uploads github link [--repo <owner/name>] [--status] [--workspace <name>]
+
+Claim or inspect this workspace's binding to a GitHub repo (see the managed
+attachments comment / webhook auto-promotion, which use this binding).
+First-claim-wins: claiming an already-bound repo never steals it from
+whichever workspace claimed it first — the command reports who owns it
+instead.
+
+--repo defaults the same way as --pr/--issue elsewhere (gh repo view, then
+the git remote). --status only inspects the current binding (files:read);
+without it, the command claims the repo (files:write).
+
+Examples:
+  uploads github link
+  uploads github link --repo buildinternet/uploads
+  uploads github link --status
+`;
+function formatGithubLink(repo, result) {
+    return result.workspace
+        ? `${repo} is bound to workspace "${result.workspace}"${result.source ? ` (${result.source})` : ""}\n`
+        : `${repo} is not bound to any workspace\n`;
+}
+export async function runGithub(ctx, args, help = false, run = execRunner) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help || !action) {
+        writeCommandHelp(GITHUB_HELP);
+        return help || parsed.help ? 0 : 2;
+    }
+    if (action !== "link")
+        throw new UsageError(`unknown github subcommand: ${action}`);
+    const repo = resolveRepo(flagString(parsed.flags, "--repo"), run);
+    const statusOnly = flagBool(parsed.flags, "--status");
+    let result;
+    try {
+        result = statusOnly
+            ? await ctx.client.githubLinkStatus(repo)
+            : await ctx.client.githubLinkClaim(repo);
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.status === 404) {
+            throw new UsageError("server does not support repo bindings yet (404) — upgrade the uploads.sh API/self-hosted worker");
+        }
+        throw err;
+    }
+    if (ctx.json) {
+        await writeJson(result);
+        return 0;
+    }
+    if (!statusOnly && result.claimed === false) {
+        process.stderr.write(`note: ${repo} is already bound to a different workspace ("${result.workspace}") — first-claim-wins, not overwritten\n`);
+    }
+    await writeStdout(formatGithubLink(repo, result));
+    return 0;
+}
 // --- usage / reconcile / purge ---
 const USAGE_HELP = `uploads usage [--workspace <name>]
 

package/dist/github-gh.d.ts

@@ -9,6 +9,8 @@ export declare const execRunner: CommandRunner;
 export declare function resolveRepo(explicit: string | undefined, run?: CommandRunner): string;
 /** Resolve the pull request associated with the current branch. */
 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;
 /**
  * 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
@@ -39,7 +41,13 @@ export declare function ghMetadataFromTargetWithTitle(target: GhTarget, run?: Co
  * Create the managed attachments comment, or edit it in place if it already
  * exists. Never touches any other comment. Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
+ *
+ * `marker` identifies which comment to hunt for (see `findManagedComment`);
+ * `body` is expected to already carry that same marker as its first line
+ * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
+ * an adopted legacy comment migrates it to the namespaced marker in place.
+ * Defaults to the shared legacy marker for backward compatibility.
  */
-export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner): {
+export declare function upsertAttachmentsComment(target: GhTarget, body: string, run?: CommandRunner, marker?: string): {
     created: boolean;
 };

package/dist/github-gh.js

@@ -68,6 +68,20 @@ export function resolveCurrentPullRequest(repo, run = execRunner) {
     }
     throw new UsageError("could not infer a pull request for the current branch — pass --pr <num> or --issue <num>");
 }
+/** Resolve the current git branch (`--branch` with no value). Throws UsageError on detached HEAD or outside a git repo. */
+export function resolveCurrentBranch(run = execRunner) {
+    let branch;
+    try {
+        branch = run("git", ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    }
+    catch {
+        throw new UsageError("could not determine the current git branch — pass --branch <name> or run inside a git repo");
+    }
+    if (branch === "" || branch === "HEAD") {
+        throw new UsageError("could not determine the current branch (detached HEAD) — pass --branch <name>");
+    }
+    return branch;
+}
 /**
  * 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
@@ -141,23 +155,41 @@ export function ghMetadataFromTargetWithTitle(target, run = execRunner) {
  * PR comments live on the issues endpoint, so one path covers PRs and issues.
  * `--paginate` follows Link headers and merges every page into one array, so the
  * marker comment is found even on threads past 100 comments.
+ *
+ * Hunts for `marker` (the namespaced, per-workspace marker) first; when none
+ * is found, falls back to a comment carrying the shared legacy
+ * `ATTACHMENTS_MARKER` (pre-4b, unnamespaced) so it can be adopted and
+ * migrated in place. When `marker` IS the legacy marker (no workspace to
+ * namespace with) this collapses to a single hunt, unchanged from pre-4b
+ * behavior.
  */
-function findManagedComment(target, run) {
+function findManagedComment(target, run, marker) {
     const raw = run("gh", [
         "api",
         `repos/${target.repo}/issues/${target.num}/comments?per_page=100`,
         "--paginate",
     ]);
     const comments = JSON.parse(raw);
+    const namespacedHit = comments.find((c) => typeof c.body === "string" && c.body.includes(marker));
+    if (namespacedHit)
+        return namespacedHit;
+    if (marker === ATTACHMENTS_MARKER)
+        return undefined;
     return comments.find((c) => typeof c.body === "string" && c.body.includes(ATTACHMENTS_MARKER));
 }
 /**
  * Create the managed attachments comment, or edit it in place if it already
  * exists. Never touches any other comment. Body is passed via stdin
  * (`-F body=@-`) so it is never shell-interpolated.
+ *
+ * `marker` identifies which comment to hunt for (see `findManagedComment`);
+ * `body` is expected to already carry that same marker as its first line
+ * (built via `attachmentsCommentBody(items, galleries, marker)`), so patching
+ * an adopted legacy comment migrates it to the namespaced marker in place.
+ * Defaults to the shared legacy marker for backward compatibility.
  */
-export function upsertAttachmentsComment(target, body, run = execRunner) {
-    const existing = findManagedComment(target, run);
+export function upsertAttachmentsComment(target, body, run = execRunner, marker = ATTACHMENTS_MARKER) {
+    const existing = findManagedComment(target, run, marker);
     if (existing) {
         run("gh", [
             "api",

package/dist/github.d.ts

@@ -22,6 +22,26 @@ export declare function ghKeyPrefix(target: GhTarget): string;
  * (unlike buildScreenshotKey).
  */
 export declare function ghAttachmentKey(target: GhTarget, filename: string): string;
+/**
+ * Branch-staged attachment key prefix: `gh/<owner>/<repo>/branch/<branch>/`.
+ * Pre-PR staging (Phase 1 of branch-staged attachments) — no PR/issue number
+ * exists yet. `branch` goes through `sanitizeKeySegment` like every other key
+ * segment, so e.g. `feature/x` becomes `feature-x`.
+ */
+export declare function ghBranchKeyPrefix(repo: string, branch: string): string;
+/** Branch-staged attachment key: `ghBranchKeyPrefix` + the sanitized filename. */
+export declare function ghBranchAttachmentKey(repo: string, branch: string, filename: string): string;
+/**
+ * `gh.*` metadata for a branch-staged attach: `gh.repo`, `gh.kind=branch`,
+ * `gh.branch` (lowercased), and `gh.staged-at` (ISO 8601 UTC, no fractional
+ * seconds). No `gh.number`/`gh.ref`/`gh.title` — there is no PR/issue yet.
+ * Throws `UsageError` when the lowercased branch name fails the metadata
+ * value rule (printable ASCII, 1-512 chars) — unlike `gh.title`'s best-effort
+ * degrade, a branch name the caller explicitly chose (via `--branch` or the
+ * current git branch) is worth failing loudly on rather than silently
+ * dropping from the metadata set.
+ */
+export declare function ghMetadataForBranch(repo: string, branch: string, now?: Date): Record<string, string>;
 /**
  * The four `gh.*` queryable-metadata pairs `uploads attach` writes
  * automatically (`.context/2026-07-13-file-metadata-design.md`). `gh.kind`
@@ -36,11 +56,25 @@ export declare function ghAttachmentKey(target: GhTarget, filename: string): str
 export declare function ghMetadataFromTarget(target: GhTarget): Record<string, string>;
 /** Hidden marker identifying the one comment this CLI manages. Never change it — existing comments are found by exact match. */
 export declare const ATTACHMENTS_MARKER = "<!-- uploads.sh:attachments -->";
+/**
+ * Per-workspace marker (`<!-- uploads.sh:attachments ws=<workspace> -->`) so
+ * two workspaces managing the same repo don't clobber each other's comment.
+ * Falls back to the shared legacy marker when `workspace` is missing or does
+ * not look like a safe slug — degrade, don't guess or risk breaking the
+ * comment's HTML.
+ */
+export declare function attachmentsMarker(workspace?: string): string;
+/** Max attachments embedded as inline `<img>` tags before the rest collapse
+ * into a `<details>` link list. Keeps very large threads from becoming a wall
+ * of images. */
+export declare const MAX_INLINE_ATTACHMENT_IMAGES = 16;
 export interface AttachmentItem {
     key: string;
     url: string | null;
     /** Prefer for `<img src>` on GitHub (Camo-friendly host). Falls back to `url`. */
     embedUrl?: string | null;
+    /** Canonical `/f/` file-page URL (server-computed). Preferred click-through target; falls back to `url`. */
+    pageUrl?: string | null;
 }
 /** A public gallery linked to the PR or issue whose managed comment is syncing. */
 export interface GalleryCommentItem {
@@ -70,4 +104,4 @@ export declare function attachmentImageWidth(filename: string): number;
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
  */
-export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[]): string;
+export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[], marker?: string): string;

package/dist/github.js

@@ -1,5 +1,7 @@
 import { inferContentType } from "./embed.js";
 import { sanitizeKeySegment } from "./keys.js";
+import { UsageError } from "./cli-args.js";
+import { isMetaValueSafe } from "./metadata.js";
 const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 export function isValidRepo(repo) {
     return REPO_RE.test(repo);
@@ -63,6 +65,42 @@ export function ghKeyPrefix(target) {
 export function ghAttachmentKey(target, filename) {
     return `${ghKeyPrefix(target)}${sanitizeKeySegment(filename)}`;
 }
+/**
+ * Branch-staged attachment key prefix: `gh/<owner>/<repo>/branch/<branch>/`.
+ * Pre-PR staging (Phase 1 of branch-staged attachments) — no PR/issue number
+ * exists yet. `branch` goes through `sanitizeKeySegment` like every other key
+ * segment, so e.g. `feature/x` becomes `feature-x`.
+ */
+export function ghBranchKeyPrefix(repo, branch) {
+    const [owner, name] = repo.split("/");
+    return `gh/${sanitizeKeySegment(owner)}/${sanitizeKeySegment(name)}/branch/${sanitizeKeySegment(branch)}/`;
+}
+/** Branch-staged attachment key: `ghBranchKeyPrefix` + the sanitized filename. */
+export function ghBranchAttachmentKey(repo, branch, filename) {
+    return `${ghBranchKeyPrefix(repo, branch)}${sanitizeKeySegment(filename)}`;
+}
+/**
+ * `gh.*` metadata for a branch-staged attach: `gh.repo`, `gh.kind=branch`,
+ * `gh.branch` (lowercased), and `gh.staged-at` (ISO 8601 UTC, no fractional
+ * seconds). No `gh.number`/`gh.ref`/`gh.title` — there is no PR/issue yet.
+ * Throws `UsageError` when the lowercased branch name fails the metadata
+ * value rule (printable ASCII, 1-512 chars) — unlike `gh.title`'s best-effort
+ * degrade, a branch name the caller explicitly chose (via `--branch` or the
+ * current git branch) is worth failing loudly on rather than silently
+ * dropping from the metadata set.
+ */
+export function ghMetadataForBranch(repo, branch, now = new Date()) {
+    const branchLower = branch.toLowerCase();
+    if (!isMetaValueSafe(branchLower)) {
+        throw new UsageError(`invalid --branch: "${branch}" must be printable ASCII to stage as gh.branch metadata`);
+    }
+    return {
+        "gh.repo": repo.toLowerCase(),
+        "gh.kind": "branch",
+        "gh.branch": branchLower,
+        "gh.staged-at": now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+    };
+}
 /**
  * The four `gh.*` queryable-metadata pairs `uploads attach` writes
  * automatically (`.context/2026-07-13-file-metadata-design.md`). `gh.kind`
@@ -85,6 +123,28 @@ export function ghMetadataFromTarget(target) {
 }
 /** Hidden marker identifying the one comment this CLI manages. Never change it — existing comments are found by exact match. */
 export const ATTACHMENTS_MARKER = "<!-- uploads.sh:attachments -->";
+/** Workspace slugs are `[a-z0-9-]`-ish; only markers built from a slug matching
+ * this are trusted as a distinct namespace — anything else (empty, unsafe
+ * chars) degrades to the shared legacy marker rather than emitting untrusted
+ * text into comment HTML. */
+const WORKSPACE_SLUG_RE = /^[a-z0-9-]{1,64}$/;
+/**
+ * Per-workspace marker (`<!-- uploads.sh:attachments ws=<workspace> -->`) so
+ * two workspaces managing the same repo don't clobber each other's comment.
+ * Falls back to the shared legacy marker when `workspace` is missing or does
+ * not look like a safe slug — degrade, don't guess or risk breaking the
+ * comment's HTML.
+ */
+export function attachmentsMarker(workspace) {
+    if (workspace && WORKSPACE_SLUG_RE.test(workspace)) {
+        return `<!-- uploads.sh:attachments ws=${workspace} -->`;
+    }
+    return ATTACHMENTS_MARKER;
+}
+/** Max attachments embedded as inline `<img>` tags before the rest collapse
+ * into a `<details>` link list. Keeps very large threads from becoming a wall
+ * of images. */
+export const MAX_INLINE_ATTACHMENT_IMAGES = 16;
 /** Default max width for images in the managed attachments comment (HTML img). */
 export const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
 /** Portrait / device mockups — keep phones readable, not full-column. */
@@ -116,10 +176,10 @@ function escapeHtmlText(s) {
  * Render the one marker-owned GitHub comment. When there are no galleries this
  * intentionally preserves the legacy attachment-only body byte-for-byte.
  */
-export function attachmentsCommentBody(items, galleries = []) {
+export function attachmentsCommentBody(items, galleries = [], marker = ATTACHMENTS_MARKER) {
     const sorted = items.toSorted((a, b) => a.key.localeCompare(b.key));
     const sortedGalleries = galleries.toSorted((a, b) => a.title.localeCompare(b.title) || a.url.localeCompare(b.url));
-    const lines = [ATTACHMENTS_MARKER];
+    const lines = [marker];
     if (sortedGalleries.length > 0) {
         lines.push("### 🖼️ Galleries", "");
         for (const gallery of sortedGalleries) {
@@ -136,27 +196,48 @@ export function attachmentsCommentBody(items, galleries = []) {
     }
     if (sorted.length > 0 || sortedGalleries.length === 0)
         lines.push("### 📎 Attachments", "");
+    let inlinedImages = 0;
+    const overflowImages = [];
     for (const item of sorted) {
         const name = item.key.slice(item.key.lastIndexOf("/") + 1);
         const stable = item.url;
         const src = item.embedUrl ?? item.url;
-        if (src && inferContentType(name).startsWith("image/")) {
+        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) {
+            // Cap hit — defer to the collapsed overflow list below rather than
+            // embedding every remaining image inline.
+            overflowImages.push(item);
+            continue;
+        }
+        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 keeps stable URL.
+            // img src uses embed host when available (Camo revalidates); click-through prefers the file page.
             const w = attachmentImageWidth(name);
             const alt = escapeHtmlAttr(name);
-            const href = escapeHtmlAttr(stable ?? src);
+            const href = escapeHtmlAttr(link ?? src);
             const imgSrc = escapeHtmlAttr(src);
             lines.push(`<a href="${href}"><img width="${w}" alt="${alt}" src="${imgSrc}"></a>`);
             lines.push("");
         }
-        else if (stable) {
-            lines.push(`- [${name}](${stable})`);
+        else if (link) {
+            lines.push(`- [${name}](${link})`);
         }
         else {
             lines.push(`- ${name}`);
         }
     }
+    if (overflowImages.length > 0) {
+        const n = overflowImages.length;
+        lines.push(`<details><summary>${n} more attachment${n === 1 ? "" : "s"}</summary>`, "");
+        for (const item of overflowImages) {
+            const name = item.key.slice(item.key.lastIndexOf("/") + 1);
+            const link = item.pageUrl ?? item.url;
+            lines.push(link ? `- [${name}](${link})` : `- ${name}`);
+        }
+        lines.push("", "</details>", "");
+    }
     lines.push('<sub>Maintained by <a href="https://uploads.sh">uploads.sh</a> — re-uploading a file with the same name updates it everywhere it is embedded.</sub>');
     return lines.join("\n");
 }

package/dist/index.d.ts

@@ -7,7 +7,7 @@ export { UploadsError, type UploadsErrorCode } from "./errors.js";
 export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type GetMetadataResult, type PatchMetadataOptions, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, type AttachmentItem, type GhTarget, type GhTargetKind, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, type OptimizeImageOptions, type OptimizeImageResult, type OptimizeOutputFormat, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, type FrameFit, type FrameOptions, type FrameResult, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, type CommandRunner, } from "./github-gh.js";

package/dist/index.js

@@ -7,7 +7,7 @@ export { UploadsError } from "./errors.js";
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";
-export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
+export { ATTACHMENTS_MARKER, attachmentsCommentBody, ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget, ghBranchAttachmentKey, ghBranchKeyPrefix, ghMetadataForBranch, isValidRepo, parseRepoFromRemoteUrl, } from "./github.js";
 export { DEFAULT_OPTIMIZE_MAX_EDGE, DEFAULT_OPTIMIZE_QUALITY, optimizeImageForUpload, rewriteKeyExtension, withImageExtension, } from "./optimize.js";
 export { FRAME_PRESETS, applyFrame, listFramePresets, resolveFrameId, } from "./frame.js";
 export { execRunner, resolveRepo, upsertAttachmentsComment, } from "./github-gh.js";

package/dist/mcp/tools.js

@@ -123,11 +123,11 @@ export function createUploadsMcpTools(opts) {
         });
         return { config, client: clientFactory(config) };
     }
-    const syncComment = async (client, target) => {
+    const syncComment = async (client, target, workspace) => {
         let comment;
         let commentError;
         try {
-            comment = await syncAttachmentsComment(client, target, run);
+            comment = await syncAttachmentsComment(client, target, run, workspace);
         }
         catch (err) {
             // Uploads already succeeded; the comment is best-effort by design.
@@ -402,7 +402,7 @@ export function createUploadsMcpTools(opts) {
                 catch (err) {
                     usage(err instanceof Error ? err.message : String(err));
                 }
-                const { client } = clientFor(args);
+                const { config, client } = clientFor(args);
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
@@ -436,7 +436,7 @@ export function createUploadsMcpTools(opts) {
                         throw new ToolBatchError(batchFailureMessage(failures), { uploads, failures });
                     }
                     if (wantComment && target && uploads.length > 0) {
-                        const { comment, commentError } = await syncComment(client, target);
+                        const { comment, commentError } = await syncComment(client, target, config.workspace);
                         return { uploads, failures, comment, commentError };
                     }
                     return { uploads, failures };
@@ -469,7 +469,7 @@ export function createUploadsMcpTools(opts) {
                         filename: prepared.filename,
                     };
                     if (wantComment && target) {
-                        const { comment, commentError } = await syncComment(client, target);
+                        const { comment, commentError } = await syncComment(client, target, config.workspace);
                         return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
                     }
                     return {
@@ -504,7 +504,7 @@ export function createUploadsMcpTools(opts) {
                     ...(dryRun ? { dryRun: true } : {}),
                 };
                 if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target);
+                    const { comment, commentError } = await syncComment(client, target, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;
@@ -761,7 +761,7 @@ export function createUploadsMcpTools(opts) {
                     ...(dryRun ? { dryRun: true } : {}),
                 };
                 if (wantComment && target) {
-                    const { comment, commentError } = await syncComment(client, target);
+                    const { comment, commentError } = await syncComment(client, target, config.workspace);
                     return { ...flat, comment, commentError };
                 }
                 return flat;
@@ -821,7 +821,7 @@ export function createUploadsMcpTools(opts) {
                 const explicitTarget = ghTargetFromArgs(args, run);
                 const target = explicitTarget ??
                     resolveCurrentPullRequest(resolveRepo(optString(args, "repo"), run), run);
-                const { client } = clientFor(args);
+                const { config, client } = clientFor(args);
                 const contentType = optString(args, "contentType");
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
@@ -856,7 +856,7 @@ export function createUploadsMcpTools(opts) {
                 }
                 if (optBool(args, "noComment"))
                     return { target, uploads, failures };
-                const { comment, commentError } = await syncComment(client, target);
+                const { comment, commentError } = await syncComment(client, target, config.workspace);
                 return { target, uploads, failures, comment, commentError };
             },
         },
@@ -1062,8 +1062,8 @@ export function createUploadsMcpTools(opts) {
                 const target = ghTargetFromArgs(args, run);
                 if (!target)
                     usage("comment requires pr or issue");
-                const { client } = clientFor(args);
-                const result = await syncAttachmentsComment(client, target, run);
+                const { config, client } = clientFor(args);
+                const result = await syncAttachmentsComment(client, target, run, config.workspace);
                 return { ...target, ...result };
             },
         },

package/package.json

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