unique-sdk 2026.26.0.dev9__tar.gz → 2026.26.0.dev11__tar.gz

{unique_sdk-2026.26.0.dev9 → unique_sdk-2026.26.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.26.0.dev9
+Version: 2026.26.0.dev11
 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.26.0.dev9 → unique_sdk-2026.26.0.dev11}/pyproject.toml

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

{unique_sdk-2026.26.0.dev9 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/cli.py

@@ -13,6 +13,7 @@ from unique_sdk.cli.commands.dynamic_frontend import (
     cmd_dynamic_frontend_list,
 )
 from unique_sdk.cli.commands.elicitation import (
+    DEFAULT_WAIT_TIMEOUT_SECONDS,
     cmd_elicit_ask,
     cmd_elicit_create,
     cmd_elicit_get,
@@ -398,9 +399,41 @@ def cite(
 
 @main.command(name="read")
 @click.argument("cont_id")
+@click.option(
+    "--page",
+    "-p",
+    type=int,
+    default=None,
+    help="Read a single page (shorthand for --from-page N --to-page N).",
+)
+@click.option(
+    "--from-page",
+    type=int,
+    default=None,
+    help="First page to include (inclusive).",
+)
+@click.option(
+    "--to-page",
+    type=int,
+    default=None,
+    help="Last page to include (inclusive).",
+)
+@click.option(
+    "--max-chars",
+    type=int,
+    default=None,
+    help="Truncate the printed text to at most N characters.",
+)
 @click.pass_context
-def read_cmd(ctx: click.Context, cont_id: str) -> None:
-    """Read all indexed text chunks for a known content ID.
+def read_cmd(
+    ctx: click.Context,
+    cont_id: str,
+    page: int | None,
+    from_page: int | None,
+    to_page: int | None,
+    max_chars: int | None,
+) -> None:
+    """Read indexed text chunks for a known content ID.
 
     \b
     CONT_ID must be a content ID (cont_...) obtained from a prior `ls` or
@@ -411,11 +444,34 @@ def read_cmd(ctx: click.Context, cont_id: str) -> None:
     Use `search` when you need to find documents by topic or keyword.
     Use `read` when you already know the content ID and want the full text.
 
+    \b
+    Restrict to a page range with --page (single page) or --from-page/--to-page.
+    A chunk spanning pages 2-4 is returned for any overlapping request; files
+    without page numbers (e.g. plain text/markdown) are returned only without a
+    page range.
+
     \b
     Examples:
       unique-cli read cont_abc123
+      unique-cli read cont_abc123 --page 12
+      unique-cli read cont_abc123 --from-page 5 --to-page 9
+      unique-cli read cont_abc123 --to-page 3 --max-chars 8000
     """
-    output = cmd_read(LazyState.get(ctx), cont_id)
+    if page is not None and (from_page is not None or to_page is not None):
+        click.echo(
+            "read: use either --page or --from-page/--to-page, not both", err=True
+        )
+        raise SystemExit(1)
+    if page is not None:
+        from_page = page
+        to_page = page
+    output = cmd_read(
+        LazyState.get(ctx),
+        cont_id,
+        from_page=from_page,
+        to_page=to_page,
+        max_chars=max_chars,
+    )
     if _is_read_error_output(output):
         click.echo(output, err=True)
         raise SystemExit(1)
@@ -1004,19 +1060,16 @@ def elicit() -> None:
 )
 @click.option("--chat-id", "-c", default=None, help="Associated chat ID.")
 @click.option("--message-id", "-m", default=None, help="Associated message ID.")
-@click.option(
-    "--expires-in",
-    "expires_in_seconds",
-    type=int,
-    default=None,
-    help="Expire the elicitation after N seconds if not answered.",
-)
 @click.option(
     "--timeout",
     type=int,
-    default=300,
+    default=DEFAULT_WAIT_TIMEOUT_SECONDS,
     show_default=True,
-    help="Max seconds to block waiting for the user's response.",
+    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."
+    ),
 )
 @click.option(
     "--poll-interval",
@@ -1075,7 +1128,6 @@ def elicit_ask(
     schema: str | None,
     chat_id: str | None,
     message_id: str | None,
-    expires_in_seconds: int | None,
     timeout: int,
     poll_interval: float,
     metadata: tuple[str, ...],
@@ -1112,7 +1164,6 @@ def elicit_ask(
         "schema": schema,
         "chat_id": chat_id,
         "message_id": message_id,
-        "expires_in_seconds": expires_in_seconds,
         "timeout": timeout,
         "poll_interval": poll_interval,
         "metadata": parsed_metadata or None,
@@ -1296,7 +1347,7 @@ def elicit_get(ctx: click.Context, elicitation_id: str) -> None:
 @click.option(
     "--timeout",
     type=int,
-    default=300,
+    default=DEFAULT_WAIT_TIMEOUT_SECONDS,
     show_default=True,
     help="Max seconds to wait for a terminal state.",
 )

{unique_sdk-2026.26.0.dev9 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/commands/elicitation.py

@@ -26,7 +26,7 @@ from unique_sdk.cli.formatting import (
 from unique_sdk.cli.state import ShellState
 
 DEFAULT_POLL_INTERVAL_SECONDS = 2.0
-DEFAULT_WAIT_TIMEOUT_SECONDS = 300
+DEFAULT_WAIT_TIMEOUT_SECONDS = 7200
 TERMINAL_STATUSES = {
     "RESPONDED",
     "ACCEPTED",
@@ -669,9 +669,27 @@ def cmd_elicit_wait(
                 terminal_status = status
                 return format_elicitation(elicitation)
             if time.monotonic() >= deadline:
+                # One last read on the deadline. When the caller coupled
+                # ``--expires-in`` to ``--timeout`` (the default for
+                # ``elicit ask``), the record's ``expiresAt`` lands at this
+                # 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,
+                    )
+                )
+                last = final
+                final_status = str(final.get("status", "")).upper()
+                if final_status in TERMINAL_STATUSES:
+                    terminal_status = final_status
+                    return format_elicitation(final)
                 return (
                     f"elicit: timed out after {timeout}s waiting for "
-                    f"{elicitation_id} (last status: {status or 'UNKNOWN'})\n\n"
+                    f"{elicitation_id} (last status: {final_status or 'UNKNOWN'})\n\n"
                     f"{format_elicitation(last)}"
                 )
             time.sleep(poll_interval)
@@ -715,7 +733,6 @@ def cmd_elicit_ask(
     schema: str | None = None,
     chat_id: str | None = None,
     message_id: str | None = None,
-    expires_in_seconds: int | None = None,
     timeout: int = DEFAULT_WAIT_TIMEOUT_SECONDS,
     poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
     metadata: list[tuple[str, str]] | None = None,
@@ -751,6 +768,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
+
         user_metadata = _parse_metadata_pairs(metadata)
         effective_message_id = message_id
         placeholder_message_id: str | None = None

unique_sdk-2026.26.0.dev11/unique_sdk/cli/commands/read.py

@@ -0,0 +1,176 @@
+"""Read command: retrieve all indexed text chunks for a known content ID.
+
+Calls ``Content.search(where={"id": {"equals": cont_id}})`` — a direct
+Postgres lookup that returns every indexed chunk for the document in one
+request, no vector search involved.
+
+Use this when you already know the ``cont_*`` ID (e.g. from a prior ``ls``
+or ``unique-cli search`` result) and want to read the full document text.
+For discovery or query-based retrieval use ``unique-cli search`` instead.
+
+Pass ``from_page``/``to_page`` to read only part of a long document by page
+range; chunks are filtered client-side on the ``startPage``/``endPage`` the
+platform already returns, so no ingestion changes are required.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import unique_sdk
+from unique_sdk.cli.state import ShellState
+
+READ_ERROR_PREFIX = "read:"
+
+
+def _chunk_in_page_range(
+    chunk: dict[str, Any],
+    from_page: int | None,
+    to_page: int | None,
+) -> bool:
+    """Return True if *chunk* overlaps the requested ``[from_page, to_page]`` span.
+
+    A chunk covers ``startPage``..``endPage`` inclusive. With page-based chunking
+    these are equal (one chunk per page); otherwise a single chunk can span
+    several pages, so we keep any chunk that *overlaps* the requested range
+    rather than one fully contained in it. Chunks without page numbers are
+    excluded, since they cannot be placed on a page. ``from_page``/``to_page``
+    that are ``None`` act as open bounds.
+    """
+    start: int | None = chunk.get("startPage")
+    end: int | None = chunk.get("endPage")
+    if start is None:
+        start = end
+    if end is None:
+        end = start
+    if start is None or end is None:
+        return False
+
+    low = from_page if from_page is not None else start
+    high = to_page if to_page is not None else end
+    return start <= high and end >= low
+
+
+def _format_requested_range(from_page: int | None, to_page: int | None) -> str:
+    """Human-readable label for a requested page range (for messages)."""
+    if from_page is not None and to_page is not None:
+        return str(from_page) if from_page == to_page else f"{from_page}-{to_page}"
+    if from_page is not None:
+        return f"{from_page}+"
+    return f"up to {to_page}"
+
+
+def cmd_read(
+    state: ShellState,
+    cont_id: str,
+    from_page: int | None = None,
+    to_page: int | None = None,
+    max_chars: int | None = None,
+) -> str:
+    """Return indexed text chunks for *cont_id* as plain text.
+
+    Args:
+        state: Shell state carrying user/company credentials.
+        cont_id: A content ID (``cont_...``) to retrieve.
+        from_page: First page to include (inclusive). ``None`` = open start.
+        to_page: Last page to include (inclusive). ``None`` = open end.
+        max_chars: Truncate the returned text to at most this many characters.
+
+    Returns:
+        A formatted string of chunks, or an error message prefixed with
+        ``read:``.
+
+    When ``from_page``/``to_page`` are given, chunks are filtered to those that
+    overlap the requested pages. The page numbers come from ingestion; nothing
+    needs to change there. A chunk spanning pages 2-4 is returned for any range
+    touching 2-4, so the text may include a little from neighbouring pages.
+    """
+    if not cont_id.startswith("cont_"):
+        return f"{READ_ERROR_PREFIX} expected a content ID starting with 'cont_', got: {cont_id!r}"
+
+    if from_page is not None and to_page is not None and from_page > to_page:
+        return f"{READ_ERROR_PREFIX} invalid page range ({from_page} > {to_page})"
+
+    if max_chars is not None and max_chars < 1:
+        return f"{READ_ERROR_PREFIX} invalid --max-chars ({max_chars}); must be >= 1"
+
+    # Enforce the same .unique-search.json workspace boundary as search/ls/rm.
+    # Content.search has no scopeIds param, so we guard by owner scope before
+    # the point-lookup — matching rm/mv, not search's API-level scopeIds filter.
+    if not state.is_content_within_workspace(cont_id):
+        return f"{READ_ERROR_PREFIX} permission denied (outside workspace scope)"
+
+    try:
+        results = unique_sdk.Content.search(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            where={"id": {"equals": cont_id}},
+        )
+    except unique_sdk.APIError as e:
+        return f"{READ_ERROR_PREFIX} {e}"
+
+    if not results:
+        return f"{READ_ERROR_PREFIX} no content found for ID: {cont_id}"
+
+    content = results[0]
+    title = getattr(content, "title", None) or getattr(content, "key", None) or cont_id
+    chunks = getattr(content, "chunks", None) or []
+
+    if not chunks:
+        return (
+            f"Content: {title} ({cont_id})\n"
+            "No indexed chunks found — the document may still be ingesting or ingestion failed."
+        )
+
+    sorted_chunks = sorted(chunks, key=lambda c: c.get("order") or 0)
+
+    if from_page is not None or to_page is not None:
+        sorted_chunks = [
+            c for c in sorted_chunks if _chunk_in_page_range(c, from_page, to_page)
+        ]
+        if not sorted_chunks:
+            page_range = _format_requested_range(from_page, to_page)
+            return (
+                f"Content: {title} ({cont_id})\n"
+                f"No indexed chunks found in page range {page_range}. The document "
+                "may not have page numbers (e.g. plain text/markdown) or spans a "
+                "different range — read without a page range to see all text."
+            )
+
+    lines: list[str] = [
+        f"Content: {title} ({cont_id}) — {len(sorted_chunks)} chunk(s)\n"
+    ]
+    for chunk in sorted_chunks:
+        text = (chunk.get("text") or "").strip()
+        if not text:
+            continue
+        start = chunk.get("startPage")
+        end = chunk.get("endPage")
+        if start is not None or end is not None:
+            page_start = start if start is not None else end
+            page_end = end if end is not None else start
+            if page_start is not None and page_end is not None:
+                page_ref = (
+                    f"[p.{page_start}]"
+                    if page_start == page_end
+                    else f"[p.{page_start}-{page_end}]"
+                )
+                lines.append(f"{page_ref} {text}")
+            else:
+                lines.append(text)
+        else:
+            lines.append(text)
+
+    output = "\n\n".join(lines)
+    if max_chars is not None and len(output) > max_chars:
+        if from_page is not None or to_page is not None:
+            hint = "narrow the page range or raise --max-chars to see more"
+        else:
+            hint = "use a page range (--page/--from-page/--to-page) or raise --max-chars to see more"
+        output = f"{output[:max_chars]}\n... [truncated at {max_chars} chars; {hint}]"
+    return output
+
+
+def is_error_output(output: str) -> bool:
+    """Return ``True`` when *output* is an error message from ``cmd_read``."""
+    return output.startswith(READ_ERROR_PREFIX)

{unique_sdk-2026.26.0.dev9 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/shell.py

@@ -9,6 +9,7 @@ from typing import Any
 
 from unique_sdk.cli import __version__
 from unique_sdk.cli.commands.elicitation import (
+    DEFAULT_WAIT_TIMEOUT_SECONDS,
     cmd_elicit_ask,
     cmd_elicit_create,
     cmd_elicit_get,
@@ -68,7 +69,11 @@ OVERVIEW_HELP = textwrap.dedent("""\
         --folder <path|id>        Restrict to a folder
         --metadata <key=value>    Filter by metadata (repeatable)
         --limit <N>               Max results (default: 200)
-      read <cont_id>            Read all indexed text chunks for a content ID
+      read <cont_id> [options]  Read indexed text chunks for a content ID
+        --page / -p <N>           Read a single page
+        --from-page <N>           First page (inclusive)
+        --to-page <N>             Last page (inclusive)
+        --max-chars <N>           Truncate output to N characters
 
     MCP:
       mcp [options] <json>      Call an MCP server tool
@@ -83,8 +88,8 @@ OVERVIEW_HELP = textwrap.dedent("""\
         --schema <json>                JSON schema (default: single 'answer' field)
         --chat-id / -c <id>            Associated chat ID
         --message-id / -m <id>         Associated message ID
-        --expires-in <seconds>         Auto-expire the request
-        --timeout <seconds>            Max wait time (default: 300)
+        --timeout <seconds>            Max wait time, also sets when the
+                                       request expires (default: 7200)
         --poll-interval <seconds>      Poll frequency (default: 2.0)
         --metadata key=value           Metadata (repeatable)
         --no-visible                   Skip the UN-19815 visibility workaround
@@ -108,7 +113,7 @@ OVERVIEW_HELP = textwrap.dedent("""\
       elicit pending                 List pending elicitations
       elicit get <id>                Show one elicitation
       elicit wait <id> [opts]        Poll until answered / expired
-        --timeout <seconds>            Max wait (default: 300)
+        --timeout <seconds>            Max wait (default: 7200)
         --poll-interval <seconds>      Poll frequency (default: 2.0)
       elicit respond <id> [opts]     Respond on behalf of the user
         --action ACCEPT|DECLINE|CANCEL|REJECT Response action (required)
@@ -470,27 +475,95 @@ class UniqueShell(cmd.Cmd):
             return
         self._print(cmd_cite_file(self.state, positional[0], pages))
 
+    def _parse_int(self, raw: str, flag: str) -> tuple[int | None, bool]:
+        """Parse an int option value, returning (value, ok). Prints on failure."""
+        try:
+            return int(raw), True
+        except ValueError:
+            self._print(f"Invalid {flag}: {raw} (expected an integer)")
+            return None, False
+
     def do_read(self, arg: str) -> None:
-        """Read all indexed text chunks for a known content ID.
+        """Read indexed text chunks for a known content ID (optionally by page).
 
-        Usage: read <cont_id>
+        Usage: read <cont_id> [--page N | --from-page N --to-page M] [--max-chars N]
 
         Retrieves every indexed chunk for the document directly from the
-        database — no vector search, no query string needed.
+        database — no vector search, no query string needed. Use --page for a
+        single page or --from-page/--to-page for a range; a chunk spanning
+        pages 2-4 is returned for any overlapping request.
 
         Use `search` to find documents by topic; use `read` once you have
         the content ID and want the full text.
 
         Examples:
           /Reports> read cont_abc123
+          /Reports> read cont_abc123 --page 12
+          /Reports> read cont_abc123 --from-page 5 --to-page 9
         """
         from unique_sdk.cli.commands.read import cmd_read
 
         parts = shlex.split(arg)
+        usage = (
+            "Usage: read <cont_id> "
+            "[--page N | --from-page N --to-page M] [--max-chars N]"
+        )
         if not parts:
-            self._print("Usage: read <cont_id>")
+            self._print(usage)
             return
-        self._print(cmd_read(self.state, parts[0]))
+
+        cont_id: str | None = None
+        page: int | None = None
+        from_page: int | None = None
+        to_page: int | None = None
+        max_chars: int | None = None
+
+        int_flags = ("--page", "-p", "--from-page", "--to-page", "--max-chars")
+        i = 0
+        while i < len(parts):
+            tok = parts[i]
+            if tok in int_flags:
+                if i + 1 >= len(parts):
+                    self._print(f"Missing value for {tok}")
+                    return
+                value, ok = self._parse_int(parts[i + 1], tok)
+                if not ok:
+                    return
+                if tok in ("--page", "-p"):
+                    page = value
+                elif tok == "--from-page":
+                    from_page = value
+                elif tok == "--to-page":
+                    to_page = value
+                else:  # --max-chars
+                    max_chars = value
+                i += 2
+            elif cont_id is None:
+                cont_id = tok
+                i += 1
+            else:
+                self._print(f"Unknown argument: {tok}")
+                return
+
+        if cont_id is None:
+            self._print(usage)
+            return
+        if page is not None and (from_page is not None or to_page is not None):
+            self._print("read: use either --page or --from-page/--to-page, not both")
+            return
+        if page is not None:
+            from_page = page
+            to_page = page
+
+        self._print(
+            cmd_read(
+                self.state,
+                cont_id,
+                from_page=from_page,
+                to_page=to_page,
+                max_chars=max_chars,
+            )
+        )
 
     def do_rm(self, arg: str) -> None:
         """Delete a file.
@@ -716,8 +789,9 @@ class UniqueShell(cmd.Cmd):
           --mode FORM|URL              Display mode (create only, required)
           --chat-id / -c <id>          Associated chat ID
           --message-id / -m <id>       Associated message ID
-          --expires-in <seconds>       Auto-expire the request
-          --timeout <seconds>          (ask / wait) max wait time, default 300
+          --expires-in <seconds>       Auto-expire the request (create only)
+          --timeout <seconds>          (ask / wait) max wait time, default 7200;
+                                       for ask this also sets when it expires
           --poll-interval <seconds>    (ask / wait) poll frequency, default 2
           --external-id <id>           External identifier (create only)
           --metadata key=value         Metadata (repeatable)
@@ -791,7 +865,7 @@ class UniqueShell(cmd.Cmd):
             "message_id": None,
             "expires_in_seconds": None,
             "external_elicitation_id": None,
-            "timeout": 300,
+            "timeout": DEFAULT_WAIT_TIMEOUT_SECONDS,
             "poll_interval": 2.0,
             "action": None,
             "content": None,
@@ -900,6 +974,13 @@ 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,
@@ -907,7 +988,6 @@ class UniqueShell(cmd.Cmd):
             "schema": opts["schema"],
             "chat_id": opts["chat_id"],
             "message_id": opts["message_id"],
-            "expires_in_seconds": opts["expires_in_seconds"],
             "timeout": opts["timeout"],
             "poll_interval": opts["poll_interval"],
             "metadata": opts["metadata"] or None,

{unique_sdk-2026.26.0.dev9 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/skills/unique-cli-elicitation/SKILL.md

@@ -133,8 +133,7 @@ unique-cli elicit ask "Please provide report settings" \
 | `--message-id` | `-m` | none | **MANDATORY.** The current assistant message ID. Always pass `"$UNIQUE_MESSAGE_ID"`. Anchors the elicitation to the correct message in the conversation thread. |
 | `--tool-name` | `-t` | `agent_question` | Short snake_case label shown to the user (e.g. `clarify`, `confirm_delete`, `choose_report`). |
 | `--schema` | | single `answer` string | JSON Schema for the form body. |
-| `--expires-in` | | none | Seconds before the request auto-expires on the platform. |
-| `--timeout` | | `300` | Max seconds to block locally before giving up. |
+| `--timeout` | | `7200` | Max seconds to block locally before giving up. This is the single knob for `ask`: it also sets when the request expires on the platform, so the prompt expires exactly when you stop waiting and the chat UI can offer the user a way to continue. |
 | `--poll-interval` | | `2.0` | Seconds between status polls. |
 | `--metadata` | | none | `key=value` metadata (repeatable). |
 | `--assistant-id` | | `$UNIQUE_ASSISTANT_ID`, else latest assistant in chat | Assistant id for the placeholder message created by the visibility workaround. Set this (or export `UNIQUE_ASSISTANT_ID`) only if the chat is brand-new with no prior assistant messages. |
@@ -159,9 +158,34 @@ Terminal statuses:
 | `RESPONDED` / `COMPLETED` | User answered | Parse `Response:` JSON and proceed. |
 | `DECLINED` | User explicitly declined | Do not proceed. Acknowledge and stop. |
 | `CANCELLED` | Cancelled (by user or system) | Do not proceed. |
-| `EXPIRED` | Timed out on the platform (via `--expires-in`) | Ask again only if the task still needs it. |
+| `EXPIRED` | Timed out on the platform — the user did not answer within `--timeout` | Ask again only if the task still needs it; do not treat the expiry as approval. |
 
-If the CLI itself times out locally (`elicit: timed out after Ns ...`), raise `--timeout` and try again. If this happens repeatedly, double-check that you passed `--chat-id` and did not pass `--no-visible` — an invisible elicitation is the most common cause of a local timeout.
+Because `ask` derives the request's expiry from `--timeout`, when the user does not answer in time the platform expires the request and `elicit ask` returns a clean `EXPIRED` status (rather than a local-only timeout). If you instead see `elicit: timed out after Ns ...`, raise `--timeout` and try again. If this happens repeatedly, double-check that you passed `--chat-id` and did not pass `--no-visible` — an invisible elicitation is the most common cause of a local timeout.
+
+### Repeat the answer back in chat
+
+After a `RESPONDED` / `COMPLETED` elicitation, always repeat the user's answer back in the normal chat before you continue. This keeps the decision in the chat history and makes it clear what the user said.
+
+Write this as a user-readable summary, not as raw JSON. Use the field descriptions and option labels from the schema to translate the response into plain language:
+
+```markdown
+Got it — you chose Markdown for the report format and asked me to include the appendix.
+```
+
+If the exact structured response is useful for auditing or debugging, put it behind a collapsed details block after the readable summary instead of leading with it:
+
+````markdown
+<details>
+<summary>Structured elicitation response</summary>
+
+```json
+{"format":"Markdown","include_appendix":true}
+```
+
+</details>
+````
+
+Do not expose raw JSON by default when a natural-language confirmation would be clearer.
 
 ## Scripting pattern
 
@@ -192,7 +216,7 @@ esac
 - Use `enum` for closed choices so the UI can render a selector.
 - Use `"type": "boolean"` for confirmations; treat `true` as "go ahead", everything else as "stop".
 - Add short `description` strings -- they are shown as help text next to each field.
-- Keep schemas small. Break long flows into several sequential `elicit ask` calls instead of one giant form.
+- Keep schemas small. Ask at most 5 questions in a single elicitation; if you need more, split the flow so the user is not confused by an oversized form.
 
 ## Agent workflow rules
 
@@ -203,9 +227,11 @@ esac
 5. **Never run destructive CLI commands without a confirmation elicitation.** This includes `rm`, `rmdir -r`, bulk renames, large uploads, schedule deletion, etc.
 6. **Pick a meaningful `--tool-name`.** `confirm_delete`, `choose_region`, `pick_report` -- short snake_case describing the intent.
 7. **Constrain answers with a schema** whenever the valid set is finite -- don't rely on parsing free text when `enum` is an option.
-8. **Handle non-`RESPONDED` outcomes explicitly.** If the status is `DECLINED` / `CANCELLED` / `EXPIRED`, tell the user you stopped and ask what they want to do next instead of silently proceeding.
-9. **Don't spam elicitations.** One well-designed form with several fields is better than five sequential yes/no questions.
-10. **Respect timeouts.** The default `--timeout` is 5 minutes -- raise it only if you genuinely expect the user to take longer.
+8. **Repeat answered elicitations back in chat.** Summarize what the user chose in natural language before acting on it; hide raw JSON in a collapsible details block only when it adds value.
+9. **Handle non-`RESPONDED` outcomes explicitly.** If the status is `DECLINED` / `CANCELLED` / `EXPIRED`, tell the user you stopped and ask what they want to do next instead of silently proceeding.
+10. **Don't spam elicitations.** One well-designed form with a few related fields is better than five sequential yes/no questions.
+11. **Cap each elicitation at 5 questions.** If you need more than 5 answers, split them into multiple focused elicitations so the user can respond confidently.
+12. **Respect timeouts.** The default `--timeout` is 2 hours -- override it only when the task needs a shorter or longer wait.
 
 ## Prerequisites
 

{unique_sdk-2026.26.0.dev9 → unique_sdk-2026.26.0.dev11}/unique_sdk/cli/skills/unique-cli-file-management/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Manage files and folders on the Unique AI Platform using the unique-cli
   command-line tool. Use when the user asks to upload, download, delete,
   rename, list, find, restore versions, list versions, look for, or organize files and folders on Unique,
+  or to read / view / quote the text contents of a known file (optionally by
+  page or page range, e.g. "what's on page 5?", "read pages 10-12"),
   or when working with scope IDs (scope_*) or content IDs (cont_*).
   IMPORTANT: When a user says they are "looking for a file" or wants to
   "find a file", they typically mean locating it within the Unique AI
@@ -64,6 +66,13 @@ unique-cli restore-version cver_abc123
 unique-cli download report.pdf ./local/
 unique-cli download cont_abc123 ~/Desktop/
 
+# Read a file's extracted text by content ID (whole file)
+unique-cli read cont_abc123
+
+# Read a single page or a page range
+unique-cli read cont_abc123 --page 12
+unique-cli read cont_abc123 --from-page 5 --to-page 9
+
 # Declare page citations after reading a file
 unique-cli cite report.pdf --pages 3,5,7
 unique-cli cite cont_abc123 --pages 1-4
@@ -141,6 +150,57 @@ unique-cli mkdir "2025/Q1/Financials"
 unique-cli upload ./budget.xlsx /2025/Q1/Financials/
 ```
 
+## Reading File Contents (by page range)
+
+Use `read` to retrieve the **extracted text** of a single, known file — for
+example to answer "what does page 5 say?", to quote an exact passage, or to
+read a long document a few pages at a time. This differs from `search`:
+`search` ranks chunks across many files by relevance; `read` returns the text
+of one file in document order.
+
+`read` takes a **content ID** (`cont_...`), not a file name. Get the ID first
+from `ls` or `search`, then pass it to `read`.
+
+```bash
+# Whole file
+unique-cli read cont_abc123
+
+# A single page
+unique-cli read cont_abc123 --page 12
+
+# A page range (inclusive)
+unique-cli read cont_abc123 --from-page 5 --to-page 9
+
+# Cap the output size (protects your context window on huge files)
+unique-cli read cont_abc123 --to-page 3 --max-chars 8000
+```
+
+| Option | Description |
+|--------|-------------|
+| `--page` / `-p N` | Read only page N (shorthand for `--from-page N --to-page N`) |
+| `--from-page N` | First page to include (inclusive) |
+| `--to-page N` | Last page to include (inclusive) |
+| `--max-chars N` | Truncate the printed text to N characters |
+
+Each chunk is prefixed with its source page(s) as `[p.N]` or `[p.N-M]`, so you
+can attribute text to pages.
+
+### How page filtering behaves (important)
+
+- **Page numbers come from ingestion.** Each chunk carries a `startPage` and
+  `endPage`; the page filter is applied to those values. Nothing in the
+  ingestion pipeline needs to change.
+- **Ranges overlap, they don't slice.** A chunk that spans pages 2-4 is
+  returned for `--page 3` (or any range touching 2-4). The returned text is the
+  whole chunk, so it may include a little from neighbouring pages. Treat the
+  result as "the chunks covering these pages", not a pixel-perfect page cut.
+- **Some files have no page numbers.** Plain text, markdown, and similar
+  content has no page numbers; those chunks are returned only when you read
+  **without** a page range. A page-filtered read of such a file returns nothing.
+- **Empty / not indexed?** If `read` reports the file is still ingesting or has
+  no indexed chunks, there is no extracted text to return — use `download` to
+  fetch the original bytes instead.
+
 ## Citing File Pages
 
 After reading **any** file and using its content in your answer, declare citations:

unique_sdk-2026.26.0.dev9/unique_sdk/cli/commands/read.py

@@ -1,93 +0,0 @@
-"""Read command: retrieve all indexed text chunks for a known content ID.
-
-Calls ``Content.search(where={"id": {"equals": cont_id}})`` — a direct
-Postgres lookup that returns every indexed chunk for the document in one
-request, no vector search involved.
-
-Use this when you already know the ``cont_*`` ID (e.g. from a prior ``ls``
-or ``unique-cli search`` result) and want to read the full document text.
-For discovery or query-based retrieval use ``unique-cli search`` instead.
-"""
-
-from __future__ import annotations
-
-import unique_sdk
-from unique_sdk.cli.state import ShellState
-
-READ_ERROR_PREFIX = "read:"
-
-
-def cmd_read(state: ShellState, cont_id: str) -> str:
-    """Return all indexed text chunks for *cont_id* as plain text.
-
-    Args:
-        state: Shell state carrying user/company credentials.
-        cont_id: A content ID (``cont_...``) to retrieve.
-
-    Returns:
-        A formatted string of chunks, or an error message prefixed with
-        ``read:``.
-    """
-    if not cont_id.startswith("cont_"):
-        return f"{READ_ERROR_PREFIX} expected a content ID starting with 'cont_', got: {cont_id!r}"
-
-    # Enforce the same .unique-search.json workspace boundary as search/ls/rm.
-    # Content.search has no scopeIds param, so we guard by owner scope before
-    # the point-lookup — matching rm/mv, not search's API-level scopeIds filter.
-    if not state.is_content_within_workspace(cont_id):
-        return f"{READ_ERROR_PREFIX} permission denied (outside workspace scope)"
-
-    try:
-        results = unique_sdk.Content.search(
-            user_id=state.config.user_id,
-            company_id=state.config.company_id,
-            where={"id": {"equals": cont_id}},
-        )
-    except unique_sdk.APIError as e:
-        return f"{READ_ERROR_PREFIX} {e}"
-
-    if not results:
-        return f"{READ_ERROR_PREFIX} no content found for ID: {cont_id}"
-
-    content = results[0]
-    title = getattr(content, "title", None) or getattr(content, "key", None) or cont_id
-    chunks = getattr(content, "chunks", None) or []
-
-    if not chunks:
-        return (
-            f"Content: {title} ({cont_id})\n"
-            "No indexed chunks found — the document may still be ingesting or ingestion failed."
-        )
-
-    sorted_chunks = sorted(chunks, key=lambda c: c.get("order") or 0)
-
-    lines: list[str] = [
-        f"Content: {title} ({cont_id}) — {len(sorted_chunks)} chunk(s)\n"
-    ]
-    for chunk in sorted_chunks:
-        text = (chunk.get("text") or "").strip()
-        if not text:
-            continue
-        start = chunk.get("startPage")
-        end = chunk.get("endPage")
-        if start is not None or end is not None:
-            page_start = start if start is not None else end
-            page_end = end if end is not None else start
-            if page_start is not None and page_end is not None:
-                page_ref = (
-                    f"[p.{page_start}]"
-                    if page_start == page_end
-                    else f"[p.{page_start}-{page_end}]"
-                )
-                lines.append(f"{page_ref} {text}")
-            else:
-                lines.append(text)
-        else:
-            lines.append(text)
-
-    return "\n\n".join(lines)
-
-
-def is_error_output(output: str) -> bool:
-    """Return ``True`` when *output* is an error message from ``cmd_read``."""
-    return output.startswith(READ_ERROR_PREFIX)