maybeai-sheet-cli 0.13.0__tar.gz → 0.13.2__tar.gz

{maybeai_sheet_cli-0.13.0 → maybeai_sheet_cli-0.13.2}/.gitignore

@@ -23,3 +23,4 @@ temp
 .clauderc.json
 docs_requirement
 artifacts/
+.worktrees/

maybeai_sheet_cli-0.13.2/PKG-INFO

@@ -0,0 +1,593 @@
+Metadata-Version: 2.4
+Name: maybeai-sheet-cli
+Version: 0.13.2
+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
+Project-URL: Issues, https://github.com/OmniMCP-AI/maybeai-sheet-cli/issues
+Author: OmniMCP-AI
+License: Proprietary
+Keywords: cli,excel,maybeai,spreadsheet
+Classifier: Environment :: Console
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Office/Business :: Financial :: Spreadsheet
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: rich<14,>=13.7
+Requires-Dist: typer<1,>=0.12
+Description-Content-Type: text/markdown
+
+# maybeai-sheet-cli
+
+CLI for MaybeAI spreadsheet operations.
+
+`mbs` wraps the MaybeAI spreadsheet HTTP APIs behind a stable command-line interface for humans, CI jobs, and agents.
+
+## Install
+
+On Debian/Ubuntu and other **PEP 668** systems, do **not** use bare `pip install` on system Python. Use **pipx** (recommended for CLIs):
+
+```bash
+sudo apt install -y pipx python3-venv
+pipx ensurepath
+# re-login or: source ~/.bashrc
+
+pipx install maybeai-sheet-cli
+mbs --version
+```
+
+For local venvs or macOS/dev machines, plain pip is fine:
+
+```bash
+pip install maybeai-sheet-cli
+```
+
+Upgrade to the latest release:
+
+```bash
+mbs update          # when installed via pip or pipx
+pipx upgrade maybeai-sheet-cli   # alternative on pipx installs
+```
+
+Install a specific version:
+
+```bash
+mbs update --version 0.3.2
+pipx install maybeai-sheet-cli==0.3.2 --force   # pipx reinstall pin
+```
+
+Uninstall:
+
+```bash
+pipx uninstall maybeai-sheet-cli
+# not: pip uninstall -U  (-U is invalid for uninstall)
+```
+
+## Requirements
+
+- Python 3.10+
+- `MAYBEAI_API_TOKEN`
+
+## Configure
+
+Set your API token:
+
+```bash
+export MAYBEAI_API_TOKEN="YOUR_TOKEN"
+```
+
+Optional global flags:
+
+- `--base-url` to point at a different MaybeAI API host
+- `--output json|table|yaml`
+- `--timeout <seconds>`
+- `--verbose`
+
+Alias note:
+
+- Prefer nested worksheet media/layout commands such as `mbs excel-worksheet style ...`
+- The CLI also exposes compatibility shortcuts `mbs style ...`, `mbs image ...`,
+  `mbs chart ...`, and `mbs dashboard ...` for the same command groups
+
+## Quick Start
+
+The examples below follow the target protocol names.
+
+List user-visible workbooks:
+
+```bash
+mbs workbook list-user-workbooks --limit 20
+```
+
+Read a worksheet:
+
+```bash
+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:
+
+```bash
+mbs workbook list-worksheets --doc-id abc123
+```
+
+Inspect the first worksheet-backed table:
+
+```bash
+mbs excel-table metadata --doc-id abc123 --worksheet-name Sheet1 --table-id 1
+```
+
+Create a workbook:
+
+```bash
+mbs workbook create --title "Board Pack"
+```
+
+Import a workbook-style `.xlsx` through the default Excelize path:
+
+```bash
+mbs workbook import ./report.xlsx
+```
+
+Import a large table-like `.xlsx` into SheetTable/PG:
+
+```bash
+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
+mbs excel-table insert --doc-id abc123 --worksheet-name Sheet1 --table-id 1 --rows rows.json --verify
+```
+
+Grant workbook access:
+
+```bash
+mbs share create --doc-id abc123 --email teammate@example.com --role viewer
+```
+
+Rename a worksheet and inspect a destructive row delete before sending it:
+
+```bash
+mbs excel-worksheet rename --doc-id abc123 --worksheet-name Old --new-name New
+mbs excel-worksheet row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --dry-run
+mbs excel-worksheet row delete --doc-id abc123 --worksheet-name Sheet1 --row 10 --yes
+```
+
+Search, style, inspect history, and export:
+
+```bash
+mbs excel-worksheet range search --doc-id abc123 --worksheet-name Sheet1 --query revenue --max-results 20
+mbs excel-worksheet range lineage --doc-id abc123 --worksheet-name Sheet1 --range B14:D14 --format tree
+mbs excel-worksheet style freeze-panes --doc-id abc123 --worksheet-name Sheet1 --cell B2
+mbs excel-worksheet style worksheet plan --doc-id abc123 --worksheet-name Sheet1 --mode auto_detect --spec worksheet_style.json
+mbs excel-worksheet style worksheet apply --doc-id abc123 --worksheet-name Sheet1 --mode auto_detect --spec worksheet_style.json
+mbs excel-worksheet image list --doc-id abc123 --worksheet-name Dashboard
+mbs excel-worksheet chart list --doc-id abc123 --worksheet-name Dashboard
+mbs excel-worksheet dashboard manifest --doc-id abc123 --worksheet-name Dashboard
+mbs workbook calculate --doc-id abc123
+mbs excel-worksheet calculate --doc-id abc123 --worksheet-name Sheet1
+mbs excel-worksheet range calculate --doc-id abc123 --worksheet-name Sheet1 --cell E2 --formula "=SUM(B2:D2)"
+mbs version list --doc-id abc123 --limit 10
+mbs workbook export --doc-id abc123 --out workbook.xlsx
+```
+
+The worksheet media/layout groups are available in both forms:
+
+```bash
+mbs excel-worksheet chart list --doc-id abc123 --worksheet-name Dashboard
+mbs chart list --doc-id abc123 --worksheet-name Dashboard
+```
+
+Prefer the nested `excel-worksheet ...` form in docs and agent prompts when you
+want the object model to stay explicit.
+
+For chart specs authored as `type: "json"`, keep metadata `title` when the chart
+needs an internal or custom-rendered title, and hide the visible container title
+with `hide_title: true` or `spec.style.showContainerTitle: false` rather than
+deleting `title`.
+
+## Relationship
+1 workbok
+ |                         \
+N db_worksheet(PG)   N excel_worksheets
+                            |                        \
+                      M(N>1) db_worksheet(db_table)   J(<N) excel_table
+
+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`.
+
+
+## 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`. This tree includes
+implemented, planned, deferred, and not-recommended command surfaces.
+
+Status legend for the full tree:
+
+- `NOW`: released in the current CLI under this command shape.
+- `API`: route exists or is expected, but the target command wrapper/refactor is
+  not released under this shape yet.
+- `PG`: SheetTable/PG-specific; defer until exposed through the public API.
+- `PLAN`: needs a backend/product contract before implementation.
+- `DEFER`: intentionally not part of the clean agent-first surface yet.
+- `SKIP`: not recommended for this CLI.
+
+```text
+mbs
+├── update
+│   └── Update maybeai-sheet-cli from PyPI.
+│
+├── workbook
+│   ├── metadata               API    Inspect workbook profile and routing metadata.(workshets)
+│   ├── source                 PLAN   Similar to NotebookLM source (menu on the left).
+│   ├── create                 NOW    Create a new workbook.
+│   ├── create-from-file       NOW    Import an .xlsx file.
+│   ├── import                 NOW    Preferred alias for create-from-file.
+│   ├── list-user-workbooks    API    List user workbooks with bounded output.
+│   ├── list-worksheets        API    List worksheets, including engine.
+│   ├── search                 NOW    Search user workbooks with bounded output.
+│   ├── calculate              NOW    Recalculate formulas across the workbook.
+│   ├── export                 API    Export workbook bytes.
+│   ├── copy                   API    Copy a workbook.
+│   ├── upload                 API    Upload a file through workbook import flow.
+│   ├── update                 API    Update a stored workbook file not change doc_id
+│   ├── export                 API    Export workbook bytes to --out.
+│   ├── delete                 API    Delete a stored file.
+│   └── rename                 API    Rename a stored file.
+│
+├── excel_worksheet
+│   ├── read                   API    Read the full range of the worksheet.
+│   ├── check-error            API    Read worksheet cells and scan for formula-style errors.
+│   ├── calculate              NOW    Recalculate formulas in one worksheet.
+│   ├── list-table             API    Detect content-backed tables in a worksheet.
+│   ├── create                 API    Create a worksheet, optionally with starter values.
+│   ├── update                 API    Update worksheet metadata.
+│   ├── sample                 PLAN   Return bounded worksheet/range sample rows.
+│   ├── delete                 API    Delete a worksheet; requires --yes unless --dry-run.
+│   ├── rename                 API    Rename a worksheet.
+│   ├── move                   API    Move a worksheet to a zero-based index.
+│   ├── copy                   API    Copy a worksheet.
+│   └── metadata               API    Include table meta: range, header, table id, data summary.
+│
+├── excel_table
+│   ├── create                 PLAN   Create a table view from a worksheet range.
+│   ├── update                 PLAN   Update table view metadata or range.
+│   ├── delete                 PLAN   Delete a table view; requires --yes unless --dry-run.
+│   ├── schema                 API    Infer table schema from a resolved table range.
+│   ├── sample                 API    Return bounded table sample rows.
+│   ├── read                   API    Read header-aware table rows.
+│   ├── insert                 API    Insert table rows.
+│   └── metadata               API    Include table meta: range, header, table id, data summary.
+│
+├── excel_worksheet range
+│   ├── read                   API    Read a bounded A1 range.
+│   ├── write                  API    Write a JSON matrix into an A1 range.
+│   ├── clear                  API    Clear an A1 range.
+│   ├── read-many              DEFER  Legacy alias only until a real batch API exists.
+│   ├── copy                   API    Copy a range.
+│   ├── search                 API    Search a worksheet with bounded results.
+│   ├── used-range             PLAN   Return worksheet used range after a routed contract exists.
+│   ├── set-formula            API    Set one formula cell.
+│   ├── calculate              API    Calculate one formula cell.
+│   └── lineage                API    Trace cell/range lineage.
+│
+├── db_worksheet(AKA db_table)
+│   ├── create                 API    Create a PG-backed table from JSON row data.
+│   ├── create-from-query      API    Calculate SQL and create a PG-backed table from tabular results.
+│   ├── 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.
+│   ├── insert                 API    Insert PG-backed table rows.
+│   └── metadata               API    Include table meta, backend id, schema, and data summary.
+│
+├── excel_worksheet row
+│   ├── insert                 API    Insert rows.
+│   ├── delete                 API    Delete rows; requires --yes unless --dry-run.
+│   └── move                   API    Move rows.
+│
+├── excel_worksheet column
+│   ├── insert                 API    Insert columns.
+│   ├── delete                 API    Delete columns; requires --yes unless --dry-run.
+│   ├── move                   API    Move columns.
+│   ├── width                  API    Set column width.
+│   └── append                 API    Append columns.
+│
+├── excel_worksheet chart
+│   ├── list                   NOW    List charts in one worksheet.
+│   ├── get                    NOW    Read one chart spec and source binding.
+│   ├── preview                PLAN   Preview one chart from its spec/source binding.
+│   ├── create-config          NOW    Create one chart from a chart spec.
+│   ├── update                 NOW    Update one chart from a chart spec.
+│   ├── refresh                PLAN   Refresh one chart from its current source binding.
+│   └── delete                 NOW    Delete one chart.
+│
+├── excel_worksheet dashboard
+│   ├── manifest               NOW    Aggregate worksheet metadata and chart inventory for one dashboard sheet.
+│   ├── create-config          NOW    Create a dashboard worksheet and compose charts from one spec.
+│   ├── validate               NOW    Validate dashboard layout, worksheet target, and chart source fields locally.
+│   └── refresh                NOW    Upsert dashboard charts from one spec and re-verify chart inventory.
+│
+│
+├── excel-worksheet style
+│   ├── cell batch-set          NOW    Apply cell style batches from JSON.
+│   ├── columns-width           NOW    Set column widths.
+│   ├── rows-height             NOW    Set row heights.
+│   ├── freeze-panes            NOW    Freeze rows/columns using an A1 boundary.
+│   ├── gridlines toggle        NOW    Toggle worksheet gridlines.
+│   ├── auto-filter set         NOW    Set worksheet auto-filter range.
+│   ├── auto-filter remove      NOW    Remove worksheet auto-filter.
+│   ├── filter-values           NOW    Apply filter values.
+│   ├── conditional-formats set NOW    Set conditional formatting rules.
+│   ├── worksheet plan          NOW    Generate a worksheet styling plan.
+│   └── worksheet apply         NOW    Apply a worksheet styling plan.
+│
+├── excel_worksheet image
+│   ├── list                   NOW    List worksheet images from worksheet formatting metadata.
+│   ├── read                   NOW    Read one worksheet image by cell or picture id.
+│   ├── replace                NOW    Replace one worksheet image in place.
+│   ├── insert                 NOW    Add an image file.
+│   └── delete                 NOW    Delete an image.
+│
+├── version
+│   ├── list                   API    List workbook history with bounded output.
+│   └── restore                PLAN   Restore a workbook history version after a routed contract exists.
+│
+│
+├── share
+│   ├── create                 API    Create or grant sharing access.
+│   ├── remove                 API    Remove a user's access.
+│   └── modify                 API    Modify sharing access.
+```
+
+Full tree examples:
+
+These examples cover every top-level category. Commands marked `API`, `PLAN`,
+`PG`, or `DEFER` show the intended CLI shape, but are not guaranteed to be
+available until their status moves to `NOW`. They use hyphenated CLI command
+names even when the reviewed protocol tree uses underscore model labels.
+
+```bash
+# update
+mbs update --check
+
+# workbook
+mbs workbook metadata --doc-id abc123  # API
+mbs workbook list-user-workbooks --limit 20  # API
+mbs workbook list-worksheets --doc-id abc123  # API
+mbs workbook export --doc-id abc123 --out workbook.xlsx  # API
+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 check-error --doc-id abc123 --worksheet-name Model --range B2:H80  # 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 list-table --doc-id abc123 --gid 3  # 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, 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 --range B14:D14 --format tree  # API
+
+# excel-table
+mbs excel-table metadata --doc-id abc123 --worksheet-name Orders --table-id 1  # API
+mbs excel-table schema --doc-id abc123 --worksheet-name Orders --table-id 1  # API
+mbs excel-table sample --doc-id abc123 --worksheet-name Orders --table-id 1 --limit 50  # API
+mbs excel-table read --doc-id abc123 --worksheet-name Orders --table-id 1 --limit 50  # API
+mbs excel-table insert --doc-id abc123 --worksheet-name Orders --table-id 1 --rows rows.json  # API
+mbs excel-table style columns-width --doc-id abc123 --worksheet-name Orders --table-id 1 --column B --width 120  # API
+
+# db-table
+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 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  # API
+mbs db-table create-from-query --doc-id abc123 --name OrderSummary --sql-file order_summary.sql  # 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 --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
+
+# column
+mbs excel-worksheet column width --doc-id abc123 --worksheet-name Actuals --column B --width 120  # API
+mbs excel-worksheet column append --doc-id abc123 --worksheet-name Actuals --values columns.json  # API
+
+# cell
+mbs excel-worksheet range lineage --doc-id abc123 --worksheet-name Model --range B14:D14 --format tree  # API
+
+# formula
+mbs workbook calculate --doc-id abc123  # API
+mbs excel-worksheet calculate --doc-id abc123 --worksheet-name Model  # API
+mbs excel-worksheet range calculate --doc-id abc123 --worksheet-name Model --cell E2 --formula "=SUM(B2:D2)"  # API
+mbs excel-worksheet range set-formula --doc-id abc123 --worksheet-name Model --cell E2 --formula "=SUM(B2:D2)"  # API
+
+# chart
+mbs excel-worksheet chart list --doc-id abc123 --worksheet-name Dashboard  # NOW
+mbs excel-worksheet chart get --doc-id abc123 --worksheet-name Dashboard --cell J2  # NOW
+mbs excel-worksheet chart create-config --doc-id abc123 --worksheet-name Dashboard --cell J2 --spec chart.json  # NOW
+mbs excel-worksheet chart update --doc-id abc123 --worksheet-name Dashboard --cell J2 --chart-id rId1 --spec chart.json  # NOW
+mbs excel-worksheet chart delete --doc-id abc123 --worksheet-name Dashboard --chart-id rId1  # NOW
+
+# recommended chart.json shape
+# prefer top-level `"type": "json"` and put the renderer in `html`
+# do not treat `"type": "line"` / `"bar"` / `"pie"` as the default authored form
+# {
+#   "type": "json",
+#   "sql": "select Month, Revenue from Sheet1",
+#   "title": "Monthly Revenue",
+#   "legend": "bottom",
+#   "html": "{ library: 'echarts', handler: (data) => ({ xAxis: { type: 'category', data: data.map(r => r.Month) }, yAxis: { type: 'value' }, series: [{ type: 'line', data: data.map(r => Number(r.Revenue) || 0) }] }) }",
+#   "spec": { "style": { "title": "Monthly Revenue" } }
+# }
+
+# dashboard
+mbs excel-worksheet dashboard validate --spec dashboard.json  # NOW
+mbs excel-worksheet dashboard manifest --doc-id abc123 --worksheet-name Dashboard  # NOW
+mbs excel-worksheet dashboard create-config --doc-id abc123 --spec dashboard.json --create-worksheet  # NOW
+mbs excel-worksheet dashboard refresh --doc-id abc123 --spec dashboard.json  # NOW
+
+# recommended dashboard.json chart entries
+# {
+#   "worksheet_name": "Dashboard",
+#   "charts": [
+#     {
+#       "cell": "J2",
+#       "chart": {
+#         "type": "json",
+#         "sql": "select Month, Revenue from Sheet1",
+#         "title": "Monthly Revenue",
+#         "legend": "bottom",
+#         "html": "{ library: 'echarts', handler: (data) => ({ xAxis: { type: 'category', data: data.map(r => r.Month) }, yAxis: { type: 'value' }, series: [{ type: 'line', data: data.map(r => Number(r.Revenue) || 0) }] }) }"
+#       }
+#     }
+#   ]
+# }
+
+# style
+mbs excel-worksheet style freeze-panes --doc-id abc123 --worksheet-name Actuals --cell B2  # NOW
+mbs excel-worksheet style cell batch-set --doc-id abc123 --worksheet-name Actuals --range A1:G1 --style header_style.json  # NOW
+mbs excel-worksheet style conditional-formats set --doc-id abc123 --worksheet-name Actuals --spec conditional_formats.json  # NOW
+mbs excel-worksheet style worksheet apply --doc-id abc123 --worksheet-name Actuals --mode auto_detect --spec worksheet_style.json  # NOW
+
+# image
+mbs excel-worksheet image list --doc-id abc123 --worksheet-name Dashboard  # NOW
+mbs excel-worksheet image read --doc-id abc123 --worksheet-name Dashboard --cell A1 --out logo.png  # NOW
+mbs excel-worksheet image insert --doc-id abc123 --worksheet-name Dashboard --cell A1 --file logo.png  # NOW
+mbs excel-worksheet image replace --doc-id abc123 --worksheet-name Dashboard --cell A1 --file logo_v2.png  # NOW
+mbs excel-worksheet image delete --doc-id abc123 --worksheet-name Dashboard --cell A1  # NOW
+
+# version
+mbs version list --doc-id abc123 --limit 10  # API
+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
+```
+
+`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. `db-table create-from-query` is CLI-composed: it
+calculates a tabular `=SQL(...)` result through `calc-formula`, then creates a
+PG/SheetTable-backed table through `db_table/create`. 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`.
+
+Not recommended as first-class CLI commands:
+
+```text
+validation create/update/delete                  PLAN
+protection protect/unprotect                     PLAN
+sort range/table                                 PLAN
+comment create/update/delete                     PLAN
+named-range create/update/delete                 PLAN
+macro/vba                                        SKIP
+power-query                                      SKIP
+power-pivot                                      SKIP
+workbook diff                                    PLAN
+dependency graph beyond cell lineage             PLAN
+```
+
+Relationship guide:
+
+- Use `workbook` for file-level creation, upload/import, and manifest checks.
+- 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
+  contain multiple tables, so workbook metadata should expose simple ordinal
+  table ids such as `1`, `2`, `3`, and `4`, each mapped to the real worksheet
+  range behind the scenes. `excel-table` commands should accept optional
+  `--table-id`; when omitted, the CLI should default to `--table-id 1` only
+  inside an unambiguous worksheet target.
+- Use `db-table` for PG/SheetTable-backed tables. These are not worksheet
+  ranges, so prefer human-readable `--name` or backend ids instead of worksheet
+  `--table-id`.
+- Use `excel-worksheet row` and `excel-worksheet column` for structural
+  row/column changes.
+- Use `excel-worksheet style` for worksheet layout operations like freeze
+  panes, filter ranges, widths, heights, gridlines, conditional formats, and
+  worksheet style planning/apply.
+- Use `excel-worksheet chart` for list/get/create/update/delete of individual
+  source-backed visualizations.
+- Use `excel-worksheet dashboard` for local validation and worksheet-level chart
+  orchestration such as manifest, create-config, and refresh.
+- Use `excel-worksheet image` for list/read/insert/replace/delete image
+  workflows.
+- Use `version` for workbook history inspection and restore.
+- Use `share` for visibility and collaborator access.
+
+Targeting notes:
+
+- Most commands accept `--doc-id`, `--url`, or `--uri`.
+- Prefer `--worksheet-name` when the backend route supports names.
+- Use `--table-id` when operating on an `excel-table`. It is a simple ordinal
+  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 when a route specifically requires gid targeting.
+
+## Input Rules
+
+- Use `--doc-id`, `--url`, or `--uri` to identify a workbook.
+- Use `--worksheet-name` when the endpoint supports it.
+- Use `--table-id` when operating on an `excel-table`; default to `1` only when
+  the target worksheet is unambiguous.
+- Use `--name` or backend ids when operating on a `db-table`.
+- Use `--gid` for gid-specific sheet targeting.
+- File inputs like `--rows`, `--values`, `--targets`, and `--operations` must be JSON.
+
+## Output
+
+Default output is JSON. `table` is optimized for sheet-like payloads; `yaml` is also supported.
+
+## Development
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -U pip
+pip install -e .
+```
+
+Run tests:
+
+```bash
+python -m unittest discover -s tests -v
+```