maybeai-sheet-cli 0.4.1__tar.gz → 0.6.0__tar.gz

{maybeai_sheet_cli-0.4.1 → maybeai_sheet_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maybeai-sheet-cli
-Version: 0.4.1
+Version: 0.6.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
@@ -90,8 +90,7 @@ Optional global flags:
 
 ## Quick Start
 
-The examples below follow the target protocol names. The currently shipped
-compatibility aliases are listed in the Implemented Command Tree.
+The examples below follow the target protocol names.
 
 List user-visible workbooks:
 
@@ -99,10 +98,11 @@ List user-visible workbooks:
 mbs workbook list-user-workbooks --limit 20
 ```
 
-Read a bounded range:
+Read a worksheet:
 
 ```bash
-mbs excel-worksheet range read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:H1
 ```
 
 List worksheets:
@@ -135,6 +135,13 @@ Import a large table-like `.xlsx` into SheetTable/PG:
 mbs workbook import ./large-table.xlsx --engine postgres
 ```
 
+Import a mixed workbook and let the backend select engines per worksheet:
+
+```bash
+mbs workbook import ./mixed-workbook.xlsx --engine auto
+mbs workbook import ./mixed-workbook.xlsx --engine "postgres,excel,excel,postgres"
+```
+
 Append rows and verify:
 
 ```bash
@@ -176,131 +183,13 @@ CLI command names normalize these relationship labels to hyphenated groups:
 `excel_worksheet` becomes `excel-worksheet`, `excel_table` becomes
 `excel-table`, and `db_worksheet(db_table)` becomes `db-table`.
 
-## Implemented Command Tree
-
-This is the current shipped command surface. The full roadmap tree below is
-separate and includes planned or deferred commands.
-
-```text
-mbs
-├── update
-│   └── Update maybeai-sheet-cli from PyPI.
-│
-├── workbook
-│   ├── create             Create a new workbook.
-│   ├── create-from-file   Import an .xlsx file.
-│   ├── import             Preferred alias for create-from-file.
-│   ├── metadata           Inspect workbook profile and routing metadata.
-│   ├── list-user-workbooks
-│   │                      Preferred alias for bounded user workbook listing.
-│   ├── list-worksheets    List worksheets in a workbook.
-│   ├── list               List user workbooks with bounded output.
-│   ├── search             Search user workbooks with bounded output.
-│   ├── manifest           Compatibility alias for metadata.
-│   └── capabilities       Inspect workbook capability/profile metadata.
-│
-├── excel-worksheet
-│   ├── metadata           Inspect worksheet metadata through workbook profile.
-│   └── list-table         List worksheet/table metadata for a workbook.
-│
-├── excel-table
-│   ├── metadata           Resolve a worksheet-backed table from workbook metadata.
-│   ├── schema             Infer schema from a resolved worksheet-backed table range.
-│   ├── sample             Return bounded table sample rows.
-│   ├── read               Read a resolved worksheet-backed table range.
-│   └── insert             Insert row objects into a worksheet-backed table.
-│
-├── db-table
-│   ├── metadata           Resolve PG/SheetTable-backed worksheet metadata.
-│   ├── schema             Infer schema from a bounded PG read.
-│   ├── sample             Return bounded PG table sample rows.
-│   ├── read               Read PG-backed table rows through routed APIs.
-│   └── insert             Insert rows into a PG-backed table.
-│
-├── worksheet
-│   ├── list               List worksheets in a workbook.
-│   ├── create             Create a worksheet, optionally with starter values.
-│   ├── rename             Rename a worksheet.
-│   ├── delete             Delete a worksheet; requires --yes unless --dry-run.
-│   ├── copy               Copy a worksheet.
-│   └── move               Move a worksheet to a zero-based index.
-│
-├── range
-│   ├── read               Read a bounded A1 range.
-│   ├── write              Write a JSON matrix into an A1 range.
-│   ├── clear              Clear an A1 range.
-│   └── search             Search a worksheet with bounded results.
-│
-├── row
-│   ├── insert             Insert rows.
-│   ├── delete             Delete rows; requires --yes unless --dry-run.
-│   └── move               Move rows.
-│
-├── column
-│   ├── insert             Insert columns.
-│   ├── delete             Delete columns; requires --yes unless --dry-run.
-│   ├── move               Move columns.
-│   └── width              Set column width.
-│
-├── formula
-│   ├── read               Read formulas with FORMULA render mode.
-│   ├── set                Set one formula cell.
-│   ├── batch-set          Set formula ranges from a JSON operations file.
-│   ├── recalculate        Recalculate formulas for a worksheet/workbook.
-│   ├── calculate          Calculate one formula cell.
-│   └── lineage            Trace formula lineage for one cell.
-│
-├── style
-│   ├── freeze-panes       Freeze rows/columns using an A1 cell boundary.
-│   ├── auto-filter set    Set worksheet auto-filter range.
-│   ├── auto-filter remove Remove worksheet auto-filter.
-│   ├── columns-width      Set column widths.
-│   └── rows-height        Set row heights.
-│
-├── history
-│   ├── list               List workbook versions with bounded output.
-│   └── read               Read a workbook version.
-│
-├── file
-│   ├── export             Export workbook bytes to --out.
-│   ├── list               List files with bounded output.
-│   └── search             Search files with bounded output.
-│
-├── share
-│   ├── visibility         Set workbook visibility.
-│   ├── grant              Grant a user permission.
-│   ├── permission         Read current permission.
-│   ├── remove             Remove a user's access.
-│   └── list               List sharing entries.
-│
-├── raw
-│   └── post               Low-level POST escape hatch for routed API paths.
-│
-└── sheet                  Legacy compatibility aliases.
-    ├── read
-    ├── read-range
-    ├── read-many
-    ├── named-range
-    ├── headers
-    ├── worksheets
-    ├── formulas
-    ├── write-range
-    ├── clear-range
-    ├── append
-    ├── upsert
-    ├── formula-set
-    ├── formula-batch-set
-    ├── recalculate
-    └── create-worksheet
-```
 
 ## Full Command Tree
 
 The reviewed tree below is the source of truth for the protocol shape. Product
 model labels in this block use underscores; CLI names in examples and future
 router code should normalize them to hyphenated command groups such as
-`excel-worksheet`, `excel-table`, and `db-table`. The older `sheet ...`
-commands remain available as compatibility aliases. This tree includes
+`excel-worksheet`, `excel-table`, and `db-table`. This tree includes
 implemented, planned, deferred, and not-recommended command surfaces.
 
 Status legend for the full tree:
@@ -336,6 +225,7 @@ mbs
 │   └── rename                   API   Rename a stored file.
 │
 ├── excel_worksheet
+│   ├── read                     API   Read the full range of the worksheet.
 │   ├── list-table               API   List worksheets in a workbook.
 │   ├── create                   API   Create a worksheet, optionally with starter values.
 │   ├── update                   API   Update worksheet metadata.
@@ -369,9 +259,9 @@ mbs
 |   |- lineage                   API   Trace cell/range lineage.
 │
 ├── db_worksheet(AKA db_table)
-│   ├── create                   PG    Create a PG-backed table.
-│   ├── update                   PG    Update PG-backed table metadata.
-│   ├── delete                   PG    Delete a PG-backed table; requires --yes unless --dry-run.
+│   ├── create                   PLAN  Create a PG-backed table from JSON row data.
+│   ├── update                   PLAN  Update PG-backed rows from JSON row data.
+│   ├── delete                   PLAN  Delete PG-backed rows/table; requires --yes unless --dry-run.
 │   ├── schema                   API   Infer table schema from a bounded PG read.
 │   ├── sample                   API   Return bounded table sample rows.
 │   ├── read                     API   Read PG-backed table rows.
@@ -434,24 +324,6 @@ mbs
 │   ├── create                   API   Create or grant sharing access.
 │   ├── remove                   API   Remove a user's access.
 │   ├── modify                   API   Modify sharing access.
-│
-│
-└── sheet                  Legacy compatibility aliases.
-    ├── read
-    ├── read-range
-    ├── read-many
-    ├── named-range
-    ├── headers
-    ├── worksheets
-    ├── formulas
-    ├── write-range
-    ├── clear-range
-    ├── append
-    ├── upsert
-    ├── formula-set
-    ├── formula-batch-set
-    ├── recalculate
-    └── create-worksheet
 ```
 
 Full tree examples:
@@ -474,13 +346,15 @@ mbs workbook copy --doc-id abc123 --name "Budget Copy"  # API
 mbs workbook delete --doc-id abc123 --dry-run  # API
 
 # excel-worksheet
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Actuals  # API
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API
 mbs excel-worksheet create --doc-id abc123 --name Actuals  # API
 mbs excel-worksheet update --doc-id abc123 --worksheet-name Actuals --title "Actuals FY26"  # API
 mbs excel-worksheet metadata --doc-id abc123 --worksheet-name Actuals  # API
 mbs excel-worksheet sample --doc-id abc123 --worksheet-name Actuals --range A1:Z5000 --limit 50  # PLAN
 
 # excel-worksheet range
-mbs excel-worksheet range read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API
+mbs excel-worksheet range read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API, advanced structured alias
 mbs excel-worksheet range used-range --doc-id abc123 --worksheet-name Actuals  # PLAN
 mbs excel-worksheet range lineage --doc-id abc123 --worksheet-name Model --cell E2 --format tree  # API
 
@@ -496,8 +370,17 @@ mbs excel-table style columns-width --doc-id abc123 --worksheet-name Orders --ta
 mbs db-table metadata --doc-id abc123 --name orders-large  # API
 mbs db-table schema --doc-id abc123 --name orders-large  # API
 mbs db-table sample --doc-id abc123 --name orders-large --limit 50  # API
-mbs db-table read --doc-id abc123 --name orders-large --limit 50  # API
+mbs db-table read --doc-id abc123 --name orders-large --limit 100 --offset 200  # API
 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  # PLAN
+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 --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
+mbs db-table delete --doc-id abc123 --name Orders --where '{"order_id":"A1"}' --yes  # PLAN
+mbs db-table delete --doc-id abc123 --name Orders --row-index 42 --count 10 --yes  # PLAN
+mbs db-table delete --doc-id abc123 --name Orders --column-index 3 --yes  # PLAN
+mbs db-table delete --doc-id abc123 --name Orders --column-name status --yes  # PLAN
 
 # row
 mbs excel-worksheet row insert --doc-id abc123 --worksheet-name Actuals --row 10 --count 2  # API
@@ -535,11 +418,13 @@ mbs version restore --doc-id abc123 --version-id v42 --dry-run  # PLAN
 
 # share
 mbs share create --doc-id abc123 --email teammate@example.com --role viewer  # API
-
-# sheet
-mbs sheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
 ```
 
+`db-table read`, `schema`, and `sample` keep reads bounded. The default read
+limit is 100 rows, and `--limit` / `--offset` are capped at 10,000 to avoid
+accidental large PG scans. Use a keyset-style backend contract for deeper
+pagination when it becomes available.
+
 Refactor planning is tracked separately from this README:
 `docs/superpowers/plans/2026-07-01-mbs-two-engine-command-refactor.md`.
 
@@ -561,8 +446,8 @@ dependency graph beyond cell lineage             PLAN
 Relationship guide:
 
 - Use `workbook` for file-level creation, upload/import, and manifest checks.
-- Use `excel-worksheet` for Excel tab lifecycle operations and worksheet/range
-  inspection.
+- Use `excel-worksheet read` for full worksheet used-range inspection.
+- Use `excel-worksheet` for Excel tab lifecycle operations.
 - Use `excel-worksheet range` for coordinate-based reads, writes, formulas, and
   cell lineage.
 - Use `excel-table` for worksheet-backed table views. One Excel worksheet can
@@ -597,7 +482,7 @@ Targeting notes:
   from workbook metadata, for example `--table-id 1`, and maps internally to
   table metadata such as `worksheet_name` and `range`.
 - Use `--name` or backend ids when operating on a `db-table`.
-- Use `--gid` only for legacy gid-specific compatibility aliases.
+- Use `--gid` only when a route specifically requires gid targeting.
 
 ## Input Rules
 

{maybeai_sheet_cli-0.4.1 → maybeai_sheet_cli-0.6.0}/README.md

@@ -66,8 +66,7 @@ Optional global flags:
 
 ## Quick Start
 
-The examples below follow the target protocol names. The currently shipped
-compatibility aliases are listed in the Implemented Command Tree.
+The examples below follow the target protocol names.
 
 List user-visible workbooks:
 
@@ -75,10 +74,11 @@ List user-visible workbooks:
 mbs workbook list-user-workbooks --limit 20
 ```
 
-Read a bounded range:
+Read a worksheet:
 
 ```bash
-mbs excel-worksheet range read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:H1
 ```
 
 List worksheets:
@@ -111,6 +111,13 @@ Import a large table-like `.xlsx` into SheetTable/PG:
 mbs workbook import ./large-table.xlsx --engine postgres
 ```
 
+Import a mixed workbook and let the backend select engines per worksheet:
+
+```bash
+mbs workbook import ./mixed-workbook.xlsx --engine auto
+mbs workbook import ./mixed-workbook.xlsx --engine "postgres,excel,excel,postgres"
+```
+
 Append rows and verify:
 
 ```bash
@@ -152,131 +159,13 @@ CLI command names normalize these relationship labels to hyphenated groups:
 `excel_worksheet` becomes `excel-worksheet`, `excel_table` becomes
 `excel-table`, and `db_worksheet(db_table)` becomes `db-table`.
 
-## Implemented Command Tree
-
-This is the current shipped command surface. The full roadmap tree below is
-separate and includes planned or deferred commands.
-
-```text
-mbs
-├── update
-│   └── Update maybeai-sheet-cli from PyPI.
-│
-├── workbook
-│   ├── create             Create a new workbook.
-│   ├── create-from-file   Import an .xlsx file.
-│   ├── import             Preferred alias for create-from-file.
-│   ├── metadata           Inspect workbook profile and routing metadata.
-│   ├── list-user-workbooks
-│   │                      Preferred alias for bounded user workbook listing.
-│   ├── list-worksheets    List worksheets in a workbook.
-│   ├── list               List user workbooks with bounded output.
-│   ├── search             Search user workbooks with bounded output.
-│   ├── manifest           Compatibility alias for metadata.
-│   └── capabilities       Inspect workbook capability/profile metadata.
-│
-├── excel-worksheet
-│   ├── metadata           Inspect worksheet metadata through workbook profile.
-│   └── list-table         List worksheet/table metadata for a workbook.
-│
-├── excel-table
-│   ├── metadata           Resolve a worksheet-backed table from workbook metadata.
-│   ├── schema             Infer schema from a resolved worksheet-backed table range.
-│   ├── sample             Return bounded table sample rows.
-│   ├── read               Read a resolved worksheet-backed table range.
-│   └── insert             Insert row objects into a worksheet-backed table.
-│
-├── db-table
-│   ├── metadata           Resolve PG/SheetTable-backed worksheet metadata.
-│   ├── schema             Infer schema from a bounded PG read.
-│   ├── sample             Return bounded PG table sample rows.
-│   ├── read               Read PG-backed table rows through routed APIs.
-│   └── insert             Insert rows into a PG-backed table.
-│
-├── worksheet
-│   ├── list               List worksheets in a workbook.
-│   ├── create             Create a worksheet, optionally with starter values.
-│   ├── rename             Rename a worksheet.
-│   ├── delete             Delete a worksheet; requires --yes unless --dry-run.
-│   ├── copy               Copy a worksheet.
-│   └── move               Move a worksheet to a zero-based index.
-│
-├── range
-│   ├── read               Read a bounded A1 range.
-│   ├── write              Write a JSON matrix into an A1 range.
-│   ├── clear              Clear an A1 range.
-│   └── search             Search a worksheet with bounded results.
-│
-├── row
-│   ├── insert             Insert rows.
-│   ├── delete             Delete rows; requires --yes unless --dry-run.
-│   └── move               Move rows.
-│
-├── column
-│   ├── insert             Insert columns.
-│   ├── delete             Delete columns; requires --yes unless --dry-run.
-│   ├── move               Move columns.
-│   └── width              Set column width.
-│
-├── formula
-│   ├── read               Read formulas with FORMULA render mode.
-│   ├── set                Set one formula cell.
-│   ├── batch-set          Set formula ranges from a JSON operations file.
-│   ├── recalculate        Recalculate formulas for a worksheet/workbook.
-│   ├── calculate          Calculate one formula cell.
-│   └── lineage            Trace formula lineage for one cell.
-│
-├── style
-│   ├── freeze-panes       Freeze rows/columns using an A1 cell boundary.
-│   ├── auto-filter set    Set worksheet auto-filter range.
-│   ├── auto-filter remove Remove worksheet auto-filter.
-│   ├── columns-width      Set column widths.
-│   └── rows-height        Set row heights.
-│
-├── history
-│   ├── list               List workbook versions with bounded output.
-│   └── read               Read a workbook version.
-│
-├── file
-│   ├── export             Export workbook bytes to --out.
-│   ├── list               List files with bounded output.
-│   └── search             Search files with bounded output.
-│
-├── share
-│   ├── visibility         Set workbook visibility.
-│   ├── grant              Grant a user permission.
-│   ├── permission         Read current permission.
-│   ├── remove             Remove a user's access.
-│   └── list               List sharing entries.
-│
-├── raw
-│   └── post               Low-level POST escape hatch for routed API paths.
-│
-└── sheet                  Legacy compatibility aliases.
-    ├── read
-    ├── read-range
-    ├── read-many
-    ├── named-range
-    ├── headers
-    ├── worksheets
-    ├── formulas
-    ├── write-range
-    ├── clear-range
-    ├── append
-    ├── upsert
-    ├── formula-set
-    ├── formula-batch-set
-    ├── recalculate
-    └── create-worksheet
-```
 
 ## Full Command Tree
 
 The reviewed tree below is the source of truth for the protocol shape. Product
 model labels in this block use underscores; CLI names in examples and future
 router code should normalize them to hyphenated command groups such as
-`excel-worksheet`, `excel-table`, and `db-table`. The older `sheet ...`
-commands remain available as compatibility aliases. This tree includes
+`excel-worksheet`, `excel-table`, and `db-table`. This tree includes
 implemented, planned, deferred, and not-recommended command surfaces.
 
 Status legend for the full tree:
@@ -312,6 +201,7 @@ mbs
 │   └── rename                   API   Rename a stored file.
 │
 ├── excel_worksheet
+│   ├── read                     API   Read the full range of the worksheet.
 │   ├── list-table               API   List worksheets in a workbook.
 │   ├── create                   API   Create a worksheet, optionally with starter values.
 │   ├── update                   API   Update worksheet metadata.
@@ -345,9 +235,9 @@ mbs
 |   |- lineage                   API   Trace cell/range lineage.
 │
 ├── db_worksheet(AKA db_table)
-│   ├── create                   PG    Create a PG-backed table.
-│   ├── update                   PG    Update PG-backed table metadata.
-│   ├── delete                   PG    Delete a PG-backed table; requires --yes unless --dry-run.
+│   ├── create                   PLAN  Create a PG-backed table from JSON row data.
+│   ├── update                   PLAN  Update PG-backed rows from JSON row data.
+│   ├── delete                   PLAN  Delete PG-backed rows/table; requires --yes unless --dry-run.
 │   ├── schema                   API   Infer table schema from a bounded PG read.
 │   ├── sample                   API   Return bounded table sample rows.
 │   ├── read                     API   Read PG-backed table rows.
@@ -410,24 +300,6 @@ mbs
 │   ├── create                   API   Create or grant sharing access.
 │   ├── remove                   API   Remove a user's access.
 │   ├── modify                   API   Modify sharing access.
-│
-│
-└── sheet                  Legacy compatibility aliases.
-    ├── read
-    ├── read-range
-    ├── read-many
-    ├── named-range
-    ├── headers
-    ├── worksheets
-    ├── formulas
-    ├── write-range
-    ├── clear-range
-    ├── append
-    ├── upsert
-    ├── formula-set
-    ├── formula-batch-set
-    ├── recalculate
-    └── create-worksheet
 ```
 
 Full tree examples:
@@ -450,13 +322,15 @@ mbs workbook copy --doc-id abc123 --name "Budget Copy"  # API
 mbs workbook delete --doc-id abc123 --dry-run  # API
 
 # excel-worksheet
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Actuals  # API
+mbs excel-worksheet read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API
 mbs excel-worksheet create --doc-id abc123 --name Actuals  # API
 mbs excel-worksheet update --doc-id abc123 --worksheet-name Actuals --title "Actuals FY26"  # API
 mbs excel-worksheet metadata --doc-id abc123 --worksheet-name Actuals  # API
 mbs excel-worksheet sample --doc-id abc123 --worksheet-name Actuals --range A1:Z5000 --limit 50  # PLAN
 
 # excel-worksheet range
-mbs excel-worksheet range read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API
+mbs excel-worksheet range read --doc-id abc123 --worksheet-name Actuals --range A1:D20  # API, advanced structured alias
 mbs excel-worksheet range used-range --doc-id abc123 --worksheet-name Actuals  # PLAN
 mbs excel-worksheet range lineage --doc-id abc123 --worksheet-name Model --cell E2 --format tree  # API
 
@@ -472,8 +346,17 @@ mbs excel-table style columns-width --doc-id abc123 --worksheet-name Orders --ta
 mbs db-table metadata --doc-id abc123 --name orders-large  # API
 mbs db-table schema --doc-id abc123 --name orders-large  # API
 mbs db-table sample --doc-id abc123 --name orders-large --limit 50  # API
-mbs db-table read --doc-id abc123 --name orders-large --limit 50  # API
+mbs db-table read --doc-id abc123 --name orders-large --limit 100 --offset 200  # API
 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  # PLAN
+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 --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
+mbs db-table delete --doc-id abc123 --name Orders --where '{"order_id":"A1"}' --yes  # PLAN
+mbs db-table delete --doc-id abc123 --name Orders --row-index 42 --count 10 --yes  # PLAN
+mbs db-table delete --doc-id abc123 --name Orders --column-index 3 --yes  # PLAN
+mbs db-table delete --doc-id abc123 --name Orders --column-name status --yes  # PLAN
 
 # row
 mbs excel-worksheet row insert --doc-id abc123 --worksheet-name Actuals --row 10 --count 2  # API
@@ -511,11 +394,13 @@ mbs version restore --doc-id abc123 --version-id v42 --dry-run  # PLAN
 
 # share
 mbs share create --doc-id abc123 --email teammate@example.com --role viewer  # API
-
-# sheet
-mbs sheet read --doc-id abc123 --worksheet-name Sheet1 --range A1:D20
 ```
 
+`db-table read`, `schema`, and `sample` keep reads bounded. The default read
+limit is 100 rows, and `--limit` / `--offset` are capped at 10,000 to avoid
+accidental large PG scans. Use a keyset-style backend contract for deeper
+pagination when it becomes available.
+
 Refactor planning is tracked separately from this README:
 `docs/superpowers/plans/2026-07-01-mbs-two-engine-command-refactor.md`.
 
@@ -537,8 +422,8 @@ dependency graph beyond cell lineage             PLAN
 Relationship guide:
 
 - Use `workbook` for file-level creation, upload/import, and manifest checks.
-- Use `excel-worksheet` for Excel tab lifecycle operations and worksheet/range
-  inspection.
+- Use `excel-worksheet read` for full worksheet used-range inspection.
+- Use `excel-worksheet` for Excel tab lifecycle operations.
 - Use `excel-worksheet range` for coordinate-based reads, writes, formulas, and
   cell lineage.
 - Use `excel-table` for worksheet-backed table views. One Excel worksheet can
@@ -573,7 +458,7 @@ Targeting notes:
   from workbook metadata, for example `--table-id 1`, and maps internally to
   table metadata such as `worksheet_name` and `range`.
 - Use `--name` or backend ids when operating on a `db-table`.
-- Use `--gid` only for legacy gid-specific compatibility aliases.
+- Use `--gid` only when a route specifically requires gid targeting.
 
 ## Input Rules
 

maybeai_sheet_cli-0.6.0/docs/superpowers/reports/import-engine-local-20260702-150800/import_engine_local_report.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<title>本地导入引擎验证报告</title>
+<style>
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;margin:24px;color:#111827;line-height:1.45}
+h1{font-size:24px} h2{font-size:18px;margin-top:28px}
+table{border-collapse:collapse;width:100%;font-size:13px}th,td{border:1px solid #d1d5db;padding:6px;text-align:left;vertical-align:top}th{background:#f3f4f6}
+.status-pass{color:#166534;background:#dcfce7;font-weight:700}.status-fail{color:#991b1b;background:#fee2e2;font-weight:700}.status-warn,.status-skip{color:#92400e;background:#fef3c7;font-weight:700}
+code,pre{background:#f3f4f6;padding:2px 4px;border-radius:4px}pre{padding:12px;overflow:auto}
+.human-needed{border-left:4px solid #d97706;padding-left:12px;background:#fffbeb}
+</style>
+</head>
+<body>
+<h1>本地导入引擎验证报告</h1>
+<p>运行时间：2026-07-02T15:20:29</p>
+<p>API base：<code>http://localhost:7011</code></p>
+<p>提交版本：maybeai-sheet-cli <code>a988277</code>，play-be <code>76ec7f4</code>，SheetTable <code>2cafe2c</code></p>
+<p>结果汇总：PASS=2，FAIL=0，WARN=1，SKIP=0</p>
+<h2>MaybeSheet URL</h2>
+<ul><li><a href="http://localhost:3003/docs/spreadsheets/d/6a460e52e6feec692aa2b7ee">http://localhost:3003/docs/spreadsheets/d/6a460e52e6feec692aa2b7ee</a></li><li><a href="http://localhost:3003/docs/spreadsheets/d/6a460e59e6feec692aa2b7f2">http://localhost:3003/docs/spreadsheets/d/6a460e59e6feec692aa2b7f2</a></li></ul>
+<h2>流程</h2>
+<div class="mermaid">flowchart LR
+  CLI[mbs CLI] --&gt; Play[play-be /api/v1/excel/import]
+  Play --&gt; Auto{engine=auto}
+  Auto --&gt;|layout/report| Excelize[excelize-mcp]
+  Auto --&gt;|forced pg worksheets| SheetTable[SheetTable]
+  SheetTable --&gt; PG[(PostgreSQL typed tables)]
+  Play --&gt; Response[JSON response]
+  Response --&gt; Report[本地 HTML 报告]
+  classDef excelize fill:#dbeafe,stroke:#2563eb,color:#111827;
+  classDef pg fill:#dcfce7,stroke:#16a34a,color:#111827;
+  classDef warn fill:#fef3c7,stroke:#d97706,color:#111827;
+  class Excelize excelize;
+  class SheetTable,PG pg;
+  class Auto warn;
+</div>
+<pre>flowchart LR
+  CLI[mbs CLI] --&gt; Play[play-be /api/v1/excel/import]
+  Play --&gt; Auto{engine=auto}
+  Auto --&gt;|layout/report| Excelize[excelize-mcp]
+  Auto --&gt;|forced pg worksheets| SheetTable[SheetTable]
+  SheetTable --&gt; PG[(PostgreSQL typed tables)]
+  Play --&gt; Response[JSON response]
+  Response --&gt; Report[本地 HTML 报告]
+  classDef excelize fill:#dbeafe,stroke:#2563eb,color:#111827;
+  classDef pg fill:#dcfce7,stroke:#16a34a,color:#111827;
+  classDef warn fill:#fef3c7,stroke:#d97706,color:#111827;
+  class Excelize excelize;
+  class SheetTable,PG pg;
+  class Auto warn;
+</pre>
+<h2>对比结果</h2>
+<table><thead><tr><th>类别</th><th>用例</th><th>来源文件</th><th>document_id</th><th>MaybeSheet URL</th><th>期望引擎</th><th>实际引擎</th><th>worksheet_engines</th><th>top-level selected_engine</th><th>preprocess</th><th>list 数量</th><th>read 检查</th><th>结果</th><th>备注</th></tr></thead><tbody><tr><td>auto import</td><td>yunling auto import</td><td>~/Downloads/yunling_v4_20sheet.xlsx</td><td>6a460e52e6feec692aa2b7ee</td><td>http://localhost:3003/docs/spreadsheets/d/6a460e52e6feec692aa2b7ee</td><td>excelize</td><td>excelize</td><td>excelize:21</td><td>absent</td><td>0</td><td>21</td><td>PASS</td><td class="status-pass">PASS</td><td>响应仅保留 top-level engine；每个 worksheet_engines 保留 requested_engine/selected_engine。</td></tr><tr><td>auto import</td><td>llm_cost auto import</td><td>~/Downloads/llm_cost_stats_2026_05_export.xlsx</td><td>6a460e59e6feec692aa2b7f2</td><td>http://localhost:3003/docs/spreadsheets/d/6a460e59e6feec692aa2b7f2</td><td>excelize</td><td>excelize</td><td>excelize:12</td><td>absent</td><td>0</td><td>12</td><td>PASS</td><td class="status-pass">PASS</td><td>响应仅保留 top-level engine；每个 worksheet_engines 保留 requested_engine/selected_engine。</td></tr><tr><td>forced mixed import</td><td>llm_cost forced excelize+postgres list</td><td>~/Downloads/llm_cost_stats_2026_05_export.xlsx</td><td>n/a</td><td>n/a</td><td>composite</td><td>timeout</td><td>SheetTable 日志显示 PG typed writes 已执行；CLI 600s 内未收到 play-be 响应，随后仍在 post-import sync。</td><td>unknown</td><td>observed in SheetTable typed writes</td><td>n/a</td><td>SKIP</td><td class="status-warn">WARN</td><td>命令 --engine &quot;excelize,postgres,...&quot; 触发 PG typed materialization，但 600s 内未返回响应；临时服务关闭时 play-be 记录 SheetTable import failed/server disconnected。需要进一步查 mixed response/registry completion 与 post-import sync 耗时。</td></tr></tbody></table>
+<h2>响应结构检查</h2>
+<ul>
+<li><code>yunling_v4_20sheet.xlsx</code> auto 响应 top-level <code>selected_engine</code>：absent</li>
+<li><code>llm_cost_stats_2026_05_export.xlsx</code> auto 响应 top-level <code>selected_engine</code>：absent</li>
+<li>两个成功响应都保留 <code>engine</code> 和 per-worksheet <code>worksheet_engines[].requested_engine/selected_engine</code>。</li>
+</ul>
+<h2>覆盖率</h2>
+<table><thead><tr><th>区域</th><th>已覆盖</th><th>总数</th><th>百分比</th><th>未覆盖/备注</th></tr></thead><tbody>
+<tr><td>auto import</td><td>2</td><td>2</td><td>100%</td><td>layout/report 与 large workbook</td></tr>
+<tr><td>list worksheets</td><td>2</td><td>2</td><td>100%</td><td>均通过 CLI routed API</td></tr>
+<tr><td>range read</td><td>2</td><td>2</td><td>100%</td><td>均返回样例数据</td></tr>
+<tr><td>forced mixed route</td><td>0</td><td>1</td><td>0%</td><td>SheetTable 完成 typed writes，但 play-be/CLI 响应超时</td></tr>
+</tbody></table>
+<section class="human-needed"><h2>需要人工核验</h2>
+<p>打开上面的 localhost MaybeSheet URL，确认 UI 可以加载对应工作簿。自动化已经验证 import/list/read API；UI 渲染不在本次 CLI 自动检查范围内。</p>
+</section>
+<h2>原始证据文件</h2><p>目录：<code>docs/superpowers/reports/import-engine-local-20260702-150800</code></p><ul><li><code>llm_cost_import_auto.json</code></li><li><code>llm_cost_import_mixed_forced.json</code></li><li><code>llm_cost_list_worksheets.json</code></li><li><code>llm_cost_read_detail_A1_T5.json</code></li><li><code>yunling_import_auto.json</code></li><li><code>yunling_list_worksheets.json</code></li><li><code>yunling_read_T00_A1_F5.json</code></li></ul>
+<script type="module">import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs"; mermaid.initialize({startOnLoad:true, securityLevel:"strict"});</script>
+</body></html>