@buildinternet/uploads 0.29.0 → 0.31.0

package/dist/annotate/spec.js

@@ -0,0 +1,237 @@
+/**
+ * Annotation spec: types, validation, and selector resolution.
+ *
+ * NOT exported outside this module directly — only `index.ts` re-exports
+ * these. Keep the public surface narrow so the renderer stays swappable
+ * (see the module header in `index.ts`).
+ */
+/** Thrown by `validateSpec` and `resolveSelectors`; carries every collected error. */
+export class AnnotateSpecError extends Error {
+    errors;
+    constructor(errors) {
+        super(errors
+            .map((e) => (e.index === null ? e.message : `annotations[${e.index}]: ${e.message}`))
+            .join("; "));
+        this.name = "AnnotateSpecError";
+        this.errors = errors;
+    }
+}
+const GEOMETRIC_TYPES = new Set(["box", "arrow", "label", "redact"]);
+/**
+ * Default placement offsets used when a spec omits an explicit position —
+ * kept together so "where things land by default" has one home. Units are
+ * image pixels; `labelAt` is additionally multiplied by the render scale.
+ */
+export const DEFAULT_PLACEMENT = {
+    /** Selector-only arrow: tail offset from the target center (resolveSelectors). */
+    arrowFrom: [120, -120],
+    /** Label with a target but no `at`: bubble offset above-right (renderLabel). */
+    labelAt: [30, -90],
+};
+/**
+ * Returns a rejection reason if a raw `svg` fragment is unsafe, else null.
+ * Shared by `validateSpec` and the renderer (defense in depth — the renderer
+ * re-checks in case a caller bypasses validation): `<script` is an obvious
+ * injection, and librsvg resolves href/xlink:href and CSS url() references,
+ * which has been an arbitrary-file-read vector (e.g. CVE-2023-38633).
+ */
+export function unsafeSvgFragmentReason(fragment) {
+    if (/<script/i.test(fragment))
+        return "svg fragment must not contain <script";
+    if (/\bhref\s*=|\burl\s*\(/i.test(fragment)) {
+        return "svg fragment must not reference external resources (href= or url())";
+    }
+    return null;
+}
+function isFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+function isPoint(v) {
+    return Array.isArray(v) && v.length === 2 && isFiniteNumber(v[0]) && isFiniteNumber(v[1]);
+}
+function hasOwn(obj, key) {
+    return Object.prototype.hasOwnProperty.call(obj, key);
+}
+/** Validates one raw annotation, pushing any `SpecError`s onto `errors`. */
+function validateAnnotation(raw, index, errors) {
+    const fail = (message) => errors.push({ index, message });
+    if (typeof raw !== "object" || raw === null) {
+        fail("must be an object");
+        return;
+    }
+    const a = raw;
+    const type = a.type;
+    if (typeof type !== "string") {
+        fail("missing or non-string type");
+        return;
+    }
+    const hasSelector = typeof a.selector === "string" && a.selector.length > 0;
+    const hasPixelGeometry = (() => {
+        switch (type) {
+            case "box":
+            case "redact":
+                return hasOwn(a, "x") || hasOwn(a, "y") || hasOwn(a, "w") || hasOwn(a, "h");
+            // `from` is deliberately allowed alongside a selector: the selector
+            // resolves the arrow's head (`to`), and an explicit `from` overrides
+            // the default tail placement (see resolveSelectors).
+            case "arrow":
+                return hasOwn(a, "to");
+            case "label":
+                return hasOwn(a, "target");
+            default:
+                return false;
+        }
+    })();
+    if (GEOMETRIC_TYPES.has(type) && hasSelector && hasPixelGeometry) {
+        fail("ambiguous: both pixel geometry and a selector are present, pick one");
+        return;
+    }
+    const requireBoxFields = () => {
+        if (hasSelector)
+            return;
+        if (!isFiniteNumber(a.x) ||
+            !isFiniteNumber(a.y) ||
+            !isFiniteNumber(a.w) ||
+            !isFiniteNumber(a.h)) {
+            fail(`${type} requires finite x, y, w, h (or a selector)`);
+        }
+    };
+    switch (type) {
+        case "box": {
+            requireBoxFields();
+            break;
+        }
+        case "redact": {
+            requireBoxFields();
+            if (hasOwn(a, "style") && a.style !== "blur" && a.style !== "solid") {
+                fail('redact style must be "blur" or "solid"');
+            }
+            break;
+        }
+        case "arrow": {
+            if (hasSelector)
+                break;
+            if (!isPoint(a.from) || !isPoint(a.to)) {
+                fail("arrow requires from/to points (or a selector)");
+            }
+            break;
+        }
+        case "label": {
+            if (typeof a.text !== "string" || a.text.length === 0) {
+                fail("label requires non-empty text");
+            }
+            if (hasSelector)
+                break;
+            if (hasOwn(a, "target") && !isPoint(a.target)) {
+                fail("label target must be a point");
+            }
+            if (hasOwn(a, "at") && !isPoint(a.at)) {
+                fail("label at must be a point");
+            }
+            break;
+        }
+        case "draw": {
+            if (!Array.isArray(a.points) || a.points.length < 2 || !a.points.every(isPoint)) {
+                fail("draw requires at least 2 points");
+            }
+            break;
+        }
+        case "svg": {
+            if (typeof a.fragment !== "string" || a.fragment.length === 0) {
+                fail("svg requires a non-empty fragment");
+            }
+            else {
+                const unsafe = unsafeSvgFragmentReason(a.fragment);
+                if (unsafe)
+                    fail(unsafe);
+            }
+            break;
+        }
+        default:
+            fail(`unknown annotation type "${String(type)}"`);
+    }
+}
+/** Throws AnnotateSpecError (carries errors: SpecError[]) on invalid input. */
+export function validateSpec(json) {
+    const errors = [];
+    if (typeof json !== "object" || json === null) {
+        throw new AnnotateSpecError([{ index: null, message: "spec must be an object" }]);
+    }
+    const raw = json;
+    if (raw.version !== 1) {
+        errors.push({ index: null, message: `version must be 1, got ${JSON.stringify(raw.version)}` });
+    }
+    if (!Array.isArray(raw.annotations) || raw.annotations.length === 0) {
+        errors.push({ index: null, message: "annotations must be a non-empty array" });
+    }
+    if (errors.length > 0)
+        throw new AnnotateSpecError(errors);
+    const annotations = raw.annotations;
+    annotations.forEach((a, i) => validateAnnotation(a, i, errors));
+    if (errors.length > 0)
+        throw new AnnotateSpecError(errors);
+    return { version: 1, annotations: annotations };
+}
+/** True if any annotation still carries an unresolved selector. */
+export function hasSelectors(spec) {
+    return spec.annotations.some((a) => "selector" in a && typeof a.selector === "string");
+}
+/** All distinct selectors in the spec, in order. */
+export function specSelectors(spec) {
+    const seen = [];
+    for (const a of spec.annotations) {
+        const sel = "selector" in a ? a.selector : undefined;
+        if (typeof sel === "string" && !seen.includes(sel))
+            seen.push(sel);
+    }
+    return seen;
+}
+function center(box) {
+    return [box.x + box.w / 2, box.y + box.h / 2];
+}
+/**
+ * Replace selector targeting with pixel geometry using measured boxes keyed
+ * by selector. Throws AnnotateSpecError naming any selector missing from
+ * boxes.
+ */
+export function resolveSelectors(spec, boxes) {
+    const errors = [];
+    const resolved = spec.annotations.map((a, index) => {
+        const sel = "selector" in a ? a.selector : undefined;
+        if (typeof sel !== "string")
+            return a;
+        const box = boxes[sel];
+        if (!box) {
+            errors.push({ index, message: `selector "${sel}" was not found among the measured boxes` });
+            return a;
+        }
+        switch (a.type) {
+            case "box":
+            case "redact": {
+                const { selector: _selector, ...rest } = a;
+                return { ...rest, x: box.x, y: box.y, w: box.w, h: box.h };
+            }
+            case "arrow": {
+                const { selector: _selector, ...rest } = a;
+                const to = center(box);
+                // A selector-only arrow points at the element from its upper right;
+                // the renderer clamps if that lands outside the image.
+                const from = rest.from ??
+                    [
+                        to[0] + DEFAULT_PLACEMENT.arrowFrom[0],
+                        to[1] + DEFAULT_PLACEMENT.arrowFrom[1],
+                    ];
+                return { ...rest, from, to };
+            }
+            case "label": {
+                const { selector: _selector, ...rest } = a;
+                return { ...rest, target: center(box) };
+            }
+            default:
+                return a;
+        }
+    });
+    if (errors.length > 0)
+        throw new AnnotateSpecError(errors);
+    return { version: 1, annotations: resolved };
+}

package/dist/annotate/text.d.ts

@@ -0,0 +1,15 @@
+export interface TextMetrics {
+    /** SVG path `d` data, already positioned at the requested x/y baseline. */
+    d: string;
+    /** Total advance width in pixels at the requested font size. */
+    width: number;
+    /** Ascent + descent in pixels at the requested font size (line height). */
+    height: number;
+}
+/** Renders `text` to an SVG path at the given baseline origin and font size (px). */
+export declare function textToPath(text: string, x: number, y: number, fontSize: number): TextMetrics;
+/** Measures `text` at the given font size without generating path data. */
+export declare function measureText(text: string, fontSize: number): {
+    width: number;
+    height: number;
+};

package/dist/annotate/text.js

@@ -0,0 +1,39 @@
+/**
+ * Text-as-paths via opentype.js + the bundled Excalifont.
+ *
+ * Not exported outside this module — only `index.ts` re-exports the public
+ * surface (see the module header there). Rendering label text as SVG paths
+ * (instead of an SVG `<text>` element) sidesteps librsvg's fontconfig-based
+ * font resolution entirely, so the renderer produces identical output no
+ * matter which fonts happen to be installed on the host.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import opentype from "opentype.js";
+const FONT_URL = new URL("../../assets/Excalifont-Regular.ttf", import.meta.url);
+let cachedFont;
+function loadFont() {
+    if (!cachedFont) {
+        const buf = readFileSync(fileURLToPath(FONT_URL));
+        const arrayBuffer = buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+        cachedFont = opentype.parse(arrayBuffer);
+    }
+    return cachedFont;
+}
+/** Renders `text` to an SVG path at the given baseline origin and font size (px). */
+export function textToPath(text, x, y, fontSize) {
+    const font = loadFont();
+    const path = font.getPath(text, x, y, fontSize);
+    const width = font.getAdvanceWidth(text, fontSize);
+    const scale = fontSize / font.unitsPerEm;
+    const height = (font.ascender - font.descender) * scale;
+    return { d: path.toPathData(2), width, height };
+}
+/** Measures `text` at the given font size without generating path data. */
+export function measureText(text, fontSize) {
+    const font = loadFont();
+    const width = font.getAdvanceWidth(text, fontSize);
+    const scale = fontSize / font.unitsPerEm;
+    const height = (font.ascender - font.descender) * scale;
+    return { width, height };
+}

package/dist/cli-args.d.ts

@@ -45,6 +45,21 @@ export declare function parseCommandArgs(args: string[]): CommandFlags;
  * `--repo a --repo b` → `"b"`). Genuinely repeatable flags should use
  * `flagValues` instead.
  */
+/**
+ * Rewrites short aliases (e.g. `-o` -> `--out`) before `parseCommandArgs`,
+ * which only understands `--long` flags — a bare short flag would otherwise
+ * land in positionals.
+ */
+export declare function expandFlagAliases(args: string[], aliases: Record<string, string>): string[];
+/**
+ * Pulls a `--flag -` pair (the stdin convention) out of `args` before the
+ * generic parse: `parseCommandArgs` treats a bare `-` as a flag boundary, so
+ * it can never be consumed as a flag's value.
+ */
+export declare function extractDashValue(args: string[], flag: string): {
+    args: string[];
+    dash: boolean;
+};
 export declare function flagString(flags: CommandFlags["flags"], name: string): string | undefined;
 export declare function flagBool(flags: CommandFlags["flags"], name: string): boolean;
 /**

package/dist/cli-args.js

@@ -139,6 +139,27 @@ export function parseCommandArgs(args) {
  * `--repo a --repo b` → `"b"`). Genuinely repeatable flags should use
  * `flagValues` instead.
  */
+/**
+ * Rewrites short aliases (e.g. `-o` -> `--out`) before `parseCommandArgs`,
+ * which only understands `--long` flags — a bare short flag would otherwise
+ * land in positionals.
+ */
+export function expandFlagAliases(args, aliases) {
+    return args.map((a) => aliases[a] ?? a);
+}
+/**
+ * Pulls a `--flag -` pair (the stdin convention) out of `args` before the
+ * generic parse: `parseCommandArgs` treats a bare `-` as a flag boundary, so
+ * it can never be consumed as a flag's value.
+ */
+export function extractDashValue(args, flag) {
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === flag && args[i + 1] === "-") {
+            return { args: [...args.slice(0, i), ...args.slice(i + 2)], dash: true };
+        }
+    }
+    return { args, dash: false };
+}
 export function flagString(flags, name) {
     const value = flags.get(name);
     if (typeof value === "string")

package/dist/cli-catalog.d.ts

@@ -29,6 +29,8 @@ export declare const PUT_LIKE_FLAGS: readonly string[];
  * screenshot never parses.
  */
 export declare const SCREENSHOT_FLAGS: readonly string[];
+/** All flags `uploads annotate` actually reads (verified against commands/annotate.ts). */
+export declare const ANNOTATE_FLAGS: readonly string[];
 export declare const LIST_LIKE_FLAGS: readonly string[];
 export declare const ROOT_COMMANDS: readonly CatalogCommand[];
 export declare const COMPLETION_SHELLS: readonly ["bash", "zsh", "fish"];

package/dist/cli-catalog.js

@@ -59,6 +59,7 @@ export const SCREENSHOT_FLAGS = [
     "--dark",
     "--light",
     "--wait",
+    "--annotate",
     "--out",
     "--no-sidecar",
     "--no-upload",
@@ -92,6 +93,16 @@ export const SCREENSHOT_FLAGS = [
     "--help",
     "-h",
 ];
+/** All flags `uploads annotate` actually reads (verified against commands/annotate.ts). */
+export const ANNOTATE_FLAGS = [
+    "--spec",
+    "-o",
+    "--out",
+    "--seed",
+    "--format",
+    "--help",
+    "-h",
+];
 export const LIST_LIKE_FLAGS = [
     "--prefix",
     "--limit",
@@ -125,6 +136,11 @@ export const ROOT_COMMANDS = [
         summary: "Capture a URL or .html file and host it (local browser or remote render)",
         essential: true,
     },
+    {
+        name: "annotate",
+        usage: "annotate <image>",
+        summary: "Bake hand-drawn boxes, arrows, labels, and redactions onto an image",
+    },
     {
         name: "gallery",
         summary: "Create and organize public media galleries",

package/dist/cli.js

@@ -19,6 +19,7 @@ import { runLogout, runWhoami } from "./commands/session.js";
 import { runTelemetry } from "./commands/telemetry.js";
 import { runReport } from "./commands/report.js";
 import { runScreenshot } from "./commands/screenshot.js";
+import { runAnnotate } from "./commands/annotate.js";
 import { packageVersion } from "./package-version.js";
 import { checkForUpdate, maybeHintUpdate } from "./update-check.js";
 import { maybeSyncSessionCliVersion } from "./session-cli-version.js";
@@ -281,6 +282,11 @@ export async function runCli(argv) {
             case "completions":
                 code = await runCompletion(cmdArgs, showHelp);
                 break;
+            case "annotate":
+                // No CliContext needed — annotate is a pure local pixel transform,
+                // never touches auth/client/upload.
+                code = await runAnnotate(cmdArgs, showHelp);
+                break;
             case "attach":
             case "put":
             case "staged":

package/dist/client.d.ts

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

package/dist/commands/annotate.d.ts

@@ -0,0 +1,3 @@
+export declare function runAnnotate(args: string[], help?: boolean, 
+/** Injectable for tests — avoids depending on a real stdin stream. */
+readStdinImpl?: () => Promise<string>): Promise<number>;

package/dist/commands/annotate.js

@@ -0,0 +1,124 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { basename, extname, join, dirname } from "node:path";
+import sharp from "sharp";
+import { expandFlagAliases, extractDashValue, flagInt, flagString, parseCommandArgs, UsageError, } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { readStdin, writeJson, writeStdout } from "../io.js";
+const ANNOTATE_HELP = `uploads annotate <image> --spec <file|-> [options]
+
+Bake hand-drawn boxes, arrows, labels, freeform strokes, and redactions onto
+an existing image. image is a path to a local PNG/JPEG file. The spec is a
+JSON document (see the annotate-screenshots skill for the full format);
+pass a file path or "-" to read it from stdin.
+
+Selector-bearing specs (annotations that point at a CSS selector instead of
+pixel coordinates) are rejected here — selectors can only be resolved
+against a live page, via "uploads screenshot --annotate".
+
+Options:
+  --spec <file|->    JSON annotation spec (required)
+  -o, --out <file>   Output PNG path (default: <stem>.annotated.png next to the image)
+  --seed <n>         Fix the rough.js seed for deterministic sketchy rendering (default: 7)
+  --format human|json  Output format (default: human)
+
+Exit codes: 0 ok · 1 invalid spec · 2 usage.
+
+Examples:
+  uploads annotate ./shot.png --spec ./callouts.json
+  cat ./callouts.json | uploads annotate ./shot.png --spec -
+  uploads annotate ./shot.png --spec ./callouts.json --out ./shot.marked.png
+`;
+function defaultOutPath(imagePath) {
+    const ext = extname(imagePath);
+    const stem = ext ? basename(imagePath, ext) : basename(imagePath);
+    return join(dirname(imagePath), `${stem}.annotated.png`);
+}
+export async function runAnnotate(args, help = false, 
+/** Injectable for tests — avoids depending on a real stdin stream. */
+readStdinImpl = readStdin) {
+    if (help) {
+        writeCommandHelp(ANNOTATE_HELP);
+        return 0;
+    }
+    const { args: preArgs, dash: specFromDash } = extractDashValue(expandFlagAliases(args, { "-o": "--out" }), "--spec");
+    const parsed = parseCommandArgs(preArgs);
+    if (parsed.help) {
+        writeCommandHelp(ANNOTATE_HELP);
+        return 0;
+    }
+    const imagePath = parsed.positionals[0];
+    if (!imagePath) {
+        writeCommandHelp(ANNOTATE_HELP);
+        return 2;
+    }
+    if (parsed.positionals.length > 1) {
+        throw new UsageError("annotate takes exactly one image argument");
+    }
+    const specArg = specFromDash ? "-" : flagString(parsed.flags, "--spec");
+    if (!specArg) {
+        throw new UsageError("--spec is required (a file path or - for stdin)");
+    }
+    const outFlag = flagString(parsed.flags, "--out");
+    const seed = flagInt(parsed.flags, "--seed", "--seed");
+    const format = flagString(parsed.flags, "--format");
+    if (format && format !== "human" && format !== "json") {
+        throw new UsageError(`invalid --format: ${format} (use human or json)`);
+    }
+    const wantJson = format === "json";
+    let specText;
+    if (specArg === "-") {
+        specText = await readStdinImpl();
+    }
+    else {
+        try {
+            specText = readFileSync(specArg, "utf8");
+        }
+        catch (err) {
+            throw new UsageError(`could not read --spec ${specArg}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    const { validateSpec, hasSelectors, renderAnnotations, clampReport, AnnotateSpecError } = await import("../annotate/index.js");
+    let specJson;
+    try {
+        specJson = JSON.parse(specText);
+    }
+    catch (err) {
+        await writeStdout("");
+        process.stderr.write(`spec is not valid JSON: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    let spec;
+    try {
+        spec = validateSpec(specJson);
+    }
+    catch (err) {
+        if (err instanceof AnnotateSpecError) {
+            for (const e of err.errors) {
+                const prefix = e.index === null ? "spec" : `annotations[${e.index}]`;
+                process.stderr.write(`${prefix}: ${e.message}\n`);
+            }
+            return 1;
+        }
+        throw err;
+    }
+    if (hasSelectors(spec)) {
+        throw new UsageError('annotate works on pixels; selectors need "uploads screenshot --annotate" (live page required)');
+    }
+    const image = readFileSync(imagePath);
+    const meta = await sharp(image).metadata();
+    const width = meta.width ?? 0;
+    const height = meta.height ?? 0;
+    const warnings = clampReport(spec, width, height);
+    for (const w of warnings)
+        process.stderr.write(`${w}\n`);
+    const rendered = await renderAnnotations(image, spec, seed !== undefined ? { seed } : undefined);
+    const outPath = outFlag ?? defaultOutPath(imagePath);
+    writeFileSync(outPath, rendered);
+    if (wantJson) {
+        await writeJson({ out: outPath, width, height, warnings });
+    }
+    else {
+        await writeStdout(`${outPath}\n`);
+    }
+    return 0;
+}

package/dist/commands/completion.js

@@ -1,5 +1,5 @@
 import { parseCommandArgs, UsageError } from "../cli-args.js";
-import { COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_LIKE_FLAGS, SCREENSHOT_FLAGS, ROOT_COMMANDS, isCompletionShell, } from "../cli-catalog.js";
+import { ANNOTATE_FLAGS, COMPLETION_SHELLS, GLOBAL_FLAGS, LIST_LIKE_FLAGS, PUT_LIKE_FLAGS, SCREENSHOT_FLAGS, ROOT_COMMANDS, isCompletionShell, } from "../cli-catalog.js";
 import { writeCommandHelp } from "../cli-style.js";
 const HELP = `uploads completion <shell>
 
@@ -29,6 +29,7 @@ function bashScript() {
     const putFlags = PUT_LIKE_FLAGS.join(" ");
     const listFlags = LIST_LIKE_FLAGS.join(" ");
     const screenshotFlags = SCREENSHOT_FLAGS.join(" ");
+    const annotateFlags = ANNOTATE_FLAGS.join(" ");
     const subMaps = ROOT_COMMANDS.filter((c) => c.subcommands?.length).map((c) => {
         const names = c.subcommands.map((s) => s.name).join(" ");
         return `    ${c.name}) subs="${names}" ;;`;
@@ -54,6 +55,7 @@ _uploads() {
   local -a put_flags=(${putFlags})
   local -a list_flags=(${listFlags})
   local -a screenshot_flags=(${screenshotFlags})
+  local -a annotate_flags=(${annotateFlags})
 
   # Find the first non-global positional (the subcommand).
   local cmd="" i=1
@@ -107,6 +109,9 @@ ${subMaps.join("\n")}
       screenshot)
         COMPREPLY=( $(compgen -W "\${screenshot_flags[*]}" -- "$cur") )
         ;;
+      annotate)
+        COMPREPLY=( $(compgen -W "\${annotate_flags[*]}" -- "$cur") )
+        ;;
       list|find)
         COMPREPLY=( $(compgen -W "\${list_flags[*]}" -- "$cur") )
         ;;
@@ -119,7 +124,7 @@ ${subMaps.join("\n")}
 
   # File paths for upload-style commands.
   case "$cmd" in
-    put|attach|screenshot)
+    put|attach|screenshot|annotate)
       COMPREPLY=( $(compgen -f -- "$cur") )
       ;;
   esac
@@ -199,7 +204,7 @@ ${globalArgs} \\
     args)
       case $line[1] in
 ${subCases}
-      put|attach|screenshot)
+      put|attach|screenshot|annotate)
         _files
         ;;
       esac
@@ -265,8 +270,19 @@ function fishScript() {
             continue;
         lines.push(`complete -c uploads -n '__fish_seen_subcommand_from list find' -l ${flag.slice(2)}`);
     }
-    // File completion for put/attach/screenshot
-    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach screenshot' -F`);
+    for (const flag of ANNOTATE_FLAGS) {
+        if (flag === "-o")
+            continue; // folded into --out's paired completion below
+        if (flag === "--out") {
+            lines.push(`complete -c uploads -n '__fish_seen_subcommand_from annotate' -s o -l out`);
+            continue;
+        }
+        if (!flag.startsWith("--"))
+            continue;
+        lines.push(`complete -c uploads -n '__fish_seen_subcommand_from annotate' -l ${flag.slice(2)}`);
+    }
+    // File completion for put/attach/screenshot/annotate
+    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach screenshot annotate' -F`);
     return lines.join("\n") + "\n";
 }
 export function generateCompletionScript(shell) {

package/dist/commands/install.js

@@ -5,10 +5,11 @@ import { writeCommandHelp } from "../cli-style.js";
 import { HOOK_COMMAND, installHookManifests } from "../hooks-install.js";
 export const DEFAULT_MCP_URL = "https://agents.uploads.sh/mcp";
 const SKILL_SOURCE = "buildinternet/uploads";
-const SKILL_NAMES = ["uploads-cli", "github-screenshots"];
+const SKILL_NAMES = ["uploads-cli", "github-screenshots", "annotate-screenshots"];
 const INSTALL_HELP = `uploads install — set up agent integrations (skills + remote MCP + hooks)
 
-Installs the github-screenshots and uploads-cli agent skills, registers the
+Installs the github-screenshots, uploads-cli, and annotate-screenshots agent
+skills, registers the
 hosted MCP server with Claude Code, and installs the PR screenshot reminder
 hook for Grok / Cursor when those tools are present. The remote MCP endpoint
 infers your workspace from the bearer token, so only the token is needed.
@@ -21,7 +22,8 @@ Usage:
 
 What it does:
   skill   Agent skills (via npx skills) — github-screenshots: visuals into
-          PRs/issues; uploads-cli: full CLI reference
+          PRs/issues; uploads-cli: full CLI reference; annotate-screenshots:
+          hand-drawn callouts and redaction on screenshots
   mcp     Hosted MCP server in Claude Code — put, list, attach, galleries
   hooks   PR screenshot reminder for Grok / Cursor (user-global manifests)