unique-sdk 2026.44.0.dev4__tar.gz → 2026.44.0.dev6__tar.gz

{unique_sdk-2026.44.0.dev4 → unique_sdk-2026.44.0.dev6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.44.0.dev4
+Version: 2026.44.0.dev6
 Summary: 
 Author: Martin Fadler, Konstantin Krauss, Andreas Hauri
 Author-email: Martin Fadler <martin.fadler@unique.ch>, Konstantin Krauss <konstantin@unique.ch>, Andreas Hauri <andreas@unique.ch>

{unique_sdk-2026.44.0.dev4 → unique_sdk-2026.44.0.dev6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_sdk"
-version = "2026.44.0.dev4"
+version = "2026.44.0.dev6"
 description = ""
 readme = "README.md"
 license = { text = "MIT" }

{unique_sdk-2026.44.0.dev4 → unique_sdk-2026.44.0.dev6}/unique_sdk/cli/cli.py

@@ -105,6 +105,7 @@ from unique_sdk.cli.commands.subagent import (
 from unique_sdk.cli.commands.web_search import (
     cmd_web_crawl,
     cmd_web_search,
+    cmd_web_search_many,
 )
 from unique_sdk.cli.commands.web_search import (
     is_error_output as _is_web_search_error_output,
@@ -2127,6 +2128,7 @@ Examples:
   unique-cli web-search search "quarterly earnings 2026"
   unique-cli web-search search "AI regulation" -n 10
   unique-cli web-search search "python tutorial" --json
+  unique-cli web-search search "git history" "redis history" "docker history"
   unique-cli web-search search "sustainability" --include-content --json
   unique-cli web-search search "tax reform" \\
     --engine-config '{"searchEngineName":"Google","fetchSize":3}'
@@ -2135,7 +2137,7 @@ Examples:
 
 
 @web_search_group.command("search", help=_SEARCH_HELP)
-@click.argument("query")
+@click.argument("queries", nargs=-1, required=True)
 @click.option(
     "--fetch-size",
     "-n",
@@ -2191,7 +2193,7 @@ Examples:
 @click.pass_context
 def web_search_search_cmd(
     ctx: click.Context,
-    query: str,
+    queries: tuple[str, ...],
     fetch_size: int | None,
     include_content: bool,
     engine_config_raw: str | None,
@@ -2202,17 +2204,30 @@ def web_search_search_cmd(
 ) -> None:
     """Search the web via the Unique public API."""
     resolved_config = _resolve_web_search_config_path(ctx, config_path)
-    output = cmd_web_search(
-        LazyState.get(ctx),
-        query,
-        fetch_size=fetch_size,
-        include_content=include_content,
-        engine_config_raw=engine_config_raw,
-        crawler_config_raw=crawler_config_raw,
-        output_json=output_json,
-        config_path=resolved_config,
-        chat_id=_resolve_cli_chat_id(ctx, chat_id),
-    )
+    if len(queries) == 1:
+        output = cmd_web_search(
+            LazyState.get(ctx),
+            queries[0],
+            fetch_size=fetch_size,
+            include_content=include_content,
+            engine_config_raw=engine_config_raw,
+            crawler_config_raw=crawler_config_raw,
+            output_json=output_json,
+            config_path=resolved_config,
+            chat_id=_resolve_cli_chat_id(ctx, chat_id),
+        )
+    else:
+        output = cmd_web_search_many(
+            LazyState.get(ctx),
+            list(queries),
+            fetch_size=fetch_size,
+            include_content=include_content,
+            engine_config_raw=engine_config_raw,
+            crawler_config_raw=crawler_config_raw,
+            output_json=output_json,
+            config_path=resolved_config,
+            chat_id=_resolve_cli_chat_id(ctx, chat_id),
+        )
     _emit_web_search(ctx, output)
 
 

{unique_sdk-2026.44.0.dev4 → unique_sdk-2026.44.0.dev6}/unique_sdk/cli/commands/files.py

@@ -38,6 +38,12 @@ _SUPPORTED_UPLOAD_MIME_TYPES = {
     ".md": "text/markdown",
 }
 
+# Bounds so one name resolve can never page through the whole knowledge base.
+_MAX_RESOLVE_MATCH_CANDIDATES = 100
+_MAX_RESOLVE_INFOS_PAGES = 10
+_RESOLVE_INFOS_PAGE_SIZE = 100
+_MAX_RESOLVE_INFOS_ENTRIES = _MAX_RESOLVE_INFOS_PAGES * _RESOLVE_INFOS_PAGE_SIZE
+
 
 def _normalize_unique_file_path(cwd: str, path: str) -> str:
     """Normalize a Unique file path without allowing traversal above root."""
@@ -79,6 +85,7 @@ def _resolve_content_id(
         return name_or_id, name_or_id
 
     lookup_name = name_or_id
+    folder_path = state.cwd
     scope_id = state.scope_id
     if "/" in name_or_id:
         unique_path = _normalize_unique_file_path(state.cwd, name_or_id)
@@ -124,16 +131,10 @@ def _resolve_content_id(
         if not scope_id:
             raise ValueError(f"folder not found: {folder_path}")
     elif scope_id is None:
-        # A bare file name with no folder context resolves via an *unparented*
-        # Content.get_infos scan across the whole knowledge base.
+        # Resolving a bare name at the root would page the whole knowledge base.
         if state.workspace_metadata_filter is not None:
-            # With a per-message filter active, a whole-KB filename scan would
-            # discover documents outside the task scope before the per-id gate
-            # runs — and the deny-vs-not-found distinction is an existence/title
-            # oracle across the task boundary. That is broader than the
-            # ls/read-at-root gating intent, so require a bounded context
-            # instead. The cont_ fast-path, an explicit in-scope path, or a
-            # ``cd`` into an in-scope folder all still work. See UN-21780.
+            # With a per-message filter active that is also a cross-scope
+            # existence/title oracle. See UN-21780.
             raise ValueError(
                 f"permission denied: {name_or_id} can't be resolved by name at "
                 f"the knowledge-base root while a task scope is active "
@@ -141,51 +142,180 @@ def _resolve_content_id(
                 "by content id, or 'cd' into an in-scope folder."
             )
         if not state.is_within_workspace():
-            # No per-message filter: defer to the static scopeIds boundary.
             raise ValueError("permission denied (outside workspace scope)")
+        raise ValueError(
+            f"{name_or_id} can't be resolved by name at the knowledge-base "
+            "root. Use 'unique-cli search', pass a content id (cont_...), "
+            "or 'cd' into a folder first."
+        )
+
+    return _resolve_content_id_in_folder(
+        state=state,
+        name_or_id=name_or_id,
+        lookup_name=lookup_name,
+        folder_path=folder_path,
+        scope_id=scope_id,
+        allow_chat_files=allow_chat_files,
+    )
+
+
+def _resolve_content_id_in_folder(
+    *,
+    state: ShellState,
+    name_or_id: str,
+    lookup_name: str,
+    folder_path: str,
+    scope_id: str,
+    allow_chat_files: bool,
+) -> tuple[str, str]:
+    """Resolve ``lookup_name`` inside one folder without paging the whole KB."""
+    match = _pick_match(
+        hits=_hits_by_file_path(
+            state=state,
+            folder_path=folder_path,
+            lookup_name=lookup_name,
+            scope_id=scope_id,
+        ),
+        lookup_name=lookup_name,
+    )
+    capped = False
+    if match is None:
+        hits, capped = _hits_by_search(
+            state=state, lookup_name=lookup_name, scope_id=scope_id
+        )
+        match = _pick_match(hits=hits, lookup_name=lookup_name)
+    if match is None:
+        if capped:
+            raise ValueError(
+                f"File not found in the first {_MAX_RESOLVE_INFOS_ENTRIES} "
+                f"entries of this folder: {name_or_id}. Use 'unique-cli "
+                "search' or pass a content id (cont_...)."
+            )
+        raise ValueError(f"File not found: {name_or_id}")
+
+    resolved_id, display_name = match
+    # Gate the *resolved* id too: resolving by file name or path must not
+    # bypass the per-message metadata-filter scope that the cont_ fast-path
+    # above enforces, and must honour the same read-only chat-file
+    # exemption (so rm/mv by name can't reach an out-of-scope attachment
+    # either). See UN-21780.
+    if not state.is_content_within_workspace(
+        resolved_id, allow_chat_files=allow_chat_files
+    ):
+        raise ValueError(
+            f"permission denied: {name_or_id} is outside your "
+            f"task scope ({state.scope_denial_hint()}). Use "
+            "'unique-cli search' or 'ls' within that scope "
+            "instead."
+        )
+    return resolved_id, display_name
+
+
+def _hits_by_file_path(
+    *, state: ShellState, folder_path: str, lookup_name: str, scope_id: str
+) -> Sequence[Any]:
+    # One indexed lookup that returns no chunks and also finds files whose
+    # ingestion failed.
+    try:
+        result = unique_sdk.Content.get_info(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            filePath=f"{folder_path.rstrip('/')}/{lookup_name}",
+        )
+    except unique_sdk.UniqueError:
+        return []
+    # A server that ignores filePath returns unrelated content.
+    return [
+        info
+        for info in result.get("contentInfo", [])
+        if info.get("ownerId") == scope_id
+    ]
+
+
+def _hits_by_search(
+    *, state: ShellState, lookup_name: str, scope_id: str
+) -> tuple[Sequence[Any], bool]:
+    """Return the hits, and whether the get_infos fallback hit its page cap."""
+    try:
+        hits = unique_sdk.Content.search(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            where={
+                "AND": [
+                    {"ownerId": {"equals": scope_id}},
+                    {
+                        "OR": [
+                            {"title": {"equals": lookup_name}},
+                            {"key": {"equals": lookup_name}},
+                        ]
+                    },
+                ]
+            },
+            includeFailedContent=True,
+        )
+    except unique_sdk.UniqueError:
+        return _resolve_content_id_via_infos_fallback(
+            state=state,
+            lookup_name=lookup_name,
+            scope_id=scope_id,
+        )
+    return hits, False
+
 
-    params: dict[str, Any] = {}
-    if scope_id:
-        params["parentId"] = scope_id
+def _pick_match(*, hits: Sequence[Any], lookup_name: str) -> tuple[str, str] | None:
+    for content in hits[:_MAX_RESOLVE_MATCH_CANDIDATES]:
+        info = _as_content_fields(content)
+        resolved_id = info.get("id")
+        if not isinstance(resolved_id, str) or not resolved_id:
+            continue
+        title = info.get("title") or ""
+        key = info.get("key") or ""
+        if lookup_name in {title, key}:
+            return resolved_id, title or key
+    return None
 
-    take = 100
+
+def _as_content_fields(content: Any) -> Mapping[str, Any]:
+    if isinstance(content, Mapping):
+        return content
+    return {
+        "id": getattr(content, "id", None),
+        "title": getattr(content, "title", None),
+        "key": getattr(content, "key", None),
+    }
+
+
+def _resolve_content_id_via_infos_fallback(
+    *,
+    state: ShellState,
+    lookup_name: str,
+    scope_id: str,
+) -> tuple[list[Mapping[str, Any]], bool]:
+    """Folder-scoped get_infos fallback with a hard page cap.
+
+    Returns the match (if any), and whether the cap stopped the scan early.
+    """
     skip = 0
-    while True:
+    for _ in range(_MAX_RESOLVE_INFOS_PAGES):
         result = unique_sdk.Content.get_infos(
             user_id=state.config.user_id,
             company_id=state.config.company_id,
+            parentId=scope_id,
             skip=skip,
-            take=take,
-            **params,
+            take=_RESOLVE_INFOS_PAGE_SIZE,
         )
         content_infos = result.get("contentInfos", [])
         if not content_infos:
-            break
-
+            return [], False
         for info in content_infos:
             title = info.get("title") or ""
             key = info.get("key") or ""
             if lookup_name in {title, key}:
-                resolved_id = info["id"]
-                # Gate the *resolved* id too: resolving by file name or path
-                # must not bypass the per-message metadata-filter scope that
-                # the cont_ fast-path above enforces, and must honour the same
-                # read-only chat-file exemption (so rm/mv by name can't reach
-                # an out-of-scope attachment either). See UN-21780.
-                if not state.is_content_within_workspace(
-                    resolved_id, allow_chat_files=allow_chat_files
-                ):
-                    raise ValueError(
-                        f"permission denied: {name_or_id} is outside your "
-                        f"task scope ({state.scope_denial_hint()}). Use "
-                        "'unique-cli search' or 'ls' within that scope "
-                        "instead."
-                    )
-                return resolved_id, title or key
-
+                return [info], False
+        if len(content_infos) < _RESOLVE_INFOS_PAGE_SIZE:
+            return [], False
         skip += len(content_infos)
-
-    raise ValueError(f"File not found: {name_or_id}")
+    return [], True
 
 
 def _detect_upload_mime_type(path: Path) -> str:

{unique_sdk-2026.44.0.dev4 → unique_sdk-2026.44.0.dev6}/unique_sdk/cli/commands/web_search.py

@@ -19,6 +19,7 @@ from __future__ import annotations
 
 import json
 import logging
+from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 from typing import Any, cast
 
@@ -40,6 +41,8 @@ from unique_sdk.cli.workspace import manifest_path as workspace_manifest_path
 _LOGGER = logging.getLogger(__name__)
 
 DEFAULT_PARALLEL = 10
+MAX_SEARCH_QUERIES = 8
+SEARCH_CONCURRENCY = 4
 _SNIPPET_PREVIEW_LIMIT = 200
 _CONTENT_PREVIEW_LIMIT = 500
 _WEB_REFS_LOG_RELATIVE_PATH = Path(".unique") / "web-refs.jsonl"
@@ -231,14 +234,18 @@ def _format_search_results(payload: dict[str, Any]) -> str:
     return "\n".join(lines).rstrip()
 
 
+def _search_results_projection(payload: dict[str, Any]) -> dict[str, Any]:
+    """Stable projection — drops the SDK envelope ``object`` discriminator."""
+    return {
+        "engine": payload.get("engine"),
+        "query": payload.get("query"),
+        "results": payload.get("results", []),
+    }
+
+
 def _format_search_results_json(payload: dict[str, Any]) -> str:
-    """Stable JSON projection — drops the SDK envelope ``object`` discriminator."""
     return json.dumps(
-        {
-            "engine": payload.get("engine"),
-            "query": payload.get("query"),
-            "results": payload.get("results", []),
-        },
+        _search_results_projection(payload),
         indent=2,
         ensure_ascii=False,
     )
@@ -385,6 +392,40 @@ def cmd_web_search(
         chat_id: Optional chat id this call is made on behalf of. When
             set, the space's Web Search toggle is enforced server-side.
     """
+    options = _search_request_options(
+        fetch_size=fetch_size,
+        include_content=include_content,
+        engine_config_raw=engine_config_raw,
+        crawler_config_raw=crawler_config_raw,
+        config_path=config_path,
+        chat_id=chat_id,
+    )
+    if isinstance(options, str):
+        return options
+
+    payload = _fetch_search_payload(state, query, options)
+    if isinstance(payload, str):
+        return payload
+
+    try:
+        payload = _annotate_web_results_for_citations(payload)
+    except UnsafeRefsLogPathError as exc:
+        return f"{WEB_SEARCH_ERROR_PREFIX} {exc}"
+    if output_json:
+        return _format_search_results_json(payload)
+    return _format_search_results(payload)
+
+
+def _search_request_options(
+    *,
+    fetch_size: int | None,
+    include_content: bool,
+    engine_config_raw: str | None,
+    crawler_config_raw: str | None,
+    config_path: str | None,
+    chat_id: str | None,
+) -> dict[str, Any] | str:
+    """Build the request fields shared by every query, or return an error string."""
     file_overrides = _load_file_overrides(config_path)
     if isinstance(file_overrides, str):
         return file_overrides
@@ -402,34 +443,147 @@ def cmd_web_search(
     if fetch_size is None:
         fetch_size = file_overrides.fetch_size
 
-    params: dict[str, Any] = {"query": query}
+    options: dict[str, Any] = {}
     if fetch_size is not None:
-        params["fetchSize"] = fetch_size
+        options["fetchSize"] = fetch_size
     if include_content:
-        params["includeContent"] = True
+        options["includeContent"] = True
     if engine_override is not None:
-        params["searchEngineConfig"] = engine_override
+        options["searchEngineConfig"] = engine_override
     if crawler_override is not None:
-        params["crawlerConfig"] = crawler_override
+        options["crawlerConfig"] = crawler_override
     if chat_id:
-        params["chatId"] = chat_id
+        options["chatId"] = chat_id
+    return options
 
+
+def _fetch_search_payload(
+    state: ShellState,
+    query: str,
+    options: dict[str, Any],
+) -> dict[str, Any] | str:
+    """Run one search request; return the payload, or an error string."""
     try:
         resource = unique_sdk.WebSearch.search(
             user_id=state.config.user_id,
             company_id=state.config.company_id,
-            **params,
+            query=query,
+            **options,
         )
-    except (ValueError, unique_sdk.APIError) as exc:
+    except (ValueError, unique_sdk.UniqueError) as exc:
         return f"{WEB_SEARCH_ERROR_PREFIX} {exc}"
+    return _payload_from_resource(resource)
+
+
+def cmd_web_search_many(
+    state: ShellState,
+    queries: list[str],
+    fetch_size: int | None = None,
+    include_content: bool = False,
+    engine_config_raw: str | None = None,
+    crawler_config_raw: str | None = None,
+    output_json: bool = False,
+    config_path: str | None = None,
+    chat_id: str | None = None,
+) -> str:
+    """Run several web searches in one call and return one block per query.
+
+    Requests run concurrently, at most ``SEARCH_CONCURRENCY`` at a time.
+    Citation numbers are assigned afterwards, one query at a time in the
+    order given, so ``[websourceN]`` is the same on every run. A URL found
+    by several queries keeps one number; the manifest gets one row per search.
+
+    A failed query shows its own error and does not drop the others. The
+    output is a ``web-search:`` error only when every query failed.
+    ``output_json`` returns a list with one entry per query: the usual
+    ``{engine, query, results}`` object, or ``{query, error}`` on failure.
+    """
+    if not queries:
+        return f"{WEB_SEARCH_ERROR_PREFIX} no queries provided."
+    if len(queries) > MAX_SEARCH_QUERIES:
+        return (
+            f"{WEB_SEARCH_ERROR_PREFIX} too many queries ({len(queries)}); "
+            f"the limit is {MAX_SEARCH_QUERIES} per call. "
+            "Split them across several calls."
+        )
+
+    options = _search_request_options(
+        fetch_size=fetch_size,
+        include_content=include_content,
+        engine_config_raw=engine_config_raw,
+        crawler_config_raw=crawler_config_raw,
+        config_path=config_path,
+        chat_id=chat_id,
+    )
+    if isinstance(options, str):
+        return options
+
+    with ThreadPoolExecutor(
+        max_workers=min(SEARCH_CONCURRENCY, len(queries))
+    ) as executor:
+        fetched = list(
+            executor.map(
+                lambda query: _fetch_search_payload(state, query, options), queries
+            )
+        )
+
+    outcomes: list[dict[str, Any] | str] = []
+    for item in fetched:
+        if isinstance(item, str):
+            outcomes.append(item)
+            continue
+        try:
+            outcomes.append(_annotate_web_results_for_citations(item))
+        except UnsafeRefsLogPathError as exc:
+            return f"{WEB_SEARCH_ERROR_PREFIX} {exc}"
+
+    failures = [
+        f"{query!r}: {outcome}"
+        for query, outcome in zip(queries, outcomes, strict=True)
+        if isinstance(outcome, str)
+    ]
+    if len(failures) == len(queries):
+        return (
+            f"{WEB_SEARCH_ERROR_PREFIX} all {len(queries)} queries failed.\n"
+            + "\n".join(failures)
+        )
 
-    try:
-        payload = _annotate_web_results_for_citations(_payload_from_resource(resource))
-    except UnsafeRefsLogPathError as exc:
-        return f"{WEB_SEARCH_ERROR_PREFIX} {exc}"
     if output_json:
-        return _format_search_results_json(payload)
-    return _format_search_results(payload)
+        return _format_many_search_results_json(queries, outcomes)
+    return _format_many_search_results(queries, outcomes)
+
+
+def _format_many_search_results(
+    queries: list[str],
+    outcomes: list[dict[str, Any] | str],
+) -> str:
+    blocks: list[str] = []
+    failed = 0
+    for position, (query, outcome) in enumerate(
+        zip(queries, outcomes, strict=True), start=1
+    ):
+        header = f"=== query {position}/{len(queries)} ==="
+        if isinstance(outcome, str):
+            failed += 1
+            blocks.append(f"{header}\nquery: {query!r}\nERROR: {outcome}")
+            continue
+        blocks.append(f"{header}\n{_format_search_results(outcome)}")
+    if failed:
+        blocks.append(f"{failed} of {len(queries)} queries failed.")
+    return "\n\n".join(blocks)
+
+
+def _format_many_search_results_json(
+    queries: list[str],
+    outcomes: list[dict[str, Any] | str],
+) -> str:
+    entries = [
+        {"query": query, "error": outcome}
+        if isinstance(outcome, str)
+        else _search_results_projection(outcome)
+        for query, outcome in zip(queries, outcomes, strict=True)
+    ]
+    return json.dumps(entries, indent=2, ensure_ascii=False)
 
 
 def cmd_web_crawl(

{unique_sdk-2026.44.0.dev4 → unique_sdk-2026.44.0.dev6}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -99,6 +99,10 @@ unique-cli mv report.pdf "Annual Report 2025.pdf"
 | Content ID | `cont_abc123` | File directly by ID |
 | File path | `/Reports/Q1/report.pdf` | File in a folder |
 
+A bare file name such as `report.pdf` resolves in the current folder. At the
+root (`/`) a bare file name is an error: pass a full path, a content ID, or `cd`
+into the folder first.
+
 ## Upload Destination Resolution
 
 The `upload` command always enables immutable content versioning. It does not expose an unversioned upload mode. Its destination works like Linux `cp`:

{unique_sdk-2026.44.0.dev4 → unique_sdk-2026.44.0.dev6}/unique_sdk/cli/skills/unique-cli-web-search/SKILL.md

@@ -58,6 +58,31 @@ unique-cli web-search search "python tutorial" --json
 unique-cli web-search search "sustainability reports" --include-content --json
 ```
 
+### Several searches: pass every query in ONE call
+
+When you need more than one search (several topics, companies or
+questions), pass all queries as separate arguments of a single `search`
+command. Do **not** run one `unique-cli web-search search` call per query,
+and do not start several in the background: the queries run concurrently
+inside the one call and the answer comes back in one round.
+
+```bash
+unique-cli web-search search "Git first release" "Redis first release" "Docker first release" --json
+```
+
+- Up to 8 queries per call (4 run at the same time). More than 8 is an
+  error: split them across calls.
+- Options such as `-n`, `--include-content` and `--json` apply to every
+  query. With `--include-content`, prefer fewer queries per call: the output
+  grows with every query.
+- Output has one block per query, in the order you gave them, each with
+  its query. `--json` returns a list with one entry per query.
+- `[websourceN]` numbers follow the query order. A URL found by two
+  queries has one number.
+- A query that fails shows its own error and the other queries still
+  return. The command exits `1` only when every query failed.
+- A single query behaves exactly as before.
+
 ### Per-call engine override
 
 Force a specific engine (or any engine-specific knob) without changing server config:
@@ -141,7 +166,7 @@ discriminator:
 
 ## Command Reference
 
-### `unique-cli web-search search <query>`
+### `unique-cli web-search search <query> [<query>...]`
 
 | Option | Short | Default | Description |
 |--------|-------|---------|-------------|
@@ -217,6 +242,28 @@ Found 3 result(s):
 >   | unique-cli web-search crawl --stdin
 > ```
 
+### `search` with several queries (text)
+
+```
+=== query 1/2 ===
+engine: Google    query: 'Git first release'
+Found 1 result(s):
+
+  1. Git history [websource1]
+     https://example.com/git
+     ...
+
+=== query 2/2 ===
+query: 'Redis first release'
+ERROR: web-search: upstream failed
+
+1 of 2 queries failed.
+```
+
+With `--json` the output is a list. Each entry is the usual
+`{engine, query, results}` object, or `{"query": "...", "error": "..."}`
+for a query that failed.
+
 ### `crawl` (text)
 
 ```
@@ -261,7 +308,10 @@ In one-shot mode, the CLI exits **`0`** on success and **`1`** on
 failures (config-file errors, invalid JSON overrides, API errors,
 missing URLs for `crawl`, and citation-manifest I/O failures — e.g.
 when `.unique/web-refs.jsonl` cannot be written or its parent
-directory is unsafe). Error messages are prefixed with
+directory is unsafe). With several queries in one `search` call, a failed
+query alone does not change the exit code: it exits `1` only when every
+query failed, or when the call is invalid (more than 8 queries, bad
+override JSON). Error messages are prefixed with
 `web-search:` or `web-crawl:` so they're easy to grep.
 
 ```bash