maybeai-sheet-cli 0.19.2__tar.gz → 0.20.0__tar.gz

{maybeai_sheet_cli-0.19.2 → maybeai_sheet_cli-0.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maybeai-sheet-cli
-Version: 0.19.2
+Version: 0.20.0
 Summary: CLI for common MaybeAI spreadsheet operations
 Project-URL: Homepage, https://github.com/OmniMCP-AI/maybeai-sheet-cli
 Project-URL: Repository, https://github.com/OmniMCP-AI/maybeai-sheet-cli
@@ -641,7 +641,7 @@ mbs db-table insert --doc-id abc123 --name orders-large --rows rows.json  # API
 mbs db-table create --doc-id abc123 --name Orders --rows orders.json  # API
 mbs db-table create-from-query --doc-id abc123 --name OrderSummary --sql-file order_summary.sql  # API
 mbs db-table create-from-range --doc-id target123 --name R_OrderLines_Store1 --source-doc-id source123 --worksheet-name "1店" --range A2:AR423 --header-row 0 --use-header-names --if-exists adopt --verify  # API
-mbs db-table update --doc-id abc123 --name Orders --key order_id --rows orders_patch.json  # PLAN
+mbs db-table update --doc-id abc123 --name Orders --key order_id --rows orders_patch.json  # API
 mbs db-table update --doc-id abc123 --name Orders --row-index 42 --rows row_patch.json  # PLAN
 mbs db-table update --doc-id abc123 --name Orders --where '{"status":"open"}' --rows status_patch.json  # PLAN
 mbs db-table update --doc-id abc123 --name Orders --column-index 3 --column-name status  # PLAN
@@ -751,6 +751,21 @@ is also CLI-composed: it reads a source worksheet range, reshapes header/data
 rows, then creates a PG/SheetTable on the target workbook. Use a keyset-style
 backend contract for deeper pagination when it becomes available.
 
+`db-table update` currently supports keyed row updates through the routed
+`update_range_by_lookup` backend contract:
+
+```bash
+mbs db-table update --doc-id abc123 --name Orders --key order_id --rows orders_patch.json
+```
+
+The `--key` column must be present in each row object and is used to match target
+rows, for example `order_id`, `sku`, or `id`. Patch files may include only the
+columns that should change; omitted columns are left unchanged. Blank values
+overwrite existing values only when `--override` is passed. Positional updates
+with `--row-index`, column-level updates with `--column-index` / `--column-name`,
+and JSON-filter updates with `--where` remain planned until the backend exposes a
+stable native db-table contract for those modes.
+
 Refactor planning is tracked separately from this README:
 `docs/superpowers/plans/2026-07-01-mbs-two-engine-command-refactor.md`.
 

{maybeai_sheet_cli-0.19.2 → maybeai_sheet_cli-0.20.0}/README.md

@@ -617,7 +617,7 @@ mbs db-table insert --doc-id abc123 --name orders-large --rows rows.json  # API
 mbs db-table create --doc-id abc123 --name Orders --rows orders.json  # API
 mbs db-table create-from-query --doc-id abc123 --name OrderSummary --sql-file order_summary.sql  # API
 mbs db-table create-from-range --doc-id target123 --name R_OrderLines_Store1 --source-doc-id source123 --worksheet-name "1店" --range A2:AR423 --header-row 0 --use-header-names --if-exists adopt --verify  # API
-mbs db-table update --doc-id abc123 --name Orders --key order_id --rows orders_patch.json  # PLAN
+mbs db-table update --doc-id abc123 --name Orders --key order_id --rows orders_patch.json  # API
 mbs db-table update --doc-id abc123 --name Orders --row-index 42 --rows row_patch.json  # PLAN
 mbs db-table update --doc-id abc123 --name Orders --where '{"status":"open"}' --rows status_patch.json  # PLAN
 mbs db-table update --doc-id abc123 --name Orders --column-index 3 --column-name status  # PLAN
@@ -727,6 +727,21 @@ is also CLI-composed: it reads a source worksheet range, reshapes header/data
 rows, then creates a PG/SheetTable on the target workbook. Use a keyset-style
 backend contract for deeper pagination when it becomes available.
 
+`db-table update` currently supports keyed row updates through the routed
+`update_range_by_lookup` backend contract:
+
+```bash
+mbs db-table update --doc-id abc123 --name Orders --key order_id --rows orders_patch.json
+```
+
+The `--key` column must be present in each row object and is used to match target
+rows, for example `order_id`, `sku`, or `id`. Patch files may include only the
+columns that should change; omitted columns are left unchanged. Blank values
+overwrite existing values only when `--override` is passed. Positional updates
+with `--row-index`, column-level updates with `--column-index` / `--column-name`,
+and JSON-filter updates with `--where` remain planned until the backend exposes a
+stable native db-table contract for those modes.
+
 Refactor planning is tracked separately from this README:
 `docs/superpowers/plans/2026-07-01-mbs-two-engine-command-refactor.md`.
 

{maybeai_sheet_cli-0.19.2 → maybeai_sheet_cli-0.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "maybeai-sheet-cli"
-version = "0.19.2"
+version = "0.20.0"
 description = "CLI for common MaybeAI spreadsheet operations"
 readme = "README.md"
 requires-python = ">=3.10"

{maybeai_sheet_cli-0.19.2 → maybeai_sheet_cli-0.20.0}/src/maybeai_sheet/commands/db_table.py

@@ -1162,9 +1162,6 @@ import data:
 DB_TABLE_UPDATE_EXAMPLE = """Example:
 
   mbs db-table update --doc-id <doc_id> --name Orders --key order_id --rows orders_patch.json
-  mbs db-table update --doc-id <doc_id> --name Orders --row-index 42 --rows row_patch.json
-  mbs db-table update --doc-id <doc_id> --name Orders --where '{"status":"open"}' --rows status_patch.json
-  mbs db-table update --doc-id <doc_id> --name Orders --column-index 3 --column-name status
 
 `orders_patch.json` should contain row objects keyed by --key. Positional
 updates use 1-based --row-index and --column-index when the backend exposes a
@@ -1574,12 +1571,16 @@ def create_from_range(
 
 @app.command(
     "update",
-    help="Planned: update PG/SheetTable-backed rows from JSON row data.",
+    help="Update PG/SheetTable-backed rows by lookup key from JSON row data.",
     epilog=DB_TABLE_UPDATE_EXAMPLE,
 )
 def update(
+    ctx: typer.Context,
     doc_id: Optional[str] = typer.Option(None, "--doc-id", help="MaybeAI document ID."),
+    url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
+    uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
     name: Optional[str] = typer.Option(None, "--name", help="PG-backed table name."),
+    backend_id: Optional[str] = typer.Option(None, "--backend-id", help="Advanced backend table id."),
     key: Optional[str] = typer.Option(None, "--key", help="Unique key column for matching rows."),
     row_index: Optional[int] = typer.Option(None, "--row-index", min=1, help="1-based SheetTable row index to update."),
     column_index: Optional[int] = typer.Option(None, "--column-index", min=1, help="1-based SheetTable column index to update."),
@@ -1593,10 +1594,60 @@ def update(
         resolve_path=True,
         help="Path to JSON rows payload.",
     ),
+    override: bool = typer.Option(False, "--override", help="Allow blank values in --rows to overwrite existing cells."),
+    skip_recalculation: bool = typer.Option(False, "--skip-recalculation", help="Skip immediate recalculation."),
+    output: Optional[str] = output_option(),
+    verbose: Optional[bool] = verbose_option(),
+    timeout: Optional[float] = timeout_option(),
 ) -> None:
-    _ = (doc_id, name, key, row_index, column_index, column_name, where, rows)
     try:
-        _planned_db_table_error("update", DB_TABLE_UPDATE_EXAMPLE)
+        if row_index is not None or column_index is not None or column_name is not None or where is not None:
+            raise UsageError(
+                "db-table update currently supports keyed row updates only. "
+                "Use --key with --rows; --row-index, --column-index, --column-name, and --where are planned."
+            )
+        if not key or not key.strip():
+            raise UsageError("Provide --key for db-table update.")
+        if rows is None:
+            raise UsageError("Provide --rows for db-table update.")
+        state = _state(
+            ctx,
+            doc_id=doc_id,
+            url=url,
+            uri=uri,
+            output=output,
+            verbose=verbose,
+            timeout=timeout,
+        )
+        workbook_target = resolve_target(state)
+        client = MaybeAIClient(state)
+        resolved, target = _resolve_db_table(
+            client=client,
+            target=workbook_target,
+            name=name,
+            backend_id=backend_id,
+        )
+        endpoint = "/api/v1/excel/update_range_by_lookup"
+        response = client.post_json(
+            endpoint,
+            {
+                "uri": target.uri,
+                "worksheet_name": resolved.worksheet_name,
+                "data": _load_rows(rows),
+                "on": [key.strip()],
+                "override": override,
+                "skip_recalculation": skip_recalculation,
+            },
+        )
+        render_output(
+            build_command_output(
+                endpoint=endpoint,
+                target=target,
+                result=response,
+                metadata=get_endpoint_metadata("db-table.update") if state.verbose else None,
+            ),
+            state.output,
+        )
     except Exception as error:  # pragma: no cover - CLI boundary
         handle_cli_error(error)
 

{maybeai_sheet_cli-0.19.2 → maybeai_sheet_cli-0.20.0}/src/maybeai_sheet/commands/style.py

@@ -51,6 +51,28 @@ _BEAUTIFY_DEFAULTS: dict[str, object] = {
     "preset": "clean_data_table",
     "hideGridlines": True,
 }
+_BEAUTIFY_BODY_BANDING: dict[str, object] = {
+    "enabled": True,
+    "oddRowBackground": "#FFFFFF",
+    "evenRowBackground": "#F8FAFC",
+}
+_BEAUTIFY_COLUMN_POLICY: dict[str, object] = {
+    "backgroundBySemanticType": False,
+    "allowFontColorBySemanticType": True,
+    "allowFormatBySemanticType": True,
+    "allowAlignmentBySemanticType": True,
+}
+_BEAUTIFY_CONFIG_KEYS = frozenset(
+    {
+        "defaults",
+        "layout",
+        "bodyBanding",
+        "columnPolicy",
+        "headerStyle",
+        "categoryStyles",
+        "sampling",
+    }
+)
 _BEAUTIFY_SAMPLE_RANGE = "A1:ZZ20"
 _BEAUTIFY_HEADER_STYLE: dict[str, object] = {
     "bold": True,
@@ -78,47 +100,40 @@ _BEAUTIFY_TEXT_STYLE: dict[str, object] = {
     "format": "text",
     "horizontal": "left",
     "vertical": "middle",
-    "bg_color": "#FFFFFF",
 }
 _BEAUTIFY_DATE_STYLE: dict[str, object] = {
     "format": "date",
     "format_code": "yyyy-mm-dd",
     "horizontal": "center",
-    "bg_color": "#F8FAFC",
 }
 _BEAUTIFY_CURRENCY_STYLE: dict[str, object] = {
     "format": "currency",
     "format_code": "$#,##0.00",
     "horizontal": "right",
     "font_color": "#065F46",
-    "bg_color": "#ECFDF5",
 }
 _BEAUTIFY_PERCENT_STYLE: dict[str, object] = {
     "format": "percent",
     "format_code": "0.00%",
     "horizontal": "right",
     "font_color": "#1D4ED8",
-    "bg_color": "#EFF6FF",
 }
 _BEAUTIFY_INTEGER_STYLE: dict[str, object] = {
     "format": "integer",
     "format_code": "#,##0",
     "horizontal": "right",
     "font_color": "#581C87",
-    "bg_color": "#F5F3FF",
 }
 _BEAUTIFY_NUMBER_STYLE: dict[str, object] = {
     "format": "number",
     "format_code": "0.00",
     "horizontal": "right",
     "font_color": "#374151",
-    "bg_color": "#F9FAFB",
 }
 _BEAUTIFY_STATUS_STYLE: dict[str, object] = {
     "format": "text",
     "horizontal": "left",
     "font_color": "#92400E",
-    "bg_color": "#FEF3C7",
 }
 _BEAUTIFY_STYLE_BY_CATEGORY: dict[str, dict[str, object]] = {
     "text": _BEAUTIFY_TEXT_STYLE,
@@ -129,6 +144,47 @@ _BEAUTIFY_STYLE_BY_CATEGORY: dict[str, dict[str, object]] = {
     "number": _BEAUTIFY_NUMBER_STYLE,
     "status": _BEAUTIFY_STATUS_STYLE,
 }
+
+
+def _default_beautify_style_policy() -> dict[str, object]:
+    return {
+        "defaults": dict(_BEAUTIFY_DEFAULTS),
+        "bodyBanding": dict(_BEAUTIFY_BODY_BANDING),
+        "columnPolicy": dict(_BEAUTIFY_COLUMN_POLICY),
+    }
+
+
+def _merge_dict(base: dict[str, object], override: object, *, option: str) -> dict[str, object]:
+    if override is None:
+        return dict(base)
+    if not isinstance(override, dict):
+        raise UsageError(f"{option} must be a JSON object.")
+    merged = dict(base)
+    merged.update(override)
+    return merged
+
+
+def _beautify_config(config_path: Path | None) -> tuple[dict[str, object] | None, str | None]:
+    if config_path is None:
+        return None, None
+    config = load_json_object_argument(config_path, option="--config")
+    unsupported = sorted(set(config) - _BEAUTIFY_CONFIG_KEYS)
+    if unsupported:
+        raise UsageError(f"--config contains unsupported keys: {', '.join(unsupported)}.")
+    return config, str(config_path)
+
+
+def _beautify_style_policy(config: dict[str, object] | None = None) -> dict[str, object]:
+    policy = _default_beautify_style_policy()
+    if not config:
+        return policy
+    if "defaults" in config:
+        policy["defaults"] = _merge_dict(policy["defaults"], config["defaults"], option="--config defaults")  # type: ignore[arg-type]
+    if "bodyBanding" in config:
+        policy["bodyBanding"] = _merge_dict(policy["bodyBanding"], config["bodyBanding"], option="--config bodyBanding")  # type: ignore[arg-type]
+    if "columnPolicy" in config:
+        policy["columnPolicy"] = _merge_dict(policy["columnPolicy"], config["columnPolicy"], option="--config columnPolicy")  # type: ignore[arg-type]
+    return policy
 _BEAUTIFY_KEYWORDS: dict[str, tuple[str, ...]] = {
     "date": (
         "date",
@@ -580,6 +636,39 @@ def _beautify_workbook_payload(
     }
 
 
+def _is_styleable_worksheet(worksheet: dict[str, object]) -> bool:
+    worksheet_name = _worksheet_name(worksheet)
+    if not worksheet_name:
+        return False
+    row_count = _int_payload_value(worksheet, ("row_count", "rows", "total_rows", "max_row"))
+    column_count = _int_payload_value(
+        worksheet,
+        ("column_count", "col_count", "columns", "total_columns", "max_column", "max_col"),
+    )
+    return not ((row_count is not None and row_count <= 0) or (column_count is not None and column_count <= 0))
+
+
+def _select_beautify_worksheets(target, worksheet_response: dict[str, object]) -> list[dict[str, object]]:
+    styleable = [worksheet for worksheet in _worksheet_items(worksheet_response) if _is_styleable_worksheet(worksheet)]
+    if not styleable:
+        if target.worksheet_name:
+            raise UsageError(f"No styleable worksheet found for --worksheet-name {target.worksheet_name!r}.")
+        raise UsageError("No styleable worksheets found. The workbook may be empty or missing dimensions.")
+    if target.worksheet_name:
+        selected = [worksheet for worksheet in styleable if _worksheet_name(worksheet) == target.worksheet_name]
+        if not selected:
+            raise UsageError(f"No styleable worksheet found for --worksheet-name {target.worksheet_name!r}.")
+        return selected[:1]
+    if target.gid is not None:
+        selected = [worksheet for worksheet in styleable if _worksheet_gid(worksheet) == target.gid]
+        if not selected:
+            raise UsageError(f"No styleable worksheet found for gid {target.gid}.")
+        return selected[:1]
+    if len(styleable) == 1:
+        return styleable
+    raise UsageError("Workbook has multiple styleable worksheets. Provide --gid or --worksheet-name.")
+
+
 def _bounded_table_range_from_shape(column_count: int, row_count: int) -> str:
     if column_count <= 0 or row_count <= 0:
         raise UsageError("Cannot beautify an empty worksheet.")
@@ -867,6 +956,7 @@ def _excel_column_style_operations(
             continue
         operations.append(
             {
+                "kind": "semantic_column_style",
                 "range_addresses": [
                     f"{_column_letters_from_index(run_start)}2:{_column_letters_from_index(one_based_index - 1)}{data_last_row}"
                 ],
@@ -877,6 +967,7 @@ def _excel_column_style_operations(
         run_style = style
     operations.append(
         {
+            "kind": "semantic_column_style",
             "range_addresses": [
                 f"{_column_letters_from_index(run_start)}2:{_column_letters_from_index(len(headers))}{data_last_row}"
             ],
@@ -886,7 +977,51 @@ def _excel_column_style_operations(
     return operations
 
 
-def _excel_beautify_plan(worksheet: dict[str, object], read_response: dict[str, object] | None = None) -> dict[str, object]:
+def _excel_body_banding_operations(
+    *,
+    column_count: int,
+    last_row: int,
+    style_policy: dict[str, object],
+) -> list[dict[str, object]]:
+    banding = style_policy.get("bodyBanding")
+    if not isinstance(banding, dict) or banding.get("enabled") is False:
+        return []
+    if column_count <= 0 or last_row < 2:
+        return []
+    odd_background = str(banding.get("oddRowBackground", "#FFFFFF"))
+    even_background = str(banding.get("evenRowBackground", "#F8FAFC"))
+    last_column = _column_letters_from_index(column_count)
+    odd_ranges: list[str] = []
+    even_ranges: list[str] = []
+    for row_number in range(2, last_row + 1):
+        target = odd_ranges if (row_number - 2) % 2 == 0 else even_ranges
+        target.append(f"A{row_number}:{last_column}{row_number}")
+    operations: list[dict[str, object]] = []
+    if odd_ranges:
+        operations.append(
+            {
+                "kind": "body_banding",
+                "range_addresses": odd_ranges,
+                "style": {"bg_color": odd_background},
+            }
+        )
+    if even_ranges:
+        operations.append(
+            {
+                "kind": "body_banding",
+                "range_addresses": even_ranges,
+                "style": {"bg_color": even_background},
+            }
+        )
+    return operations
+
+
+def _excel_beautify_plan(
+    worksheet: dict[str, object],
+    read_response: dict[str, object] | None = None,
+    *,
+    style_policy: dict[str, object] | None = None,
+) -> dict[str, object]:
     headers = _header_values_from_read_response(read_response or {})
     if not headers:
         column_count = _int_payload_value(
@@ -902,10 +1037,12 @@ def _excel_beautify_plan(worksheet: dict[str, object], read_response: dict[str,
     classifications = _excel_column_classifications(headers, read_response)
     last_row = _range_data_last_row(table_range)
     header_range = f"A1:{_column_letters_from_index(column_count)}1"
+    resolved_style_policy = style_policy or _default_beautify_style_policy()
     return {
         "worksheet_name": _worksheet_name(worksheet),
         "engine": "excelize",
         "table_range": table_range,
+        "style_policy": resolved_style_policy,
         "headers": headers,
         "columns": [
             _column_classification_plan(
@@ -917,14 +1054,17 @@ def _excel_beautify_plan(worksheet: dict[str, object], read_response: dict[str,
         ],
         "operations": [
             {
+                "kind": "freeze_header",
                 "endpoint": "/api/v1/excel/freeze_panes",
                 "payload": {"freeze_rows": 1, "freeze_columns": 0},
             },
             {
+                "kind": "filter",
                 "endpoint": "/api/v1/excel/set_auto_filter",
                 "payload": {"auto_filter": {"ref": table_range}},
             },
             {
+                "kind": "header_style",
                 "endpoint": "/api/v1/excel/batch_set_cell_style",
                 "payload": {
                     "range_addresses": [header_range],
@@ -933,8 +1073,21 @@ def _excel_beautify_plan(worksheet: dict[str, object], read_response: dict[str,
             },
             *[
                 {
+                    "kind": operation.get("kind", "body_banding"),
+                    "endpoint": "/api/v1/excel/batch_set_cell_style",
+                    "payload": {key: value for key, value in operation.items() if key != "kind"},
+                }
+                for operation in _excel_body_banding_operations(
+                    column_count=column_count,
+                    last_row=last_row,
+                    style_policy=resolved_style_policy,
+                )
+            ],
+            *[
+                {
+                    "kind": operation.get("kind", "semantic_column_style"),
                     "endpoint": "/api/v1/excel/batch_set_cell_style",
-                    "payload": operation,
+                    "payload": {key: value for key, value in operation.items() if key != "kind"},
                 }
                 for operation in _excel_column_style_operations(headers, classifications, last_row)
             ],
@@ -942,6 +1095,65 @@ def _excel_beautify_plan(worksheet: dict[str, object], read_response: dict[str,
     }
 
 
+def _bounded_verify_range(table_range: object) -> str:
+    if not isinstance(table_range, str):
+        return "A1:Z20"
+    end = _range_end(table_range)
+    if end is None:
+        return "A1:Z20"
+    column_count = min(column_index_from_letters(end[0]), column_index_from_letters("Z"))
+    row_count = min(end[1], 20)
+    return f"A1:{_column_letters_from_index(column_count)}{row_count}"
+
+
+def _excel_beautify_verify(client: MaybeAIClient, *, target, plan: dict[str, object]) -> dict[str, object]:
+    worksheet_name = plan.get("worksheet_name")
+    try:
+        read_payload = base_payload(
+            SimpleNamespace(uri=target.uri, worksheet_name=worksheet_name if isinstance(worksheet_name, str) else None)
+        ) | {
+            "range_address": _bounded_verify_range(plan.get("table_range")),
+            "value_render_option": "FORMATTED_VALUE",
+        }
+        read_response = client.post_json("/api/v1/excel/read_sheet", read_payload)
+        return {
+            "success": bool(read_response.get("success", True)),
+            "scope": "worksheet_sample",
+            "endpoint": "/api/v1/excel/read_sheet",
+            "range_address": read_payload["range_address"],
+            "worksheet_name": worksheet_name,
+            "response": read_response,
+        }
+    except Exception as error:  # verify is best-effort after a successful apply
+        return {
+            "success": False,
+            "scope": "worksheet_sample",
+            "endpoint": "/api/v1/excel/read_sheet",
+            "worksheet_name": worksheet_name,
+            "error": str(error),
+        }
+
+
+def _pg_beautify_verify(client: MaybeAIClient, *, target, gid: int) -> dict[str, object]:
+    try:
+        metadata_response = client.post_json("/api/v1/excel/table/metadata", _pg_table_metadata_payload(target, gid))
+        return {
+            "success": bool(metadata_response.get("success", True)),
+            "scope": "field_metadata",
+            "endpoint": "/api/v1/excel/table/metadata",
+            "gid": gid,
+            "response": metadata_response,
+        }
+    except Exception as error:
+        return {
+            "success": False,
+            "scope": "field_metadata",
+            "endpoint": "/api/v1/excel/table/metadata",
+            "gid": gid,
+            "error": str(error),
+        }
+
+
 def _pg_fields_from_metadata(metadata_response: dict[str, object], *, gid: int, worksheet_name: str | None) -> list[dict[str, object]]:
     tables = metadata_response.get("tables")
     if not isinstance(tables, list):
@@ -1021,11 +1233,17 @@ def _pg_beautify_field_update(
     style = classification.style
     existing_property = field.get("property")
     property_payload: dict[str, object] = dict(existing_property) if isinstance(existing_property, dict) else {}
-    beautify_property = _field_property_payload(
-        formatter=str(style["format_code"]) if "format_code" in style else None,
-        color=str(style["font_color"]) if "font_color" in style else None,
-        background_color=str(style["bg_color"]) if "bg_color" in style else None,
-        width=None,
+    formatter = str(style["format_code"]) if "format_code" in style else None
+    font_color = str(style["font_color"]) if "font_color" in style else None
+    beautify_property = (
+        _field_property_payload(
+            formatter=formatter,
+            color=font_color,
+            background_color=None,
+            width=None,
+        )
+        if formatter is not None or font_color is not None
+        else {}
     )
     beautify_style = beautify_property.pop("style", None)
     property_payload.update(beautify_property)
@@ -1909,20 +2127,27 @@ def beautify(
     doc_id: Optional[str] = typer.Option(None, "--doc-id", "--docs-id", help="MaybeAI document ID."),
     url: Optional[str] = typer.Option(None, "--url", help="MaybeAI workbook URL."),
     uri: Optional[str] = typer.Option(None, "--uri", help="Resolved workbook URI."),
+    gid: Optional[int] = typer.Option(None, "--gid", help="Worksheet gid."),
     worksheet_name: Optional[str] = typer.Option(None, "--worksheet-name", help="Optional worksheet name to beautify."),
     mode: Optional[str] = typer.Option(None, "--mode", help="single_table, multi_table, or auto_detect."),
     dry_run: bool = typer.Option(False, "--dry-run", help="Preview the generated beautify plan without applying styles."),
+    verify: bool = typer.Option(False, "--verify", help="Read back a bounded sample after applying styles."),
+    config: Optional[Path] = typer.Option(None, "--config", exists=True, dir_okay=False, help="Optional JSON beautify style policy."),
     output: Optional[str] = output_option(),
     verbose: Optional[bool] = verbose_option(),
     timeout: Optional[float] = timeout_option(),
 ) -> None:
     try:
+        if dry_run and verify:
+            raise UsageError("--dry-run and --verify cannot be combined.")
+        config_payload, config_source = _beautify_config(config)
+        style_policy = _beautify_style_policy(config_payload)
         state = common_options(
             ctx,
             doc_id=doc_id,
             url=url,
             uri=uri,
-            gid=None,
+            gid=gid,
             worksheet_name=worksheet_name,
             output=output,
             verbose=verbose,
@@ -1939,28 +2164,11 @@ def beautify(
             },
         )
         _worksheet_style_mode(mode)
-        selected_worksheets: list[dict[str, object]] = []
-        for worksheet in _worksheet_items(worksheet_response):
-            worksheet_item_name = _worksheet_name(worksheet)
-            if not worksheet_item_name:
-                continue
-            if worksheet_name and worksheet_item_name != worksheet_name:
-                continue
-            row_count = _int_payload_value(worksheet, ("row_count", "rows", "total_rows", "max_row"))
-            column_count = _int_payload_value(
-                worksheet,
-                ("column_count", "col_count", "columns", "total_columns", "max_column", "max_col"),
-            )
-            if (row_count is not None and row_count <= 0) or (column_count is not None and column_count <= 0):
-                continue
-            selected_worksheets.append(worksheet)
-        if not selected_worksheets:
-            if worksheet_name:
-                raise UsageError(f"No styleable worksheet found for --worksheet-name {worksheet_name!r}.")
-            raise UsageError("No styleable worksheets found. The workbook may be empty or missing dimensions.")
+        selected_worksheets = _select_beautify_worksheets(target, worksheet_response)
 
         plans: list[dict[str, object]] = []
         responses: list[dict[str, object]] = []
+        verify_results: list[dict[str, object]] = []
         if dry_run:
             for worksheet in selected_worksheets:
                 engine = _normalize_engine(worksheet.get("data_engine") or worksheet.get("engine"))
@@ -1993,6 +2201,7 @@ def beautify(
                             "gid": gid,
                             "metadata_endpoint": "/api/v1/excel/table/metadata",
                             "operation": "field formatter/style updates with header layout defaults",
+                            "style_policy": style_policy,
                             "layout": _pg_beautify_layout_plan(len(fields)),
                             "columns": columns,
                             "fields": columns,
@@ -2007,7 +2216,7 @@ def beautify(
                     "value_render_option": "FORMATTED_VALUE",
                 }
                 read_response = client.post_json("/api/v1/excel/read_sheet", read_payload)
-                plans.append(_excel_beautify_plan(worksheet, read_response))
+                plans.append(_excel_beautify_plan(worksheet, read_response, style_policy=style_policy))
             response: dict[str, object] = {
                 "success": True,
                 "dry_run": True,
@@ -2076,6 +2285,8 @@ def beautify(
                     )
                     if fallback_reason:
                         responses[-1]["batch_update_fallback_reason"] = fallback_reason
+                    if verify:
+                        verify_results.append(_pg_beautify_verify(client, target=target, gid=gid))
                     continue
 
                 read_payload = base_payload(
@@ -2085,7 +2296,7 @@ def beautify(
                     "value_render_option": "FORMATTED_VALUE",
                 }
                 read_response = client.post_json("/api/v1/excel/read_sheet", read_payload)
-                plan = _excel_beautify_plan(worksheet, read_response)
+                plan = _excel_beautify_plan(worksheet, read_response, style_policy=style_policy)
                 plans.append(plan)
                 operation_responses: list[dict[str, object]] = []
                 for operation in plan["operations"]:
@@ -2109,6 +2320,8 @@ def beautify(
                         "operations": operation_responses,
                     }
                 )
+                if verify:
+                    verify_results.append(_excel_beautify_verify(client, target=target, plan=plan))
             response = {
                 "success": all(bool(item.get("success", True)) for item in responses),
                 "styled_worksheet_count": len(responses),
@@ -2142,7 +2355,10 @@ def beautify(
                     "list_endpoint": list_endpoint,
                     "worksheet_count": len(plans),
                     "engine": plans[0].get("engine") if len(plans) == 1 else "mixed",
+                    "config_applied": config_payload is not None,
+                    **({"config_source": config_source} if config_source else {}),
                 },
+                verify=verify_results[0] if len(verify_results) == 1 else (verify_results or None),
                 metadata=get_endpoint_metadata("style.beautify") if state.verbose else None,
             ),
             state.output,