@buildinternet/uploads 0.53.0 → 0.55.0

package/README.md

@@ -31,6 +31,8 @@ uploads put --url https://cdn.example/shot.png --pr 123
 uploads put --url http://localhost:4321/shot.png
 uploads gallery create --title "Release screenshots"
 uploads put ./after.png --gallery gal_example
+uploads feed create --repo owner/repo
+uploads feed create --repo owner/repo --pr 123
 # custom metadata (queryable): page URL, in-app path, which surface
 uploads put ./shot.png --meta url=https://app.example/settings --meta path=/settings --meta app=web
 uploads meta get screenshots/myapp/42/shot.webp
@@ -43,9 +45,9 @@ Inside this monorepo only, `pnpm uploads …` builds the package first so you pi
 up local source; product docs and PR “how to try it” examples should use the
 global `uploads` form above.
 
-Commands: `attach`, `put`, `screenshot`, `annotate`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
+Commands: `attach`, `put`, `screenshot`, `annotate`, `gallery`, `feed`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
 `reconcile`, `purge-expired`, `setup`, `install`, `login`, `whoami` (alias `status`),
-`logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `changelog`, `mcp`,
+`logout`, `invite`, `admin`, `config`, `telemetry`, `report`, `doctor`, `health`, `changelog`, `docs`, `mcp`,
 `completion`.
 
 **Help:** bare `uploads` / `uploads help` / `--help` shows essentials; use
@@ -192,13 +194,33 @@ When adding several keys, `uploads gallery add` processes them sequentially and
 individual failures in `--json` output. Gallery item updates use the API's current version to
 avoid overwriting concurrent changes.
 
+## Change feeds
+
+A feed is a public newest-first page of screenshots already tagged with a GitHub `owner/repo`,
+or with one pull request or issue. Same product — `--pr` / `--issue` / `--github` is one extra
+filter. It is a live query, not a curated gallery. Use a gallery when you pick the files; use
+a repo feed for the latest shots across a repo; use a PR feed when reviewers should see only
+that pull request. The API returns the canonical public URL.
+
+```bash
+uploads feed create --repo owner/repo
+uploads feed create --repo owner/repo --pr 123
+uploads feed create --github owner/repo#123
+uploads feed create --repo owner/repo --path /settings
+```
+
+Creating the same scope again returns the existing URL. Anyone who knows that URL can
+view the feed. Each shot also has `/c/<id>/<item>` with previous / next. Syncing a
+managed PR comment creates the PR feed if needed and points image clicks at that pager.
+MCP: `feed_create` (`repo`, plus `pr` / `issue` / `github` / `path`) and `feed_get`.
+
 Link a gallery to a GitHub issue or pull request with `gallery link --github`. Run `uploads comment --pr <number>` to refresh that target’s one managed comment with every linked gallery and loose attachment. Coordinates and strict `https://github.com/<owner>/<repo>/issues|pull/<number>` URLs are accepted; `gallery list --github` performs the authenticated reverse lookup. Links never change gallery identity, and GitHub repository visibility does not make the public gallery private.
 
 Config layers (first match wins): CLI flags → env vars → `--env-file` → `~/.config/buildinternet/config`. See `config.example` for keys.
 
 ## MCP server
 
-`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `whoami`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`whoami` needs no auth).
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows (`gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, `gallery_find_by_reference`) and change feeds (`feed_create`, `feed_get` — pass `pr` or `github` to scope a feed to one pull request). Gallery and feed tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `whoami`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`whoami` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
@@ -208,7 +230,7 @@ Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. C
 
 The MCP Registry lists this server as `sh.uploads/mcp`.
 
-For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP with whichever of Claude Code, Codex, and Grok are on PATH (a missing CLI is skipped) + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations (including `get_metadata` / `set_metadata` / `find_files`) plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, `gallery_find_by_reference`, `feed_create`, and `feed_get`; all use the same bearer-token workspace scopes and gallery/feed URLs come from the API — see `apps/mcp` in the repo. The hosted `put` also accepts a `metadata` param. `uploads install` registers the skills + hosted MCP with whichever of Claude Code, Codex, and Grok are on PATH (a missing CLI is skipped) + Grok/Cursor hooks (short progress; `--verbose` for underlying output). Claude and Codex use their plugins for the same pre-PR screenshot reminder (`uploads hook pre-pr-screenshot`). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use
 

package/dist/cli-catalog.js

@@ -156,6 +156,16 @@ export const ROOT_COMMANDS = [
             { name: "unlink", summary: "Unlink a gallery from GitHub" },
         ],
     },
+    {
+        name: "feed",
+        summary: "Create a public newest-first screenshot feed for a GitHub repo or pull request",
+        subcommands: [
+            { name: "create", summary: "Create or reuse a repo or PR change feed" },
+            { name: "show", summary: "Show a feed" },
+            { name: "list", summary: "List feeds" },
+            { name: "delete", summary: "Delete a feed record" },
+        ],
+    },
     {
         name: "comment",
         summary: "Create/update a PR/issue attachments comment (via gh)",
@@ -237,6 +247,11 @@ export const ROOT_COMMANDS = [
         name: "changelog",
         summary: "Show recent product updates (and a link to the full changelog)",
     },
+    {
+        name: "docs",
+        summary: "Search public uploads.sh docs (or fetch one page as markdown)",
+        usage: "docs [query]",
+    },
     {
         name: "login",
         summary: "Sign in via browser (or an enrollment code) and save credentials",

package/dist/cli-help.js

@@ -165,6 +165,7 @@ ${section(style, "Examples:")}
   ${style.command("uploads attach")} ./artifact.zip --issue 45 --no-comment
   ${style.command("uploads attach")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads gallery")} create --title "Release screenshots"
+  ${style.command("uploads feed")} create --repo owner/repo
   ${style.command("uploads doctor")}
   ${style.command("uploads logout")}
   ${style.command("uploads --version")}

package/dist/cli.js

@@ -7,6 +7,7 @@ import { commandSummary, suggestCommand } from "./cli-suggest.js";
 import { writeJson } from "./io.js";
 import { colorEnabled, createStyle } from "./cli-style.js";
 import { runPut, runAttach, runStaged, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runGithub, runIngest, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { runFeed } from "./commands/feed.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
@@ -17,6 +18,7 @@ import { runInstall } from "./commands/install.js";
 import { runHook } from "./commands/hook.js";
 import { runUpdate } from "./commands/update.js";
 import { runChangelog } from "./commands/changelog.js";
+import { runDocs } from "./commands/docs.js";
 import { runCompletion } from "./commands/completion.js";
 import { runLogout, runWhoami } from "./commands/session.js";
 import { runTelemetry } from "./commands/telemetry.js";
@@ -243,6 +245,10 @@ export async function runCli(argv) {
                 // Public feed — no token, independent of the API origin.
                 code = await runChangelog(cmdArgs, { json }, showHelp);
                 break;
+            case "docs":
+                // Public catalog — no token, independent of the API origin.
+                code = await runDocs(cmdArgs, { json }, showHelp);
+                break;
             case "config":
                 code = await runConfig(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
                 break;
@@ -304,6 +310,7 @@ export async function runCli(argv) {
             case "staged":
             case "screenshot":
             case "gallery":
+            case "feed":
             case "list":
             case "find":
             case "meta":
@@ -332,6 +339,9 @@ export async function runCli(argv) {
                     case "gallery":
                         code = await runGallery(ctx, cmdArgs, showHelp);
                         break;
+                    case "feed":
+                        code = await runFeed(ctx, cmdArgs, showHelp);
+                        break;
                     case "comment":
                         code = await runComment(ctx, cmdArgs, showHelp);
                         break;

package/dist/client.d.ts

@@ -257,6 +257,59 @@ export interface FindGalleriesByReferenceOptions {
     limit?: number;
     cursor?: string;
 }
+/** A workspace-owned, query-backed public repo change feed. */
+export interface FeedItem {
+    id: string;
+    objectKey: string;
+    filename: string;
+    status: "available" | "missing" | "withheld";
+    url: string | null;
+    embedUrl: string | null;
+    /** Canonical `/c/<id>/<item>` page when the API computed one. */
+    pageUrl?: string;
+    contentType: string | null;
+    size: number | null;
+    uploaded: string | null;
+    modified: string | null;
+    path: string | null;
+    state: string | null;
+    posterUrl?: string;
+    videoDimensions?: {
+        width: number;
+        height: number;
+    };
+}
+export interface Feed {
+    id: string;
+    /** Canonical public URL returned by the API; clients must not construct it. */
+    url: string;
+    workspace: string;
+    repo: string;
+    path: string | null;
+    number: number | null;
+    kind: "pull" | "issue" | null;
+    title: string;
+    createdAt: string;
+    updatedAt: string;
+    items: FeedItem[];
+}
+export type FeedSummary = Omit<Feed, "items">;
+export interface FeedListOptions {
+    limit?: number;
+    cursor?: string;
+}
+export interface FeedListResult {
+    feeds: FeedSummary[];
+    nextCursor: string | null;
+}
+export interface CreateFeedOptions {
+    repo: string;
+    path?: string | null;
+    number?: number | null;
+    kind?: "pull" | "issue" | null;
+    pr?: number | null;
+    issue?: number | null;
+}
 /**
  * Reasons the bot did not post. The CLI falls back to the local `gh` path
  * for all of these except `not_authorized` (issue #297 baseline control):
@@ -734,6 +787,13 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         id: string;
     }>;
     findGalleriesByReference(opts: FindGalleriesByReferenceOptions): Promise<GalleryListResult>;
+    createFeed(opts: CreateFeedOptions): Promise<Feed>;
+    getFeed(id: string): Promise<Feed>;
+    listFeeds(opts?: FeedListOptions): Promise<FeedListResult>;
+    deleteFeed(id: string): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
     /**
      * Upsert the managed attachments comment. `resync: true` marks an
      * explicit "make the comment state correct" call (`uploads comment`), so

package/dist/client.js

@@ -307,6 +307,9 @@ function usageBase(config) {
 function galleriesBase(config) {
     return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/galleries`;
 }
+function feedsBase(config) {
+    return `${config.apiUrl}/v1/workspaces/${encodeURIComponent(config.workspace)}/feeds`;
+}
 function mapApiError(status, error, code, requiredScope, existingUrl) {
     const normalized = error.toLowerCase();
     if (status === 401 || code === "unauthorized" || normalized === "unauthorized") {
@@ -652,6 +655,27 @@ export function createUploadsClient(config) {
                 params.set("cursor", opts.cursor);
             return request("GET", galleriesBase(config) + "/by-reference?" + params);
         },
+        async createFeed(opts) {
+            return request("POST", feedsBase(config), {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        async getFeed(id) {
+            return request("GET", `${feedsBase(config)}/${encodeURIComponent(id)}`);
+        },
+        async listFeeds(opts = {}) {
+            const params = new URLSearchParams();
+            if (opts.limit != null)
+                params.set("limit", String(opts.limit));
+            if (opts.cursor)
+                params.set("cursor", opts.cursor);
+            const qs = params.toString();
+            return request("GET", `${feedsBase(config)}${qs ? `?${qs}` : ""}`);
+        },
+        async deleteFeed(id) {
+            return request("DELETE", `${feedsBase(config)}/${encodeURIComponent(id)}`);
+        },
         /**
          * Upsert the managed attachments comment. `resync: true` marks an
          * explicit "make the comment state correct" call (`uploads comment`), so

package/dist/commands/docs.d.ts

@@ -0,0 +1,8 @@
+import { type SearchDocsOptions } from "../docs.js";
+export interface RunDocsOptions {
+    json?: boolean;
+    fetch?: SearchDocsOptions["fetchImpl"];
+    url?: string;
+    catalog?: SearchDocsOptions["catalog"];
+}
+export declare function runDocs(args: string[], opts?: RunDocsOptions, help?: boolean): Promise<number>;

package/dist/commands/docs.js

@@ -0,0 +1,67 @@
+import { flagBool, flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { UploadsError } from "../errors.js";
+import { DEFAULT_DOCS_LIMIT, MAX_DOCS_LIMIT, formatDocsHuman, searchDocs, } from "../docs.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { writeJson, writeStdout } from "../io.js";
+const DOCS_HELP = `uploads docs — search public uploads.sh documentation
+
+Lists the docs catalog, searches by topic, or fetches one page as markdown.
+
+Usage:
+  uploads docs [query…] [options]
+
+Options:
+  --page <slug>  Fetch the full markdown of one page (slug, path, or URL)
+  --limit <n>    Number of search hits to show (default ${DEFAULT_DOCS_LIMIT}, max ${MAX_DOCS_LIMIT})
+  --json         JSON on stdout (also accepts global --json)
+
+Examples:
+  uploads docs
+  uploads docs stage before a PR
+  uploads docs attach
+  uploads docs --page agents
+  uploads docs --json "github app"
+`;
+export async function runDocs(args, opts = {}, help = false) {
+    const parsed = parseCommandArgs(args);
+    if (help || parsed.help) {
+        writeCommandHelp(DOCS_HELP);
+        return 0;
+    }
+    const json = Boolean(opts.json) || flagBool(parsed.flags, "--json");
+    const page = flagString(parsed.flags, "--page");
+    const limit = flagInt(parsed.flags, "--limit", "--limit");
+    if (limit !== undefined && limit > MAX_DOCS_LIMIT) {
+        throw new UsageError(`--limit must be ${MAX_DOCS_LIMIT} or less (got ${limit})`, {
+            example: `uploads docs --limit ${MAX_DOCS_LIMIT}`,
+        });
+    }
+    const query = parsed.positionals.join(" ").trim();
+    if (page && query) {
+        throw new UsageError("pass a search query or --page, not both", {
+            example: "uploads docs --page attach",
+        });
+    }
+    let doc;
+    try {
+        doc = await searchDocs({
+            query: query || undefined,
+            page: page || undefined,
+            limit,
+            fetchImpl: opts.fetch,
+            url: opts.url,
+            catalog: opts.catalog,
+        });
+    }
+    catch (err) {
+        if (err instanceof UploadsError && err.code === "USAGE") {
+            throw new UsageError(err.message, { example: "uploads docs --page attach" });
+        }
+        throw err;
+    }
+    if (json)
+        await writeJson(doc);
+    else
+        await writeStdout(formatDocsHuman(doc));
+    return 0;
+}

package/dist/commands/feed.d.ts

@@ -0,0 +1,2 @@
+import type { CliContext } from "../commands.js";
+export declare function runFeed(ctx: CliContext, args: string[], help?: boolean): Promise<number>;

package/dist/commands/feed.js

@@ -0,0 +1,133 @@
+import { flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+import { writeCommandHelp } from "../cli-style.js";
+import { parseGithubIssueRef } from "../github.js";
+import { resolveRepo } from "../github-gh.js";
+import { writeJson, writeStdout } from "../io.js";
+const FEED_HELP = `uploads feed <command> [args]
+
+A public newest-first feed of screenshots tagged with a GitHub owner/repo,
+or one pull request / issue. Same product — pass --pr, --issue, or --github
+to scope it. A gallery is a hand-picked list; a feed is live. Anyone who
+knows the URL can view it. Creating the same scope again returns the
+existing feed.
+
+Commands:
+  create [--repo <owner/repo>] [--pr <n> | --issue <n> | --github <ref>] [--path <page-path>]
+  show <feed-id>
+  list [--limit <n>] [--cursor <c>]
+  delete <feed-id>
+
+Examples:
+  uploads feed create
+  uploads feed create --repo acme/app
+  uploads feed create --repo acme/app --pr 123
+  uploads feed create --github acme/app#123
+  uploads feed create --repo acme/app --path /settings
+  uploads feed show feed_example
+`;
+function resolveCreateOptions(parsed) {
+    const github = flagString(parsed.flags, "--github");
+    const pr = flagInt(parsed.flags, "--pr", "--pr");
+    const issue = flagInt(parsed.flags, "--issue", "--issue");
+    const path = flagString(parsed.flags, "--path");
+    const repoFlag = flagString(parsed.flags, "--repo");
+    if (pr != null && issue != null) {
+        throw new UsageError("--pr and --issue are mutually exclusive", {
+            example: "uploads feed create --repo owner/repo --pr 123",
+        });
+    }
+    if (github && (pr != null || issue != null)) {
+        throw new UsageError("--github cannot be combined with --pr or --issue", {
+            example: "uploads feed create --github owner/repo#123",
+        });
+    }
+    if (github) {
+        const ref = parseGithubIssueRef(github);
+        if (!ref) {
+            throw new UsageError("--github must be owner/repo#number or a GitHub issue/PR URL", {
+                example: "uploads feed create --github owner/repo#123",
+            });
+        }
+        if (repoFlag && repoFlag.trim().toLowerCase() !== ref.repo) {
+            throw new UsageError("--repo does not match --github", {
+                example: "uploads feed create --github owner/repo#123",
+            });
+        }
+        return {
+            repo: ref.repo,
+            path,
+            number: ref.number,
+            kind: ref.kind,
+        };
+    }
+    return {
+        repo: resolveRepo(repoFlag).toLowerCase(),
+        path,
+        ...(pr != null ? { number: pr, kind: "pull" } : {}),
+        ...(issue != null ? { number: issue, kind: "issue" } : {}),
+    };
+}
+export async function runFeed(ctx, args, help = false) {
+    const parsed = parseCommandArgs(args);
+    const action = parsed.positionals[0];
+    if (help || parsed.help) {
+        writeCommandHelp(FEED_HELP);
+        return 0;
+    }
+    if (!action) {
+        throw new UsageError("feed requires a subcommand: create, show, list, or delete", {
+            example: "uploads feed create --repo owner/repo --pr 123",
+        });
+    }
+    switch (action) {
+        case "create": {
+            const feed = await ctx.client.createFeed(resolveCreateOptions(parsed));
+            if (ctx.json)
+                await writeJson(feed);
+            else
+                await writeStdout(`${feed.url}\n`);
+            if (!ctx.quiet && !ctx.json)
+                process.stderr.write("warning: feeds are public to anyone with the URL\n");
+            return 0;
+        }
+        case "show": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("feed show requires a feed ID");
+            const feed = await ctx.client.getFeed(id);
+            if (ctx.json)
+                await writeJson(feed);
+            else
+                await writeStdout(`${feed.url}\n`);
+            return 0;
+        }
+        case "list": {
+            const page = await ctx.client.listFeeds({
+                limit: flagInt(parsed.flags, "--limit", "--limit"),
+                cursor: flagString(parsed.flags, "--cursor"),
+            });
+            if (ctx.json)
+                await writeJson(page);
+            else {
+                for (const feed of page.feeds)
+                    await writeStdout(`${feed.id}  ${feed.url}  ${feed.title}\n`);
+                if (page.nextCursor)
+                    process.stderr.write(`cursor: ${page.nextCursor}\n`);
+            }
+            return 0;
+        }
+        case "delete": {
+            const id = parsed.positionals[1];
+            if (!id)
+                throw new UsageError("feed delete requires a feed ID");
+            const result = await ctx.client.deleteFeed(id);
+            if (ctx.json)
+                await writeJson(result);
+            else if (!ctx.quiet)
+                process.stderr.write(`deleted feed ${result.id}\n`);
+            return 0;
+        }
+        default:
+            throw new UsageError(`unknown feed command: ${action} (expected create, show, list, or delete)`, { example: "uploads feed create --repo owner/repo --pr 123" });
+    }
+}

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

@@ -90,7 +90,7 @@ export interface AttachmentItem {
     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`. */
+    /** Preferred click-through (PR feed item, `/f/` file page, or equivalent). Falls back to `url`. */
     pageUrl?: string | null;
     /**
      * The only canonical metadata the managed comment renders (issue #365).

package/dist/docs.d.ts

@@ -0,0 +1,52 @@
+export declare const DOCS_HUB_URL = "https://uploads.sh/docs";
+export declare const DOCS_JSON_URL = "https://uploads.sh/docs.json";
+export declare const DEFAULT_DOCS_LIMIT = 5;
+export declare const MAX_DOCS_LIMIT = 50;
+export declare const DOCS_SNIPPET_MAX_CHARS = 1500;
+export declare const DOCS_PAGE_MAX_CHARS = 50000;
+export type DocsCatalogPage = {
+    page: string;
+    title: string;
+    url: string;
+    summary: string;
+    aliases: string[];
+};
+export type DocsCatalog = {
+    url: string;
+    pages: DocsCatalogPage[];
+};
+export type DocsSearchHit = {
+    title: string;
+    url: string;
+    page: string;
+    snippet: string;
+    body?: string;
+    truncated?: boolean;
+};
+export type DocsSearchDocument = {
+    url: string;
+    query?: string;
+    results: DocsSearchHit[];
+    total: number;
+};
+export type SearchDocsOptions = {
+    query?: string;
+    page?: string;
+    limit?: number;
+    url?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    userAgent?: string;
+    /** Skip the network catalog fetch (tests). */
+    catalog?: DocsCatalog;
+};
+/** Built-in catalog used when /docs.json is unreachable. */
+export declare const FALLBACK_DOCS_CATALOG: DocsCatalog;
+export declare function parseDocsCatalog(raw: unknown): DocsCatalog;
+export declare function resolveDocsPage(catalog: DocsCatalog, raw: string): DocsCatalogPage | undefined;
+export declare function rankDocsPages(catalog: DocsCatalog, query: string): DocsCatalogPage[];
+export declare function truncateDocsSnippet(text: string, maxChars?: number): string;
+/** Human terminal output for catalog/search hits. A fetched page prints its body. */
+export declare function formatDocsHuman(doc: DocsSearchDocument): string;
+export declare function loadDocsCatalog(opts?: SearchDocsOptions): Promise<DocsCatalog>;
+export declare function searchDocs(opts?: SearchDocsOptions): Promise<DocsSearchDocument>;