unique-sdk 2026.44.0.dev3__tar.gz → 2026.44.0.dev5__tar.gz

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.44.0.dev3
+Version: 2026.44.0.dev5
 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.dev3 → unique_sdk-2026.44.0.dev5}/pyproject.toml

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

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/unique_sdk/cli/cli.py

@@ -58,6 +58,9 @@ from unique_sdk.cli.commands.files import (
 from unique_sdk.cli.commands.files import (
     is_permission_denied_output as _is_permission_denied_output,
 )
+from unique_sdk.cli.commands.files import (
+    is_upload_error_output as _is_upload_error_output,
+)
 from unique_sdk.cli.commands.folders import cmd_mkdir, cmd_mvdir, cmd_rmdir
 from unique_sdk.cli.commands.folders import (
     is_mkdir_error_output as _is_mkdir_error_output,
@@ -67,6 +70,9 @@ from unique_sdk.cli.commands.mcp import (
     is_error_output as _is_mcp_error_output,
 )
 from unique_sdk.cli.commands.navigation import cmd_cd, cmd_ls, cmd_pwd
+from unique_sdk.cli.commands.navigation import (
+    is_ls_error_output as _is_ls_error_output,
+)
 from unique_sdk.cli.commands.read import cmd_read
 from unique_sdk.cli.commands.read import (
     is_error_output as _is_read_error_output,
@@ -99,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,
@@ -322,23 +329,25 @@ def ls(ctx: click.Context, target: str | None) -> None:
       unique-cli ls scope_abc    List by scope ID
     """
     output = cmd_ls(LazyState.get(ctx), target)
-    emit(output)
+    emit(output, is_error=_is_ls_error_output)
 
 
 @main.command()
 @click.argument("name")
 @click.pass_context
 def mkdir(ctx: click.Context, name: str) -> None:
-    """Create a new folder under the current directory.
+    """Create a folder by relative name or absolute path.
 
     \b
-    NAME is the folder name to create. Nested paths are supported
-    (e.g., "A/B/C" creates the full hierarchy).
+    A relative NAME is created under the current directory. An absolute
+    path (starting with /) is created from the root, including under
+    /home-<userId>. Nested paths create the full hierarchy.
 
     \b
     Examples:
       unique-cli mkdir Q2
       unique-cli mkdir "2025/Q1"
+      unique-cli mkdir /home-user_1/second-brain/clients/X
     """
     output = cmd_mkdir(LazyState.get(ctx), name)
     emit(output, is_error=_is_mkdir_error_output)
@@ -421,7 +430,7 @@ def upload(ctx: click.Context, local_path: str, destination: str | None) -> None
       unique-cli upload ./report.pdf /Archive/2025/
     """
     output = cmd_upload(LazyState.get(ctx), local_path, destination)
-    emit(output)
+    emit(output, is_error=_is_upload_error_output)
 
 
 @main.command()
@@ -2119,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}'
@@ -2127,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",
@@ -2183,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,
@@ -2194,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.dev3 → unique_sdk-2026.44.0.dev5}/unique_sdk/cli/commands/files.py

@@ -11,6 +11,7 @@ from typing import Any
 
 import unique_sdk
 from unique_sdk.cli.formatting import format_content_info
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 from unique_sdk.utils.file_io import download_content, upload_file
 
@@ -280,6 +281,18 @@ def _resolve_upload_destination(
         resolved_id = info.get("id")
         if not resolved_id:
             raise ValueError(f"folder not found: {folder_path}")
+        try:
+            actual = canonical_folder_path(
+                state.config.user_id,
+                state.config.company_id,
+                resolved_id,
+            )
+        except (ValueError, unique_sdk.UniqueError) as e:
+            raise ValueError(f"refused to upload to {folder_path}: {e}") from e
+        if not same_folder_path(actual, folder_path):
+            raise ValueError(
+                f"refused to upload to {folder_path}: resolved to {actual}"
+            )
         return resolved_id, display_name
 
     scope_id = state.scope_id
@@ -350,7 +363,12 @@ def cmd_upload(
             versioning_enabled=True,
         )
 
-        content_id = result.id if hasattr(result, "id") else "?"
+        content_id = getattr(result, "id", None)
+        if not content_id:
+            return (
+                f"upload: refused to upload {display_name} to {scope_id}: "
+                "no content id returned"
+            )
         folder_path = unique_sdk.Folder.get_folder_path(
             user_id=state.config.user_id,
             company_id=state.config.company_id,
@@ -358,7 +376,7 @@ def cmd_upload(
         ).get("folderPath", scope_id)
         return f"Uploaded: {display_name} ({content_id}) to {folder_path}"
 
-    except (ValueError, unique_sdk.UniqueError, OSError) as e:
+    except (ValueError, unique_sdk.UniqueError, OSError, RuntimeError) as e:
         return f"upload: {e}"
 
 
@@ -492,6 +510,15 @@ def cmd_mv_file(state: ShellState, old_name: str, new_name: str) -> str:
         return f"mv: {e}"
 
 
+def is_upload_error_output(output: str) -> bool:
+    """Return True when *output* is a ``cmd_upload`` error.
+
+    Success text is ``Uploaded: ...``. Local misses, missing destinations,
+    and API failures all start with ``upload:`` and must exit non-zero.
+    """
+    return output.startswith("upload:")
+
+
 def is_permission_denied_output(output: str) -> bool:
     """Return ``True`` when a file-op result is a permission/scope denial.
 

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/unique_sdk/cli/commands/folders.py

@@ -6,6 +6,7 @@ import os
 
 import unique_sdk
 from unique_sdk.cli.formatting import format_folder_info
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 
 
@@ -40,8 +41,60 @@ def _metadata_filter_denies_folder(state: ShellState, scope_id: str | None) -> b
     return not state.folder_allowed_by_metadata_filter(scope_id)
 
 
+def _existing_folder_id(state: ShellState, folder_path: str) -> str | None:
+    """Return the scope id at *folder_path* when that exact folder exists."""
+    try:
+        info = unique_sdk.Folder.get_info(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            folderPath=folder_path,
+        )
+    except (ValueError, unique_sdk.UniqueError):
+        return None
+    folder_id = info.get("id")
+    if not folder_id:
+        return None
+    try:
+        actual = canonical_folder_path(
+            state.config.user_id,
+            state.config.company_id,
+            folder_id,
+        )
+    except (ValueError, unique_sdk.UniqueError):
+        return None
+    if not same_folder_path(actual, folder_path):
+        return None
+    return folder_id
+
+
+def _created_folder_error(
+    state: ShellState,
+    scope_id: str | None,
+    folder_path: str,
+) -> str | None:
+    """Return an ``mkdir:`` error when *scope_id* is not exactly *folder_path*.
+
+    ``create_paths`` can return the ``/home-<userId>`` id in place of the leaf.
+    A failed lookup is a refusal: printing ``Created:`` would claim the folder
+    exists.
+    """
+    if not scope_id:
+        return f"mkdir: refused to create {folder_path}"
+    try:
+        actual = canonical_folder_path(
+            state.config.user_id,
+            state.config.company_id,
+            scope_id,
+        )
+    except (ValueError, unique_sdk.UniqueError) as e:
+        return f"mkdir: refused to create {folder_path}: {e}"
+    if not same_folder_path(actual, folder_path):
+        return f"mkdir: refused to create {folder_path}: resolved to {actual}"
+    return None
+
+
 def cmd_mkdir(state: ShellState, name: str) -> str:
-    """Create a new folder under the current directory."""
+    """Create a folder by relative name or absolute path."""
     # A per-message metaDataFilter *replaces* the static scopeIds, so the
     # static-scope check must not over-deny an in-filter destination; the
     # normalized path is gated against the filter below. See UN-21780.
@@ -49,7 +102,7 @@ def cmd_mkdir(state: ShellState, name: str) -> str:
         state.workspace_metadata_filter is None
         and not state.is_folder_target_within_workspace(name)
     ):
-        return "mkdir: permission denied (outside workspace scope)"
+        return f"mkdir: permission denied: refused {name} (outside workspace scope)"
     # Resolve the destination (collapsing any `..`) and gate the *path*, not
     # just the current scope id: `mkdir ../../Other/X` would otherwise pass a
     # cwd-only check and create structure outside the per-message task scope.
@@ -68,9 +121,15 @@ def cmd_mkdir(state: ShellState, name: str) -> str:
         )
         created = result.get("createdFolders", [])
         if created:
-            last = created[-1]
-            return f"Created: {full_path} ({last['id']})"
-        return f"Created: {full_path}"
+            last_id = created[-1].get("id")
+            mismatch = _created_folder_error(state, last_id, full_path)
+            if mismatch:
+                return mismatch
+            return f"Created: {full_path} ({last_id})"
+        existing_id = _existing_folder_id(state, full_path)
+        if existing_id:
+            return f"Created: {full_path} ({existing_id})"
+        return f"mkdir: refused to create {full_path}"
     except (ValueError, unique_sdk.UniqueError) as e:
         return f"mkdir: {e}"
 

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/unique_sdk/cli/commands/navigation.py

@@ -7,6 +7,7 @@ from typing import Any
 import unique_sdk
 from unique_sdk.cli.formatting import format_ls
 from unique_sdk.cli.metadata_filter import _collect_filter_targets
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.state import ShellState
 
 
@@ -23,13 +24,73 @@ def cmd_cd(state: ShellState, target: str) -> str:
         return f"cd: {e}"
 
 
+def _canonical_listing_error(
+    state: ShellState,
+    label: str,
+    claimed_path: str,
+    scope_id: str,
+) -> str | None:
+    """Return an ``ls:`` error when *scope_id* is not exactly *claimed_path*.
+
+    ``get_info`` can hand back an ancestor for ``/home-<userId>/...``. The
+    comparison runs before any rows are trusted, including when that ancestor
+    has children. A failed lookup is an error: printing ``(empty)`` would hide
+    it.
+    """
+    try:
+        actual = canonical_folder_path(
+            state.config.user_id,
+            state.config.company_id,
+            scope_id,
+        )
+    except (ValueError, unique_sdk.UniqueError) as e:
+        return f"ls: cannot list {label}: {e}"
+    if not same_folder_path(actual, claimed_path):
+        return (
+            f"ls: cannot list {label}: resolved to {actual} instead (not listable here)"
+        )
+    return None
+
+
+def _counts_without_rows_error(
+    label: str,
+    total_folders: int,
+    total_files: int,
+) -> str | None:
+    """Return an ``ls:`` error when the API reports rows it did not return."""
+    if total_folders or total_files:
+        return (
+            f"ls: cannot list {label}: listing returned no entries "
+            f"({total_folders} folder(s), {total_files} file(s) reported)"
+        )
+    return None
+
+
+def _with_unlistable_marker(output: str, unlistable: list[str]) -> str:
+    """Append folders that could not be listed, or fail when none could."""
+    if not unlistable:
+        return output
+    if output.startswith("(empty)"):
+        return "ls: cannot list " + ", ".join(unlistable) + " (not listable)"
+    return output + "\nnot listable: " + ", ".join(unlistable)
+
+
+def is_ls_error_output(output: str) -> bool:
+    """Return True when *output* is a ``cmd_ls`` error.
+
+    Success listings start with a table, ``(empty)``, or a count. Failures
+    start with ``ls:`` and must exit non-zero from the one-shot CLI.
+    """
+    return output.startswith("ls:")
+
+
 def cmd_ls(state: ShellState, target: str | None = None) -> str:
     """List folders and files at the given (or current) path."""
     try:
         if target is not None:
-            _, scope_id = state.resolve_path(target)
+            resolved_path, scope_id = state.resolve_path(target)
         else:
-            scope_id = state.scope_id
+            resolved_path, scope_id = state.cwd, state.scope_id
 
         # A non-root target must lie inside the per-message scope: without
         # this, `ls <path>` would enumerate out-of-scope folders/files that
@@ -56,6 +117,7 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
             # UN-21780.
             folder_ids = state.navigable_folder_ids()
             scoped_folders: list[Any] = []
+            unlistable_folders: list[str] = []
             for sid in folder_ids:
                 try:
                     scoped_folders.append(
@@ -66,7 +128,7 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                         )
                     )
                 except unique_sdk.UniqueError:
-                    pass
+                    unlistable_folders.append(sid)
             scoped_files: list[Any] = []
             for cid in content_ids:
                 # A contentId mentioned in the filter is not necessarily in
@@ -93,12 +155,13 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                 f"\n{len(scoped_folders)} folder(s), {len(scoped_files)} "
                 "file(s) in task scope"
             )
-            return output + summary
+            return _with_unlistable_marker(output + summary, unlistable_folders)
 
         # When at root with a workspace restriction, show only the allowed scope
         # folders — the agent must not see the full company folder tree.
         if scope_id is None and state.workspace_scope_ids:
             folders: list[Any] = []
+            unlistable_folders = []
             for ws_id in state.workspace_scope_ids:
                 try:
                     info = unique_sdk.Folder.get_info(
@@ -108,10 +171,21 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
                     )
                     folders.append(info)
                 except unique_sdk.UniqueError:
-                    pass
+                    unlistable_folders.append(ws_id)
             output = format_ls(folders, [])
             summary = f"\n{len(folders)} folder(s), 0 file(s)"
-            return output + summary
+            return _with_unlistable_marker(output + summary, unlistable_folders)
+
+        if scope_id:
+            label = target if target is not None else resolved_path
+            path_error = _canonical_listing_error(
+                state,
+                label,
+                resolved_path,
+                scope_id,
+            )
+            if path_error:
+                return path_error
 
         folder_params: dict[str, Any] = {}
         content_params: dict[str, Any] = {}
@@ -136,6 +210,16 @@ def cmd_ls(state: ShellState, target: str | None = None) -> str:
         total_folders = folder_result.get("totalCount", len(folders))
         total_files = content_result.get("totalCount", len(files))
 
+        if scope_id and not folders and not files:
+            label = target if target is not None else resolved_path
+            counts_error = _counts_without_rows_error(
+                label,
+                total_folders,
+                total_files,
+            )
+            if counts_error:
+                return counts_error
+
         # With a per-message filter, listing inside an allowed folder must not
         # reveal files the filter excludes (e.g. a combined folder + contentId
         # allowlist): read/cite would deny them, so ls must hide them too.

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/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.dev5/unique_sdk/cli/paths.py

@@ -0,0 +1,42 @@
+"""Folder-path comparisons shared by the CLI commands."""
+
+from __future__ import annotations
+
+import os
+
+import unique_sdk
+
+
+def same_folder_path(left: str, right: str) -> bool:
+    """True when two folder paths name the same location.
+
+    A missing leading slash and a trailing slash do not make two paths differ.
+    """
+
+    def norm(value: str) -> str:
+        text = value.strip()
+        if text and not text.startswith("/"):
+            text = f"/{text}"
+        return os.path.normpath(text.rstrip("/")) or "/"
+
+    return norm(left) == norm(right)
+
+
+def canonical_folder_path(user_id: str, company_id: str, scope_id: str) -> str:
+    """Return the stored path for *scope_id*.
+
+    Raises:
+        ValueError: The folder has no path.
+        unique_sdk.UniqueError: The path lookup failed.
+    """
+    actual = (
+        unique_sdk.Folder.get_folder_path(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=scope_id,
+        ).get("folderPath")
+        or ""
+    )
+    if not actual:
+        raise ValueError(f"folder {scope_id} has no path")
+    return actual

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/unique_sdk/cli/shell.py

@@ -239,12 +239,13 @@ class UniqueShell(cmd.Cmd):
     # -- Folder operations --
 
     def do_mkdir(self, arg: str) -> None:
-        """Create a new folder under the current directory.
+        """Create a folder by relative name or absolute path.
 
         Usage: mkdir <name>
 
-        Creates a child folder with the given name. Nested paths are
-        supported (e.g., "A/B/C" creates the full hierarchy).
+        A relative name is created under the current directory. An absolute
+        path (starting with /) is created from the root, including under
+        /home-<userId>. Nested paths create the full hierarchy.
 
         Examples:
           /Reports> mkdir Q2
@@ -252,6 +253,9 @@ class UniqueShell(cmd.Cmd):
 
           /Reports> mkdir "2025/Q1"
           Created: /Reports/2025/Q1 (scope_xyz999)
+
+          /> mkdir /home-user_1/second-brain/clients/X
+          Created: /home-user_1/second-brain/clients/X (scope_home1)
         """
         name = arg.strip()
         if not name:

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/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

{unique_sdk-2026.44.0.dev3 → unique_sdk-2026.44.0.dev5}/unique_sdk/cli/state.py

@@ -10,6 +10,7 @@ from typing import Any
 import unique_sdk
 from unique_sdk.cli.config import Config
 from unique_sdk.cli.metadata_filter import MetadataFilter
+from unique_sdk.cli.paths import canonical_folder_path, same_folder_path
 from unique_sdk.cli.workspace import manifest_path as workspace_manifest_path
 
 _SEARCH_CONFIG_FILENAME = ".unique-search.json"
@@ -561,6 +562,19 @@ class ShellState:
     def prompt(self) -> str:
         return f"{self._path}> "
 
+    def _enter_folder(self, scope_id: str, folder_path: str) -> str:
+        """Store *folder_path* only when *scope_id* is that exact folder."""
+        actual = canonical_folder_path(
+            self.config.user_id,
+            self.config.company_id,
+            scope_id,
+        )
+        if not same_folder_path(actual, folder_path):
+            raise ValueError(f"cannot change to {folder_path}: resolved to {actual}")
+        self._scope_id = scope_id
+        self._path = folder_path
+        return self._path
+
     def cd(self, target: str) -> str:
         """Change directory. Returns the new path.
 
@@ -590,8 +604,7 @@ class ShellState:
                     company_id=self.config.company_id,
                     folderPath=parent,
                 )
-                self._path = parent
-                self._scope_id = info["id"]
+                return self._enter_folder(info["id"], parent)
             return self._path
 
         if target.startswith("scope_"):
@@ -619,9 +632,7 @@ class ShellState:
             company_id=self.config.company_id,
             folderPath=resolved_path,
         )
-        self._scope_id = info["id"]
-        self._path = resolved_path
-        return self._path
+        return self._enter_folder(info["id"], resolved_path)
 
     def resolve_path(self, target: str | None) -> tuple[str, str | None]:
         """Resolve a target to (path, scope_id) without changing state.