unique-sdk 2026.42.0.dev1__tar.gz → 2026.42.0.dev2__tar.gz

{unique_sdk-2026.42.0.dev1 → unique_sdk-2026.42.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-sdk
-Version: 2026.42.0.dev1
+Version: 2026.42.0.dev2
 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.42.0.dev1 → unique_sdk-2026.42.0.dev2}/pyproject.toml

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

{unique_sdk-2026.42.0.dev1 → unique_sdk-2026.42.0.dev2}/unique_sdk/cli/cli.py

@@ -23,6 +23,7 @@ from unique_sdk.cli.commands.agentic_table_write import (
     cmd_export,
     cmd_import,
     cmd_rerun_row,
+    cmd_set_cell,
 )
 from unique_sdk.cli.commands.browser import (
     cmd_browser_action,
@@ -2304,9 +2305,9 @@ Work with Agentic Table (magic table) sheets over the public magic-table API.
 \b
 Reads (get-sheet / get-cell / cell-history / list-exports) are Tier 0: no
 confirmation, no side effects. Writes (create-sheet / import / rerun-row /
-export) build and run a sheet — the full loop of create, populate, run, and
-export, plus re-answering a single row. Every
-call is scoped to the current user/company; sheet-role access (Owner / Can
+set-cell / export) build and run a sheet — the full loop of create, populate,
+run, and export — plus re-answering a single row or writing one cell's text.
+Every call is scoped to the current user/company; sheet-role access (Owner / Can
 manage / Can edit) is enforced server-side and a denial is reported as
 `agentic-table: permission denied`.
 
@@ -2322,6 +2323,7 @@ Write subcommands:
   create-sheet   Create a new sheet in a space
   import         Import questions/sources (adding questions triggers the run)
   rerun-row      Re-run the agent for a single row (import cannot redo a row)
+  set-cell       Write text into one cell by row/column order (no run)
   export         Generate export artifacts (report / question export)
 
 \b
@@ -2329,6 +2331,7 @@ Examples:
   unique-cli agentic-table get-sheet mt_abc123 --cells --metadata
   unique-cli agentic-table create-sheet asst_123 --name "Vendor DDQ"
   unique-cli agentic-table import mt_abc123 --question-file-id c_q --source-file-id c_src --wait
+  unique-cli agentic-table set-cell mt_abc123 --row 1 --col 2 --text "Fee is 2%."
   unique-cli agentic-table export mt_abc123 --type FULL_REPORT --wait
 """
 
@@ -2710,6 +2713,127 @@ def agentic_table_rerun_row(
     )
 
 
+@agentic_table.command(name="set-cell")
+@click.argument("table_id")
+@click.option(
+    "--row",
+    "row_order",
+    type=click.IntRange(min=0),
+    required=True,
+    help="Row order (0-based; 0 is the header).",
+)
+@click.option(
+    "--col",
+    "column_order",
+    type=click.IntRange(min=0),
+    required=True,
+    help="Column order (0-based).",
+)
+@click.option(
+    "--text",
+    "text",
+    default=None,
+    help="Cell text (exactly one of --text, --file, --stdin).",
+)
+@click.option(
+    "--file",
+    "file",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Read cell text from a UTF-8 file.",
+)
+@click.option(
+    "--stdin",
+    "stdin",
+    is_flag=True,
+    default=False,
+    help="Read cell text from stdin.",
+)
+@click.option(
+    "--log-file",
+    "log_file",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="JSON array of log entries (text, actorType, createdAt).",
+)
+@click.option(
+    "--log-json",
+    "log_json",
+    default=None,
+    help="Inline JSON array of log entries (text, actorType, createdAt).",
+)
+@click.option(
+    "--allow-create",
+    "allow_create",
+    is_flag=True,
+    default=False,
+    help="Allow creating the next row or column (not a gap).",
+)
+@click.option(
+    "--force",
+    "force",
+    is_flag=True,
+    default=False,
+    help="Write even while the sheet is PROCESSING.",
+)
+@click.option(
+    "--json", "output_json", is_flag=True, default=False, help="Print raw JSON."
+)
+@click.pass_context
+def agentic_table_set_cell(
+    ctx: click.Context,
+    table_id: str,
+    row_order: int,
+    column_order: int,
+    text: str | None,
+    file: str | None,
+    stdin: bool,
+    log_file: str | None,
+    log_json: str | None,
+    allow_create: bool,
+    force: bool,
+    output_json: bool,
+) -> None:
+    """Write text into one cell by row and column order.
+
+    \b
+    This is not a run. Pass the cell value you already have; the API returns
+    the updated cell immediately. --row/--col are 0-based like get-cell; row 0
+    is the header and is allowed. A missing row or column is refused unless
+    --allow-create, which adds only the next index. A PROCESSING sheet is
+    refused unless --force. Use
+    rerun-row to have the table agent regenerate an answer from sources.
+
+    \b
+    Provide exactly one of --text, --file, or --stdin. Long or multi-line
+    answers belong in a file or stdin. Optional --log-file / --log-json is a
+    JSON array of {text, actorType, createdAt} with actorType TOOL or ASSISTANT.
+
+    \b
+    Examples:
+      unique-cli agentic-table set-cell mt_abc123 --row 1 --col 2 --text "Fee is 2%."
+      unique-cli agentic-table set-cell mt_abc123 --row 1 --col 2 --file ./answer.md
+      unique-cli agentic-table set-cell mt_abc123 --row 1 --col 2 --stdin < answer.md
+    """
+    emit(
+        cmd_set_cell(
+            LazyState.get(ctx),
+            table_id,
+            row_order=row_order,
+            column_order=column_order,
+            text=text,
+            file=file,
+            stdin=stdin,
+            log_file=log_file,
+            log_json=log_json,
+            allow_create=allow_create,
+            force=force,
+            output_json=output_json,
+        ),
+        is_error=_is_agentic_table_error_output,
+    )
+
+
 @agentic_table.command(name="export")
 @click.argument("table_id")
 @click.option(

{unique_sdk-2026.42.0.dev1 → unique_sdk-2026.42.0.dev2}/unique_sdk/cli/commands/agentic_table_write.py

@@ -5,6 +5,7 @@ The full-loop write slice over the public magic-table API (``2023-12-06``):
 - ``create-sheet`` — create an empty sheet in a space.
 - ``import`` — add questions/sources; adding new questions triggers the agent run.
 - ``rerun-row`` — re-run the agent for a single row.
+- ``set-cell`` — write text into one cell (no run).
 - ``export`` — generate export artifacts (report / question export) and list them.
 
 Together these let an agent build a sheet, run it, and collect the answers it
@@ -35,14 +36,19 @@ from __future__ import annotations
 
 import asyncio
 import json
+import sys
 import time
-from collections.abc import Awaitable, Callable
-from typing import NamedTuple, TypeVar
+from collections.abc import Awaitable, Callable, Mapping
+from datetime import datetime
+from pathlib import Path
+from typing import Literal, NamedTuple, TypeVar, cast
 
 from unique_sdk._error import UniqueError
 from unique_sdk.api_resources._agentic_table import (
     AgenticTable,
     AgenticTableSheetState,
+    LogDetail,
+    LogEntry,
     MagicTableActionResult,
     MagicTableArtifact,
     MagicTableArtifactState,
@@ -57,6 +63,7 @@ from unique_sdk.cli.commands.agentic_table import AGENTIC_TABLE_ERROR_PREFIX
 from unique_sdk.cli.formatting import (
     format_agentic_table_action_result,
     format_agentic_table_artifacts,
+    format_agentic_table_cell,
     format_agentic_table_created_sheet,
 )
 from unique_sdk.cli.state import ShellState
@@ -152,6 +159,249 @@ def _rejected(result: MagicTableActionResult, *, action: str) -> str:
     return f"{AGENTIC_TABLE_ERROR_PREFIX} {action} rejected: {message}"
 
 
+# unique-cli is primarily agent-driven: USER/SYSTEM would be spoofable
+# provenance on cell-history, so only ASSISTANT and TOOL are accepted here.
+_LOG_ACTOR_TYPES = frozenset({"ASSISTANT", "TOOL"})
+_LOG_FILE_ERRORS = (OSError, UnicodeDecodeError)
+
+
+def _parse_log_created_at(raw: object, *, index: int) -> str:
+    """Return *raw* if it is an ISO-8601 timestamp string.
+
+    ``Z`` is accepted as UTC. Non-strings and unparseable values fail locally
+    so they never become cell-history labels.
+    """
+    if not isinstance(raw, str):
+        raise ValueError(f"logEntries[{index}] createdAt must be an ISO-8601 string")
+    candidate = raw[:-1] + "+00:00" if raw.endswith("Z") else raw
+    try:
+        datetime.fromisoformat(candidate)
+    except ValueError as exc:
+        raise ValueError(f"logEntries[{index}] createdAt must be ISO-8601") from exc
+    return raw
+
+
+def _sheet_column_count(sheet: Mapping[str, object]) -> int:
+    """Return 1 + max ``columnOrder`` in the sheet cells, or 0 if none."""
+    cells = sheet.get("magicTableCells")
+    if not isinstance(cells, list):
+        return 0
+    orders = [
+        order
+        for cell in cells
+        if isinstance(cell, dict)
+        for order in [cell.get("columnOrder")]
+        if isinstance(order, int)
+    ]
+    return max(orders) + 1 if orders else 0
+
+
+def _read_cell_text(
+    *,
+    text: str | None,
+    file: str | None,
+    stdin: bool,
+) -> str:
+    """Return cell text from exactly one of ``text``, ``file``, or stdin.
+
+    Raises ``ValueError`` with an unprefixed message when the sources are
+    missing, ambiguous, unreadable, empty, or a TTY. Whitespace-only text is
+    kept: the API treats it as non-empty.
+    """
+    sources = sum([text is not None, file is not None, stdin])
+    if sources == 0:
+        raise ValueError("cell text is required: pass --text, --file, or --stdin")
+    if sources > 1:
+        raise ValueError(
+            "ambiguous input: provide exactly one of --text, --file, or --stdin"
+        )
+
+    if stdin:
+        if sys.stdin.isatty():
+            raise ValueError("stdin is a tty: pipe input or use --text / --file")
+        body = sys.stdin.read()
+    elif file is not None:
+        try:
+            body = Path(file).read_text(encoding="utf-8")
+        except _LOG_FILE_ERRORS as exc:
+            raise ValueError(f"could not read --file: {exc}") from exc
+    else:
+        assert text is not None
+        body = text
+
+    if body == "":
+        raise ValueError("cell text is empty")
+    return body
+
+
+def _parse_log_entries(
+    *,
+    log_file: str | None,
+    log_json: str | None,
+) -> list[LogEntry] | None:
+    """Parse optional log entries from a file or an inline JSON array.
+
+    Raises ``ValueError`` with an unprefixed message when both sources are
+    set, JSON is invalid, or a required field is missing. ``None`` means
+    omit ``logEntries`` from the request.
+    """
+    if log_file is not None and log_json is not None:
+        raise ValueError(
+            "ambiguous logs: provide at most one of --log-file or --log-json"
+        )
+    raw: str | None
+    if log_file is not None:
+        try:
+            raw = Path(log_file).read_text(encoding="utf-8")
+        except _LOG_FILE_ERRORS as exc:
+            raise ValueError(f"could not read --log-file: {exc}") from exc
+    elif log_json is not None:
+        raw = log_json
+    else:
+        return None
+
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"log entries must be JSON: {exc}") from exc
+
+    if not isinstance(parsed, list):
+        raise ValueError("log entries must be a JSON array")
+
+    entries: list[LogEntry] = []
+    for index, item in enumerate(parsed):
+        if not isinstance(item, dict):
+            raise ValueError(f"logEntries[{index}] must be an object")
+        missing = [key for key in ("text", "actorType", "createdAt") if key not in item]
+        if missing:
+            raise ValueError(
+                f"logEntries[{index}] missing required field(s): {', '.join(missing)}"
+            )
+        actor_raw = item["actorType"]
+        if not isinstance(actor_raw, str) or actor_raw not in _LOG_ACTOR_TYPES:
+            raise ValueError(
+                f"logEntries[{index}] actorType must be one of "
+                f"{', '.join(sorted(_LOG_ACTOR_TYPES))}"
+            )
+        text_raw = item["text"]
+        if not isinstance(text_raw, str):
+            raise ValueError(f"logEntries[{index}] text must be a string")
+        actor = cast(Literal["USER", "SYSTEM", "ASSISTANT", "TOOL"], actor_raw)
+        entry: LogEntry = {
+            "text": text_raw,
+            "actorType": actor,
+            "createdAt": _parse_log_created_at(item["createdAt"], index=index),
+        }
+        message_id = item.get("messageId")
+        if message_id is not None:
+            if not isinstance(message_id, str):
+                raise ValueError(f"logEntries[{index}] messageId must be a string")
+            entry["messageId"] = message_id
+        if "details" in item and item["details"] is not None:
+            if not isinstance(item["details"], dict):
+                raise ValueError(f"logEntries[{index}] details must be an object")
+            entry["details"] = cast(LogDetail, cast(object, item["details"]))
+        entries.append(entry)
+    return entries
+
+
+def cmd_set_cell(
+    state: ShellState,
+    table_id: str,
+    *,
+    row_order: int,
+    column_order: int,
+    text: str | None = None,
+    file: str | None = None,
+    stdin: bool = False,
+    log_file: str | None = None,
+    log_json: str | None = None,
+    allow_create: bool = False,
+    force: bool = False,
+    output_json: bool = False,
+) -> str:
+    """Upsert one cell (``POST /magic-table/{id}/cell``).
+
+    Writes the given text at ``(row_order, column_order)``. This is not a
+    run: unlike ``import`` / ``rerun-row`` it does not start the table agent.
+    Row 0 (the header) is allowed. ``allow_create`` may add only the next
+    row or column; a gap is refused. A ``PROCESSING`` sheet is refused
+    unless ``force``.
+    """
+    try:
+        cell_text = _read_cell_text(text=text, file=file, stdin=stdin)
+        log_entries = _parse_log_entries(log_file=log_file, log_json=log_json)
+    except ValueError as exc:
+        return f"{AGENTIC_TABLE_ERROR_PREFIX} {exc}"
+
+    params: AgenticTable.SetCell = {
+        "tableId": table_id,
+        "rowOrder": row_order,
+        "columnOrder": column_order,
+        "text": cell_text,
+    }
+    if log_entries is not None:
+        params["logEntries"] = log_entries
+
+    async def _run() -> str:
+        # GET + POST in one loop; a second asyncio.run closes the HTTP client.
+        sheet = await AgenticTable.get_sheet_data(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            tableId=table_id,
+            includeCells=True,
+            includeRowCount=True,
+            rowOrders=[0],
+        )
+        if sheet["state"] == AgenticTableSheetState.PROCESSING and not force:
+            return (
+                f"{AGENTIC_TABLE_ERROR_PREFIX} sheet is PROCESSING; wait for IDLE "
+                "or pass --force"
+            )
+        row_count = sheet.get("magicTableRowCount")
+        if not isinstance(row_count, int):
+            row_count = 0
+        column_count = _sheet_column_count(sheet)
+        if allow_create:
+            if row_order > row_count:
+                return (
+                    f"{AGENTIC_TABLE_ERROR_PREFIX} row {row_order} is too far "
+                    f"(sheet has {row_count} rows); --allow-create only adds the next "
+                    "row"
+                )
+            if column_order > column_count:
+                return (
+                    f"{AGENTIC_TABLE_ERROR_PREFIX} col {column_order} is too far "
+                    f"(sheet has {column_count} columns); --allow-create only adds "
+                    "the next column"
+                )
+        else:
+            if row_order >= row_count:
+                return (
+                    f"{AGENTIC_TABLE_ERROR_PREFIX} row {row_order} is out of range "
+                    f"(sheet has {row_count} rows); pass --allow-create to add a row"
+                )
+            if column_order >= column_count:
+                return (
+                    f"{AGENTIC_TABLE_ERROR_PREFIX} col {column_order} is out of range "
+                    f"(sheet has {column_count} columns); pass --allow-create to add a "
+                    "column"
+                )
+        cell = await AgenticTable.set_cell(
+            user_id=state.config.user_id,
+            company_id=state.config.company_id,
+            **params,
+        )
+        if output_json:
+            return json.dumps(cell, indent=2, default=str)
+        return format_agentic_table_cell(cell)
+
+    try:
+        return asyncio.run(_run())
+    except UniqueError as exc:
+        return _error(exc)
+
+
 def cmd_create_sheet(
     state: ShellState,
     assistant_id: str,

{unique_sdk-2026.42.0.dev1 → unique_sdk-2026.42.0.dev2}/unique_sdk/cli/skills/unique-cli-agentic-table/SKILL.md

@@ -4,11 +4,11 @@ description: >-
   Read and drive Agentic Table (magic table / due-diligence) sheets through the
   unique-cli agentic-table command. Use when the user or task involves an
   Agentic Table: inspecting a sheet's state, a cell's value or lock state, a
-  cell's edit history or its export artifacts; or running the full loop —
-  creating a sheet, importing a questionnaire and sources, waiting for the
-  agent to answer, and exporting the result. Access is enforced per sheet by
-  the platform and varies from sheet to sheet; a denial is reported as
-  `agentic-table: permission denied`.
+  cell's edit history or its export artifacts; writing text into a specific
+  cell; or running the full loop — creating a sheet, importing a questionnaire
+  and sources, waiting for the agent to answer, and exporting the result.
+  Access is enforced per sheet by the platform and varies from sheet to sheet;
+  a denial is reported as `agentic-table: permission denied`.
 ---
 
 # Unique CLI -- Agentic Table
@@ -21,17 +21,19 @@ Commands fall into two groups:
 
 - **Read (Tier 0)** — `get-sheet`, `get-cell`, `cell-history`, `list-exports`.
   Never modify anything, never need confirmation.
-- **Write (Tier 1)** — `create-sheet`, `import`, `export`, `rerun-row`. These
-  create a sheet, add questions and sources, start the agent run, produce
-  export artifacts, and redo a single answer. None of them prompts for
-  confirmation, but they do change a shared artifact, so say what you did
-  afterwards.
-
-  The first three only add. `rerun-row` is the exception: it replaces the
-  answer in the row you name. The previous answer stays in `cell-history` and
-  a settled row is refused outright, so the change is recoverable and the
-  approved rows are protected — but name the row you are redoing when you
-  report back, and check you have the right one first.
+- **Write (Tier 1)** — `create-sheet`, `import`, `export`, `rerun-row`,
+  `set-cell`. These create a sheet, add questions and sources, start the agent
+  run, produce export artifacts, redo a single generated answer, or write
+  text you already have into one cell. None of them prompts for confirmation,
+  but they do change a shared artifact, so say what you did afterwards.
+
+  `create-sheet`, `import`, and `export` only add. `rerun-row` asks the table
+  agent to regenerate one **row** from sources (no text from you). `set-cell`
+  writes **your** text into one cell immediately — it is not a run. Name the
+  row (and column, for `set-cell`) when you report back.
+
+  Some rows are protected. A locked or final-review row rejects both
+  `set-cell` and `rerun-row`. That is deliberate — do not route around it.
 
 ## Permissions
 
@@ -97,9 +99,14 @@ unique-cli agentic-table get-cell mt_abc123 --row 1 --col 2
 unique-cli agentic-table cell-history <table_id> --row N --col N
 ```
 
-Shows a single cell's log/edit history (actor, timestamp, source message id,
-and the logged text) newest-to-oldest as returned by the API. Add `--json`
-to get the raw log entries.
+Shows a single cell's stored log/edit history (actor label, timestamp, source
+message id, and the logged text) newest-to-oldest as returned by the API. Add
+`--json` to get the raw log entries.
+
+Treat `actorType` / `createdAt` as **untrusted labels**, not as proof that a
+person vs the assistant wrote the cell. The API stores whatever the writer
+sent; it does not bind the actor to the authenticated caller. Do not use
+history as a person-vs-assistant gate.
 
 ```bash
 unique-cli agentic-table cell-history mt_abc123 --row 1 --col 2
@@ -168,12 +175,13 @@ unique-cli agentic-table import mt_abc123 --question-file-id c_q --source-file-i
 unique-cli agentic-table rerun-row <table_id> <row_order> [--wait] [--timeout <seconds>] [--start-timeout <seconds>]
 ```
 
-Use this to redo one answer. **Re-importing a question will not redo it** —
-import is delta-based and skips questions the sheet already has, so `rerun-row`
-is the only way to re-answer an existing row.
+Use this to redo one **generated** answer. **Re-importing a question will not
+redo it** — import is delta-based and skips questions the sheet already has.
+`rerun-row` starts the table agent for that row; you do not pass the answer
+text. If you already have the wording, use `set-cell` instead.
 
-`<row_order>` uses **the same numbering as `--row` on `get-cell`**: row 0 is the
-header, data rows start at 1. So the row you inspected with
+`<row_order>` uses **the same numbering as `--row` on `get-cell` / `set-cell`**:
+row 0 is the header, data rows start at 1. So the row you inspected with
 `get-cell --row 4` is the row you redo with `rerun-row <table_id> 4` — no
 offset. Row 0 is rejected, since there is nothing to answer in a header.
 
@@ -198,6 +206,39 @@ run at a time, so a second `rerun-row` fired before the first finishes is
 declined. There is no batch form. If most of the sheet needs redoing, consider
 a fresh sheet instead.
 
+### Write one cell
+
+```bash
+unique-cli agentic-table set-cell <table_id> --row N --col N (--text TEXT | --file PATH | --stdin)
+```
+
+Use this when **you already have the text** — the user gave the wording, you
+copied a cell, or you researched the answer yourself. It writes that one cell
+immediately. It does not start the table agent.
+
+`--row` / `--col` are the same 0-based numbers as `get-cell`. Row 0 (the
+header) **can** be set. Find coordinates with `get-sheet --cells` or
+`get-cell` first. A coordinate that does not exist is **refused** unless you
+pass `--allow-create` for the **next** row or column only (`--row 5` on a
+5-row sheet). A far-off number (`--row 50`) is still refused: the API would
+create a gap.
+
+There is no batch form. Several cells means several `set-cell` calls. The
+sheet must be `IDLE`; `PROCESSING` is refused unless you pass `--force` (the
+row-runner can overwrite the cell).
+
+Long or multi-line answers: `--file` or `--stdin`, not `--text`. Prefer omitting
+`--log-json` / `--log-file`. If you attach a note, send `{text, actorType,
+createdAt}` with `actorType` `TOOL` or `ASSISTANT` and a current ISO-8601 time.
+`USER` and `SYSTEM` are rejected by the CLI.
+
+```bash
+unique-cli agentic-table set-cell mt_abc123 --row 1 --col 2 --text "The management fee is 2%."
+unique-cli agentic-table set-cell mt_abc123 --row 1 --col 2 --file ./answer.md
+```
+
+After a write, say which row and column you changed.
+
 ### Export answers
 
 ```bash
@@ -234,32 +275,38 @@ empty and the rest of the chain running against a sheet that does not exist.
 
 To fill in an existing questionnaire from a sheet someone else has already
 answered, skip the create and import steps: read the answers with
-`get-sheet --cells` or `get-cell`, and use `cell-history` if you need to know
-whether an answer came from a person or the assistant.
+`get-sheet --cells` or `get-cell`. `cell-history` is a stored log, not a bound
+identity signal — do not treat actor labels as proof a person vs the assistant
+wrote the cell.
 
-If a specific answer looks wrong or incomplete, fix that row with `rerun-row`
-and export again, rather than re-importing the question or rebuilding the
-sheet.
+If a generated answer looks wrong and you want the table agent to try again,
+fix that row with `rerun-row` and export again — not `set-cell`, and not
+re-import.
 
 ## Rules
 
 1. Rows and columns are numbered from 0, and row 0 is the header — so the first
-   question is row 1. This holds for `--row`/`--col` on `get-cell` and
-   `cell-history` and for `<row_order>` on `rerun-row` alike; the same number
-   means the same row in every command.
+   question is row 1. This holds for `--row`/`--col` on `get-cell`,
+   `cell-history`, and `set-cell`, and for `<row_order>` on `rerun-row`; the
+   same number means the same row in every command. `set-cell` may write row 0;
+   `rerun-row` may not.
 2. Fetch what you need, not everything. `get-cell` for one value,
    `get-sheet --cells` for an overview — don't dump a whole sheet unless asked.
+   Look up coordinates before `set-cell`; do not guess a column index.
 3. Use `--wait` when a later step depends on the result, and only then. Without
    it, `import` and `export` return as soon as the request is accepted, and the
-   answers or artifacts will not be ready yet.
+   answers or artifacts will not be ready yet. `set-cell` has no `--wait`: the
+   cell is updated when the command returns.
 4. Never re-run `import` with the same questions to "retry" — ids and texts
    already on the sheet are skipped, and a run that is already in flight will
    reject the call.
 5. Tell the user what you changed. A sheet is shared, and someone else may be
-   working in it.
+   working in it. For `set-cell`, name the row and column.
 6. Use `--json` when you need to parse fields programmatically (e.g. reading a
    `contentId` before downloading an export); use the default formatted output
    when summarising for a person.
+7. `set-cell` when you have the text. `rerun-row` when the table agent should
+   regenerate from sources. Never both for the same correction.
 
 ## Prerequisites