unique-sdk 2026.32.0.dev8__tar.gz → 2026.32.0.dev10__tar.gz

{unique_sdk-2026.32.0.dev8 → unique_sdk-2026.32.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.32.0.dev8
+Version: 2026.32.0.dev10
 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.32.0.dev8 → unique_sdk-2026.32.0.dev10}/pyproject.toml

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

{unique_sdk-2026.32.0.dev8 → unique_sdk-2026.32.0.dev10}/unique_sdk/__init__.py

@@ -77,9 +77,6 @@ from unique_sdk.api_resources._message import Message as Message
 from unique_sdk.api_resources._integrated import Integrated as Integrated
 from unique_sdk.api_resources._search import Search as Search
 from unique_sdk.api_resources._content import Content as Content
-from unique_sdk.api_resources._dynamic_frontend import (
-    DynamicFrontend as DynamicFrontend,
-)
 from unique_sdk.api_resources._search_string import SearchString as SearchString
 from unique_sdk.api_resources._short_term_memory import (
     ShortTermMemory as ShortTermMemory,

{unique_sdk-2026.32.0.dev8 → unique_sdk-2026.32.0.dev10}/unique_sdk/cli/cli.py

@@ -31,11 +31,6 @@ from unique_sdk.cli.commands.cite_file import cmd_cite_file
 from unique_sdk.cli.commands.cite_file import (
     is_error_output as _is_cite_error_output,
 )
-from unique_sdk.cli.commands.dynamic_frontend import (
-    cmd_dynamic_frontend_delete,
-    cmd_dynamic_frontend_deploy,
-    cmd_dynamic_frontend_list,
-)
 from unique_sdk.cli.commands.elicitation import (
     DEFAULT_WAIT_TIMEOUT_SECONDS,
     cmd_elicit_ask,
@@ -97,8 +92,6 @@ from unique_sdk.cli.identity import TurnIdentityError, resolve_message_id
 from unique_sdk.cli.shell import UniqueShell
 from unique_sdk.cli.state import ShellState
 
-_DYNAMIC_FRONTEND_ERROR_PREFIX = "dynamic-frontend "
-
 
 def _resolve_cli_message_id(
     ctx: click.Context,
@@ -174,7 +167,6 @@ Examples:
   unique-cli subagent Legal "Review" Invoke a connected space/subagent
   unique-cli web-search search "x"  Search the web via the public API
   unique-cli web-search crawl URL   Crawl a URL via the public API
-  unique-cli dynamic-frontend list  List manageable Dynamic Frontend spaces
   unique-cli browser get-dom        Read the user's live Chrome tab (a11y tree)
   unique-cli agentic-table get-sheet mt_abc123  Show a magic-table sheet summary
 """
@@ -582,101 +574,6 @@ def read_cmd(
     emit(output, is_error=_is_read_error_output)
 
 
-@main.group(name="dynamic-frontend")
-def dynamic_frontend() -> None:
-    """Deploy, list, and delete Dynamic Frontend spaces."""
-
-
-@dynamic_frontend.command(name="deploy")
-@click.option(
-    "--file",
-    "file_path",
-    default=None,
-    type=click.Path(exists=True),
-    help="Path to an upload-ready Dynamic Frontend ZIP bundle.",
-)
-@click.option(
-    "--content-id",
-    default=None,
-    help="Existing Knowledge Base content id for the ZIP bundle.",
-)
-@click.option(
-    "--name",
-    default=None,
-    help="Space display name. Required when creating; optional rename when updating.",
-)
-@click.option(
-    "--space-id", default=None, help="Existing Dynamic Frontend space id to update."
-)
-@click.option(
-    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
-)
-@click.pass_context
-def dynamic_frontend_deploy(
-    ctx: click.Context,
-    file_path: str | None,
-    content_id: str | None,
-    name: str | None,
-    space_id: str | None,
-    output_json: bool,
-) -> None:
-    """Create or update a Dynamic Frontend space.
-
-    \b
-    Examples:
-      unique-cli dynamic-frontend deploy --file ./app.zip --name "Revenue Dashboard"
-      unique-cli dynamic-frontend deploy --content-id content_123 --name "Revenue Dashboard"
-      unique-cli dynamic-frontend deploy --space-id assistant_123 --file ./app.zip
-    """
-    output = cmd_dynamic_frontend_deploy(
-        LazyState.get(ctx),
-        file=file_path,
-        content_id=content_id,
-        name=name,
-        space_id=space_id,
-        output_json=output_json,
-    )
-    click.echo(output)
-    if output.startswith(_DYNAMIC_FRONTEND_ERROR_PREFIX):
-        ctx.exit(1)
-
-
-@dynamic_frontend.command(name="list")
-@click.option(
-    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
-)
-@click.pass_context
-def dynamic_frontend_list(ctx: click.Context, output_json: bool) -> None:
-    """List Dynamic Frontend spaces the current user can manage."""
-    output = cmd_dynamic_frontend_list(LazyState.get(ctx), output_json=output_json)
-    click.echo(output)
-    if output.startswith(_DYNAMIC_FRONTEND_ERROR_PREFIX):
-        ctx.exit(1)
-
-
-@dynamic_frontend.command(name="delete")
-@click.argument("space_id")
-@click.option(
-    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
-)
-@click.pass_context
-def dynamic_frontend_delete(
-    ctx: click.Context, space_id: str, output_json: bool
-) -> None:
-    """Delete a deployed Dynamic Frontend space by its space id.
-
-    \b
-    Example:
-      unique-cli dynamic-frontend delete assistant_123
-    """
-    output = cmd_dynamic_frontend_delete(
-        LazyState.get(ctx), space_id, output_json=output_json
-    )
-    click.echo(output)
-    if output.startswith(_DYNAMIC_FRONTEND_ERROR_PREFIX):
-        ctx.exit(1)
-
-
 @main.command()
 @click.argument("name_or_id")
 @click.pass_context
@@ -1257,9 +1154,24 @@ def elicit() -> None:
     default=DEFAULT_WAIT_TIMEOUT_SECONDS,
     show_default=True,
     help=(
-        "Max seconds to block waiting for the user's response. This also "
-        "sets when the elicitation expires, so the request expires exactly "
-        "when we stop waiting and the chat UI can offer a way to continue."
+        "Max seconds to block waiting for the user's response. Without "
+        "--expires-in, this also sets when the elicitation expires, so the "
+        "request expires exactly when we stop waiting and the chat UI can "
+        "offer a way to continue."
+    ),
+)
+@click.option(
+    "--expires-in",
+    "expires_in_seconds",
+    type=int,
+    default=None,
+    help=(
+        "Seconds before the platform expires the request, decoupled from "
+        "--timeout (the local wait budget). Use this when this process's "
+        "wait budget is shorter than how long a human should realistically "
+        "get to answer (e.g. a harness with its own foreground timeout) -- "
+        "otherwise the request expires under the user before they can "
+        "answer. Defaults to --timeout, exactly matching prior behavior."
     ),
 )
 @click.option(
@@ -1320,6 +1232,7 @@ def elicit_ask(
     chat_id: str | None,
     message_id: str | None,
     timeout: int,
+    expires_in_seconds: int | None,
     poll_interval: float,
     metadata: tuple[str, ...],
     visible: bool = True,
@@ -1332,7 +1245,9 @@ def elicit_ask(
     \b
     Creates a FORM elicitation in the Unique UI with the given MESSAGE
     and blocks until the user responds, the elicitation is declined /
-    cancelled / expired, or --timeout is reached.
+    cancelled / expired, or --timeout is reached. Immediately after
+    creation, before polling starts, a single line is written to stderr:
+    "UNIQUE_ELICITATION_CREATED id=<id> expires_at=<iso8601>".
 
     \b
     Examples:
@@ -1340,6 +1255,8 @@ def elicit_ask(
       unique-cli elicit ask "Confirm deletion of /Archive" --timeout 60
       unique-cli elicit ask "Pick a region" \\
         --schema '{"type":"object","properties":{"region":{"type":"string","enum":["EU","US","APAC"]}},"required":["region"]}'
+      unique-cli elicit ask "Long-running approval" \\
+        --expires-in 7200 --timeout 300
     """
     parsed_metadata: list[tuple[str, str]] = []
     for kv in metadata:
@@ -1356,6 +1273,7 @@ def elicit_ask(
         "chat_id": chat_id,
         "message_id": _resolve_cli_message_id(ctx, message_id),
         "timeout": timeout,
+        "expires_in_seconds": expires_in_seconds,
         "poll_interval": poll_interval,
         "metadata": parsed_metadata or None,
         "visible": visible,

{unique_sdk-2026.32.0.dev8 → unique_sdk-2026.32.0.dev10}/unique_sdk/cli/commands/elicitation.py

@@ -13,8 +13,9 @@ from __future__ import annotations
 
 import json
 import os
+import sys
 import time
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from typing import Any, Literal, cast
 
 import unique_sdk
@@ -37,6 +38,23 @@ TERMINAL_STATUSES = {
     "COMPLETED",
 }
 
+# --- Transient-failure retry (UN-23310) ---------------------------------
+#
+# ``cmd_elicit_wait`` used to return on the very first ``APIError`` /
+# ``APIConnectionError`` raised mid-poll, treating a transient 502 the same
+# as a genuine terminal condition. Now that a single ``elicit ask`` call is
+# expected to carry the whole wait unsupervised, that one dropped connection
+# would otherwise cost the entire turn. These constants bound the retry
+# loop's backoff; the overall ``--timeout`` remains the hard outer bound.
+TRANSIENT_RETRY_BASE_SECONDS = 1.0
+TRANSIENT_RETRY_MAX_BACKOFF_SECONDS = 30.0
+
+# Prefix for the machine-readable line ``cmd_elicit_ask`` writes to stderr
+# immediately after creating the elicitation, before it starts polling. Kept
+# as a module constant so producer (here) and any future consumer/tests stay
+# in lockstep on the exact contract string.
+ELICITATION_CREATED_STDERR_PREFIX = "UNIQUE_ELICITATION_CREATED"
+
 # --- Visibility workaround for UN-19815 ---------------------------------
 #
 # The chat UI (as of 2026-04-21) only renders an elicitation when the host
@@ -632,6 +650,74 @@ def cmd_elicit_respond(
         return f"elicit: {exc}"
 
 
+def _is_transient_api_failure(exc: BaseException) -> bool:
+    """Return ``True`` if *exc* is worth retrying.
+
+    Transient: connection-level failures (timeouts, resets --
+    ``APIConnectionError``) and ``APIError``s with no HTTP status or a 5xx
+    status. Not transient: 4xx client errors, which cannot succeed on
+    retry -- retrying those would just burn the wait budget on a request
+    that is doomed regardless.
+
+    Note ``InvalidRequestError`` / ``AuthenticationError`` / ``PermissionError``
+    are not ``APIError`` subclasses and are not matched here; they propagate
+    unchanged, exactly as they did before this retry logic existed.
+    """
+    if isinstance(exc, unique_sdk.APIConnectionError):
+        return True
+    if isinstance(exc, unique_sdk.APIError):
+        status = getattr(exc, "http_status", None)
+        return status is None or status >= 500
+    return False
+
+
+def _get_elicitation_with_retry(
+    state: ShellState,
+    elicitation_id: str,
+    *,
+    deadline: float,
+) -> dict[str, Any]:
+    """Fetch an elicitation, retrying transient failures with backoff.
+
+    Retries are bounded by *deadline* (a ``time.monotonic()`` timestamp) --
+    once it passes, the last exception is re-raised so the caller's overall
+    ``--timeout`` is always the hard outer bound, never exceeded by retries.
+    Non-transient failures (see :func:`_is_transient_api_failure`) are
+    re-raised immediately without retrying. Each retry is logged to stderr
+    with the attempt number and backoff so a string of dropped connections
+    is diagnosable instead of silently eating the wait budget.
+    """
+    backoff = TRANSIENT_RETRY_BASE_SECONDS
+    attempt = 0
+    while True:
+        try:
+            return dict(
+                unique_sdk.Elicitation.get_elicitation(
+                    user_id=state.config.user_id,
+                    company_id=state.config.company_id,
+                    elicitation_id=elicitation_id,
+                )
+            )
+        except (unique_sdk.APIError, unique_sdk.APIConnectionError) as exc:
+            if not _is_transient_api_failure(exc):
+                raise
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise
+            attempt += 1
+            sleep_for = max(
+                0.0, min(backoff, TRANSIENT_RETRY_MAX_BACKOFF_SECONDS, remaining)
+            )
+            print(
+                f"elicit: transient error on attempt {attempt} fetching "
+                f"{elicitation_id} ({exc}); retrying in {sleep_for:.1f}s",
+                file=sys.stderr,
+            )
+            if sleep_for > 0:
+                time.sleep(sleep_for)
+            backoff = min(backoff * 2, TRANSIENT_RETRY_MAX_BACKOFF_SECONDS)
+
+
 def cmd_elicit_wait(
     state: ShellState,
     elicitation_id: str,
@@ -658,12 +744,10 @@ def cmd_elicit_wait(
     try:
         deadline = time.monotonic() + max(1, timeout)
         while True:
-            elicitation = unique_sdk.Elicitation.get_elicitation(
-                user_id=state.config.user_id,
-                company_id=state.config.company_id,
-                elicitation_id=elicitation_id,
+            elicitation = _get_elicitation_with_retry(
+                state, elicitation_id, deadline=deadline
             )
-            last = dict(elicitation)
+            last = elicitation
             status = str(elicitation.get("status", "")).upper()
             if status in TERMINAL_STATUSES:
                 terminal_status = status
@@ -675,12 +759,8 @@ def cmd_elicit_wait(
                 # same instant; this fetch forces the backend's lazy expiry to
                 # run so we report a clean EXPIRED — and publish it to the chat
                 # subscription — instead of a stale PENDING.
-                final = dict(
-                    unique_sdk.Elicitation.get_elicitation(
-                        user_id=state.config.user_id,
-                        company_id=state.config.company_id,
-                        elicitation_id=elicitation_id,
-                    )
+                final = _get_elicitation_with_retry(
+                    state, elicitation_id, deadline=deadline
                 )
                 last = final
                 final_status = str(final.get("status", "")).upper()
@@ -703,7 +783,7 @@ def cmd_elicit_wait(
                     f"{format_elicitation(last)}"
                 )
             time.sleep(poll_interval)
-    except unique_sdk.APIError as exc:
+    except (unique_sdk.APIError, unique_sdk.APIConnectionError) as exc:
         return f"elicit: {exc}"
     finally:
         # If the poll loop exited before we ever received a response
@@ -720,7 +800,7 @@ def cmd_elicit_wait(
                         elicitation_id=elicitation_id,
                     )
                 )
-            except unique_sdk.APIError:
+            except (unique_sdk.APIError, unique_sdk.APIConnectionError):
                 last = None
         ctx = _extract_visibility_context(last)
         if ctx is not None:
@@ -735,6 +815,36 @@ def cmd_elicit_wait(
             )
 
 
+def _emit_elicitation_created_stderr_line(
+    elicitation_id: str,
+    expires_at: object,
+    expires_in_seconds: int,
+) -> None:
+    """Write the ``UNIQUE_ELICITATION_CREATED`` contract line to stderr.
+
+    Format (stable, greppable, one line, stderr only)::
+
+        UNIQUE_ELICITATION_CREATED id=<id> expires_at=<iso8601>
+
+    Prefers the platform-returned ``expiresAt`` (authoritative); falls back
+    to a locally computed timestamp if the platform omitted it, so the line
+    is always emitted with a usable value.
+    """
+    if isinstance(expires_at, str) and expires_at:
+        resolved_expires_at = expires_at
+    else:
+        resolved_expires_at = (
+            (datetime.now(tz=timezone.utc) + timedelta(seconds=expires_in_seconds))
+            .isoformat(timespec="milliseconds")
+            .replace("+00:00", "Z")
+        )
+    print(
+        f"{ELICITATION_CREATED_STDERR_PREFIX} id={elicitation_id} "
+        f"expires_at={resolved_expires_at}",
+        file=sys.stderr,
+    )
+
+
 def cmd_elicit_ask(
     state: ShellState,
     *,
@@ -745,6 +855,7 @@ def cmd_elicit_ask(
     message_id: str | None = None,
     timeout: int = DEFAULT_WAIT_TIMEOUT_SECONDS,
     poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
+    expires_in_seconds: int | None = None,
     metadata: list[tuple[str, str]] | None = None,
     visible: bool = True,
     assistant_id: str | None = None,
@@ -757,6 +868,23 @@ def cmd_elicit_ask(
     free-text ``answer`` is used. This is the preferred entry point when an
     agent needs to ask the user a clarifying question.
 
+    ``expires_in_seconds``, when given, decouples the server-side expiry
+    (``expiresInSeconds`` sent to the platform) from ``timeout`` (how long
+    *this process* blocks polling). When omitted (the default), behaviour is
+    unchanged from before this parameter existed: the elicitation expires
+    exactly when the local wait gives up, coupling the two. Pass this when
+    the caller's own wait budget (e.g. a harness's foreground timeout) is
+    shorter than how long a human should realistically have to answer --
+    otherwise the elicitation expires under the user before they see it.
+
+    Immediately after creation (before polling starts), a single line is
+    written to stderr for callers that want the elicitation id without
+    polling the pending list:
+
+        UNIQUE_ELICITATION_CREATED id=<id> expires_at=<iso8601>
+
+    This is stderr-only and does not change stdout's format.
+
     When ``chat_id`` is set and ``visible`` is ``True`` (the default), the
     elicitation is wrapped in a placeholder thinking timeline so the chat UI
     actually renders it — see the "Visibility workaround for UN-19815" note
@@ -778,16 +906,17 @@ def cmd_elicit_ask(
                 "required": ["answer"],
             }
 
-        # `ask` exposes a single knob: `--timeout` is both how long we wait and
-        # when the record expires. The two are always the same here, so the
-        # backend's default (5 minutes) never leaves the record PENDING after
-        # we have stopped waiting — which would otherwise prevent the chat UI
-        # from flipping the prompt to EXPIRED and offering the user a way to
-        # continue. The poll loop below reads the freshly EXPIRED record and the
-        # elicitation subscription delivers the terminal status to the chat.
-        # (Use `elicit create --expires-in` if you need expiry decoupled from a
-        # local wait.)
-        expires_in_seconds = timeout
+        # By default `ask` exposes a single knob: `--timeout` is both how long
+        # we wait and when the record expires. The two are the same unless the
+        # caller passes `--expires-in` explicitly, so the backend's default (5
+        # minutes) never leaves the record PENDING after we have stopped
+        # waiting — which would otherwise prevent the chat UI from flipping
+        # the prompt to EXPIRED and offering the user a way to continue. The
+        # poll loop below reads the freshly EXPIRED record and the elicitation
+        # subscription delivers the terminal status to the chat.
+        effective_expires_in_seconds = (
+            expires_in_seconds if expires_in_seconds is not None else timeout
+        )
 
         user_metadata = _parse_metadata_pairs(metadata)
         effective_message_id = message_id
@@ -836,7 +965,7 @@ def cmd_elicit_ask(
             url=None,
             chat_id=chat_id,
             message_id=effective_message_id,
-            expires_in_seconds=expires_in_seconds,
+            expires_in_seconds=effective_expires_in_seconds,
             external_elicitation_id=None,
             metadata=user_metadata,
         )
@@ -856,6 +985,12 @@ def cmd_elicit_ask(
             _cleanup_placeholder_if_needed()
             return "elicit: platform did not return an elicitation id"
 
+        _emit_elicitation_created_stderr_line(
+            elicitation_id,
+            elicitation.get("expiresAt"),
+            effective_expires_in_seconds,
+        )
+
         # ``cmd_elicit_wait`` handles its own placeholder teardown by
         # reading the markers back from the elicitation's metadata.
         return cmd_elicit_wait(

{unique_sdk-2026.32.0.dev8 → unique_sdk-2026.32.0.dev10}/unique_sdk/cli/shell.py

@@ -89,7 +89,10 @@ OVERVIEW_HELP = textwrap.dedent("""\
         --chat-id / -c <id>            Associated chat ID
         --message-id / -m <id>         Associated message ID
         --timeout <seconds>            Max wait time, also sets when the
-                                       request expires (default: 7200)
+                                       request expires unless --expires-in
+                                       is given (default: 7200)
+        --expires-in <seconds>         Decouple server-side expiry from
+                                       --timeout (defaults to --timeout)
         --poll-interval <seconds>      Poll frequency (default: 2.0)
         --metadata key=value           Metadata (repeatable)
         --no-visible                   Skip the UN-19815 visibility workaround
@@ -814,9 +817,12 @@ class UniqueShell(cmd.Cmd):
           --mode FORM|URL              Display mode (create only, default: FORM)
           --chat-id / -c <id>          Associated chat ID
           --message-id / -m <id>       Associated message ID
-          --expires-in <seconds>       Auto-expire the request (create only)
+          --expires-in <seconds>       Auto-expire the request. For ask, this
+                                       decouples expiry from --timeout
+                                       (defaults to --timeout when omitted)
           --timeout <seconds>          (ask / wait) max wait time, default 7200;
                                        for ask this also sets when it expires
+                                       unless --expires-in is given
           --poll-interval <seconds>    (ask / wait) poll frequency, default 2
           --external-id <id>           External identifier (create only)
           --metadata key=value         Metadata (repeatable)
@@ -999,13 +1005,6 @@ class UniqueShell(cmd.Cmd):
         if not message:
             self._print("Usage: elicit ask <message> [options]")
             return
-        if opts["expires_in_seconds"] is not None:
-            self._print(
-                "No such option: --expires-in for 'elicit ask'. Use --timeout "
-                "(it also sets when the request expires). For expiry decoupled "
-                "from a local wait, use 'elicit create --expires-in'."
-            )
-            return
 
         ask_kwargs: dict[str, Any] = {
             "message": message,
@@ -1014,6 +1013,7 @@ class UniqueShell(cmd.Cmd):
             "chat_id": opts["chat_id"],
             "message_id": opts["message_id"],
             "timeout": opts["timeout"],
+            "expires_in_seconds": opts["expires_in_seconds"],
             "poll_interval": opts["poll_interval"],
             "metadata": opts["metadata"] or None,
             "visible": opts["visible"],

{unique_sdk-2026.32.0.dev8 → unique_sdk-2026.32.0.dev10}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -235,24 +235,29 @@ If you obtained the content some other way (you `download`ed the raw bytes and p
 CSV, `.txt`, HTML, images) have no pages — always omit `--pages`** and cite the
 whole file.
 
-**Choosing `--read-method`** (declare the *representation* of the source you actually read):
+**Choosing `--read-method`** (declare the *representation* you actually read the
+cited value from). Pick it by the **modality you read** — NOT by how you *located*
+the page. Locating a page with `unique-cli read` does **not** force `indexed`: if you
+then rendered that page and read a chart/figure with vision, the method is `vision`.
 
 - `text` → you used **extracted text** (`pdftotext`, PyMuPDF / `fitz` `page.get_text()`, MarkItDown, or any text extraction).
-- `vision` → you read a **rendered image** of the page/slide (e.g. `get_pixmap()`) with your vision capability.
-- `indexed` → you relied on **`unique-cli read`** output (the platform's indexed chunks).
+- `vision` → you read a **rendered image** of the page/slide (e.g. `get_pixmap()`) with your vision capability — including when you located the page via `unique-cli read` but then rendered it to read a chart, figure, table, or scanned page.
+- `indexed` → you used the **text returned by `unique-cli read`** (the platform's indexed chunks) as your answer source.
 
 | Value | When to use |
 |-------|-------------|
-| `text` | You read the page/document as extracted text and used that text. |
-| `vision` | You rendered the page to an image and read it with your vision capability. |
-| `indexed` | You read the content via `unique-cli read` (indexed chunks). |
-
-**Verify page numbers before citing — unless you already have them from `unique-cli read`.**
-If you cited straight from `unique-cli read` output (`--read-method indexed`), its
-`[p.N]` / `[p.N-M]` markers are already physical positions — skip the checks below
-and cite them directly. Otherwise — you read the raw bytes yourself
-(`--read-method text`/`vision`) — pick the row matching the file you read and
-verify the cited content really is where you claim before calling `cite`:
+| `text` | You extracted the page/document text yourself and used that text. |
+| `vision` | You read a rendered image of the page with your vision capability — even if you located the page via `unique-cli read`. |
+| `indexed` | You used the text returned by `unique-cli read` (indexed chunks) as your source. |
+
+**Verify page numbers before citing — unless you located them via `unique-cli read`.**
+This is about the *page number* only, and is **independent of `--read-method`**. If you
+located the page with `unique-cli read`, its `[p.N]` / `[p.N-M]` markers are already
+physical positions — trust them and skip the checks below, even if you then rendered the
+page and read it with vision (in that case still cite `--read-method vision`). Only when
+you obtained the page some other way — you `download`ed the raw bytes and parsed them
+yourself, or `read` returned no `[p.N]` markers — pick the row matching the file you read
+and verify the cited content really is where you claim before calling `cite`:
 
 - **PDF** — `pdfinfo file.pdf | grep Pages` for the total physical page count, then
   for **each** page run `pdftotext -f N -l N file.pdf -` and confirm the content is
@@ -265,11 +270,13 @@ verify the cited content really is where you claim before calling `cite`:
 - **Non-paginated (XLSX/CSV/TXT/HTML/images)** — there are no pages. Do **NOT**
   pass `--pages`; cite the whole file and verify the content exists in it.
 
-Then determine `--read-method`: report the representation you actually read. In a
-fallback chain (e.g. text extraction returned nothing → render + read visually),
-report `text` if you used extracted text or `vision` if you read a rendered image.
-Only after verifying, call `unique-cli cite` with the verified page numbers (if any)
-and `--read-method`.
+Then determine `--read-method` by the **modality you actually read** — independent of
+how you located the page. In a fallback chain (e.g. text extraction returned nothing →
+render + read visually), report `text` if you used extracted text or `vision` if you read
+a rendered image. If you located the page via `unique-cli read` but read the cited value
+off a rendered image (a chart, figure, table, or scanned page), report `vision`, not
+`indexed`. Only after confirming the page numbers, call `unique-cli cite` with the
+verified page numbers (if any) and `--read-method`.
 
 - **One method per `cite` call.** If different pages were read with different methods, issue separate `cite` calls — one per method.
 - Numbers are **per-turn only**; do not reuse from prior turns.