{"id":"4cf9af5b-d396-40ec-a7cd-a6fc6f8a638f","entityType":"agent","slug":"clawhub-no7dw-maybeai-sheet-cli","name":"Maybeai Sheet Cli Skill","canonicalUrl":"https://www.xpersona.co/agent/clawhub-no7dw-maybeai-sheet-cli","canonicalPath":"/agent/clawhub-no7dw-maybeai-sheet-cli","generatedAt":"2026-10-10T04:07:50.423Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:15:20.543Z","emptyReason":null},"description":"Inspect, import, edit, dashboard, template, and share MaybeAI spreadsheets","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.6K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17dw3azb29a9p8fh7vntn908983kwvf:maybeai-sheet-cli","sourceUrl":"https://clawhub.ai/no7dw/maybeai-sheet-cli","homepage":"https://clawhub.ai/no7dw/skills/maybeai-sheet-cli","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/no7dw/maybeai-sheet-cli","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/no7dw/skills/maybeai-sheet-cli","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":68,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Maybeai Sheet Cli Skill technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:15:20.543Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:15:20.543Z","emptyReason":null},"stars":null,"forks":null,"downloads":2579,"packageName":null,"latestVersion":"v0.21.8","tractionLabel":"2.6K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:15:20.543Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T13:15:20.543Z","lastCrawledAt":"2026-10-09T13:15:20.543Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T13:15:20.543Z","lastVerifiedAt":null,"highlights":[{"version":"v0.21.8","createdAt":"2026-09-14T04:12:08.081Z","changelog":"Release v0.21.8","fileCount":26,"zipByteSize":64643},{"version":"v0.21.7","createdAt":"2026-09-02T11:50:40.306Z","changelog":"Release v0.21.7","fileCount":26,"zipByteSize":62632},{"version":"v0.21.6","createdAt":"2026-09-01T10:57:45.724Z","changelog":"feat: 对接定时删除过期workbook任务","fileCount":23,"zipByteSize":57704},{"version":"v0.21.5","createdAt":"2026-09-01T09:23:28.892Z","changelog":"Downgrade to v0.21.5 as requested","fileCount":26,"zipByteSize":61236},{"version":"v0.21.4","createdAt":"2026-08-28T07:24:25.494Z","changelog":"feat: sync with cli 0.28.4 release","fileCount":26,"zipByteSize":60697},{"version":"v0.21.3","createdAt":"2026-08-26T03:31:35.200Z","changelog":"Release v0.21.3: bump cli_version to 0.28.3","fileCount":23,"zipByteSize":56849},{"version":"0.21.2","createdAt":"2026-08-25T11:28:46.672Z","changelog":"update cli_version to 0.28.2","fileCount":26,"zipByteSize":58666},{"version":"0.21.1","createdAt":"2026-08-25T06:59:41.133Z","changelog":"bump to v0.21.1","fileCount":25,"zipByteSize":86520}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17dw3azb29a9p8fh7vntn908983kwvf:maybeai-sheet-cli","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17dw3azb29a9p8fh7vntn908983kwvf:maybeai-sheet-cli` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/no7dw/maybeai-sheet-cli before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T04:07:50.417Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-no7dw-maybeai-sheet-cli/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T13:15:20.543Z","emptyReason":null},"readme":"Skill: Maybeai Sheet Cli Skill\n\nOwner: no7dw\n\nSummary: Inspect, import, edit, dashboard, template, and share MaybeAI spreadsheets\n\nTags: latest:v0.21.8, latest=v0.21.5:v0.21.5, latest=v0.21.7:v0.21.7, latest=v0.21.8:v0.21.8\n\nVersion history:\n\nvv0.21.8 | 2026-09-14T04:12:08.081Z | user\n\nRelease v0.21.8\n\nvv0.21.7 | 2026-09-02T11:50:40.306Z | user\n\nRelease v0.21.7\n\nvv0.21.6 | 2026-09-01T10:57:45.724Z | user\n\nfeat: 对接定时删除过期workbook任务\n\nvv0.21.5 | 2026-09-01T09:23:28.892Z | user\n\nDowngrade to v0.21.5 as requested\n\nvv0.21.4 | 2026-08-28T07:24:25.494Z | user\n\nfeat: sync with cli 0.28.4 release\n\nvv0.21.3 | 2026-08-26T03:31:35.200Z | user\n\nRelease v0.21.3: bump cli_version to 0.28.3\n\nv0.21.2 | 2026-08-25T11:28:46.672Z | user\n\nupdate cli_version to 0.28.2\n\nv0.21.1 | 2026-08-25T06:59:41.133Z | user\n\nbump to v0.21.1\n\nv0.21.0 | 2026-08-24T11:30:00.380Z | user\n\nfeat: update to v0.21.0\n\nv0.20.6 | 2026-08-19T11:42:45.006Z | user\n\nfix: merge cells + sheet/base notes (note naming)\n\nv0.20.5 | 2026-08-18T11:39:28.400Z | user\n\nfix: Merge pull request #37 from OmniMCP-AI/codex/dimension-px-units\n\nv0.20.4 | 2026-08-12T09:31:30.827Z | user\n\nbump: v0.20.4\n\nv0.20.3 | 2026-08-12T04:19:17.763Z | user\n\nchore: bump version to v0.20.3\n\nv0.20.2 | 2026-08-11T11:27:06.671Z | user\n\nfeat: align skill with current sheet CLI\n\nv0.20.1 | 2026-08-09T12:45:31.437Z | user\n\nfix: Merge pull request #31 from OmniMCP-AI/codex/sql-query-independent\n\nv0.20.0 | 2026-08-07T03:01:05.964Z | user\n\nfeat: document worksheet convert-to-base workflow; docs: clarify full refresh verification and persistent excel table usage\n\nv0.19.1 | 2026-08-04T10:51:13.144Z | user\n\nfix: forum calculate 加上save_result的参数\n\nv0.19.0 | 2026-07-31T12:24:39.418Z | user\n\nfeat: document worksheet convert-to-base workflow\n\nv0.18.0 | 2026-07-28T15:12:11.470Z | user\n\nfeat: Merge pull request #26 from OmniMCP-AI/feat-name\n\nv0.17.0 | 2026-07-28T10:16:43.185Z | user\n\nfeat: Merge pull request #24 from OmniMCP-AI/feature/pg-only-image-hint\n\nv0.16.2 | 2026-07-24T09:47:57.708Z | user\n\nfix: add references/excelize-multiple-tables.md\n\nv0.15.0 | 2026-07-16T10:00:40.969Z | user\n\nfeat: Merge PR #15 - Update workbook import skill docs\n\nv0.14.0 | 2026-07-14T09:38:48.322Z | user\n\nfeat: pivot table, feat: dashboard v2, merge PR #11 and #10\n\nv0.13.5 | 2026-07-14T09:35:17.194Z | user\n\nfix: prefer import path for sheet uploads\n\nv0.13.4 | 2026-07-14T06:31:06.619Z | user\n\nfix: clarify SQL handoff persistence\n\nv0.13.1 | 2026-07-13T03:26:52.894Z | user\n\nfix: correct published display metadata\n\nv0.13.0 | 2026-07-13T03:25:57.558Z | user\n\nfeat: add excel worksheet check-error guidance\n\nv0.11.2 | 2026-07-10T02:30:26.250Z | user\n\nfix: mbs formula reference guidance\n\nv0.11.1 | 2026-07-08T16:42:04.040Z | user\n\nfix: restore skill display name\n\nv0.11.0 | 2026-07-08T16:41:08.443Z | user\n\nfeat: document db-table create\n\nv0.10.3 | 2026-07-08T07:12:45.873Z | user\n\nfix: clarify SQL formula persistence\n\nv0.10.2 | 2026-07-08T06:57:41.525Z | user\n\nfix: remove obsolete mbs raw post usage\n\nv0.10.1 | 2026-07-02T12:24:22.079Z | user\n\nfix: preserve skill display name\n\nv0.10.0 | 2026-07-02T12:23:59.035Z | user\n\nfeat: document workbook and worksheet calculate commands\n\nv0.9.0 | 2026-07-02T09:48:43.263Z | user\n\nfeat: document local worksheet table detection\n\nv0.8.8 | 2026-07-02T04:45:01.702Z | user\n\nfix: update mbs command workflow\n\nv0.8.7 | 2026-06-30T05:46:06.405Z | user\n\nfix: document PG import selection for large sheet data\n\nv0.8.6 | 2026-06-30T05:20:13.053Z | user\n\nfix: Document update_range value list parse results\n\nv0.8.5 | 2026-06-30T05:19:43.402Z | user\n\nfix: Document update_range value list parse results\n\nv0.8.4 | 2026-06-30T03:52:15.755Z | user\n\nfix: Document sheet sharing commands\n\nv0.8.2 | 2026-06-25T15:49:36.615Z | user\n\nfix: remove redundant version field from SKILL frontmatter\n\nv0.8.1 | 2026-06-25T09:36:05.496Z | user\n\nfix: make skill CLI-first and align SKILL.md with best practices\n\nArchive index:\n\nArchive vv0.21.8: 26 files, 64643 bytes\n\nFiles: agents/openai.yaml (1293b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (2699b), references/base-mode-verification.md (2776b), references/charts-formatting.md (18892b), references/cli-commands.md (12943b), references/cli-packaging-plan.md (703b), references/clickable-refs.md (5172b), references/engine-selection-when-create.md (4295b), references/errors-recovery.md (10709b), references/excelize-multiple-tables.md (3254b), references/file-management.md (22074b), references/formulas-sql.md (3322b), references/lineage-trace.md (4691b), references/permission-sharing.md (4528b), references/pivot-tables.md (4956b), references/read-write.md (4969b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (2574b), scripts/check_runtime_help_policy.py (2575b), scripts/sync_cli_release.py (4003b), skill-card.md (3673b), SKILL.md (29915b), todo.md (692b), _meta.json (138b)\n\nFile vv0.21.8:SKILL.md\n\n---\nversion: v0.21.8\nname: maybeai-sheet-cli\ndescription: Use when the user works with MaybeAI spreadsheets through the mbs CLI for workbook inspection, local or remote-URL file import, native cross-workbook import/export, worksheet/range/table writes, worksheet calculation and error scans, complete table/SQL reads with frame export, SQL-to-Base materialization, full worksheet data refreshes that keep headers, formulas, worksheet styling, chart/image CRUD, dashboard validate/refresh/export-template flows, or sharing. Route dashboard design and chart composition to `sheet-dashboard`.\nmetadata:\n cli_version: \"0.28.4\"\n openclaw:\n requires:\n env:\n - MAYBEAI_API_TOKEN\n primaryEnv: MAYBEAI_API_TOKEN\n emoji: \"📊\"\n homepage: https://github.com/OmniMCP-AI/maybeai-uni\nrequired_environment_variables:\n - name: MAYBEAI_API_TOKEN\n---\n\n# MaybeAI Sheet CLI\n\nExecute spreadsheet work through `mbs`, the console script from\n`maybeai-sheet-cli`. Use first-class object commands.\n\n## Target model gate\n\nBefore choosing a command, inspect the installed CLI rather than relying on a\ndocumented command map:\n\n```bash\nmbs --help\nmbs workbook --help\nmbs worksheet --help\nmbs --help\n```\n\nUse `mbs workbook inspect` to inspect the workbook and `mbs worksheet list` to\ndiscover worksheet identities. A worksheet name or `gid` is only a locator; it\ndoes not prove the target supports cells, ranges, or stable table records.\n\n| Target model | Required identity | Use | Do not use |\n|---|---|---|---|\n| Sheet grid | `worksheet_name` or `gid` | A1 ranges, cell formulas, worksheet calculation, row/column layout, cell notes | Base record/field selectors |\n| Sheet table | worksheet locator plus persistent `table_id` when multiple tables exist | table read/insert/update and table/row/column views | treating a scan-order table number as a stable ID |\n| Base table | `table_id` (or `table_name` for resolution), then `field_id`/`record_id` | typed records, Base field/column operations, Base Formula | A1/range writes, cell formulas, keep-headers refresh |\n| Worksheet SQL Config | SQL-config worksheet identity plus raw SQL | `mbs sql config`, preview, and materialization | a legacy SQL cell wrapper or cell Formula |\n\n## Canonical operation layer\n\nUse the public canonical groups (`workbook`, `worksheet`, `table`, `range`, `row`,\n`column`, and `formula`) for new work. They emit `contract_version: \"1.0\"` JSON with `ok`, `operation`,\n`target`, and either `result` or `error`; `--output table|yaml` only changes\nrendering. Mutations default to `--verify`; use `--dry-run` before a destructive\nor unfamiliar request and pass `--expected-revision`/`--idempotency-key` when\nthe workflow needs concurrency protection.\n\nCanonical target URIs are stable, redacted MaybeAI URLs:\n\n```text\nSheet worksheet: https://www.maybe.ai/docs/spreadsheets/d/?gid=\nSheet table: https://www.maybe.ai/docs/spreadsheets/d/?gid=&tid=\nBase table: https://www.maybe.ai/docs/spreadsheets/d/?tid=\nBase by name: https://www.maybe.ai/docs/spreadsheets/d/?table=\n```\n\n`--target` is accepted by canonical object operations and mutations. Use the\nruntime help output as the sole command-discovery contract; do not maintain or\ninfer a static command map from this skill.\n\nFor `sql query` and `sql preview`, a workbook target may include the worksheet\nselector `?table=`. The CLI resolves that selector first and\nthen sends the SQL request against the workbook target, so SQL still requires\na workbook URL rather than a Base-table `tid` target. Preserve the selector\nwhen the query is intended for one worksheet:\n\n```bash\nmbs sql query \\\n --target \"$WORKBOOK?table=Sheet6\" \\\n --sql-file result.sql \\\n --all \\\n --frame-out /tmp/query.parquet\n```\n\n### Runtime command discovery and compatibility policy\n\nRun `mbs --help` before selecting a top-level group, then run\n`mbs --help` before selecting its operation. The parent help lists the\npublic command surface that agents may generate. Consult the selected command's\n`--help` for required selectors and mutation flags.\n\nA command that remains directly callable but is absent from its parent help is a\nhidden compatibility command. Do **not** probe for, suggest, or generate it in\nnew workflows. If an existing integration explicitly names one, explain that it\nis compatibility-only and first look for a public workflow in the current help.\nIf no public command preserves the requested semantics, report the capability\ngap instead of silently composing a lossy substitute.\n\n`worksheet style` is public. When the user explicitly requests worksheet\nstyling, discover its supported nested operations with `mbs worksheet style\n--help`; do not duplicate a nested operation list in this skill.\n\n### Resource style commands and config aliases\n\nThe current public style operations are `worksheet style`, `table style`,\n`range style`, `row style`, and `column style`. Public resource-local config\ncommands are `worksheet config`, `table config`, `row config`, and `column\nconfig`. Use `range style` for a range; `range config` is compatibility-only and\nmust not be generated.\n\n```bash\nmbs worksheet config --target \"$SHEET\" --spec worksheet-config.json --verify\nmbs table config --target \"$SHEET_TABLE\" --section header --spec table-style.json --verify\nmbs range style --target \"$SHEET\" --range B2:D4 --spec range-style.json --verify\nmbs row config --target \"$SHEET\" --rows 2:4 --spec row-style.json --verify\n```\n\nUse `--scope entire-grid` only with `--yes` or `--dry-run`. `worksheet config`\nkeeps behavior separate from `--style-spec`; the style spec cannot be combined\nwith `--spec` or the worksheet behavior flags (`--freeze-*`, `--gridlines`, or\n`--zoom`). The `--zoom` flag is retained by the CLI but is currently rejected\nby the HTTP adapters as unsupported; do not rely on it for remote writes. Table\nstyles may target `all`, `header`, `body`, or `totals`. For\ncolumn styles, pass exactly one of `--columns` (Sheet) or `--field` (Base).\n\nFor `worksheet config --spec`, prefer the canonical nested schema:\n\n```json\n{\n \"layout\": {\n \"freeze\": {\"rows\": 1, \"columns\": 0},\n \"gridlines\": {\"visible\": false},\n \"zoom\": 110\n },\n \"filter\": {\n \"enabled\": true,\n \"range\": \"A1:H100\",\n \"conditions\": [{\"field_id\": \"col_status\", \"op\": \"in\", \"value\": [\"open\"]}]\n },\n \"view\": {\n \"id\": \"optional-view-id\",\n \"fields\": {\"order\": [\"col_status\"], \"hidden\": [\"col_internal\"]},\n \"sorts\": [{\"field_id\": \"col_status\", \"direction\": \"asc\"}]\n }\n}\n```\n\nThe CLI accepts legacy keys for compatibility but normalizes output to this\nshape. `layout.*` and `filter.range` are Sheet-only in the canonical model,\nbut the current HTTP Sheet adapters only implement `layout.freeze`,\n`layout.gridlines`, `filter.enabled`, and `filter.range`; `layout.headings` and\n`layout.zoom` are rejected as unsupported. `filter.conditions` and `view.*`\nare Base-only. For Base view configuration, use `--doc-id` plus `--table-id`\n(or a Base target URI), not a `gid`; a view ID is optional when saving a new\nview. Unsupported engine properties fail before mutation.\n\n### Column rename and resource style (`column.rename`, `column.style`)\n\n`column rename` changes one Sheet header or Base field name. Provide exactly one\nof `--column`, `--field`, or `--field-id`, plus required `--new-name`.\n\n```bash\n# Sheet/SheetTable: one A1 column; header row is 1-based and defaults to 1.\nmbs column rename --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" \\\n --column B --new-name \"Net Revenue\" --verify\n\n# Base: resolve a human-readable field or use its stable ID.\nmbs column rename --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" \\\n --field-id --new-name \"Net Amount\" --verify\n```\n\nIn the current CLI, `column config` is a command-name alias for\n`column style`, not a typed field-metadata editor. It requires `--spec` and\nexactly one style selector: `--columns` for a Sheet target or `--field` for a\nBase target. The alias still emits the `column.style` operation; it does not\naccept the older `--field-type`, `--required`, `--unique`, `--default`, or\n`--options` flags.\n\n```bash\nmbs column style --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" \\\n --columns B:D --spec column-style.json --verify\nmbs column config --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" \\\n --field amount --spec column-style.json --verify\n```\n\nFor Base schema changes, use only the public commands shown by `mbs column\n--help`, such as `column insert` and `column rename`. `column config` is a style\noperation, not a typed field-metadata editor. If a requested Base field property\nis not exposed by a public command, report a capability gap; do not generate a\nhidden compatibility command.\n\nTo convert an existing Base Formula field to an ordinary field type, use the\npublic `column batch-update` command with an update object that explicitly\nrequests materialization:\n\n```json\n[\n {\n \"field_id\": \"col_formula\",\n \"logical_type\": \"text\",\n \"formula_conversion\": \"materialize\"\n }\n]\n```\n\n```bash\nmbs column batch-update \\\n --target \"$BASE_TABLE\" \\\n --updates formula-to-text.json \\\n --dry-run\n\nmbs column batch-update \\\n --target \"$BASE_TABLE\" \\\n --updates formula-to-text.json \\\n --verify\n```\n\n`--updates` accepts an array of JSON objects, so `formula_conversion` belongs\non the individual field update and is passed through unchanged. Use\n`formula_conversion: \"materialize\"` only when the current field is Formula and\nthe requested `logical_type` is an ordinary type. Materialization preserves the\ncurrent formula results as field values and removes Formula metadata; it is a\ndestructive schema/data-semantic change and must not be inferred for ordinary\ntype, name, or style updates. The conversion instruction is not a persisted\nfield property, so verification should check the resulting `logical_type` and\nvalues rather than expect `formula_conversion` in the readback.\n\nUse `formula set`, `formula validate`, `formula calculate`, and `formula\nrecalculate` according to their runtime help. Do not generate the hidden\n`formula compile` or `formula batch-set` compatibility commands.\n\nDo not infer the model from a worksheet's name, a compatibility alias, or its\nvisual appearance. If inspection does not return an engine and Base identity,\nstop before a mutation and obtain the required target details through the public inspection/list workflow. The public Base surface is\n`mbs table`, `row`, `column`, and `formula` with a Base target. Do not\nsubstitute an A1/range or keep-headers command for a Base record write.\n\nFor local `.xls` / `.xlsx` imports, choose the engine per worksheet when a\nworkbook mixes large table-like sheets and Excel-layout sheets. The workbook\nimport commands support `--engine auto`, `--engine base`, and\ncomma-separated worksheet engine lists. CSV/TSV files and public Google Sheet\nURLs use the import-source preview flow and can import as a new workbook or\nappend all or selected worksheets/tabs to an existing workbook. Remote HTTPS\nExcel URLs create a new workbook through `/api/v1/excel/import_by_url`.\nTo migrate one existing Sheet-backed worksheet to Base, use the guarded\n`worksheet convert-to-base` workflow below; it is a one-way data migration,\nnot an import-engine setting.\n\n**Prerequisites:** `MAYBEAI_API_TOKEN`, `mbs` (`pip install maybeai-sheet-cli`)\n\n**Delegated subagent rule.** For a delegated MaybeAI task, use `terminal` first:\n`mbs --version` and `test -n \"$MAYBEAI_API_TOKEN\"`. Do not infer missing mbs,\nterminal, or token from old files, logs, or JSON artifacts. Only report a\nmissing token when that command actually shows it is absent.\n\n**CLI 0.28 compatibility boundaries.** Generate only the public command\nsurface for new workflows:\n\n- Use `mbs worksheet …`, never `mbs excel_worksheet …`; the underscore\n alias was removed.\n- Use `mbs range lineage --target --range `;\n `range lineage --cell` was removed.\n- Use `mbs worksheet beautify`, `mbs worksheet config`, or resource-local\n `range`, `row`, `column`, and `table` style commands for styling.\n- `mbs worksheet beautify` defaults to `--layout auto`: it keeps ordinary\n column tables on the field-by-column path, including date columns. It selects\n a pivot/report only after finding at least two concrete horizontal members\n (for example, `1店`/`2店`, `Store A`/`Store B`, or `Q1`/`Q2`); generic names\n such as `日期` or `门店`, and a lone `合计`/`Total`, are not pivot evidence.\n For a pivot/report, the first column of the target range is treated as row\n labels (text or numeric codes) and each value row is formatted from its\n label: `毛利率` is percent while `毛利-CNY` is currency. Use dry-run before\n applying, and pass `--layout table` or `--layout pivot` only when an explicit\n override is needed.\n- Use `mbs range note read|set|clear`, not the removed nested\n `mbs cell note read|set|clear` commands. `read` accepts an A1 range; `set`\n and `clear` currently require one A1 cell.\n\n## Quick start\n\n```bash\n# Discover the installed public surface and target identity first.\nmbs --help\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output json\nmbs table list --doc-id --output json\n\n# Read a bounded preview. Omitting --limit requests 1000 rows.\nmbs range read --target \"$SHEET\" --range A1:D20 --output table\nmbs table read --target \"$BASE_TABLE\" --limit 100 --output table\n\n# Export every page to one local frame; use backend ordering when available.\nmbs table read --target \"$BASE_TABLE\" --all --order-by order_id --frame-out /tmp/orders.parquet\n\n# Public writes use explicit frames/keys and verification.\nmbs table insert --target \"$BASE_TABLE\" --frame-in rows.json --verify\nmbs table update --target \"$BASE_TABLE\" --frame-in corrected_rows.json --key order_id --verify\nmbs formula set --target \"$SHEET\" --cell E2 --expression '=SUM(B2:D2)' --verify\nmbs range note set --target \"$SHEET\" --range B2 --text \"Reviewed\" --verify\n\n# Current public worksheet and SQL operations.\nmbs worksheet calculate --target \"$SHEET\" --verify\nmbs worksheet check-error --target \"$SHEET\" --range A1:Z100\nmbs sql query --target \"$WORKBOOK?table=Sheet6\" --sql-file result.sql --all --frame-out /tmp/query.parquet\nmbs sql materialize --target \"$BASE_TABLE\" --sql-file result.sql --mode create --schema schema.json --verify\n```\n\nAll public `table create` source variants use the canonical operation\n`table.create`, including frame, SQL-query, and worksheet-range creation.\nAdapters must not expect `table.create-from-query` or\n`table.create-from-range` in the response envelope.\n\nWhole-table replacement does not have an automatic public-command substitute.\nDo not rewrite it as a sequence of destructive calls without confirming the\nchanged semantics. For an in-place batch update of existing Base field schema,\nuse public `mbs column batch-update` only after inspecting its installed help;\nit is not a substitute for a whole-schema replacement, field deletion, or data\nmigration.\n\n## Execution order\n\n1. Run `mbs --version` and `mbs --help` once at the start of a session; trust the local CLI over remembered examples.\n2. `mbs --help` when flags are unclear.\n3. [references/cli-commands.md](references/cli-commands.md) for runtime-help-first operational guidance.\n4. Topic reference below for semantics, edge cases, and uncovered CLI gaps.\n\n## Critical rules\n\n- **Runtime help is authoritative.** Use the public groups and commands listed\n by `mbs --help` and the relevant parent `--help`; do not hard-code a full\n command map here.\n- **Model before mutation.** Inspect the workbook and list worksheets before\n choosing Sheet-range, table-record, Base-field, or SQL workflows.\n- **No hidden compatibility generation.** Never generate an operation absent\n from parent help for a new workflow, including old `excel-*`, `base-table`,\n `db-table`, `sheet`, top-level `style`, `worksheet image`, and nested\n `cell note` entry points.\n- **Formula and notes.** Use `formula set` for formula writes and `range note\n read|set|clear` for Sheet notes. `range lineage` takes `--range`, not `--cell`.\n- **Workbook deletion lifecycle.** When the user asks to delete a workbook but\n does not explicitly request a recoverable deletion, use\n `mbs workbook delete --yes`; the CLI defaults to physical `purge`. Run the\n corresponding `--dry-run` first. Use\n `--mode mark --yes` only when the user explicitly asks for mark deletion,\n recovery, or 7-day retention. Both modes use the workbook lifecycle API;\n never use the legacy file-delete route.\n- **Clear versus replace.** Use public `table clear --target \"$BASE_TABLE\" --yes --verify`\n to remove all Base records while preserving fields/schema; use `--dry-run`\n before destructive execution. `table insert` and `table update` do not\n provide atomic whole-table replacement semantics. Use\n `column batch-update` for a supported in-place batch update of existing Base\n field metadata; resource style config alone does not imply that capability.\n- **Verification.** Use `--dry-run` before destructive or unfamiliar writes;\n preserve `--expected-revision`/`--idempotency-key` when required; use\n `--verify` and target-appropriate readback after mutation.\n- **Base inspection.** `table inspect` addresses one Base table by `tid` or\n `table` name. Its canonical result may include matched worksheet dimensions;\n use `table schema` and `table read` for fields and records.\n- **Complete table reads.** `table read` defaults to 1000 rows (maximum\n 5000), so a command without `--all` is only a bounded read. Use `--all`\n with `--frame-out` for a complete export. The CLI follows a cursor or, when\n the backend returns `has_more: true` without one, advances by the page's\n actual record count. A full page with no cursor, `has_more`, total, or\n completion proof is a `backend.pagination_contract` error, not a completed\n export. See [references/cli-commands.md](references/cli-commands.md).\n- **Images and SQL.** Use `mbs image` for public image operations. Use `sql\n materialize` for public Base-table materialization and `sql config` /\n `sql overwrite` only when their runtime help matches the requested target.\n\n## Task routing\n\n| Task | Start here |\n|------|------------|\n| Command flags and examples | [references/cli-commands.md](references/cli-commands.md) |\n| Read/write targeting and API choice | [references/read-write.md](references/read-write.md) |\n| Base record/field/formula verification | [references/base-mode-verification.md](references/base-mode-verification.md) |\n| Upload, export, sharing | [references/file-management.md](references/file-management.md) |\n| Workbook semantic overview | [references/workbook-profile.md](references/workbook-profile.md) |\n| Sharing and permissions | [references/permission-sharing.md](references/permission-sharing.md) |\n| Formulas and SQL result sheets | [references/formulas-sql.md](references/formulas-sql.md) |\n| Pivot tables and pivot config specs | [references/pivot-tables.md](references/pivot-tables.md) |\n| Formula dependency tracing | [references/lineage-trace.md](references/lineage-trace.md) |\n| Charts, images, dashboards, worksheet styling | [references/charts-formatting.md](references/charts-formatting.md) |\n| Merge/unmerge cells, cell notes, Base record notes | [references/charts-formatting.md](references/charts-formatting.md) |\n| Sharing and permissions | [references/permission-sharing.md](references/permission-sharing.md) |\n| Failures and recovery | [references/errors-recovery.md](references/errors-recovery.md) |\n| Clickable cell refs in answers | [references/clickable-refs.md](references/clickable-refs.md) |\n| Legacy SQL formula migration/showcase | [references/sql-formula-showcase.md](references/sql-formula-showcase.md) |\n\n## Workflows\n\n### Inspect a workbook\n\n```\n- [ ] `mbs workbook inspect` and `mbs worksheet list`\n- [ ] identify worksheet name, table id, or Base table name\n- [ ] read sample with --output table\n```\n\n```bash\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output table\nmbs range read --doc-id --worksheet-name --output table\nmbs range read --doc-id --worksheet-name --range A1:D20 --output table\n```\n\n### Delete a workbook\n\nThe `mbs` command defaults to physical `purge`, reclaiming the workbook's\nstorage unless the user explicitly requests recoverability. Inspect the target\nand preview the physical deletion before sending it:\n\n```bash\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs workbook delete --target \"$WORKBOOK\" --dry-run\nmbs workbook delete --target \"$WORKBOOK\" --yes\n```\n\nUse a mark deletion only when the user explicitly wants the 7-day recovery\nwindow:\n\n```bash\nmbs workbook delete --target \"$WORKBOOK\" --mode mark --yes\n```\n\n### Upload and inspect\n\n```\n- [ ] workbook import\n- [ ] capture document_id from JSON output\n- [ ] use import stdout plus `--verify` as creation evidence\n- [ ] if needed, resolve and sample one representative Base table per family\n```\n\n```bash\n# Small workbook-style files\nmbs workbook import ./file.xlsx --verify\nmbs workbook import ./orders.csv --engine base\nmbs workbook import \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --engine sheet\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output table\n\n# Large table-like files\nmbs workbook import ./file.xlsx --engine base --verify\nmbs table inspect --doc-id --table-name --output json\nmbs table sample --doc-id --table-id --limit 2 --output table\n\n# Cross-workbook worksheet -> raw Base-backed surface import\nmbs worksheet import --strategy create --doc-id --source-doc-id --source-worksheet-name \"1店\" --verify\nmbs worksheet import --strategy create --doc-id --source-doc-id --source-worksheet-name \"1店\" --source-worksheet-name \"2店\" --verify\n\n# Sheet only: replace existing worksheet rows from JSON while keeping headers.\n# For Base records, use public `mbs table insert` / `mbs table update` after checking their help.\nmbs worksheet import ./rows.json --strategy replace --doc-id --worksheet-name Students --verify\n\n# Native Maybe Sheet worksheet import; engine is detected per worksheet\nmbs worksheet import --strategy create --transfer-mode native --doc-id --source-doc-id --source-worksheet-name \"工作表3\" --source-worksheet-name \"工作簿1\" --verify\nmbs worksheet import --strategy create --transfer-mode native --doc-id --source-doc-id --verify\n\n# Append source worksheets/tabs into an existing workbook\nmbs worksheet import ./file.xlsx --strategy create --doc-id --engine sheet --verify\nmbs worksheet import ./file.xlsx --strategy create --doc-id --source-worksheet-name \"联盟\" --target-worksheet-name \"联盟导入\" --engine sheet --verify\nmbs worksheet import ./file.xlsx --strategy create --doc-id --source-worksheet-name \"联盟\" --source-worksheet-name \"订单\" --engine base --verify\nmbs worksheet import ./orders.csv --strategy create --doc-id --engine base --verify\nmbs worksheet import \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --strategy create --doc-id --source-worksheet-name \"1店\" --target-worksheet-name \"Store 1\" --engine sheet --verify\n```\n\nDo not follow successful raw-surface imports with per-table `schema` / `sample` / `read` loops. See [references/file-management.md](references/file-management.md) for engine choice and Base Mode verification.\n\n### Convert a worksheet to Base\n\n```\n- [ ] inspect `worksheet list` and select exactly one Sheet-backed worksheet\n- [ ] run `convert-to-base --dry-run` with `--gid` or `--worksheet-name`\n- [ ] execute the reviewed conversion with `--yes --verify`\n- [ ] retain old Sheet-engine source cells only when explicitly requested\n```\n\n```bash\n# The workbook URL can provide both document ID and gid.\nmbs worksheet convert-to-base \\\n --url \"https://www.maybe.ai/docs/spreadsheets/d/?gid=\" \\\n --dry-run\n\n# Execute after reviewing the dry run. Source cells are scrubbed by default.\nmbs worksheet convert-to-base \\\n --doc-id \\\n --worksheet-name Orders \\\n --yes \\\n --verify\n\n# Keep the prior Sheet-engine cell content only when required.\nmbs worksheet convert-to-base \\\n --doc-id \\\n --gid \\\n --keep-sheet-source \\\n --yes \\\n --verify\n```\n\nUse `--recalculate` when the converted Base worksheet should recalculate\nimmediately. Do not combine `--dry-run` with `--verify`. The command checks\nmetadata during `--verify` and succeeds only when the selected worksheet\nreports `data_engine: base`.\n\n### Dashboard execution\n\n```\n- [ ] `mbs --version` and relevant `--help`\n- [ ] import with `--engine auto` or an explicit worksheet-index engine list\n- [ ] `worksheet list` verifies Data_* Base Mode and Dashboard/summary Sheet mode where intended\n- [ ] `dashboard validate --spec dashboard.json`\n- [ ] `dashboard refresh --dry-run` checks payload shape before mutation\n- [ ] execute `dashboard refresh`; if batch errors persist, use per-chart `chart create-config`\n- [ ] `dashboard manifest` and `chart list` verify persisted metadata\n- [ ] read source Data_* sheets and run browser/vision verification when logged-in canvas access exists\n```\n\nSee [references/charts-formatting.md](references/charts-formatting.md) for chart spec shapes, fallback, and verification limits.\n\n### Dashboard template export\n\nUse this only when the user wants to promote an existing Maybe Sheet HTML dashboard worksheet into a reusable template package. The dashboard canvas must be a `sheet` worksheet, and the worksheet should contain exactly one persisted `chart.type=html` dashboard chart unless `--chart-id` or `--cell` is provided.\n\n```bash\nmbs dashboard export-template \\\n --doc-id \\\n --worksheet-name \\\n --template-id \\\n --out-dir /dashboard-templates/ \\\n --force\n```\n\nThe command writes `template.json`, `html/dashboard.template.html`, and `html/runtime-payload.schema.json`. After export, switch to `analysis-style-system` and run `node scripts/validate_dashboard_html_template.mjs --template-dir dashboard-templates/` before using or publishing the template skill.\n\n### Sync rows by key\n\nChoose the model first. For a Base table, use public `table update` with a\nstable key and an explicit input frame. The public command surface has no\ngeneric Sheet key-merge primitive: reconcile the data before a `range write`,\nor report the capability gap rather than invoking a hidden Sheet upsert alias.\n\n```\n- [ ] inspect workbook and worksheet identities\n- [ ] confirm the stable Base record key, or explicitly approve Sheet overwrite semantics\n- [ ] use `table update --key ...` only for a Base/table target\n- [ ] recalculate Sheet formulas if downstream formulas exist\n- [ ] read back the target\n```\n\n```bash\nmbs formula recalculate --doc-id --worksheet-name \n```\n\n### SQL result sheet\n\n```\n- [ ] headers + read sample on source sheet\n- [ ] save raw SQL with `mbs sql config set`\n- [ ] use `mbs sql materialize` for a public Base-table materialization, or `mbs sql overwrite` only when the target is a SQL-config worksheet\n- [ ] read the materialized target\n- [ ] scan the worksheet with `range inspect`\n```\n\nSee [references/formulas-sql.md](references/formulas-sql.md).\n\n### Pivot table\n\n```\n- [ ] inspect source worksheet headers\n- [ ] author `pivot-config.json`\n- [ ] preview pivot output\n- [ ] upsert with explicit target worksheet and anchor cell\n- [ ] read target range to verify\n```\n\n```bash\nmbs pivot preview --doc-id --worksheet-name --spec pivot-config.json --output table\nmbs pivot upsert --doc-id --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot-config.json\nmbs range read --doc-id --worksheet-name PivotResult --range A1:H30 --output table\n```\n\nSee [references/pivot-tables.md](references/pivot-tables.md).\n\n### Trace formula lineage\n\n```bash\nmbs formula lineage --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=\" --cell E2 --format tree --output yaml\n```\n\nSee [references/lineage-trace.md](references/lineage-trace.md) for response interpretation.\n\n### Share or check access\n\n```bash\nmbs share permission --doc-id \nmbs share visibility --doc-id --visibility public --public-permission viewer\n# Share read-only access with a MaybeAI user email\nmbs share grant --doc-id --email user@example.com --permission viewer\n# Share write/edit access with a MaybeAI user email\nmbs share grant --doc-id --email user@example.com --permission editor\nmbs share list --doc-id \n```\n\nIf `mbs share visibility` returns 403 with an owner-only message, classify it as `owner_permission_required` / `permission_skipped`. If `workbook inspect` already shows the requested public/editor or public/viewer visibility, report it as a share warning rather than a dashboard failure; otherwise ask the owner or service account to update visibility. See [references/permission-sharing.md](references/permission-sharing.md) for owner requirements and access rules.\n\n## Boundaries\n\n- **Dashboard/chart layout** -> use `sheet-dashboard`, not this skill\n- **Uncovered CLI gaps** -> check current `mbs --help` for a supported command\n- **Clickable refs** -> only confirmed locations; see [references/clickable-refs.md](references/clickable-refs.md)\n\nFile vv0.21.8:README.md\n\n# maybeai-sheet-cli-skill\n\nAgent skill for the `mbs` CLI from `maybeai-sheet-cli` **0.28.0**.\n\nThe installed CLI's runtime help is the command contract. Start a spreadsheet\nsession with:\n\n```bash\nmbs --help\nmbs --help\nmbs --help\n```\n\nThe parent `--help` output identifies commands that agents may generate in new\nworkflows. A directly callable command missing from that output is a hidden\ncompatibility command: do not recommend or generate it. If public commands\ncannot preserve the requested behavior, explain the capability gap instead of\nconstructing a destructive approximation.\n\nThis skill provides model-routing guidance for Sheet, SheetTable, Base, and SQL\nworkflows; safe mutation and verification practices; and topic references for\nimports, reads/writes, formulas, charts, sharing, recovery, and lineage. It\nintentionally does **not** duplicate a complete CLI command tree. Consult the\ninstalled command help for available groups, operations, parameters, and\nfeature changes.\n\nNotable public-workflow boundaries:\n\n- Use `workbook inspect` and `worksheet list` for target discovery.\n- Use `formula set` for formula writes and `range note` for Sheet notes.\n- Use `mbs image` for image operations.\n- Use public `mbs table clear --target \"$BASE_TABLE\" --yes --verify` to remove\n all Base table records while preserving fields/schema. It is destructive, so\n preview with `--dry-run` when needed. For batch updates to existing Base\n field schema, use public `mbs column batch-update` after\n confirming its installed `--help` contract.\n\nThis repository owns agent-facing assets:\n\n- `SKILL.md` — routing, playbooks, and core rules\n- `references/` — runtime-help-first operational guidance and semantic caveats\n- `agents/` — agent metadata\n- `artifacts/` — demo datasets and reusable example specs\n\nCLI implementation lives separately at:\n\n- `../maybeai-sheet-cli`\n\nInstall the CLI:\n\n```bash\npip install maybeai-sheet-cli\n```\n\nTo get a MaybeAI API token, register at [maybe.ai](https://www.maybe.ai/), then\nopen [My Plan](https://www.maybe.ai/user/my-plan) and copy a token from the\n**API Token** section.\n\nSet `MAYBEAI_API_TOKEN`, then run `mbs --help`:\n\n```bash\nexport MAYBEAI_API_TOKEN=\"your-api-token\"\nmbs --help\n```\n\n## Sync after CLI release\n\nAfter `../maybeai-sheet-cli` is published to PyPI, sync this skill's version\nfrontmatter from the released CLI metadata:\n\n```bash\npython scripts/sync_cli_release.py --cli-repo ../maybeai-sheet-cli\n```\n\nThe hook verifies that the CLI repository version fields agree and that the\nsame version exists on PyPI before updating `SKILL.md`. Use `--skip-pypi-check`\nonly for local draft docs before a package release.\n\nFile vv0.21.8:_meta.json\n\n{\n \"ownerId\": \"kn77y6x3semab3mjjhgxyw81w9827yxy\",\n \"slug\": \"maybeai-sheet-cli\",\n \"version\": \"v0.21.8\",\n \"publishedAt\": 1789359128081\n}\n\nFile vv0.21.8:references/base-mode-verification.md\n\n# Base Mode Verification Runbook\n\n## 1. Identify the Base target\n\n```bash\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output json\nmbs table inspect --target \"$BASE_TABLE\"\nmbs table schema --target \"$BASE_TABLE\"\nmbs table sample --target \"$BASE_TABLE\" --limit 10 --output table\n```\n\nUse `table sample` for a quick, representative, non-exhaustive check of Base\nrecords and field values. Use bounded `table read` when verification needs a\nspecified result window or post-mutation readback.\n\nUse a persistent Base table ID (`tid`) and stable field/record identities. A\nworksheet name alone is insufficient for a Base record or field mutation.\nFor a Base target, canonical `table inspect` also returns matched worksheet\ndimensions when available; use `table schema` and `table read` for fields and\nrecords.\n\n## 2. Insert or update records\n\n```bash\nmbs table insert --target \"$BASE_TABLE\" --frame-in rows.json --verify\nmbs table update --target \"$BASE_TABLE\" --frame-in corrected_rows.json --key order_id --verify\nmbs table read --target \"$BASE_TABLE\" --limit 100 --output table\n```\n\n`table update` is key-based. It does not imply an atomic full-table replacement,\ndelete missing records, or preserve all legacy replacement semantics. Stop and\nreport the capability gap when those semantics are required.\n\n## 3. Fields and Formula fields\n\n```bash\nmbs column insert --target \"$BASE_TABLE\" --field gross_margin --field-type formula --verify\nmbs column rename --target \"$BASE_TABLE\" --field gross_margin --new-name \"Gross Margin\" --verify\nmbs column config --target \"$BASE_TABLE\" --field gross_margin --spec field-style.json --verify\nmbs formula validate --target \"$BASE_TABLE\" --field gross_margin --expression 'revenue - cost'\nmbs formula set --target \"$BASE_TABLE\" --field gross_margin --expression 'revenue - cost' --verify\nmbs formula recalculate --target \"$BASE_TABLE\" --field gross_margin --verify\n```\n\n`column config` configures resource style; it is not a substitute for every\nBase typed-field property. Use current parent/command help before changing a\nfield and report unsupported schema work instead of selecting a hidden command.\n\n## 4. Verify SQL materialization\n\n```bash\nmbs sql materialize \\\n --target \"$WORKBOOK?table=S_orders\" \\\n --sql-file result.sql \\\n --mode create \\\n --schema schema.json \\\n --verify\nmbs table read --target \"$WORKBOOK?table=S_orders\" --limit 100 --output table\n```\n\nVerify the result schema, row count, representative values, and the target\nidentity returned by the mutation.\n\n## 5. Reject Sheet-only misuse\n\nDo not apply A1 range writes, merge/unmerge, Sheet cell notes, or Excel cell\nformula assumptions to a Base table. Explain the mismatch and choose a public\nBase record/field workflow instead.\n\nFile vv0.21.8:references/charts-formatting.md\n\n# Charts and Formatting Reference\n\n## Contents\n\n1. When to use this\n2. Scope boundary\n3. First-class mbs coverage\n4. Styling and freezing\n5. Minimal report-polish flow\n\n## 1. When to use this\n\nRead this document when the task involves charts, pictures, frozen panes, cell styles, autofilter, or conditional formatting.\n\n## 2. Scope boundary\n\nThis skill only covers worksheet-level `mbs` execution and media/styling operations.\n\nSwitch to `sheet-dashboard` when:\n\n- chart composition is the main task\n- dashboard layout and storytelling are the main task\n- you need chart layout systems, visual systems, or dashboard workflows\n- you need an agent to generate or swap a dashboard spec before execution\n\nIf you only need to:\n\n- inspect existing chart metadata\n- call low-level chart/image CRUD APIs\n- bind a chart to an existing sheet\n\nthen this skill is sufficient.\n\nChart and picture editing is first-class in `mbs` for common worksheet\nworkflows. Use `mbs raw post` only when you already have a task-specific\npayload for an uncovered operation.\n\n## 3. First-class mbs coverage\n\nCLI:\n\n```bash\nmbs chart list --doc-id --worksheet-name \nmbs chart get --doc-id --worksheet-name --cell J2\nmbs chart create-config --doc-id --worksheet-name --cell J2 --spec chart.json\n# Current CLI also accepts top-level `cell` in chart.json when --cell is omitted.\nmbs chart update --doc-id --worksheet-name --cell J2 --chart-id rId1 --spec chart.json\nmbs chart delete --doc-id --worksheet-name --chart-id rId1\n```\n\nRecommended authored `chart.json` shape:\n\n```json\n{\n \"type\": \"json\",\n \"sql\": \"select Month, Revenue from Sheet1\",\n \"title\": \"Monthly Revenue\",\n \"hide_title\": true,\n \"legend\": \"bottom\",\n \"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) }] }) }\",\n \"spec\": {\n \"style\": {\n \"title\": \"Monthly Revenue\",\n \"showContainerTitle\": false\n }\n }\n}\n```\n\nAlternate single-chart item shape accepted by recent CLI versions:\n\n```json\n{\n \"cell\": \"B2\",\n \"chart\": {\n \"type\": \"json\",\n \"sql\": \"select Month, Revenue from Sheet1\",\n \"title\": \"Monthly Revenue\",\n \"html\": \"{ library: 'echarts', handler: (data) => ({ series: [{ type: 'line', data: data.map(r => Number(String(r.Revenue || '').replace(/,/g, '')) || 0) }] }) }\"\n }\n}\n```\n\nImportant chart authoring rule:\n\n- Prefer top-level `chart.type = \"json\"` for authored `mbs` specs.\n- Put the actual ECharts or Highcharts renderer logic in `chart.html`.\n- For `chart create-config`, the backend request is `{cell, chart}`. If you include `cell` in the spec, keep it top-level; do not nest a second `chart.chart`.\n- Do not push `chart.type = \"line\"`, `\"bar\"`, or `\"pie\"` as the default authored pattern in `mbs` docs or skills.\n- Treat those simple aliases as low-level backend-supported forms, not the primary recommendation.\n- If the chart should keep metadata `title` but hide the visible container title, prefer `hide_title: true` or explicit `spec.style.showContainerTitle: false`.\n- Do not rely on `title: \"\"` as the primary authored pattern for non-filter charts. Keep `chart.title` for metadata and hide the container title instead.\n- If `chart.html` already draws its own visible title/header, also set `spec.style.showContainerTitle: false` to avoid duplicate titles.\n\nImages:\n\n```bash\nmbs workbook inspect --doc-id --output json\nmbs worksheet list --doc-id --output json\nmbs image list --doc-id --worksheet-name \nmbs image read --doc-id --worksheet-name --cell A1 --out logo.png\nmbs image insert --doc-id --worksheet-name --cell B3 --file logo.png --format picture-format.json\nmbs image set --doc-id --worksheet-name --old-cell B3 --cell B3 --format picture-format.json --width 120 --height 91\nmbs image replace --doc-id --worksheet-name --cell B3 --file logo_v2.png --format picture-format.json\nmbs image delete --doc-id --worksheet-name --cell A1\nmbs media check --doc-id --worksheet-name \n```\n\nPicture format uses the chart-compatible floating-object anchor model:\n\n```json\n{\n \"from\": {\"col\": 1, \"row\": 2, \"col_off\": 0, \"row_off\": 0},\n \"to\": {\"col\": 4, \"row\": 10, \"col_off\": 0, \"row_off\": 0}\n}\n```\n\nUse zero-based row/column indexes in `from` and `to`. The `--cell` value is the\nanchor used by the command, but persisted layout depends on picture `format`\nand dimensions. Do not model worksheet images as cell values.\n\nEngine preflight:\n\n- Run `workbook inspect` and `worksheet list` before inserting images.\n- The target worksheet should be Sheet-backed, usually\n `data_engine=sheet` and `style_engine=sheet`.\n- Base-only worksheets do not support `add_picture`. In a Base Mode workbook,\n `worksheet create` can create a Base-only empty worksheet, which image\n insert may later report as `sheet does not exist`.\n- If the user wants a new image canvas in an existing Base Mode workbook, create a\n small local blank `.xlsx` with the desired sheet name and import it:\n\n```bash\nmbs worksheet import --strategy create ./blank.xlsx --doc-id --engine sheet --source-worksheet-name --target-worksheet-name --verify\n```\n\n- If a Base-only placeholder was created only for the image task and cannot be\n used, delete that placeholder before importing the Excel worksheet.\n\nDashboard worksheet orchestration:\n\n```bash\nmbs dashboard validate --spec dashboard.json\nmbs dashboard refresh --doc-id --spec dashboard.json --dry-run\nmbs dashboard manifest --doc-id --worksheet-name \nmbs dashboard create-config --doc-id --spec dashboard.json --create-worksheet\nmbs dashboard refresh --doc-id --spec dashboard.json\nmbs dashboard export-template --doc-id --worksheet-name --template-id --out-dir /dashboard-templates/ --force\n```\n\nGuidance:\n\n- when a dashboard is being designed from scratch, let `sheet-dashboard` generate `dashboard.json` first, then use the commands above to validate and write it\n- when an existing HTML dashboard should become a reusable template, use `dashboard export-template`; the source worksheet must be a `sheet` worksheet, and the output package belongs under `analysis-style-system/dashboard-templates/`\n- if a dashboard spec uses `dashboard_style_pack`, keep `industry_style` and `dashboard_story` alongside it so `dashboard validate` can prove the style contract is complete\n- `dashboard refresh --dry-run` is a hard step before mutation; inspect that each operation has `charts: [{cell, chart}]`, not `chart.chart`.\n- Use `chart list` or `image list` first to inspect current worksheet inventory.\n- Before editing an existing chart, confirm `chart_id`, the anchor cell, and the worksheet.\n- `chart get` requires `--cell` or `--chart-id` and resolves locally from the listed chart inventory.\n- When documenting or generating dashboard chart specs, prefer `type: \"json\"` entries there as well.\n- For non-filter charts, keep `chart.title` in metadata and hide duplicate visible titles with `spec.style.showContainerTitle: false`.\n- Dashboard chart specs should keep charts inside columns `B:N`.\n- Dashboard chart specs should include `chart.format.from` and `chart.format.to`, and the outer `cell` should match `chart.format.from`.\n- For vertically stacked dashboard charts that share horizontal space, leave at least 1 empty worksheet row between them.\n- Images are floating objects like charts. For insert, move, resize, or replace workflows, include `--format picture-format.json` so x/y position, anchors, and size survive readback and frontend drag/resize.\n- Images require an Sheet-backed worksheet. Do not insert pictures into Base-only\n worksheets; use an existing Excel sheet or import a blank `.xlsx` with\n `--engine sheet` to create one.\n- `image list` should return enough metadata for frontend display and later updates: URL/media reference when available, anchor cell, picture id, extension, alt text, size, and chart-compatible position/format fields.\n- `image set` updates an existing picture's anchor, position, size, alt text, scale, hyperlink, or format. Use it after a frontend drag/resize operation instead of reinserting the image.\n- `image replace` inherits prior `alt_text` when `--alt-text` is omitted.\n- `media check` verifies worksheet-level image/chart object presence after `add_picture`, image commands, chart commands, or dashboard refresh.\n- `dashboard refresh` is upsert-only: matching charts are updated, missing charts are created, and unrelated existing charts are not deleted.\n- If batch dashboard refresh/create-config returns a server-side or unsupported-route error, retry as per-chart calls:\n `mbs chart create-config --doc-id --worksheet-name Dashboard --cell --spec `.\n- `dashboard manifest`, `chart list`, `image list`, `media check`, and returned ids prove metadata persistence only. They do not prove the web canvas rendered successfully.\n- For delivery, also verify source data reads for every chart SQL source. If logged-in browser access to the MaybeSheet canvas is available, use a screenshot/vision check for true render validation. Public unauthenticated viewer access may show a login wall instead of charts. For HTML dashboards, use `mbs dashboard render-probe --screenshot` when possible and read the output in tiers: `local_probe_passed` proves local runtime/data binding, `screenshot_verified` proves PNG capture, and `environment_blocked` with `playwright_unavailable` / `chromium_unavailable` means the environment needs `npm i -D playwright` and `npx playwright install chromium` before final visual proof.\n- After `dashboard export-template`, switch to `analysis-style-system` and run `node scripts/validate_dashboard_html_template.mjs --template-dir dashboard-templates/` before reusing or publishing the template.\n- For KPI or chart handlers that consume formatted numeric strings, coerce defensively:\n `Number(String(value || '').replace(/,/g, '')) || 0`.\n\n## 4. Styling and freezing\n\nPrefer the resource-local canonical style layer for new work. The current CLI\nregisters `worksheet.style`, `table.style`, `range.style`, `row.style`, and\n`column.style`; `table`, `row`, and `column` also expose public `config`\noperations for resource-local configuration. `worksheet config` remains the behavior/view\ncommand, while `worksheet config --style-spec` is the appearance alias and\ncannot be combined with view options.\n\n```bash\nmbs worksheet style --target \"$SHEET\" --scope used-region --spec worksheet-style.json --verify\nmbs worksheet config --target \"$SHEET\" --style-spec worksheet-style.json --verify\nmbs table style --target \"$SHEET_TABLE\" --section header --spec table-style.json --verify\nmbs range style --target \"$SHEET\" --range A1:G1 --spec header-style.json --verify\nmbs row config --target \"$SHEET\" --rows 2:4 --spec row-style.json --verify\nmbs column config --target \"$SHEET\" --columns B:D --spec column-style.json --verify\nmbs column config --target \"$BASE_TABLE\" --field amount --spec column-style.json --verify\n```\n\nSelector and safety rules:\n\n- `worksheet style --scope` accepts `used-region` or `entire-grid`; the latter\n requires `--yes` or `--dry-run`.\n- `table style/config --section` accepts `all`, `header`, `body`, or `totals`.\n- `range style` requires a bounded A1 `--range`; `row style/config` requires\n `--rows`.\n- `column style/config` requires exactly one of `--columns` (Sheet) or\n `--field` (Base). It is a style operation, not a typed field-metadata\n editor. For Base schema work, inspect `mbs column --help`; use public\n `column batch-update --updates` for supported in-place updates to existing\n field metadata, and use individual public column operations for structural\n changes not covered by that update contract.\n\nFor advanced worksheet styling (for example conditional formats, filters, or\nexplicit dimensions), do not retain a static nested command list in this skill.\nInspect the installed public surface first:\n\n```bash\nmbs worksheet style --help\nmbs worksheet style --help\n```\n\nGenerate only an operation shown by that parent help. Use `mbs worksheet\nbeautify --help` when the task is an agent-driven polish workflow rather than a\nspecific, user-defined style operation.\n\nImportant rules:\n\n- Use `mbs worksheet beautify` for the default agent-friendly polish workflow. It\n inspects metadata first, applies Excel worksheet styling where appropriate,\n and applies Base-backed field formatter/style/header metadata through the\n native field update path when possible.\n- For column names and schema, use only the public operations shown by\n `mbs column --help`, including `mbs column rename`, `mbs column insert\n --field-type`, and `mbs column batch-update --updates` for supported\n in-place batch changes to existing Base field metadata. For resource\n appearance, use `mbs column style` or public `mbs column config --spec`.\n Do not treat batch update as a whole-schema replacement or compose destructive\n delete/recreate sequences without an explicit migration decision.\n- Base-backed table default freeze/filter/header config should be returned by the\n backend. Do not instruct the frontend to synthesize auto-filter or dark\n header backgrounds.\n- `filter-values --column` takes a zero-based absolute column index. In `--range A1:G100`, `--column 2` targets column C.\n- Even a single range should use `range_addresses: [\"A1:G1\"]`\n- Keep style payloads small and explicit\n- Prefer high-level style keys:\n - `format`\n - `bold`\n - `bg_color`\n - `font_color`\n - `font_size`\n - `font_family`\n - `horizontal`\n - `wrap_text`\n\n\nExample `header_style.json` payload for `batch-set --style`:\n\n```json\n{\n \"bold\": true,\n \"font_color\": \"#FFFFFF\",\n \"bg_color\": \"#173E56\",\n \"font_size\": 12,\n \"font_family\": \"Arial\",\n \"horizontal\": \"center\",\n \"wrap_text\": true\n}\n```\n\n## 5. Minimal report-polish flow\n\nUse this when the user asks for something like “make it look more like a management report”, “improve readability”, or “style the header row”.\n\n1. Write the data first.\n2. For a general polish request, inspect `mbs worksheet beautify --help`.\n3. For a specific worksheet-level style request, inspect `mbs worksheet style\n --help` and then the selected public child command's `--help`.\n4. Use resource-local `range style`, `row style`, or `column style` when they\n preserve the requested scope.\n5. Read the affected range to verify.\n\nIf the response includes:\n\n```text\nsource_info.styles_ignored=true\n```\n\nyou must explicitly tell the user that the current worksheet engine did not apply the styles. Do not claim the styling work is complete.\n\nUse canonical resource-local style/config commands for the common appearance\npath. Use `mbs worksheet style --help` only when the requested operation is\nworksheet-level and not covered by those resource-local commands.\nUse `mbs chart`, `image`, and `dashboard` for the first-class\nworksheet media and orchestration workflows above.\nUse `mbs raw post` only for uncovered chart/picture/style operations. Verify\nwith `mbs range read --output table`, `chart list`, or\n`image list`.\n\n## 6. Merge cells and cell notes / record notes\n\nUse these when the user asks to merge/unmerge cells, attach a cell note (Excel\ncomment) on a Sheet worksheet, or add notes on Base table records.\n\n### Merge / unmerge cells (Sheet worksheets)\n\n```bash\nmbs range merge --doc-id --worksheet-name Sheet1 --range A1:D1\nmbs range unmerge --doc-id --worksheet-name Sheet1 --range A1:D1\n```\n\nRules:\n\n- `--range` must be a range (contains `:`); merge requires at least two cells.\n- Unmerging a sub-range removes the whole containing merged region\n (Excel-compatible).\n- Merged ranges are returned by `mbs range read` under\n `formatting.merged_cells`; do not manually compute display values for merged\n titles.\n\n### Range notes (Excel comments, Sheet worksheets)\n\nUse the canonical target-based `range note` commands with a Sheet target\ncontaining worksheet identity (`gid` or an equivalent canonical target).\n\n```bash\n# Read notes from one cell or an A1 range\nmbs range note read --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" --range B2:D4\n\n# Set one note\nmbs range note set --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" --range B2 --text \"review this\" --verify\n\n# Clear one note\nmbs range note clear --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" --range B2 --verify\n```\n\nRules:\n\n- `read` accepts one A1 cell or an A1 range.\n- `set` and `clear` currently require a single A1 cell such as `B2`. The\n CLI `--text` interface emits a 1×1 matrix; do not claim that a multi-cell\n write is supported until it has a matching matrix input contract.\n- `set`/`clear` are versioned worksheet writes, so preserve the returned\n revision and use `--expected-revision` when coordinating concurrent edits.\n- Notes are stored as Excel comments inside the workbook and follow workbook\n version history.\n- The historical flat `mbs cell note-get`, `mbs cell note-set`, and\n `mbs cell note-clear` forms may remain compatibility aliases. The nested\n `mbs cell note read|set|clear` forms were removed; do not generate either\n legacy form for new instructions.\n\n### Base table record notes\n\nUse canonical row-note commands with a Base table target:\n\n```bash\nmbs row note add --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" --record-id --text \"记得核对一下\" --verify\nmbs row note list --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" --record-id \nmbs row note update --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" --record-id --note-id --text \"updated\" --verify\nmbs row note delete --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" --record-id --note-id --yes --verify\n```\n\nRules:\n\n- Record notes are collaboration metadata on Base tables; they do **not**\n participate in version history / rollback.\n- **Owner-only edit/delete**: only the note author (the API user's email/user id)\n can update or delete a note. When creating via CLI, omit `--author` (or pass\n your own email) so you remain the owner; a custom `--author` name is not the\n API user and cannot be edited/deleted through the API.\n- The historical `mbs row note|note-list|note-update|note-delete`\n commands may remain available as compatibility aliases. Prefer canonical\n `mbs row note ...` commands in new workflows.\n\nFile vv0.21.8:references/cli-commands.md\n\n# CLI Command Reference\n\n## Runtime discovery is the command contract\n\nDo not copy a static command tree from this skill. The installed CLI is the\nsource of truth for public commands and flags:\n\n```bash\nmbs --help\nmbs --help\nmbs --help\n```\n\nGenerate only commands listed by their parent `--help`. A directly callable\ncommand that is absent from parent help is a hidden compatibility surface; do\nnot probe, recommend, or generate it for new work.\n\n## Discover and identify the target\n\n```bash\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output json\nmbs table list --doc-id --output json\n```\n\nUse a Sheet target with `gid` for A1 range/cell work. Use a persistent `tid`\n(and field or record IDs when required) for Base work. Do not infer the engine\nfrom a worksheet name or visual appearance.\n\n## Public operational patterns\n\n### Read and inspect\n\n```bash\nmbs range inspect --target \"$SHEET\" --range A1:Z100\nmbs range read --target \"$SHEET\" --range A1:D20 --output table\nmbs table schema --target \"$BASE_TABLE\"\nmbs table read --target \"$BASE_TABLE\" --limit 100 --output table\nmbs table read --target \"$BASE_TABLE\" --all --order-by order_id --frame-out /tmp/orders.parquet\n```\n\n#### Complete table exports and pagination\n\n`table read` currently defaults to 1000 records per request and accepts at\nmost 5000. Without `--all`, it performs exactly one bounded read, even if the\nresponse says more records exist. Use a smaller explicit `--limit` for a\npreview; use a frame for a complete result:\n\n```bash\nmbs table read \\\n --target \"$BASE_TABLE\" \\\n --all \\\n --order-by order_id \\\n --frame-out /tmp/orders.parquet \\\n --output json\n```\n\n`--frame-out` requires `--all`. The CLI collects every page, then writes one\ncomplete `.parquet`, `.csv`, or `.json` frame; it does not leave a partial\nframe when pagination fails. It follows `next_cursor` / `nextCursor`. When a\nbackend instead returns `has_more: true` without a cursor, it requests the\nnext page with `offset += records_returned`. `has_more: false`, a reached\ndeclared total, or an explicit completion marker ends the read.\n\nNever infer completion from the number of returned rows. If a page fills the\nrequested limit but has no cursor, `has_more`, total, or completion marker,\nthe CLI exits with `backend.pagination_contract` rather than silently export a\ntruncated result. Repeated cursors, an empty page with `has_more: true`, and a\ndeclared total larger than the rows received also fail. `--order-by` is a\nbackend capability: if the target cannot honor it, the CLI returns a capability\nerror instead of sorting locally. Complete reads do not pin a table snapshot;\navoid concurrent writes when an exact point-in-time export is required.\n\n### Write table records\n\n```bash\nmbs table insert --target \"$BASE_TABLE\" --frame-in rows.json --verify\nmbs table update \\\n --target \"$BASE_TABLE\" \\\n --frame-in corrected_rows.json \\\n --key order_id \\\n --expected-revision \\\n --verify\n```\n\n`table clear` removes all Base records while preserving fields/schema and\nrequires explicit `--yes` (or `--dry-run`). `table insert` and `table update`\nare not an automatic replacement for an atomic whole-table replacement operation. If the request requires deleting\nmissing records, preserving identities, or atomic replacement semantics, state\nthe capability gap and obtain an explicit product/API decision before composing\ndestructive calls.\n\n### Write Sheet ranges, formulas, and notes\n\n```bash\nmbs range write --target \"$SHEET\" --range A1:C3 --values values.json --verify\nmbs range style --target \"$SHEET\" --range B2:D4 --spec range-style.json --verify\nmbs formula validate --target \"$SHEET\" --cell E2 --expression '=SUM(B2:D2)'\nmbs formula set --target \"$SHEET\" --cell E2 --expression '=SUM(B2:D2)' --verify\nmbs formula calculate --target \"$SHEET\" --cell E2 --save-result --verify\nmbs range note read --target \"$SHEET\" --range B2:D4\nmbs range note set --target \"$SHEET\" --range B2 --text \"Reviewed\" --verify\nmbs range note clear --target \"$SHEET\" --range B2 --verify\n```\n\nUse `formula set` for formula writes and `range note read|set|clear` for Sheet\nnotes. Notes are not Base record notes. `range lineage` uses `--range`, not\n`--cell`.\n\n### Worksheet operations and styling\n\n```bash\nmbs worksheet calculate --target \"$SHEET\" --verify\nmbs worksheet check-error --target \"$SHEET\" --range A1:Z100\nmbs worksheet config --target \"$SHEET\" --spec worksheet-config.json --verify\n# Default `--layout auto` detects a normal table or a pivot/report.\n# Always inspect the plan before an unfamiliar styling mutation.\nmbs worksheet beautify --target \"$SHEET\" --dry-run --output json\nmbs worksheet beautify --target \"$SHEET\" --verify\nmbs range merge --target \"$SHEET\" --range A1:C1 --verify\nmbs range unmerge --target \"$SHEET\" --range A1:C1 --verify\n```\n\n`worksheet beautify` uses `--layout auto` when `--layout` is omitted. It\nkeeps **table** for ordinary column-oriented data, so a field such as `日期`\nremains a date column. It selects **pivot** only after finding at least two\nconcrete horizontal members, such as `1店`/`2店`, `Store A`/`Store B`,\n`Q1`/`Q2`, or `2025-01`/`2025-02`. Generic field names (`日期`, `门店`, `月份`,\n`年度`) and a lone `合计`/`Total` do not count as pivot evidence. In a detected\npivot, the first column of the target range is the row-label area; it may hold\ntext labels or numeric codes. Its labels determine value-area formats row by\nrow: `毛利率` formats `B:E` as percent while `毛利-CNY` and `净利润-CNY` format\n`B:E` as currency. The label header `利润项目` remains text; it must not be\nclassified as a currency value merely because it contains `利润`. Numeric row\nlabels default to number formatting unless a `rowLabelRules` rule overrides\nthat classification.\n\nAuto detection currently treats only the **first column of the target range**\nas the pivot row-label column. Choose a range with that shape, or use\n`--layout pivot` for an intentional pivot whose members do not match the\nstructural patterns above; use `--layout table` to force field-by-column\nformatting.\n\nBefore applying beautify to an unfamiliar worksheet, use dry-run and inspect\n`result.plan.worksheets[0].layout_detection.selected`,\n`layout_detection.reasons`, `row_semantics`, and `value_range` in the JSON\nresponse. Override inference only when required:\n\n```bash\nmbs worksheet beautify --target \"$SHEET\" --layout pivot --verify --output json\nmbs worksheet beautify --target \"$SHEET\" --layout table --verify --output json\n```\n\nA pivot label column automatically receives a wider minimum width. Set an\nexplicit width in the beautify policy when needed:\n\n```json\n{\n \"columnWidths\": {\n \"byColumn\": {\"A\": 24},\n \"byHeader\": {\"利润项目\": 24}\n }\n}\n```\n\nWidth precedence is `byColumn` > `byHeader` > automatic width. Supply this\npolicy through `mbs worksheet beautify --config beautify-policy.json`.\n\nRun `mbs worksheet style --help` only when the task needs explicit worksheet\nstyling operations, then inspect the selected child with `--help`. Do not copy a\nnested worksheet-style command list into this skill.\n\n### Base fields and formulas\n\n```bash\nmbs column insert --target \"$BASE_TABLE\" --field new_status --field-type text --verify\nmbs column rename --target \"$BASE_TABLE\" --field status --new-name Status --verify\nmbs column config --target \"$BASE_TABLE\" --field amount --spec column-style.json --verify\nmbs column batch-update --target \"$BASE_TABLE\" --updates base-field-updates.json --verify\nmbs formula validate --target \"$BASE_TABLE\" --field gross_margin --expression 'revenue - cost'\nmbs formula set --target \"$BASE_TABLE\" --field gross_margin --expression 'revenue - cost' --verify\nmbs formula recalculate --target \"$BASE_TABLE\" --field gross_margin --verify\n```\n\n`column config` is a resource-style operation. For an in-place batch update of\nexisting Base field metadata, use public `column batch-update --updates` and\ninspect its installed help for the accepted update-object contract. It does not\nreplace whole-schema migration: adding, deleting, or reordering fields may need\nseparate public column operations and has different atomicity/data-migration\nsemantics.\n\nFor a Formula-to-ordinary-type conversion, put the explicit conversion mode on\nthe affected update object:\n\n```json\n[\n {\n \"field_id\": \"col_formula\",\n \"logical_type\": \"text\",\n \"formula_conversion\": \"materialize\"\n }\n]\n```\n\n```bash\nmbs column batch-update \\\n --target \"$BASE_TABLE\" \\\n --updates formula-to-text.json \\\n --dry-run\nmbs column batch-update \\\n --target \"$BASE_TABLE\" \\\n --updates formula-to-text.json \\\n --verify\n```\n\nThe public command already accepts arbitrary JSON update objects and forwards\n`formula_conversion` to the field batch-update API; no separate top-level CLI\nflag is required. `materialize` is required only when changing a current\nFormula field to an ordinary `logical_type`. It materializes the current\nformula results and removes Formula metadata, so do not add it automatically\nto rename, style, or ordinary type updates. Verification should assert the\nresulting field type and values, not the presence of `formula_conversion` in\nreadback metadata.\n\n### SQL materialization\n\n```bash\nmbs sql query --target \"$WORKBOOK?table=Sheet6\" --sql-file result.sql --all --frame-out /tmp/query.parquet\nmbs sql preview --target \"$WORKBOOK?table=Sheet6\" --sql-file result.sql --output table\nmbs sql materialize \\\n --target \"$WORKBOOK?table=S_orders\" \\\n --sql-file result.sql \\\n --mode create \\\n --schema schema.json \\\n --verify\n```\n\nUse `sql materialize` for public Base-table materialization. Use `sql config`\nand `sql overwrite` only when the current help and selected target show a\nWorksheet SQL Config workflow. `sql query --all --frame-out` is read-only and\nwrites a complete local Parquet, CSV, or JSON frame; it does not modify the\nworkbook.\n\n`sql query` and `sql preview` accept a workbook target with\n`?table=` to select the worksheet used by the query. The CLI\nresolves the worksheet selector before issuing the workbook SQL request. Do\nnot replace this with a Base-table `?tid=` target; SQL query and\npreview require a workbook target.\n\nThe canonical response operation for every public `table create` source is\n`table.create`, including frame, SQL-query, and worksheet-range sources. The\nsource-specific implementation path does not change the operation name in\nthe response envelope.\n\n### Other public groups\n\nFor chart, pivot, dashboard, image, media, history, file, share, and raw work,\nstart with the relevant parent help and then inspect the selected operation's\nflags. Use `mbs image`, not a worksheet image compatibility alias.\n\n## Native Sorting\n\nUse `range sort` for Sheet cells and `table sort` for a Base table view:\n\n```bash\n# Sort complete rows inside this rectangle, retaining the first row as headers.\nmbs range sort --target \"$SHEET\" --range A1:D100 --by B:asc --by C:desc --dry-run\nmbs range sort --target \"$SHEET\" --range A1:D100 --by B:asc --by C:desc\n\n# Include the first row when the range contains no header.\nmbs range sort --target \"$SHEET\" --range A2:D100 --by B:asc --no-header\n\n# Save sort keys on a Base view while retaining its filters and field settings.\nmbs table sort --doc-id \"$DOC_ID\" --table-id \"$TABLE_ID\" --by col_amount:desc\nmbs table sort --doc-id \"$DOC_ID\" --table-id \"$TABLE_ID\" --view-id \"$VIEW_ID\" --clear\n```\n\nRepeat `--by` in priority order. Sheet keys are absolute column letters inside\nthe selected rectangle; Base keys are stable field IDs. Directions are `asc`\nor `desc`. Sheet sorting is stable and places blanks last in either direction.\nIt runs on the server and preserves cell content and formatting; unsupported\ncell structures are rejected before mutation. Base sorting changes the saved\nview, not the underlying record order.\n\nSheet compatibility requires cached values for formula-valued sort keys.\nMerged cells, cell comments/hyperlinks, and unsupported formula constructs\nare rejected before mutation. Moved formulas retain absolute references and\ntranslate relative ones. Formula result caches are invalidated for recalculation.\n`range sort` reports verification as unavailable; `table sort` verifies saved\nview settings by reading them back. If that read fails after saving, the command\nreports the failure without repeating the write.\n\nThese commands require a CLI build containing native sorting. Sheet range\nsorting additionally requires the matching SheetTable `sort_range` endpoint\nand its API proxy route; older deployed servers do not provide that endpoint.\n\n## Mutation safety\n\nFor mutations, use `--dry-run` before unfamiliar or destructive work, preserve\n`--expected-revision` and `--idempotency-key` when the workflow needs them, and\nverify with a target-appropriate readback. `--output table|yaml` changes\nrendering only; it does not alter the command contract.\n\nFile vv0.21.8:references/cli-packaging-plan.md\n\n# Archived CLI Packaging Note\n\n> **Archived:** This document records an early packaging discussion from before\n> the released `mbs` CLI command surface. It is not a command contract, command\n> tree, command map, endpoint map, or execution reference.\n\nFor current usage, discover the installed public surface with:\n\n```bash\nmbs --help\nmbs --help\nmbs --help\n```\n\nGenerate only commands shown by public root or nested `--help`. Do not infer\na command from this archived note, an old package name, an endpoint name, or a\nlegacy script; do not generate hidden compatibility commands.\n\nUse `SKILL.md` and `references/cli-commands.md` for current agent guidance.\n\nFile vv0.21.8:references/clickable-refs.md\n\n# Maybe Sheet Clickable References\n\nUse this reference when an answer about a Maybe Sheet needs to mention confirmed cells, ranges, or worksheets from the current workbook. The frontend can render `sheet-ref` tags as clickable references.\n\n## Formats\n\nCell or range:\n\n```html\nVISIBLE_LABEL\n```\n\nThe tag must be paired and must include visible text. The frontend parser does not recognize self-closing tags.\n\nWorksheet:\n\n```html\nVISIBLE_LABEL\n```\n\n## Rules\n\n- Only use `sheet-ref` tags when the task is operating on a Maybe Sheet.\n- Only use `sheet-ref` tags for real cells, ranges, or worksheets from the current workbook.\n- Only use `sheet-ref` tags for references that were confirmed from the workbook, a tool result, or a reliable Maybe Sheet API response.\n- Do not use `sheet-ref` tags for examples, guesses, inferred locations, hypothetical formulas, external workbook references, or uncertain references.\n- Include the current workbook document ID in the `docId` attribute. Use the exact document ID from the Maybe Sheet URL or API response.\n- Include the target worksheet gid in the `gid` attribute. Use the exact gid from the Maybe Sheet URL, `mbs worksheet list` output, or an API response.\n- Preserve the exact worksheet name from the workbook or tool result in the `sheet` attribute.\n- Use A1 notation in the `range` attribute. For a single cell, either `A1` or `A1:A1` is acceptable; prefer the form returned or required by the active tool.\n- Use a concise visible label, usually `SheetName!A1`, `SheetName!A1:B2`, or the worksheet name.\n- Always use paired tags with visible text: `SheetName!A1`.\n- Never use self-closing tags such as ``; they are not clickable in the current frontend.\n- Do not wrap `sheet-ref` tags in code blocks in the final answer.\n- Do not put `sheet-ref` tags inside formula code blocks, SQL code blocks, JSON, shell commands, or other literal examples.\n- If the task is not about Maybe Sheet, answer normally without `sheet-ref` tags.\n\n## Chinese Rules\n\n- 只在当前任务是 Maybe Sheet 场景时使用 `sheet-ref`。\n- 只对当前 Maybe Sheet 工作簿中真实存在的单元格、区域或工作表使用。\n- 只对已经从工作簿、工具结果或可信 Maybe Sheet API 响应中确认的位置使用。\n- 不要对示例、猜测、推断位置、假设公式、外部工作簿引用或不确定位置使用。\n- 必须在 `docId` 属性中包含当前工作簿的文档 ID。使用 Maybe Sheet URL 或 API 响应中的精确 document ID。\n- 必须在 `gid` 属性中包含目标工作表 gid。使用 Maybe Sheet URL、worksheet 列表或 API 响应中的精确 gid。\n- `sheet` 必须保留工作簿或工具结果里的精确工作表名。\n- `range` 使用 A1 表示法。单个单元格可以写成 `A1` 或 `A1:A1`；优先使用当前工具返回或要求的形式。\n- 显示文本保持简短，例如 `Sheet1!A1`、`Sheet1!A1:B2` 或工作表名。\n- 必须使用带显示文本的成对标签：`SheetName!A1`。\n- 禁止使用 `` 这类自闭合标签；当前前端不会把它渲染成可点击链接。\n- 不要把 `sheet-ref` 放进最终回答的代码块。\n- 不要把 `sheet-ref` 放进公式、SQL、JSON、shell 命令或其他字面量示例中。\n- 如果任务不是 Maybe Sheet 场景，正常回答，不要输出 `sheet-ref`。\n\n## Examples\n\nGood:\n\n```md\n异常值主要出现在 订单明细!F18，汇总结果在 汇总。\n```\n\nGood:\n\n```md\n利润分析!C3 来自 利润表-2025Q2!D5。\n```\n\nBad:\n\n```md\nFor example, Sheet1!A1 could contain revenue.\n```\n\nThe bad example uses `sheet-ref` for an example, not a confirmed workbook reference.\n\nBad:\n\n```md\nQ2 销售费用在 \n```\n\nThe bad example uses a self-closing tag, which the current frontend does not recognize as a clickable reference.\n\nBad:\n\n```md\n利润分析!C3\n```\n\nThe bad example omits the required `docId` attribute.\n\nBad:\n\n```md\n利润分析!C3\n```\n\nThe bad example omits the required `gid` attribute.\n\nFile vv0.21.8:references/engine-selection-when-create.md\n\n# Engine Selection When Creating Data Products\n\nChoose the target model before creating a worksheet, table, or query output.\nThe models may coexist in one workbook but do not share a write API.\n\n## Discover the public command surface first\n\nDo not treat this reference as a command tree or a flag contract. Before\nconstructing a command, inspect the installed public surface and the relevant\nleaf help:\n\n```bash\nmbs --help\nmbs table --help\nmbs sql --help\nmbs worksheet --help\nmbs formula --help\n```\n\nGenerate only commands shown by those public help screens and their nested\n`--help` output. Use nested `--help` for the selected public leaf before\nrelying on flags or payload shape. Do not generate hidden compatibility\ncommands, even when an older script or integration still accepts them.\n\n| Need | Create/use | Identity after creation |\n|---|---|---|\n| Visual report, merged cells, charts, images, or visible formulas | Excel Sheet | `worksheet_name`, `gid`, A1 addresses |\n| Flat operational records and field-level computation | Base Table | `table_id`, `field_id`, record key/`record_id` |\n| Persisted derived result from a query | Worksheet SQL Config or supported SQL materialization | result worksheet/table and raw SQL config |\n\n## Base Table\n\nFor a new durable Base handoff table, use the public `table create` flow when\nits documented arguments cover the requested rows and schema. Capture the\nreturned table and field identities, then use `table inspect`, `table schema`,\nand a bounded `table sample` to verify the result.\n\nThe canonical response operation is `table.create` for every public creation\nsource: a local frame, a SQL query result, or a worksheet range. Source\nselection does not produce source-specific operation IDs.\n\nDo not update a Base table by writing a range, running a keep-headers refresh,\nor preserving a row-2 formula template. For later writes, select only a public\nrecord operation shown by the current `mbs table --help` and confirm its\nsemantics with the leaf help before constructing the payload.\n\nFor derived SQL output, use public `mbs sql materialize`. Discover the exact\nmaterialization options with:\n\n```bash\nmbs sql materialize --help\n```\n\n`sql materialize` is only a replacement when its documented destination,\nidentity, schema, and persistence semantics satisfy the requested durable Base\ntable outcome. If it cannot create or target the required Base table with the\nrequired name/schema, report a **capability gap** instead of substituting a\nhidden command or claiming that SQL materialization is equivalent.\n\nFor Base Formula work, use public formula validation, persisted-formula\nreadback, and recalculation evidence. Do not use compile output by itself as\nproof that a Formula field was persisted or executed.\n\n## Worksheet SQL Config\n\nUse this when the query itself must remain visible, auditable, and refreshable\nas a distinct producer. Discover the supported SQL-config and materialization\nleaves before use:\n\n```bash\nmbs sql --help\nmbs sql config --help\nmbs sql materialize --help\n```\n\nSQL Config takes raw SQL; it is not a Formula field and it must not be created\nas a legacy cell SQL wrapper. If a requested materialization destination is not\nsupported by the public `sql materialize` help, report the capability gap.\n\n## Excel Sheet\n\nUse Sheet only for layout-oriented outputs. Discover the public worksheet,\nrange, and formula leaves first; for example, inspect `mbs formula set --help`\nbefore writing a formula.\n\n```bash\nmbs worksheet create --doc-id --name --output json\nmbs range write --doc-id --worksheet-name --range A1:D20 --values --verify\nmbs formula set --doc-id --worksheet-name --cell E2 --expression '=' --language excel\nmbs formula recalculate --doc-id --worksheet-name \nmbs range inspect --doc-id --worksheet-name \n```\n\nAfter creation, inspect the workbook and list its worksheets with the public\ninspection flows:\n\n```bash\nmbs workbook inspect --doc-id --output json\nmbs worksheet list --doc-id --output json\n```\n\nIf the result is Base-backed, stop using A1/range or cell-formula instructions\nand switch to the Base verification runbook.\n\nFile vv0.21.8:references/errors-recovery.md\n\n# Errors and Recovery Reference\n\n## Contents\n\n1. When to use this\n2. Auth failures\n3. Wrote to the wrong worksheet\n4. Styles did not apply\n5. SQL compile failures\n6. Sheet table insert verifies values but reports a revision gap\n7. Formula or spill result shows worksheet errors\n8. Upload returned incomplete data\n9. Local backend mismatch\n10. Raw API body mistakes\n11. Dashboard chart write ambiguity\n12. Pre-delivery verification\n13. Full refresh changed numeric-string precision\n14. Full refresh returned `written_unverified`\n15. Required worksheet identity changed\n\n## 1. When to use this\n\nRead this document when a task fails, writes to the wrong place, ignores styles, fails SQL compilation, or returns incomplete upload metadata.\n\n## 2. Auth failures\n\nCommon symptoms:\n\n- `401`\n- `403`\n- the file can be previewed but API calls fail\n\nChecks:\n\n1. Confirm `MAYBEAI_API_TOKEN` is set\n2. Confirm the command is running in the shell where the token is set\n3. Confirm the target workbook is accessible to that account\n\nRecovery:\n\n- reset the token\n- use `mbs file list`, `mbs workbook inspect`, or `mbs worksheet list` as a minimal auth test\n\n## 3. Wrote to the wrong worksheet\n\nThis is the most common failure.\n\nCauses:\n\n- `worksheet_name` was omitted\n- a legacy command needed `--gid` but only a bare workbook target was passed\n- the caller assumed the CLI would remember the prior worksheet selection\n\nRecovery:\n\n1. `mbs workbook inspect` and `mbs worksheet list`\n2. confirm the target sheet name and gid\n3. rerun with explicit `--worksheet-name` or `--gid`\n4. `mbs range read` to confirm\n\n## 4. Styles did not apply\n\nCommon symptoms:\n\n- the request succeeded but nothing changed visually\n- the response includes `source_info.styles_ignored=true`\n\nRecovery:\n\n1. do not claim the style change succeeded\n2. explicitly tell the user the current engine ignored styles\n3. if the task requires strong visual formatting, switch to a workbook or engine that supports it\n\n## 5. SQL compile failures\n\nCommon causes:\n\n- misspelled column names\n- worksheet names not wrapped in double quotes\n- SQL dialect is too exotic or outside the current conservative Base worksheet SQL subset\n- `WITH` or a more complex structure is rejected by the backend\n\nRecovery:\n\n1. `mbs table schema` or `mbs table schema --table-id `\n2. optionally use a small `mbs range read`\n3. rewrite the query toward the conservative Base worksheet SQL subset\n4. compile first, then write the SQL result\n\n## 6. Sheet table insert verifies values but reports a revision gap\n\nCommon symptoms:\n\n- `mbs table insert --target ...?gid=&tid= --verify` writes rows\n that are visible on a subsequent range/table read.\n- The command still exits nonzero because persistent table metadata did not\n advance the expected version (`revision_advanced` or a related verification\n error).\n\nRecovery:\n\n1. Do not immediately retry; a retry can duplicate the inserted rows.\n2. Read the bounded inserted range or `mbs table read` and compare every\n submitted row.\n3. Re-run `mbs table list --doc-id --gid ` or persistent metadata\n only to observe table identity/range, not as the sole proof of the write.\n4. If values match, report the mutation as applied with a verification warning;\n if they do not, reconcile from the readback before retrying.\n\n## 7. Formula or spill result shows worksheet errors\n\nCommon symptoms:\n\n- `#VALUE!`\n- `#REF!`\n- `#DIV/0!`\n- the formula is present but the readback value is empty or missing\n\nRecovery:\n\n1. `mbs range inspect --doc-id --worksheet-name `\n2. if the formula text itself may be wrong, inspect it with `mbs formula read`\n3. rerun `mbs formula recalculate` or `mbs workbook calculate` when the workbook should recache results\n4. read the affected range with `mbs range read --output table`\n5. if the error came from a legacy `=SQL(...)` cell, validate headers with `mbs table schema` or `mbs table schema --table-id ` and simplify the SQL\n\nDo not claim a report or model worksheet is healthy based only on a successful\nformula write; verify the result range is free of worksheet errors.\n\n## 8. Upload returned incomplete data\n\nCommon symptoms:\n\n- upload succeeded but `document_id` is missing\n- only `uri` is returned\n- local file path was wrong\n\nRecovery:\n\n1. parse `document_id` from `uri`\n2. if the local file is missing, fix the path first\n3. retry with `mbs workbook import ./file.xlsx`\n\n## 9. Local backend mismatch\n\nCommon symptoms:\n\n- local source changes do not affect `mbs` output\n- `table list --gid ` returns one whole-sheet range instead of multiple content-backed table ranges\n- response looks like production even though a local service is running\n\nChecks:\n\n1. Use local `play-be`, not the chat frontend: `http://localhost:7011`\n2. Prefer `mbs --base-url http://localhost:7011 ...` when debugging base-url confusion\n3. With current CLI versions, `MAYBEAI_BASE_URL=http://localhost:7011 mbs ...` is equivalent\n4. If direct `excelize-mcp` on `http://localhost:8080/api` is correct but `mbs` is not, restart `play-be` and check its `EXCELIZE_MCP_URL`\n\n## 10. Raw API body mistakes\n\nCommon symptom:\n\n- `Invalid value for '--body': Path '{...}' does not exist.`\n\nRecovery:\n\n1. Prefer a first-class `mbs` command when one exists.\n2. For inline JSON, use `mbs raw post --json '{\"a\":\"b\"}'`.\n3. For file-backed JSON, write a body file and pass `--body body.json`.\n\nDo not pass inline JSON to `--body`.\n\n## 11. Dashboard chart write ambiguity\n\nCommon symptoms:\n\n- `Missing option '--cell'`\n- payload shows nested `chart.chart`\n- dashboard batch refresh/create-config returns a server-side error\n- chart ids are returned but the browser canvas is not visually verified\n\nRecovery:\n\n1. Run `mbs dashboard validate --spec dashboard.json`.\n2. Run `mbs dashboard refresh --doc-id --spec dashboard.json --dry-run`.\n3. Confirm dashboard operations use `charts: [{cell, chart}]`.\n4. For single-chart writes, use `chart create-config --cell --spec chart.json`, or put `cell` at spec top level.\n5. If batch still fails, split into one chart spec per chart and call `chart create-config` per cell.\n6. Treat `chart_id`, `dashboard manifest`, and `chart list` as persistence checks only; use data readback and browser canvas verification when possible.\n\n## 12. Pre-delivery verification\n\nMinimum verification standard:\n\n- `mbs workbook inspect` and `mbs worksheet list`\n- `mbs range read` or table sample on the key output range\n- `mbs range inspect` on formula or report-result worksheets\n- optionally `mbs workbook export --doc-id --out workbook.xlsx`\n\nDo not skip verification after:\n\n- SQL result writes\n- formula writes or workbook recalculation\n- range/table writes\n- `mbs table update`\n- creating or deleting worksheets\n- chart, picture, or style adjustments\n\n## 13. Full refresh changed numeric-string precision\n\nCommon symptom:\n\n- a full refresh succeeds, but a long numeric-looking string\n such as `\"46215.95520833333\"` reads back as `\"46215.95521\"`\n\nCause:\n\n- the backend parses numeric-looking strings as Excel values during this\n full-refresh operation, and Excel display/readback normalizes precision\n\nRecovery:\n\n1. Compare the source JSON and bounded readback by field, not only HTTP status.\n2. If the field is conceptually numeric or an Excel date serial, accept the\n normalized value and document the conversion.\n3. If exact text is required, do not use the full-refresh command for that\n field; write an exact bounded range through the RAW range-write path.\n4. Re-read the affected cells and confirm no column misalignment occurred.\n\n## 14. Full refresh returned `written_unverified`\n\nCommon symptoms:\n\n- `mbs worksheet import ... --strategy replace --verify` exits nonzero\n- stdout includes `written_unverified` or `verify failed`\n- the response has `error: null`\n\nThis is an indeterminate verification result, not proof that the write failed.\nDo not say the online sheet remains unchanged, set the task to `BLOCKED`, or\nask the user to select a recovery path until live values have been compared.\n\nRecovery:\n\n1. Read the refreshed footprint or, for a large sheet, header row plus known\n changed sentinels and the previous last row. Do not inspect only an unrelated\n prefix such as `A1:F5` when the claimed change is elsewhere.\n2. Compare live cells with source JSON by header. Use exact comparison for text\n and a documented tolerance for Excel-normalized numeric/date values.\n3. A changed entity/service set does not by itself change the JSON key set when\n keys are date-column headers; do not use that as a failure explanation.\n4. If values match, report success with the CLI verification warning. If they\n differ, automatically use range clear + range write when it preserves the\n required worksheet behavior. When the user required the original worksheet,\n snapshot the latest history entry and formula cells first, then re-read that\n history entry immediately before fallback. Stop the automatic fallback when\n it changed, collaborators are actively editing, or a schema change alters\n formula semantics; the CLI has no lock/revision precondition and must not\n overwrite those changes. Otherwise pass\n `--gid ` to every range mutation, calculate, and error check;\n do not delete, recreate, copy, import, or rename-swap worksheets. Exclude\n formula cells from raw clear/write. For a changed header/schema, clear and\n write the owned value/header ranges from `A1`, including the new header row;\n use `A2` only when headers are unchanged. Recalculate and scan formula\n results for errors before reporting success.\n\n## 15. Required worksheet identity changed\n\nCommon symptoms:\n\n- the target worksheet has the same name after a refresh, but a different `gid`\n- a recovery deleted, recreated, copied, imported, or rename-swapped a sheet\n- a user asked to overwrite the original data or not to create another sheet\n\nThis is a failed outcome even when the visible data looks correct. A worksheet\nname is not its identity.\n\nRecovery:\n\n1. Before a write, record the target name and `gid` with `mbs workbook inspect` and `mbs worksheet list`.\n2. For full refreshes, prefer `worksheet import --strategy replace`; when that\n is unsuitable, use `range clear` and `range write` on the\n same recorded worksheet. Before each range mutation, confirm the target name\n still maps to the recorded `gid` and pass `--gid `; for a\n header/schema change, cover the owned value/header range beginning at `A1`.\n3. Run `workbook inspect` and `worksheet list` after the write. Report success\n only when the original name still maps to the recorded `gid`.\n\nFile vv0.21.8:references/excelize-multiple-tables.md\n\n# Sheet Worksheets With Multiple Tables\n\nUse this reference when one Sheet worksheet contains two or more separate\ncontent-backed tables. A worksheet name identifies the sheet, not an individual\ntable block. Table identity comes from the table metadata and `table_id`.\n\n## Discovery\n\nList the table blocks before reading or importing the worksheet:\n\n```bash\nmbs table list \\\n --doc-id \\\n --worksheet-name '' \\\n --output json\n```\n\nThe response provides one entry per table, including:\n\n- `table_id`: stable target for `table` commands during the current run\n- `range` / `range_address`: the worksheet block to preserve and inspect\n- `header_row`: the worksheet row containing that table's header\n- `row_count` and `column_count`: coarse shape evidence\n- `gid`, `worksheet_name`, and `source`: source lineage\n- `engine`: confirm that the table is Sheet-backed\n\nDo not infer table boundaries from blank rows, visual spacing, or a worksheet-\nwide sample when table metadata is available. The metadata range is the\nboundary to use for the next readback or raw-surface mapping.\n\n## Per-Table Inspection\n\nFor every table returned by `list-table`, inspect metadata and sample/read the\nsame `table_id` independently:\n\n```bash\nmbs table inspect \\\n --doc-id \\\n --worksheet-name '' \\\n --table-id \\\n --output json\n\nmbs table sample \\\n --doc-id \\\n --worksheet-name '' \\\n --table-id \\\n --limit 20 \\\n --output json\n```\n\nIf a raw surface is required, use the metadata `range_address` for that table\nonly. Retain the source worksheet, `gid`, `table_id`, table name, range, header\nrow, and imported source document id in the import manifest. Create separate\nraw surfaces when the downstream contract treats the blocks as separate\ndatasets; never concatenate unrelated table blocks solely because they share a\nworksheet.\n\n## Worked Shape\n\nFor a worksheet named `T14_财务规划引导`, a table inventory can identify two\nindependent blocks:\n\n| table_id | range_address | header_row | data shape |\n| --- | --- | ---: | --- |\n| `46` | `A4:H11` | `4` | 8 columns, 7 reported rows |\n| `47` | `A13:H18` | `13` | 8 columns, 5 reported rows |\n\nThe corresponding metadata lookup for the first block is:\n\n```bash\nmbs table inspect \\\n --doc-id \\\n --worksheet-name 'T14_财务规划引导' \\\n --table-id 46 \\\n --output json\n```\n\nThe second block must be looked up with `--table-id 47`; do not reuse `46` or\nassume that the first table's range extends through the second block. Table ids\nand ranges are runtime values, so always use the current `list-table` response\nfor the source workbook.\n\n## Evidence Requirements\n\nStore the following readbacks for each discovered table:\n\n1. The complete `table list` response.\n2. One `table inspect` response per `table_id`.\n3. One bounded `table sample` or range read per table.\n4. The raw-surface mapping showing the source range and table identity.\n\nThe multi-table case passes intake only when every selected table is either\nmapped to a raw surface or explicitly recorded as skipped with an owner,\nreason, and impact. A successful worksheet import by itself is insufficient\nevidence that every table block was captured.\n\nFile vv0.21.8:references/file-management.md\n\n# File Management Reference\n\n## Contents\n\n1. When to use this\n2. Basic conventions\n3. Engine selection\n4. Core file commands\n5. Sharing and permissions\n6. Recommended flows\n\n## 1. When to use this\n\nRead this document when the task involves uploading, importing, searching, copying, renaming, deleting, sharing, or exporting MaybeAI spreadsheets.\n\n## 2. Basic conventions\n\n- Base URL defaults to `https://a-play-be.maybeai.cn`\n- Auth comes from `MAYBEAI_API_TOKEN`\n- Most follow-up commands use `--doc-id ` or `--url `\n- `mbs workbook import` creates a new workbook from a local file or remote source; `mbs worksheet import --strategy create` imports worksheets into an existing workbook\n- `mbs workbook delete` uses the workbook lifecycle API and defaults to physical `purge`. Use `--mode mark --yes` only when the user explicitly asks for mark deletion, recovery, or 7-day retention, and use `--dry-run` before either destructive request.\n\n- After import succeeds, record:\n - `document_id`\n - `uri`\n\n## 3. Engine selection\n\nMaybeAI Sheet routes worksheets through either Sheet mode or Base mode:\n\n- `sheet` is the workbook-style mode for Excel layout, styles, formulas, merged cells, and workbook semantics.\n- `base` is the mode for large table-like data, SQL, large row counts, large cell counts, append/upsert, and Base-native reads/writes.\n\nBest practice:\n\n- Choose engine per worksheet for mixed workbooks; do not force the whole workbook to Base Mode just because one sheet is large.\n- Inspect the file structure and choose engines before creating a workbook.\n- Use `mbs workbook import ./file.xlsx --engine auto` when the backend should detect engines per worksheet.\n- Use `mbs workbook import \"https://static.example.com/file.xlsx\" --engine auto` to create a workbook from a remote Excel URL. This routes through `/api/v1/excel/import_by_url`; it does not append into an existing workbook.\n- Use comma-separated engines by worksheet index when the target is known, for example `--engine \"base,sheet,sheet,base\"`.\n- Use `mbs workbook import ./orders.csv --engine base` or a public Google Sheet URL with `--engine ...` for import-source flows.\n- Use `mbs worksheet import --strategy create --doc-id ` for an existing workbook. Omit `--source-worksheet-name` to import all previewed worksheets/tabs, repeat it to select multiple sources, and use `--target-worksheet-name` only for one selected source.\n- Prefer Base Mode for a worksheet when it has more than 5,000 rows and is one flat table whose data columns each have one datatype except the header and missing values. The older high-cell-count preference still applies when the data is one homogeneous table.\n- If the task depends on Sheet-specific workbook fidelity, use `sheet` for those worksheets.\n- Use Sheet mode for reports, summaries, dashboards, formulas, merged cells, styled workbooks, or worksheets with multiple separated tables. For example, `L1_广州瑞鹏_详细` in the LLM cost analysis workbook has two tables in one worksheet and should use Sheet mode.\n- A small single table such as `L1_客户集中度_帕累托` can use Base Mode or Sheet mode; auto may choose Sheet mode because the sheet is not large.\n- For chart-heavy dashboards, small flat `Data_*` worksheets may still need Base Mode because chart SQL will query them. Choose `base` for SQL source sheets and `sheet` for dashboard/cover/summary sheets; use an explicit engine list only when the worksheet order is known.\n- Explicit `--engine base` is strict. If the worksheet is not Base-compatible, expect an unsupported-layout import error. Use `--engine auto` when fallback to Sheet mode is acceptable.\n- Do not push large table data through row-object JSON writes; import the file with `engine=base` instead.\n- Base import owns datatype normalization during import. The CLI should only pass intent through `--engine`; parsing to same datatype should be enabled by backend default.\n- After import, verify the response top-level `engine`, plus per-worksheet `worksheet_engines` entries such as `worksheet_name`, `index`, `requested_engine`, `selected_engine`, `final_engine`, `fallback_reason`, `reason`, and datatype warnings/errors.\n- For import-source appends into existing workbooks, single-worksheet commits should expose `target.gid` and `target.worksheet_name`; multi-worksheet commits keep top-level `target` workbook-scoped, so inspect `result.worksheets`.\n- For raw Base-backed surface imports, target table names default to `R_{sanitized_worksheet_name}`. Omit `--source-worksheet-name` to import all source worksheets, or repeat it to select worksheets. Successful `worksheet import` stdout plus `--verify` is the creation evidence.\n- If shape confirmation is needed after a batch raw-surface import, resolve one representative table with `table inspect`, then sample it by `table_id`.\n- For Maybe Sheet-to-Maybe Sheet imports, use `--transfer-mode values` for Base raw surfaces or `--transfer-mode native` to preserve each source worksheet's registered engine and supported fidelity. Native transfer does not accept `--engine`.\n\n### Base preprocess contract\n\nDo not implement datatype detection or conversion inside `maybeai-sheet-cli`.\nFor Base-backed imports, the Base backend should preprocess worksheet columns before\nmaterializing them into the Base storage layer:\n\n- infer one target datatype per column from non-header values\n- allow empty cells and common missing-value markers such as `n/a`\n- coerce values that can safely convert to the inferred datatype\n- keep or report values that cannot convert instead of silently corrupting data\n- prefer Base Mode when a worksheet has more than 10,000 rows and the columns can be normalized\n\nWhen changing this behavior, update and test the Base backend source, then\nverify through the local routed runtime described in\n`/Users/dengwei/work/ai/maybeai-uni/docs/maybeai_sheet/debugging-runtime.md`:\n\n```bash\ncd \njust run\n\ncd /Users/dengwei/work/ai/maybeai-uni/mcp/maybeai-sheet-cli\nuv run mbs --base-url http://localhost:7011 workbook import ./mixed-workbook.xlsx --engine auto\nuv run mbs --base-url http://localhost:7011 workbook inspect --doc-id --output json\nuv run mbs --base-url http://localhost:7011 worksheet list --doc-id --output json\n```\n\nThe verification target is the routed path `mbs -> play-be -> Base backend`,\nnot a direct CLI-only unit test. Also use Base backend tests such as\n`go test -v ./...` and the composite router test asset referenced by\n`debugging-runtime.md` when the change affects engine selection or registry\nrouting.\n\n## 4. Core file commands\n\n### Delete a workbook\n\nUse the lifecycle command, not a legacy file-delete endpoint. Preview first,\nthen physically delete by default:\n\n```bash\nmbs workbook delete --doc-id --dry-run\nmbs workbook delete --doc-id --yes\n```\n\nOnly when the user explicitly wants a recoverable, 7-day deletion:\n\n```bash\nmbs workbook delete --doc-id --mode mark --yes\n```\n\n### Import a mixed workbook with engine autodetect\n\nUse autodetect first when the workbook has both table-like and Excel-layout worksheets:\n\n```bash\nmbs workbook import /absolute/path/to/file.xlsx --engine auto\n```\n\nExpected response should include the selected engine for each worksheet. If that\nfield is missing, run `mbs workbook inspect --doc-id --output json`\nand `mbs worksheet list --doc-id --output json`, then verify the\nreturned workbook and worksheet engine details.\n\n### Import a remote Excel URL into a new workbook\n\nPass a public HTTPS Excel URL as the positional source:\n\n```bash\nmbs workbook import \"https://static.example.com/imports/report.xlsx\" --engine auto\nmbs workbook import \"https://static.example.com/imports/report.xlsx\" --filename \"Board Pack.xlsx\" --engine sheet\nmbs workbook import \"https://static.example.com/download?id=123\" --source-type xlsx --filename report.xlsx --engine base\n```\n\nThis path calls `POST /api/v1/excel/import_by_url` with `file_url`, the resolved\n`filename`, and `engine`. `--filename` is optional. Resolution order is the\nexplicit option, the decoded URL path basename, then `upload.xlsx`.\n\nRemote Excel URL import only creates a new workbook. Do not combine it with\n`--doc-id`, `--url`, `--uri`, worksheet selection flags, `--preview-only`, or\n`--transfer-mode native`. Use exactly one of `sheet`, `base`, or `auto`; the remote\nroute does not support comma-separated per-worksheet engines. Explicit\n`excel` forwards the URL directly to the Excel import service. `auto` and\n`table` first download the workbook for worksheet planning before routing it\nto the selected engine, so their request cost includes that planning download.\n\n### Import CSV, TSV, or Google Sheet into a new workbook\n\nCSV/TSV uploads and public Google Sheet URLs use the import-source preview +\ncommit flow:\n\n```bash\nmbs workbook import ./orders.csv --engine base\nmbs workbook import ./orders.tsv --engine sheet\nmbs workbook import \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --engine base\nmbs workbook import \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --source-worksheet-name \"1店\" --worksheet-name \"Store 1\" --engine sheet\nmbs workbook import ./orders.csv --preview-only --output json\n```\n\nWhen no explicit source worksheet/tab is selected for a new workbook, the CLI\nsends `selections: []` and lets the backend import all previewed worksheets/tabs.\nWhen selecting one Google tab, prefer `--source-worksheet-name`; use\n`--candidate-id` only to disambiguate duplicate backend candidate ids.\n\n### Import local files or Google Sheet tabs into an existing workbook\n\nUse this when the target should gain a normal worksheet, not a raw `R_*`\nBase-backed surface:\n\n```bash\n# Omit --source-worksheet-name to import all previewed worksheets/tabs.\nmbs worksheet import --strategy create ./report.xlsx --doc-id --engine sheet\nmbs worksheet import --strategy create ./orders.csv --doc-id --engine base\nmbs worksheet import --strategy create \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --doc-id --engine sheet\n\n# Pass one --source-worksheet-name to import one source worksheet/tab, optionally renamed.\nmbs worksheet import --strategy create ./report.xlsx --doc-id --source-worksheet-name \"联盟\" --target-worksheet-name \"联盟导入\" --engine sheet\nmbs worksheet import --strategy create ./report.xlsx --doc-id --source-worksheet-name \"联盟\" --target-worksheet-name \"联盟导入\" --engine base\nmbs worksheet import --strategy create ./orders.csv --doc-id --source-worksheet-name orders --target-worksheet-name Orders --engine base\nmbs worksheet import --strategy create \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --doc-id --source-worksheet-name \"1店\" --target-worksheet-name \"Store 1\" --engine sheet\n\n# Repeat --source-worksheet-name to import multiple selected source worksheets/tabs.\nmbs worksheet import --strategy create ./report.xlsx --doc-id --source-worksheet-name \"联盟\" --source-worksheet-name \"订单\" --engine base\nmbs worksheet import --strategy create ./orders.tsv --doc-id --source-worksheet-name orders --source-worksheet-name refunds --engine base\nmbs worksheet import --strategy create \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --doc-id --source-worksheet-name \"1店\" --source-worksheet-name \"2店\" --engine sheet\n```\n\nFor Excel files, `--source-worksheet-name` is the source worksheet returned by\n`import_worksheet_preview`. For CSV/TSV/Google import sources, `--source-worksheet-name`\nselects the source worksheet/tab name from preview when importing into an\nexisting workbook. If any requested worksheet/tab does not exist, the CLI fails\nbefore commit/data import and prints the available worksheet names.\n`--target-worksheet-name` controls the new worksheet name in the target workbook\nand is only valid when exactly one source worksheet/tab is selected. If omitted,\nthe backend/CLI uses the source worksheet/tab's suggested worksheet name.\n\n### Replace data rows from JSON while keeping headers\n\nUse the unified worksheet import entry point for a full data refresh of one\nexisting worksheet:\n\n```bash\nmbs worksheet import ./rows.json \\\n --strategy replace \\\n --doc-id \\\n --worksheet-name Students \\\n --verify\n```\n\nThe JSON file must be a non-empty array of objects whose keys match the target\nworksheet headers. This strategy calls `/api/v1/excel/update_data_keep_headers`,\nkeeps row 1 and column order, preserves formula columns by default, and clears\nstale data rows. Use `--dry-run` for preflight validation; it cannot be combined\nwith `--verify`. JSON replace does not accept `--engine`, `--transfer-mode`, or\nsource worksheet selection options.\n\n### Natively import worksheets from another Maybe Sheet workbook\n\nUse this when the target should receive real worksheet copies rather than\nvalue-materialized `R_*` tables:\n\n```bash\n# Copy selected worksheets. Mixed Base Mode and Sheet mode selections are supported.\nmbs worksheet import \\\n --strategy create \\\n --transfer-mode native \\\n --doc-id \\\n --source-doc-id \\\n --source-worksheet-name \"工作表3\" \\\n --source-worksheet-name \"工作簿1\" \\\n --verify \\\n --output json\n\n# Copy every source worksheet.\nmbs worksheet import \\\n --strategy create \\\n --transfer-mode native \\\n --doc-id \\\n --source-doc-id \\\n --verify \\\n --output json\n```\n\nNative flow:\n\n1. Read source `/api/v1/excel_v2/worksheet/metadata` once.\n2. Validate repeated `--source-worksheet-name` values, or select all metadata items.\n3. Derive `base` or `sheet` from each worksheet's `data_engine`/source metadata.\n4. Call `/api/v1/excel/copy_worksheet` once per worksheet.\n5. With `--verify`, read target worksheet metadata once and verify final name,\n gid, and engine. The operation result also reports the copied `rows` count;\n use that count as the copy-completeness evidence for large Base worksheets.\n\nDo not pass `--engine`; it is selected internally per worksheet. Use\n`--target-worksheet-name` only for one selected worksheet. The backend may\nrename a conflict to `Name (2)`, and the CLI reports that final name. Empty\nworksheets are valid native copies. This mode supports Base Mode -> Base Mode and Sheet mode ->\nSheet mode only; a mixed logical workbook is allowed, but no worksheet is\nconverted between engines.\n\nNative copy uses the CLI HTTP timeout, which defaults to 30 seconds. For large\nworksheets, pass `--timeout 600`. If a timeout names a worksheet, do not rerun\nthe full batch immediately: the backend may still complete after the client\ndisconnects. Inspect target worksheet metadata/listing first, then retry only\nthe unconfirmed worksheet with explicit `--worksheet-name`. Use `--verbose` to\nprint the active worksheet index and engine before each copy.\n\n### Import source worksheets into raw Base-backed surfaces in another workbook\n\nUse `worksheet import --strategy create --transfer-mode values` for cross-workbook worksheet -> raw surface creation when\nthe target should become an `R_*`-style Base-backed table:\n\n```bash\nmbs worksheet import --strategy create --transfer-mode values --doc-id --source-doc-id --source-worksheet-name \"1店\" --verify\nmbs worksheet import --strategy create --transfer-mode values --doc-id --source-doc-id --source-worksheet-name \"1店\" --source-worksheet-name \"2店\" --verify\nmbs worksheet import --strategy create --transfer-mode values --doc-id --source-doc-id --verify\n```\n\nTarget table names default to `R_{sanitized_worksheet_name}`. If\n`--source-worksheet-name` is omitted, the CLI calls `/api/v1/excel_v2/worksheet/metadata`\nfor the source workbook and imports all returned worksheets. If multiple\n`--source-worksheet-name` values are provided, the CLI validates them against source\nmetadata before importing, so missing names fail before partial creation and\nprint the available worksheet names.\n\n`values` is the compatibility default, so existing commands may omit it. This\npath only accepts omitted or `--engine base`, reads source\n`FORMATTED_VALUE`, and does not preserve formulas or Sheet formatting.\n\nTreat successful stdout plus `--verify` as the creation proof. Do not follow\nthat with repeated per-table reads. If the workflow needs a quick shape check,\nresolve one representative table by name, then sample it by native ID:\n\n```bash\nmbs table inspect --doc-id --table-name R_OrderLines_Store1 --output json\nmbs table sample --doc-id --table-id --limit 2 --output table\n```\n\n### Import with explicit per-worksheet engines\n\nThe comma-separated list matches worksheet index order:\n\n```bash\nmbs workbook import /absolute/path/to/file.xlsx --engine \"base,sheet,sheet,base\"\n```\n\nUse this when worksheet 1 and 4 are Base-compatible flat tables but worksheet\n2 and 3 require Sheet workbook fidelity.\n\nFor dashboards, a common pattern is:\n\n```text\nCover, Dashboard -> sheet\nData_KPI, Data_Trend, Data_Platform, Data_Quarter -> base when flat and SQL queried\n```\n\nDo not guess this list from memory. Use an explicit list only when the source\nworksheet order is known; otherwise let `--engine auto` choose per worksheet.\n\n### Import a large table-like file into Base Mode\n\nUse the CLI first:\n\n```bash\nmbs workbook import /absolute/path/to/file.xlsx --engine base\n```\n\nIf an older installed CLI does not expose `--engine`, upgrade the CLI before importing large table files.\n\nExpected success shape:\n\n```json\n{\n \"success\": true,\n \"documentId\": \"\",\n \"fileUri\": \"https://www.maybe.ai/docs/spreadsheets/d/\",\n \"sheets\": [\"Sheet1\"]\n}\n```\n\nThen verify routing with the CLI:\n\n```bash\nmbs workbook inspect --doc-id --output json\nmbs worksheet list --doc-id --output json\n```\n\nConfirm the workbook inspection and per-worksheet list output report the intended Base-backed engine details.\n\n### Import a workbook-style file\n\nCLI:\n\n```bash\nmbs workbook import ./report.xlsx\n```\n\nUse this for Excel/workbook-style imports where layout, styles, formulas,\nmerged cells, or workbook fidelity matter more than table scale.\n\n### List or search files\n\nUse search when you need to find historical files by keyword.\n\nCLI:\n\n```bash\nmbs file list --limit 20\nmbs file search --query \"q2 forecast\" --limit 20\n```\n\n### Export\n\nGuidance:\n\n- Prefer `export` when you want the `.xlsx` file directly\n- Use `download` when you already have a `uri`\n\nCLI:\n\n```bash\nmbs workbook export --doc-id --out workbook.xlsx\n```\n\n### Copy a workbook\n\nUse workbook copy when you need a new editable document based on an existing\nworkbook. The backend should preserve worksheet engine topology when possible,\nso verify the copied workbook with `workbook inspect` and `worksheet list` before continuing.\n\n```bash\nmbs workbook copy --doc-id --title \"Copy of Workbook\"\nmbs workbook inspect --doc-id --output json\nmbs worksheet list --doc-id --output table\n```\n\n## 5. Sharing and permissions\n\nUse the `mbs share ...` commands in [permission-sharing.md](permission-sharing.md).\n\n## 6. Recommended flows\n\n### Bring a new file into the system\n\n1. Inspect approximate row count and workbook intent\n2. If sheets are mixed, use `mbs workbook import ./file.xlsx --engine auto`\n3. If all sheets are table-like and rows > 10,000, use `mbs workbook import ./file.xlsx --engine base`\n4. If worksheet engines are known, use `mbs workbook import ./file.xlsx --engine \"base,sheet,sheet\"`\n5. Otherwise use `mbs workbook import ./file.xlsx`\n6. Record `document_id` from JSON output\n7. `mbs workbook inspect --doc-id ` and `mbs worksheet list --doc-id `\n8. Sample only when needed for shape confirmation; use at most one representative `table sample` or `table sample` after resolving its table ID\n\n### Bring in a chart-heavy dashboard workbook\n\n1. Identify SQL source worksheets, usually flat `Data_*` tabs.\n2. Identify canvas/layout worksheets, usually `Dashboard`, cover, and summaries.\n3. Import with `--engine auto`, or use an explicit worksheet-index list such as `--engine \"sheet,base,base,sheet\"` when the source order is known.\n4. `mbs workbook inspect --doc-id ` and `mbs worksheet list --doc-id --output table`\n5. Verify source `Data_*` sheets report Base Mode when chart SQL will query them.\n\n### Bring a large table-like file into the system\n\n1. Use `mbs workbook import ./file.xlsx --engine base`\n2. Record `documentId` and `fileUri`\n3. Run `mbs workbook inspect --doc-id --output json` and\n `mbs worksheet list --doc-id --output json`.\n4. Confirm response top-level `engine` and per-worksheet `worksheet_engines`, or Base-backed engine details in the inspection/list output\n5. If needed, resolve `mbs table inspect --doc-id --table-name `, then use `mbs table sample --doc-id --table-id --limit 2 --output table`.\n\n### Batch raw-surface import with probe budget\n\n1. Prepare the family-level import plan or source list.\n2. Run `mbs workbook import ... --verify`.\n3. Treat successful stdout plus `--verify` as the creation evidence.\n4. Do not loop over each created table with native `schema`, `sample`, or `read` calls.\n5. If shape confirmation is needed, resolve and sample at most one representative Base table per family.\n\n### Export before delivery\n\n1. Finish all writes\n2. `mbs range read --output table` or `mbs table sample` on key ranges\n3. `mbs workbook export --doc-id --out workbook.xlsx`\n\n### Reuse a historical file\n\n1. `mbs file search --query \"\"`\n2. If copying is needed, use `mbs workbook copy --doc-id --title \"\"`\n3. Edit the selected workbook\n\nArchive vv0.21.7: 26 files, 62632 bytes\n\nFiles: agents/openai.yaml (1293b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (2699b), references/base-mode-verification.md (2776b), references/charts-formatting.md (18892b), references/cli-commands.md (10058b), references/cli-packaging-plan.md (703b), references/clickable-refs.md (5172b), references/engine-selection-when-create.md (4295b), references/errors-recovery.md (10709b), references/excelize-multiple-tables.md (3254b), references/file-management.md (22074b), references/formulas-sql.md (3322b), references/lineage-trace.md (4691b), references/permission-sharing.md (4528b), references/pivot-tables.md (4956b), references/read-write.md (4202b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (2574b), scripts/check_runtime_help_policy.py (2575b), scripts/sync_cli_release.py (4003b), skill-card.md (2916b), SKILL.md (28743b), todo.md (692b), _meta.json (138b)\n\nFile vv0.21.7:SKILL.md\n\n---\nversion: v0.21.7\nname: maybeai-sheet-cli\ndescription: Use when the user works with MaybeAI spreadsheets through the mbs CLI for workbook inspection, local or remote-URL file import, native cross-workbook import/export, worksheet/range/table writes, worksheet calculation and error scans, complete table/SQL reads with frame export, SQL-to-Base materialization, full worksheet data refreshes that keep headers, formulas, worksheet styling, chart/image CRUD, dashboard validate/refresh/export-template flows, or sharing. Route dashboard design and chart composition to `sheet-dashboard`.\nmetadata:\n cli_version: \"0.28.4\"\n openclaw:\n requires:\n env:\n - MAYBEAI_API_TOKEN\n primaryEnv: MAYBEAI_API_TOKEN\n emoji: \"📊\"\n homepage: https://github.com/OmniMCP-AI/maybeai-uni\nrequired_environment_variables:\n - name: MAYBEAI_API_TOKEN\n---\n\n# MaybeAI Sheet CLI\n\nExecute spreadsheet work through `mbs`, the console script from\n`maybeai-sheet-cli`. Use first-class object commands.\n\n## Target model gate\n\nBefore choosing a command, inspect the installed CLI rather than relying on a\ndocumented command map:\n\n```bash\nmbs --help\nmbs workbook --help\nmbs worksheet --help\nmbs --help\n```\n\nUse `mbs workbook inspect` to inspect the workbook and `mbs worksheet list` to\ndiscover worksheet identities. A worksheet name or `gid` is only a locator; it\ndoes not prove the target supports cells, ranges, or stable table records.\n\n| Target model | Required identity | Use | Do not use |\n|---|---|---|---|\n| Sheet grid | `worksheet_name` or `gid` | A1 ranges, cell formulas, worksheet calculation, row/column layout, cell notes | Base record/field selectors |\n| Sheet table | worksheet locator plus persistent `table_id` when multiple tables exist | table read/insert/update and table/row/column views | treating a scan-order table number as a stable ID |\n| Base table | `table_id` (or `table_name` for resolution), then `field_id`/`record_id` | typed records, Base field/column operations, Base Formula | A1/range writes, cell formulas, keep-headers refresh |\n| Worksheet SQL Config | SQL-config worksheet identity plus raw SQL | `mbs sql config`, preview, and materialization | a legacy SQL cell wrapper or cell Formula |\n\n## Canonical operation layer\n\nUse the public canonical groups (`workbook`, `worksheet`, `table`, `range`, `row`,\n`column`, and `formula`) for new work. They emit `contract_version: \"1.0\"` JSON with `ok`, `operation`,\n`target`, and either `result` or `error`; `--output table|yaml` only changes\nrendering. Mutations default to `--verify`; use `--dry-run` before a destructive\nor unfamiliar request and pass `--expected-revision`/`--idempotency-key` when\nthe workflow needs concurrency protection.\n\nCanonical target URIs are stable, redacted MaybeAI URLs:\n\n```text\nSheet worksheet: https://www.maybe.ai/docs/spreadsheets/d/?gid=\nSheet table: https://www.maybe.ai/docs/spreadsheets/d/?gid=&tid=\nBase table: https://www.maybe.ai/docs/spreadsheets/d/?tid=\nBase by name: https://www.maybe.ai/docs/spreadsheets/d/?table=\n```\n\n`--target` is accepted by canonical object operations and mutations. Use the\nruntime help output as the sole command-discovery contract; do not maintain or\ninfer a static command map from this skill.\n\nFor `sql query` and `sql preview`, a workbook target may include the worksheet\nselector `?table=`. The CLI resolves that selector first and\nthen sends the SQL request against the workbook target, so SQL still requires\na workbook URL rather than a Base-table `tid` target. Preserve the selector\nwhen the query is intended for one worksheet:\n\n```bash\nmbs sql query \\\n --target \"$WORKBOOK?table=Sheet6\" \\\n --sql-file result.sql \\\n --all \\\n --frame-out /tmp/query.parquet\n```\n\n### Runtime command discovery and compatibility policy\n\nRun `mbs --help` before selecting a top-level group, then run\n`mbs --help` before selecting its operation. The parent help lists the\npublic command surface that agents may generate. Consult the selected command's\n`--help` for required selectors and mutation flags.\n\nA command that remains directly callable but is absent from its parent help is a\nhidden compatibility command. Do **not** probe for, suggest, or generate it in\nnew workflows. If an existing integration explicitly names one, explain that it\nis compatibility-only and first look for a public workflow in the current help.\nIf no public command preserves the requested semantics, report the capability\ngap instead of silently composing a lossy substitute.\n\n`worksheet style` is public. When the user explicitly requests worksheet\nstyling, discover its supported nested operations with `mbs worksheet style\n--help`; do not duplicate a nested operation list in this skill.\n\n### Resource style commands and config aliases\n\nThe current public style operations are `worksheet style`, `table style`,\n`range style`, `row style`, and `column style`. Public resource-local config\ncommands are `worksheet config`, `table config`, `row config`, and `column\nconfig`. Use `range style` for a range; `range config` is compatibility-only and\nmust not be generated.\n\n```bash\nmbs worksheet config --target \"$SHEET\" --spec worksheet-config.json --verify\nmbs table config --target \"$SHEET_TABLE\" --section header --spec table-style.json --verify\nmbs range style --target \"$SHEET\" --range B2:D4 --spec range-style.json --verify\nmbs row config --target \"$SHEET\" --rows 2:4 --spec row-style.json --verify\n```\n\nUse `--scope entire-grid` only with `--yes` or `--dry-run`. `worksheet config`\nkeeps behavior separate from `--style-spec`; the style spec cannot be combined\nwith `--spec` or the worksheet behavior flags (`--freeze-*`, `--gridlines`, or\n`--zoom`). The `--zoom` flag is retained by the CLI but is currently rejected\nby the HTTP adapters as unsupported; do not rely on it for remote writes. Table\nstyles may target `all`, `header`, `body`, or `totals`. For\ncolumn styles, pass exactly one of `--columns` (Sheet) or `--field` (Base).\n\nFor `worksheet config --spec`, prefer the canonical nested schema:\n\n```json\n{\n \"layout\": {\n \"freeze\": {\"rows\": 1, \"columns\": 0},\n \"gridlines\": {\"visible\": false},\n \"zoom\": 110\n },\n \"filter\": {\n \"enabled\": true,\n \"range\": \"A1:H100\",\n \"conditions\": [{\"field_id\": \"col_status\", \"op\": \"in\", \"value\": [\"open\"]}]\n },\n \"view\": {\n \"id\": \"optional-view-id\",\n \"fields\": {\"order\": [\"col_status\"], \"hidden\": [\"col_internal\"]},\n \"sorts\": [{\"field_id\": \"col_status\", \"direction\": \"asc\"}]\n }\n}\n```\n\nThe CLI accepts legacy keys for compatibility but normalizes output to this\nshape. `layout.*` and `filter.range` are Sheet-only in the canonical model,\nbut the current HTTP Sheet adapters only implement `layout.freeze`,\n`layout.gridlines`, `filter.enabled`, and `filter.range`; `layout.headings` and\n`layout.zoom` are rejected as unsupported. `filter.conditions` and `view.*`\nare Base-only. For Base view configuration, use `--doc-id` plus `--table-id`\n(or a Base target URI), not a `gid`; a view ID is optional when saving a new\nview. Unsupported engine properties fail before mutation.\n\n### Column rename and resource style (`column.rename`, `column.style`)\n\n`column rename` changes one Sheet header or Base field name. Provide exactly one\nof `--column`, `--field`, or `--field-id`, plus required `--new-name`.\n\n```bash\n# Sheet/SheetTable: one A1 column; header row is 1-based and defaults to 1.\nmbs column rename --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" \\\n --column B --new-name \"Net Revenue\" --verify\n\n# Base: resolve a human-readable field or use its stable ID.\nmbs column rename --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" \\\n --field-id --new-name \"Net Amount\" --verify\n```\n\nIn the current CLI, `column config` is a command-name alias for\n`column style`, not a typed field-metadata editor. It requires `--spec` and\nexactly one style selector: `--columns` for a Sheet target or `--field` for a\nBase target. The alias still emits the `column.style` operation; it does not\naccept the older `--field-type`, `--required`, `--unique`, `--default`, or\n`--options` flags.\n\n```bash\nmbs column style --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" \\\n --columns B:D --spec column-style.json --verify\nmbs column config --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" \\\n --field amount --spec column-style.json --verify\n```\n\nFor Base schema changes, use only the public commands shown by `mbs column\n--help`, such as `column insert` and `column rename`. `column config` is a style\noperation, not a typed field-metadata editor. If a requested Base field property\nis not exposed by a public command, report a capability gap; do not generate the\nhidden `column batch-update` compatibility command.\n\nUse `formula set`, `formula validate`, `formula calculate`, and `formula\nrecalculate` according to their runtime help. Do not generate the hidden\n`formula compile` or `formula batch-set` compatibility commands.\n\nDo not infer the model from a worksheet's name, a compatibility alias, or its\nvisual appearance. If inspection does not return an engine and Base identity,\nstop before a mutation and obtain the required target details through the public inspection/list workflow. The public Base surface is\n`mbs table`, `row`, `column`, and `formula` with a Base target. Do not\nsubstitute an A1/range or keep-headers command for a Base record write.\n\nFor local `.xls` / `.xlsx` imports, choose the engine per worksheet when a\nworkbook mixes large table-like sheets and Excel-layout sheets. The workbook\nimport commands support `--engine auto`, `--engine base`, and\ncomma-separated worksheet engine lists. CSV/TSV files and public Google Sheet\nURLs use the import-source preview flow and can import as a new workbook or\nappend all or selected worksheets/tabs to an existing workbook. Remote HTTPS\nExcel URLs create a new workbook through `/api/v1/excel/import_by_url`.\nTo migrate one existing Sheet-backed worksheet to Base, use the guarded\n`worksheet convert-to-base` workflow below; it is a one-way data migration,\nnot an import-engine setting.\n\n**Prerequisites:** `MAYBEAI_API_TOKEN`, `mbs` (`pip install maybeai-sheet-cli`)\n\n**Delegated subagent rule.** For a delegated MaybeAI task, use `terminal` first:\n`mbs --version` and `test -n \"$MAYBEAI_API_TOKEN\"`. Do not infer missing mbs,\nterminal, or token from old files, logs, or JSON artifacts. Only report a\nmissing token when that command actually shows it is absent.\n\n**CLI 0.28 compatibility boundaries.** Generate only the public command\nsurface for new workflows:\n\n- Use `mbs worksheet …`, never `mbs excel_worksheet …`; the underscore\n alias was removed.\n- Use `mbs range lineage --target --range `;\n `range lineage --cell` was removed.\n- Use `mbs worksheet beautify`, `mbs worksheet config`, or resource-local\n `range`, `row`, `column`, and `table` style commands for styling.\n- `mbs worksheet beautify` defaults to `--layout auto`: it keeps ordinary\n column tables on the field-by-column path, including date columns. It selects\n a pivot/report only after finding at least two concrete horizontal members\n (for example, `1店`/`2店`, `Store A`/`Store B`, or `Q1`/`Q2`); generic names\n such as `日期` or `门店`, and a lone `合计`/`Total`, are not pivot evidence.\n For a pivot/report, the first column of the target range is treated as row\n labels (text or numeric codes) and each value row is formatted from its\n label: `毛利率` is percent while `毛利-CNY` is currency. Use dry-run before\n applying, and pass `--layout table` or `--layout pivot` only when an explicit\n override is needed.\n- Use `mbs range note read|set|clear`, not the removed nested\n `mbs cell note read|set|clear` commands. `read` accepts an A1 range; `set`\n and `clear` currently require one A1 cell.\n\n## Quick start\n\n```bash\n# Discover the installed public surface and target identity first.\nmbs --help\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output json\nmbs table list --doc-id --output json\n\n# Read a bounded preview. Omitting --limit requests 1000 rows.\nmbs range read --target \"$SHEET\" --range A1:D20 --output table\nmbs table read --target \"$BASE_TABLE\" --limit 100 --output table\n\n# Export every page to one local frame; use backend ordering when available.\nmbs table read --target \"$BASE_TABLE\" --all --order-by order_id --frame-out /tmp/orders.parquet\n\n# Public writes use explicit frames/keys and verification.\nmbs table insert --target \"$BASE_TABLE\" --frame-in rows.json --verify\nmbs table update --target \"$BASE_TABLE\" --frame-in corrected_rows.json --key order_id --verify\nmbs formula set --target \"$SHEET\" --cell E2 --expression '=SUM(B2:D2)' --verify\nmbs range note set --target \"$SHEET\" --range B2 --text \"Reviewed\" --verify\n\n# Current public worksheet and SQL operations.\nmbs worksheet calculate --target \"$SHEET\" --verify\nmbs worksheet check-error --target \"$SHEET\" --range A1:Z100\nmbs sql query --target \"$WORKBOOK?table=Sheet6\" --sql-file result.sql --all --frame-out /tmp/query.parquet\nmbs sql materialize --target \"$BASE_TABLE\" --sql-file result.sql --mode create --schema schema.json --verify\n```\n\nAll public `table create` source variants use the canonical operation\n`table.create`, including frame, SQL-query, and worksheet-range creation.\nAdapters must not expect `table.create-from-query` or\n`table.create-from-range` in the response envelope.\n\nWhole-table replacement does not have an automatic public-command substitute.\nDo not rewrite it as a sequence of destructive calls without confirming the\nchanged semantics. For an in-place batch update of existing Base field schema,\nuse public `mbs column batch-update` only after inspecting its installed help;\nit is not a substitute for a whole-schema replacement, field deletion, or data\nmigration.\n\n## Execution order\n\n1. Run `mbs --version` and `mbs --help` once at the start of a session; trust the local CLI over remembered examples.\n2. `mbs --help` when flags are unclear.\n3. [references/cli-commands.md](references/cli-commands.md) for runtime-help-first operational guidance.\n4. Topic reference below for semantics, edge cases, and uncovered CLI gaps.\n\n## Critical rules\n\n- **Runtime help is authoritative.** Use the public groups and commands listed\n by `mbs --help` and the relevant parent `--help`; do not hard-code a full\n command map here.\n- **Model before mutation.** Inspect the workbook and list worksheets before\n choosing Sheet-range, table-record, Base-field, or SQL workflows.\n- **No hidden compatibility generation.** Never generate an operation absent\n from parent help for a new workflow, including old `excel-*`, `base-table`,\n `db-table`, `sheet`, top-level `style`, `worksheet image`, and nested\n `cell note` entry points.\n- **Formula and notes.** Use `formula set` for formula writes and `range note\n read|set|clear` for Sheet notes. `range lineage` takes `--range`, not `--cell`.\n- **Workbook deletion lifecycle.** When the user asks to delete a workbook but\n does not explicitly request a recoverable deletion, use\n `mbs workbook delete --yes`; the CLI defaults to physical `purge`. Run the\n corresponding `--dry-run` first. Use\n `--mode mark --yes` only when the user explicitly asks for mark deletion,\n recovery, or 7-day retention. Both modes use the workbook lifecycle API;\n never use the legacy file-delete route.\n- **Clear versus replace.** Use public `table clear --target \"$BASE_TABLE\" --yes --verify`\n to remove all Base records while preserving fields/schema; use `--dry-run`\n before destructive execution. `table insert` and `table update` do not\n provide atomic whole-table replacement semantics. Use\n `column batch-update` for a supported in-place batch update of existing Base\n field metadata; resource style config alone does not imply that capability.\n- **Verification.** Use `--dry-run` before destructive or unfamiliar writes;\n preserve `--expected-revision`/`--idempotency-key` when required; use\n `--verify` and target-appropriate readback after mutation.\n- **Base inspection.** `table inspect` addresses one Base table by `tid` or\n `table` name. Its canonical result may include matched worksheet dimensions;\n use `table schema` and `table read` for fields and records.\n- **Complete table reads.** `table read` defaults to 1000 rows (maximum\n 5000), so a command without `--all` is only a bounded read. Use `--all`\n with `--frame-out` for a complete export. The CLI follows a cursor or, when\n the backend returns `has_more: true` without one, advances by the page's\n actual record count. A full page with no cursor, `has_more`, total, or\n completion proof is a `backend.pagination_contract` error, not a completed\n export. See [references/cli-commands.md](references/cli-commands.md).\n- **Images and SQL.** Use `mbs image` for public image operations. Use `sql\n materialize` for public Base-table materialization and `sql config` /\n `sql overwrite` only when their runtime help matches the requested target.\n\n## Task routing\n\n| Task | Start here |\n|------|------------|\n| Command flags and examples | [references/cli-commands.md](references/cli-commands.md) |\n| Read/write targeting and API choice | [references/read-write.md](references/read-write.md) |\n| Base record/field/formula verification | [references/base-mode-verification.md](references/base-mode-verification.md) |\n| Upload, export, sharing | [references/file-management.md](references/file-management.md) |\n| Workbook semantic overview | [references/workbook-profile.md](references/workbook-profile.md) |\n| Sharing and permissions | [references/permission-sharing.md](references/permission-sharing.md) |\n| Formulas and SQL result sheets | [references/formulas-sql.md](references/formulas-sql.md) |\n| Pivot tables and pivot config specs | [references/pivot-tables.md](references/pivot-tables.md) |\n| Formula dependency tracing | [references/lineage-trace.md](references/lineage-trace.md) |\n| Charts, images, dashboards, worksheet styling | [references/charts-formatting.md](references/charts-formatting.md) |\n| Merge/unmerge cells, cell notes, Base record notes | [references/charts-formatting.md](references/charts-formatting.md) |\n| Sharing and permissions | [references/permission-sharing.md](references/permission-sharing.md) |\n| Failures and recovery | [references/errors-recovery.md](references/errors-recovery.md) |\n| Clickable cell refs in answers | [references/clickable-refs.md](references/clickable-refs.md) |\n| Legacy SQL formula migration/showcase | [references/sql-formula-showcase.md](references/sql-formula-showcase.md) |\n\n## Workflows\n\n### Inspect a workbook\n\n```\n- [ ] `mbs workbook inspect` and `mbs worksheet list`\n- [ ] identify worksheet name, table id, or Base table name\n- [ ] read sample with --output table\n```\n\n```bash\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output table\nmbs range read --doc-id --worksheet-name --output table\nmbs range read --doc-id --worksheet-name --range A1:D20 --output table\n```\n\n### Delete a workbook\n\nThe `mbs` command defaults to physical `purge`, reclaiming the workbook's\nstorage unless the user explicitly requests recoverability. Inspect the target\nand preview the physical deletion before sending it:\n\n```bash\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs workbook delete --target \"$WORKBOOK\" --dry-run\nmbs workbook delete --target \"$WORKBOOK\" --yes\n```\n\nUse a mark deletion only when the user explicitly wants the 7-day recovery\nwindow:\n\n```bash\nmbs workbook delete --target \"$WORKBOOK\" --mode mark --yes\n```\n\n### Upload and inspect\n\n```\n- [ ] workbook import\n- [ ] capture document_id from JSON output\n- [ ] use import stdout plus `--verify` as creation evidence\n- [ ] if needed, resolve and sample one representative Base table per family\n```\n\n```bash\n# Small workbook-style files\nmbs workbook import ./file.xlsx --verify\nmbs workbook import ./orders.csv --engine base\nmbs workbook import \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --engine sheet\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output table\n\n# Large table-like files\nmbs workbook import ./file.xlsx --engine base --verify\nmbs table inspect --doc-id --table-name --output json\nmbs table sample --doc-id --table-id --limit 2 --output table\n\n# Cross-workbook worksheet -> raw Base-backed surface import\nmbs worksheet import --strategy create --doc-id --source-doc-id --source-worksheet-name \"1店\" --verify\nmbs worksheet import --strategy create --doc-id --source-doc-id --source-worksheet-name \"1店\" --source-worksheet-name \"2店\" --verify\n\n# Sheet only: replace existing worksheet rows from JSON while keeping headers.\n# For Base records, use public `mbs table insert` / `mbs table update` after checking their help.\nmbs worksheet import ./rows.json --strategy replace --doc-id --worksheet-name Students --verify\n\n# Native Maybe Sheet worksheet import; engine is detected per worksheet\nmbs worksheet import --strategy create --transfer-mode native --doc-id --source-doc-id --source-worksheet-name \"工作表3\" --source-worksheet-name \"工作簿1\" --verify\nmbs worksheet import --strategy create --transfer-mode native --doc-id --source-doc-id --verify\n\n# Append source worksheets/tabs into an existing workbook\nmbs worksheet import ./file.xlsx --strategy create --doc-id --engine sheet --verify\nmbs worksheet import ./file.xlsx --strategy create --doc-id --source-worksheet-name \"联盟\" --target-worksheet-name \"联盟导入\" --engine sheet --verify\nmbs worksheet import ./file.xlsx --strategy create --doc-id --source-worksheet-name \"联盟\" --source-worksheet-name \"订单\" --engine base --verify\nmbs worksheet import ./orders.csv --strategy create --doc-id --engine base --verify\nmbs worksheet import \"https://docs.google.com/spreadsheets/d//edit#gid=0\" --strategy create --doc-id --source-worksheet-name \"1店\" --target-worksheet-name \"Store 1\" --engine sheet --verify\n```\n\nDo not follow successful raw-surface imports with per-table `schema` / `sample` / `read` loops. See [references/file-management.md](references/file-management.md) for engine choice and Base Mode verification.\n\n### Convert a worksheet to Base\n\n```\n- [ ] inspect `worksheet list` and select exactly one Sheet-backed worksheet\n- [ ] run `convert-to-base --dry-run` with `--gid` or `--worksheet-name`\n- [ ] execute the reviewed conversion with `--yes --verify`\n- [ ] retain old Sheet-engine source cells only when explicitly requested\n```\n\n```bash\n# The workbook URL can provide both document ID and gid.\nmbs worksheet convert-to-base \\\n --url \"https://www.maybe.ai/docs/spreadsheets/d/?gid=\" \\\n --dry-run\n\n# Execute after reviewing the dry run. Source cells are scrubbed by default.\nmbs worksheet convert-to-base \\\n --doc-id \\\n --worksheet-name Orders \\\n --yes \\\n --verify\n\n# Keep the prior Sheet-engine cell content only when required.\nmbs worksheet convert-to-base \\\n --doc-id \\\n --gid \\\n --keep-sheet-source \\\n --yes \\\n --verify\n```\n\nUse `--recalculate` when the converted Base worksheet should recalculate\nimmediately. Do not combine `--dry-run` with `--verify`. The command checks\nmetadata during `--verify` and succeeds only when the selected worksheet\nreports `data_engine: base`.\n\n### Dashboard execution\n\n```\n- [ ] `mbs --version` and relevant `--help`\n- [ ] import with `--engine auto` or an explicit worksheet-index engine list\n- [ ] `worksheet list` verifies Data_* Base Mode and Dashboard/summary Sheet mode where intended\n- [ ] `dashboard validate --spec dashboard.json`\n- [ ] `dashboard refresh --dry-run` checks payload shape before mutation\n- [ ] execute `dashboard refresh`; if batch errors persist, use per-chart `chart create-config`\n- [ ] `dashboard manifest` and `chart list` verify persisted metadata\n- [ ] read source Data_* sheets and run browser/vision verification when logged-in canvas access exists\n```\n\nSee [references/charts-formatting.md](references/charts-formatting.md) for chart spec shapes, fallback, and verification limits.\n\n### Dashboard template export\n\nUse this only when the user wants to promote an existing Maybe Sheet HTML dashboard worksheet into a reusable template package. The dashboard canvas must be a `sheet` worksheet, and the worksheet should contain exactly one persisted `chart.type=html` dashboard chart unless `--chart-id` or `--cell` is provided.\n\n```bash\nmbs dashboard export-template \\\n --doc-id \\\n --worksheet-name \\\n --template-id \\\n --out-dir /dashboard-templates/ \\\n --force\n```\n\nThe command writes `template.json`, `html/dashboard.template.html`, and `html/runtime-payload.schema.json`. After export, switch to `analysis-style-system` and run `node scripts/validate_dashboard_html_template.mjs --template-dir dashboard-templates/` before using or publishing the template skill.\n\n### Sync rows by key\n\nChoose the model first. For a Base table, use public `table update` with a\nstable key and an explicit input frame. The public command surface has no\ngeneric Sheet key-merge primitive: reconcile the data before a `range write`,\nor report the capability gap rather than invoking a hidden Sheet upsert alias.\n\n```\n- [ ] inspect workbook and worksheet identities\n- [ ] confirm the stable Base record key, or explicitly approve Sheet overwrite semantics\n- [ ] use `table update --key ...` only for a Base/table target\n- [ ] recalculate Sheet formulas if downstream formulas exist\n- [ ] read back the target\n```\n\n```bash\nmbs formula recalculate --doc-id --worksheet-name \n```\n\n### SQL result sheet\n\n```\n- [ ] headers + read sample on source sheet\n- [ ] save raw SQL with `mbs sql config set`\n- [ ] use `mbs sql materialize` for a public Base-table materialization, or `mbs sql overwrite` only when the target is a SQL-config worksheet\n- [ ] read the materialized target\n- [ ] scan the worksheet with `range inspect`\n```\n\nSee [references/formulas-sql.md](references/formulas-sql.md).\n\n### Pivot table\n\n```\n- [ ] inspect source worksheet headers\n- [ ] author `pivot-config.json`\n- [ ] preview pivot output\n- [ ] upsert with explicit target worksheet and anchor cell\n- [ ] read target range to verify\n```\n\n```bash\nmbs pivot preview --doc-id --worksheet-name --spec pivot-config.json --output table\nmbs pivot upsert --doc-id --target-worksheet-name PivotResult --anchor-cell A1 --spec pivot-config.json\nmbs range read --doc-id --worksheet-name PivotResult --range A1:H30 --output table\n```\n\nSee [references/pivot-tables.md](references/pivot-tables.md).\n\n### Trace formula lineage\n\n```bash\nmbs formula lineage --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=\" --cell E2 --format tree --output yaml\n```\n\nSee [references/lineage-trace.md](references/lineage-trace.md) for response interpretation.\n\n### Share or check access\n\n```bash\nmbs share perm\n\nArchive vv0.21.6: 23 files, 57704 bytes\n\nFiles: agents/openai.yaml (1293b), README.md (2699b), references/base-mode-verification.md (2776b), references/charts-formatting.md (18892b), references/cli-commands.md (7774b), references/cli-packaging-plan.md (703b), references/clickable-refs.md (5172b), references/engine-selection-when-create.md (4295b), references/errors-recovery.md (10709b), references/excelize-multiple-tables.md (3254b), references/file-management.md (22074b), references/formulas-sql.md (3322b), references/lineage-trace.md (4691b), references/permission-sharing.md (4528b), references/pivot-tables.md (4956b), references/read-write.md (4202b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (2574b), scripts/check_runtime_help_policy.py (2575b), scripts/sync_cli_release.py (4003b), skill-card.md (3329b), SKILL.md (28010b), _meta.json (138b)\n\nArchive vv0.21.5: 26 files, 61236 bytes\n\nFiles: agents/openai.yaml (1293b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (2699b), references/base-mode-verification.md (2776b), references/charts-formatting.md (18892b), references/cli-commands.md (7774b), references/cli-packaging-plan.md (703b), references/clickable-refs.md (5172b), references/engine-selection-when-create.md (4295b), references/errors-recovery.md (10709b), references/excelize-multiple-tables.md (3254b), references/file-management.md (22201b), references/formulas-sql.md (3322b), references/lineage-trace.md (4691b), references/permission-sharing.md (4528b), references/pivot-tables.md (4956b), references/read-write.md (4202b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (2574b), scripts/check_runtime_help_policy.py (2575b), scripts/sync_cli_release.py (4003b), skill-card.md (2664b), SKILL.md (28064b), todo.md (692b), _meta.json (138b)\n\nArchive vv0.21.4: 26 files, 60697 bytes\n\nFiles: agents/openai.yaml (1293b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (2699b), references/base-mode-verification.md (2776b), references/charts-formatting.md (18892b), references/cli-commands.md (7774b), references/cli-packaging-plan.md (703b), references/clickable-refs.md (5172b), references/engine-selection-when-create.md (4295b), references/errors-recovery.md (10709b), references/excelize-multiple-tables.md (3254b), references/file-management.md (21555b), references/formulas-sql.md (3322b), references/lineage-trace.md (4691b), references/permission-sharing.md (4528b), references/pivot-tables.md (4956b), references/read-write.md (4202b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (2574b), scripts/check_runtime_help_policy.py (2575b), scripts/sync_cli_release.py (4003b), skill-card.md (2715b), SKILL.md (27025b), todo.md (692b), _meta.json (138b)\n\nArchive vv0.21.3: 23 files, 56849 bytes\n\nFiles: agents/openai.yaml (1293b), README.md (2553b), references/base-mode-verification.md (2776b), references/charts-formatting.md (18892b), references/cli-commands.md (7656b), references/cli-packaging-plan.md (703b), references/clickable-refs.md (5172b), references/engine-selection-when-create.md (4275b), references/errors-recovery.md (10709b), references/excelize-multiple-tables.md (3254b), references/file-management.md (21555b), references/formulas-sql.md (3322b), references/lineage-trace.md (4691b), references/permission-sharing.md (4528b), references/pivot-tables.md (4956b), references/read-write.md (4202b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (2574b), scripts/check_runtime_help_policy.py (2575b), scripts/sync_cli_release.py (4003b), skill-card.md (2794b), SKILL.md (26883b), _meta.json (138b)\n\nArchive v0.21.2: 26 files, 58666 bytes\n\nFiles: agents/openai.yaml (1293b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (2553b), references/base-mode-verification.md (2776b), references/charts-formatting.md (18892b), references/cli-commands.md (5814b), references/cli-packaging-plan.md (703b), references/clickable-refs.md (5172b), references/engine-selection-when-create.md (4067b), references/errors-recovery.md (10709b), references/excelize-multiple-tables.md (3254b), references/file-management.md (21555b), references/formulas-sql.md (2867b), references/lineage-trace.md (4691b), references/permission-sharing.md (4528b), references/pivot-tables.md (4956b), references/read-write.md (3439b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (2574b), scripts/check_runtime_help_policy.py (2575b), scripts/sync_cli_release.py (4003b), skill-card.md (2866b), SKILL.md (25507b), todo.md (692b), _meta.json (137b)\n\nArchive v0.21.1: 25 files, 86520 bytes\n\nFiles: agents/openai.yaml (1293b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (2306b), references/base-mode-verification.md (5562b), references/charts-formatting.md (19704b), references/cli-commands.md (47221b), references/cli-packaging-plan.md (8172b), references/clickable-refs.md (5166b), references/engine-selection-when-create.md (3304b), references/errors-recovery.md (10655b), references/excelize-multiple-tables.md (3254b), references/file-management.md (21169b), references/formulas-sql.md (8184b), references/lineage-trace.md (3781b), references/permission-sharing.md (4166b), references/pivot-tables.md (4933b), references/read-write.md (22812b), references/sql-formula-showcase.md (1813b), references/workbook-profile.md (3661b), scripts/sync_cli_release.py (4003b), skill-card.md (3319b), SKILL.md (48367b), todo.md (692b), _meta.json (137b)\n\nArchive v0.21.0: 25 files, 86751 bytes\n\nFiles: agents/openai.yaml (1434b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (2312b), references/base-mode-verification.md (5816b), references/charts-formatting.md (20316b), references/cli-commands.md (48810b), references/cli-packaging-plan.md (8172b), references/clickable-refs.md (5166b), references/engine-selection-when-create.md (3367b), references/errors-recovery.md (10833b), references/excelize-multiple-tables.md (3325b), references/file-management.md (21230b), references/formulas-sql.md (8311b), references/lineage-trace.md (3683b), references/permission-sharing.md (4166b), references/pivot-tables.md (4953b), references/read-write.md (23976b), references/sql-formula-showcase.md (1795b), references/workbook-profile.md (3710b), scripts/sync_cli_release.py (4003b), skill-card.md (2911b), SKILL.md (49621b), todo.md (692b), _meta.json (137b)\n\nArchive v0.20.6: 25 files, 78736 bytes\n\nFiles: agents/openai.yaml (1434b), artifacts/build_sql_demo_dataset.py (9995b), artifacts/pivot-config.json (433b), README.md (1839b), references/base-mode-verification.md (5264b), references/charts-formatting.md (17128b), references/cli-commands.md (38607b), references/cli-packaging-plan.md (8172b), references/clickable-refs.md (5166b), references/engine-selection-when-create.md (3157b), references/errors-recovery.md (9907b), references/excelize-multiple-tables.md (3325b), references/file-management.md (21230b), references/formulas-sql.md (8240b), references/lineage-trace.md (3905b), references/permission-sharing.md (4166b), references/pivot-tables.md (4953b), references/read-write.md (22893b), references/sql-formula-showcase.md (1795b), references/workbook-profile.md (3670b), scripts/sync_cli_release.py (3829b), skill-card.md (2914b), SKILL.md (39749b), todo.md (692b), _meta.json (137b)","readmeExcerpt":"Skill: Maybeai Sheet Cli Skill Owner: no7dw Summary: Inspect, import, edit, dashboard, template, and share MaybeAI spreadsheets Tags: latest:v0.21.8, latest=v0.21.5:v0.21.5, latest=v0.21.7:v0.21.7, latest=v0.21.8:v0.21.8 Version history: vv0.21.8 | 2026-09-14T04:12:08.081Z | user Release v0.21.8 vv0.21.7 | 2026-09-02T11:50:40.306Z | user Release v0.21.7 vv0.21.6 | 2026-09-01T10:57:45.724Z | user feat: 对接定时删除过期workboo","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"mbs --help\nmbs workbook --help\nmbs worksheet --help\nmbs --help"},{"language":"text","snippet":"Sheet worksheet: https://www.maybe.ai/docs/spreadsheets/d/?gid=\nSheet table: https://www.maybe.ai/docs/spreadsheets/d/?gid=&tid=\nBase table: https://www.maybe.ai/docs/spreadsheets/d/?tid=\nBase by name: https://www.maybe.ai/docs/spreadsheets/d/?table="},{"language":"bash","snippet":"mbs sql query \\\n --target \"$WORKBOOK?table=Sheet6\" \\\n --sql-file result.sql \\\n --all \\\n --frame-out /tmp/query.parquet"},{"language":"bash","snippet":"mbs worksheet config --target \"$SHEET\" --spec worksheet-config.json --verify\nmbs table config --target \"$SHEET_TABLE\" --section header --spec table-style.json --verify\nmbs range style --target \"$SHEET\" --range B2:D4 --spec range-style.json --verify\nmbs row config --target \"$SHEET\" --rows 2:4 --spec row-style.json --verify"},{"language":"json","snippet":"{\n \"layout\": {\n \"freeze\": {\"rows\": 1, \"columns\": 0},\n \"gridlines\": {\"visible\": false},\n \"zoom\": 110\n },\n \"filter\": {\n \"enabled\": true,\n \"range\": \"A1:H100\",\n \"conditions\": [{\"field_id\": \"col_status\", \"op\": \"in\", \"value\": [\"open\"]}]\n },\n \"view\": {\n \"id\": \"optional-view-id\",\n \"fields\": {\"order\": [\"col_status\"], \"hidden\": [\"col_internal\"]},\n \"sorts\": [{\"field_id\": \"col_status\", \"direction\": \"asc\"}]\n }\n}"},{"language":"bash","snippet":"# Sheet/SheetTable: one A1 column; header row is 1-based and defaults to 1.\nmbs column rename --target \"https://www.maybe.ai/docs/spreadsheets/d/?gid=0\" \\\n --column B --new-name \"Net Revenue\" --verify\n\n# Base: resolve a human-readable field or use its stable ID.\nmbs column rename --target \"https://www.maybe.ai/docs/spreadsheets/d/?tid=\" \\\n --field-id --new-name \"Net Amount\" --verify"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nversion: v0.21.8\nname: maybeai-sheet-cli\ndescription: Use when the user works with MaybeAI spreadsheets through the mbs CLI for workbook inspection, local or remote-URL file import, native cross-workbook import/export, worksheet/range/table writes, worksheet calculation and error scans, complete table/SQL reads with frame export, SQL-to-Base materialization, full worksheet data refreshes that keep headers, formulas, worksheet styling, chart/image CRUD, dashboard validate/refresh/export-template flows, or sharing. Route dashboard design and chart composition to `sheet-dashboard`.\nmetadata:\n cli_version: \"0.28.4\"\n openclaw:\n requires:\n env:\n - MAYBEAI_API_TOKEN\n primaryEnv: MAYBEAI_API_TOKEN\n emoji: \"📊\"\n homepage: https://github.com/OmniMCP-AI/maybeai-uni\nrequired_environment_variables:\n - name: MAYBEAI_API_TOKEN\n---\n\n# MaybeAI Sheet CLI\n\nExecute spreadsheet work through `mbs`, the console script from\n`maybeai-sheet-cli`. Use first-class object commands.\n\n## Target model gate\n\nBefore choosing a command, inspect the installed CLI rather than relying on a\ndocumented command map:\n\n```bash\nmbs --help\nmbs workbook --help\nmbs worksheet --help\nmbs --help\n```\n\nUse `mbs workbook inspect` to inspect the workbook and `mbs worksheet list` to\ndiscover worksheet identities. A worksheet name or `gid` is only a locator; it\ndoes not prove the target supports cells, ranges, or stable table records.\n\n| Target model | Required identity | Use | Do not use |\n|---|---|---|---|\n| Sheet grid | `worksheet_name` or `gid` | A1 ranges, cell formulas, worksheet calculation, row/column layout, cell notes | Base record/field selectors |\n| Sheet table | worksheet locator plus persistent `table_id` when multiple tables exist | table read/insert/update and table/row/column views | treating a scan-order table number as a stable ID |\n| Base table | `table_id` (or `table_name` for resolution), then `field_id`/`record_id` | typed records, Base field/column operations, Base Formula | A1/range writes, cell formulas, keep-headers refresh |\n| Worksheet SQL Config | SQL-config worksheet identity plus raw SQL | `mbs sql config`, preview, and materialization | a legacy SQL cell wrapper or cell Formula |\n\n## Canonical operation layer\n\nUse the public canonical groups (`workbook`, `worksheet`, `table`, `range`, `row`,\n`column`, and `formula`) for new work. They emit `contract_version: \"1.0\"` JSON with `ok`, `operation`,\n`target`, and either `result` or `error`; `--output table|yaml` only changes\nrendering. Mutations default to `--verify`; use `--dry-run` before a destructive\nor unfamiliar request and pass `--expected-revision`/`--idempotency-key` when\nthe workflow needs concurrency protection.\n\nCanonical target URIs are stable, redacted MaybeAI URLs:\n\n```text\nSheet worksheet: https://www.maybe.ai/docs/spreadsheets/d/?gid=\nSheet table: https://www.maybe.ai/docs/spreadsheets/d/?gid=&tid=\nBase tab"},{"path":"README.md","content":"# maybeai-sheet-cli-skill\n\nAgent skill for the `mbs` CLI from `maybeai-sheet-cli` **0.28.0**.\n\nThe installed CLI's runtime help is the command contract. Start a spreadsheet\nsession with:\n\n```bash\nmbs --help\nmbs --help\nmbs --help\n```\n\nThe parent `--help` output identifies commands that agents may generate in new\nworkflows. A directly callable command missing from that output is a hidden\ncompatibility command: do not recommend or generate it. If public commands\ncannot preserve the requested behavior, explain the capability gap instead of\nconstructing a destructive approximation.\n\nThis skill provides model-routing guidance for Sheet, SheetTable, Base, and SQL\nworkflows; safe mutation and verification practices; and topic references for\nimports, reads/writes, formulas, charts, sharing, recovery, and lineage. It\nintentionally does **not** duplicate a complete CLI command tree. Consult the\ninstalled command help for available groups, operations, parameters, and\nfeature changes.\n\nNotable public-workflow boundaries:\n\n- Use `workbook inspect` and `worksheet list` for target discovery.\n- Use `formula set` for formula writes and `range note` for Sheet notes.\n- Use `mbs image` for image operations.\n- Use public `mbs table clear --target \"$BASE_TABLE\" --yes --verify` to remove\n all Base table records while preserving fields/schema. It is destructive, so\n preview with `--dry-run` when needed. For batch updates to existing Base\n field schema, use public `mbs column batch-update` after\n confirming its installed `--help` contract.\n\nThis repository owns agent-facing assets:\n\n- `SKILL.md` — routing, playbooks, and core rules\n- `references/` — runtime-help-first operational guidance and semantic caveats\n- `agents/` — agent metadata\n- `artifacts/` — demo datasets and reusable example specs\n\nCLI implementation lives separately at:\n\n- `../maybeai-sheet-cli`\n\nInstall the CLI:\n\n```bash\npip install maybeai-sheet-cli\n```\n\nTo get a MaybeAI API token, register at [maybe.ai](https://www.maybe.ai/), then\nopen [My Plan](https://www.maybe.ai/user/my-plan) and copy a token from the\n**API Token** section.\n\nSet `MAYBEAI_API_TOKEN`, then run `mbs --help`:\n\n```bash\nexport MAYBEAI_API_TOKEN=\"your-api-token\"\nmbs --help\n```\n\n## Sync after CLI release\n\nAfter `../maybeai-sheet-cli` is published to PyPI, sync this skill's version\nfrontmatter from the released CLI metadata:\n\n```bash\npython scripts/sync_cli_release.py --cli-repo ../maybeai-sheet-cli\n```\n\nThe hook verifies that the CLI repository version fields agree and that the\nsame version exists on PyPI before updating `SKILL.md`. Use `--skip-pypi-check`\nonly for local draft docs before a package release."},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn77y6x3semab3mjjhgxyw81w9827yxy\",\n \"slug\": \"maybeai-sheet-cli\",\n \"version\": \"v0.21.8\",\n \"publishedAt\": 1789359128081\n}"},{"path":"references/base-mode-verification.md","content":"# Base Mode Verification Runbook\n\n## 1. Identify the Base target\n\n```bash\nmbs workbook inspect --target \"$WORKBOOK\"\nmbs worksheet list --target \"$WORKBOOK\" --output json\nmbs table inspect --target \"$BASE_TABLE\"\nmbs table schema --target \"$BASE_TABLE\"\nmbs table sample --target \"$BASE_TABLE\" --limit 10 --output table\n```\n\nUse `table sample` for a quick, representative, non-exhaustive check of Base\nrecords and field values. Use bounded `table read` when verification needs a\nspecified result window or post-mutation readback.\n\nUse a persistent Base table ID (`tid`) and stable field/record identities. A\nworksheet name alone is insufficient for a Base record or field mutation.\nFor a Base target, canonical `table inspect` also returns matched worksheet\ndimensions when available; use `table schema` and `table read` for fields and\nrecords.\n\n## 2. Insert or update records\n\n```bash\nmbs table insert --target \"$BASE_TABLE\" --frame-in rows.json --verify\nmbs table update --target \"$BASE_TABLE\" --frame-in corrected_rows.json --key order_id --verify\nmbs table read --target \"$BASE_TABLE\" --limit 100 --output table\n```\n\n`table update` is key-based. It does not imply an atomic full-table replacement,\ndelete missing records, or preserve all legacy replacement semantics. Stop and\nreport the capability gap when those semantics are required.\n\n## 3. Fields and Formula fields\n\n```bash\nmbs column insert --target \"$BASE_TABLE\" --field gross_margin --field-type formula --verify\nmbs column rename --target \"$BASE_TABLE\" --field gross_margin --new-name \"Gross Margin\" --verify\nmbs column config --target \"$BASE_TABLE\" --field gross_margin --spec field-style.json --verify\nmbs formula validate --target \"$BASE_TABLE\" --field gross_margin --expression 'revenue - cost'\nmbs formula set --target \"$BASE_TABLE\" --field gross_margin --expression 'revenue - cost' --verify\nmbs formula recalculate --target \"$BASE_TABLE\" --field gross_margin --verify\n```\n\n`column config` configures resource style; it is not a substitute for every\nBase typed-field property. Use current parent/command help before changing a\nfield and report unsupported schema work instead of selecting a hidden command.\n\n## 4. Verify SQL materialization\n\n```bash\nmbs sql materialize \\\n --target \"$WORKBOOK?table=S_orders\" \\\n --sql-file result.sql \\\n --mode create \\\n --schema schema.json \\\n --verify\nmbs table read --target \"$WORKBOOK?table=S_orders\" --limit 100 --output table\n```\n\nVerify the result schema, row count, representative values, and the target\nidentity returned by the mutation.\n\n## 5. Reject Sheet-only misuse\n\nDo not apply A1 range writes, merge/unmerge, Sheet cell notes, or Excel cell\nformula assumptions to a Base table. Explain the mismatch and choose a public\nBase record/field workflow instead."},{"path":"references/charts-formatting.md","content":"# Charts and Formatting Reference\n\n## Contents\n\n1. When to use this\n2. Scope boundary\n3. First-class mbs coverage\n4. Styling and freezing\n5. Minimal report-polish flow\n\n## 1. When to use this\n\nRead this document when the task involves charts, pictures, frozen panes, cell styles, autofilter, or conditional formatting.\n\n## 2. Scope boundary\n\nThis skill only covers worksheet-level `mbs` execution and media/styling operations.\n\nSwitch to `sheet-dashboard` when:\n\n- chart composition is the main task\n- dashboard layout and storytelling are the main task\n- you need chart layout systems, visual systems, or dashboard workflows\n- you need an agent to generate or swap a dashboard spec before execution\n\nIf you only need to:\n\n- inspect existing chart metadata\n- call low-level chart/image CRUD APIs\n- bind a chart to an existing sheet\n\nthen this skill is sufficient.\n\nChart and picture editing is first-class in `mbs` for common worksheet\nworkflows. Use `mbs raw post` only when you already have a task-specific\npayload for an uncovered operation.\n\n## 3. First-class mbs coverage\n\nCLI:\n\n```bash\nmbs chart list --doc-id --worksheet-name \nmbs chart get --doc-id --worksheet-name --cell J2\nmbs chart create-config --doc-id --worksheet-name --cell J2 --spec chart.json\n# Current CLI also accepts top-level `cell` in chart.json when --cell is omitted.\nmbs chart update --doc-id --worksheet-name --cell J2 --chart-id rId1 --spec chart.json\nmbs chart delete --doc-id --worksheet-name --chart-id rId1\n```\n\nRecommended authored `chart.json` shape:\n\n```json\n{\n \"type\": \"json\",\n \"sql\": \"select Month, Revenue from Sheet1\",\n \"title\": \"Monthly Revenue\",\n \"hide_title\": true,\n \"legend\": \"bottom\",\n \"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) }] }) }\",\n \"spec\": {\n \"style\": {\n \"title\": \"Monthly Revenue\",\n \"showContainerTitle\": false\n }\n }\n}\n```\n\nAlternate single-chart item shape accepted by recent CLI versions:\n\n```json\n{\n \"cell\": \"B2\",\n \"chart\": {\n \"type\": \"json\",\n \"sql\": \"select Month, Revenue from Sheet1\",\n \"title\": \"Monthly Revenue\",\n \"html\": \"{ library: 'echarts', handler: (data) => ({ series: [{ type: 'line', data: data.map(r => Number(String(r.Revenue || '').replace(/,/g, '')) || 0) }] }) }\"\n }\n}\n```\n\nImportant chart authoring rule:\n\n- Prefer top-level `chart.type = \"json\"` for authored `mbs` specs.\n- Put the actual ECharts or Highcharts renderer logic in `chart.html`.\n- For `chart create-config`, the backend request is `{cell, chart}`. If you include `cell` in the spec, keep it top-level; do not nest a second `chart.chart`.\n- Do not push `chart.type = \"line\"`, `\"bar\"`, or `\"pie\"` as the default authored pattern in `mbs` docs or skills.\n- Treat those simple aliases as low-level backend-supported forms, not "}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1295,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:15:20.543Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T13:15:20.543Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T04:07:50.423Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}