--- name: gridcraft description: >- GridCraft is an open-source, clean-room Rust reimplementation of Microsoft Excel: a spreadsheet app for macOS (also Windows, Linux, BSD and the web) that reads and writes real .xlsx files and can be driven headlessly through a CLI, an MCP server and a live JSON control channel. Use this skill whenever the user mentions GridCraft by name; asks what it can do or which formats, keyboard shortcuts, commands or worksheet functions it has; wants to create, edit, convert, calculate, print or export spreadsheets with it; wants to automate or script it (MCP, CLI, control channel, recorded scripts); needs inputs prepared for it (build/convert .xlsx, CSV, TSV, JSON, or convert .xls/.xlsb/.ods into .xlsx); wants its output verified, repaired or round-tripped (gridcraft-cli check); or reports a symptom (crash, wrong formula result, formatting lost on save, Excel saying "we found a problem with some content"). Trigger it even when the app is not named but the job is Excel-style spreadsheet work — "make me an Excel file", "add a formula column", "sort and filter this sheet", "pivot this data", "export this workbook to PDF", "read the values out of this spreadsheet". Do not assume Excel parity from Excel knowledge; check this skill first. --- # GridCraft **Audit basis:** this checkout is tag `v0.11.1`, commit `ac8da7d49cbeb4be6aa1ad5869f3d29fe2da8cd9` (release commit, 2026-10-22). The installed `/Applications/GridCraft.app` reports version `0.11.1` (`CFBundleShortVersionString`), its `GridCraftBuildCommit` is the same SHA, and its binary prints `GridCraft 0.11.1`, so the bundle matches this source exactly. **Verify against your installed version** if the ArtCraft Launcher has auto-updated since. Counts and formats below were re-derived from this tag; every claim carries a repo-relative pointer. ## Overview GridCraft is an open-source, clean-room reimplementation of Microsoft Excel's workflow in pure Rust (README.md), by the ArtCraft team; source: `github.com/storytold/gridcraft`. XLSX is the native document format, and the architecture is engine-first: every ribbon button, menu item, dialog OK, keystroke and mouse gesture is a *command* (`crates/engine/src/cmd/`), reachable over a JSON control channel, an MCP server and a headless CLI (README.md §"For agents"; `docs/architecture.md`). Maturity is **alpha**: the core workflow (open XLSX → edit/format → sort/filter → chart/pivot → print to PDF → save XLSX) works end to end, but the project's own estimate is ~75% feature breadth and ~50% "ready for real work" (ROADMAP.md headline; `docs/target-app-parity.md`). It runs natively on macOS 11+, Windows, Linux and BSD, and in the browser via WebAssembly (`apps/gridcraft-web`). ## Capabilities (verified) ### Core workbook and editing - Several workbooks open at once inside one OS window ("documents"); the Window menu lists them (`view.switchWindows`) and `window.activate {index}` switches. Sheet tabs, defined names, freeze panes, outline groups, hidden sheets, tab colours (implemented — `crates/engine/src/cmd/{file,sheet,extra}.rs`). One window only; see limitations. - Three built-in samples `budget`, `sales`, `grades`: `file.new {sample}`, CLI `--sample`, URL `?sample=` (`crates/engine/src/sample.rs`). - 346 engine commands (341 at v0.10.0); 275 of the 291 Excel ribbon/menu ids implemented, 94.5% (274/290 before) — `crates/engine/src/catalog.rs`, generated `docs/parity-checklist.md`. Added since v0.10.0: `automate.trustScripts`, `formulas.convertToNumber`, `formulas.selectPrecedents`, `formulas.selectDependents`, `view.showObjects`. - Formatting: fonts, fills, borders, alignment, merges, Excel's number-format language (`crates/numfmt`), cell styles and themes, conditional formatting (cell-is, expression, text, top-10, above-average, time period, duplicate/unique, colour scale, data bar, icon set) and data validation (whole, decimal, list, date, time, text length, custom) — `crates/engine/src/cmd/{format,insert}.rs`, `crates/model/src/features.rs`. - Tables (structured references, header/total rows, banded rows, style gallery, Resize Table, remove duplicates), notes and threaded comments with replies/resolution/timestamps, hyperlinks, pictures floating or inside a cell (PNG/JPEG only), shapes and text boxes (9 kinds: rectangle, rounded rectangle, ellipse, triangle, line, arrow, text box, icon, ink), checkboxes, freehand ink with Ink to Shape, sparklines (line/column/win-loss) — `crates/engine/src/cmd/{insert,extra,draw}.rs`, `crates/model/src/features.rs`, `docs/cell-pictures.md`. - Editing: fill handle (drag; right-drag opens Copy Cells / Fill Series / Fill Formatting Only / Fill Without Formatting / Series…), AutoFill, Flash Fill, Paste Special (values/formats/formulas/comments, transpose, Paste Link), Format Painter, Find/Replace, Go To and Go To Special, Watch Window, undo/redo with bounded history — `crates/ui-egui/src/grid.rs`, `crates/engine/src/cmd/{edit,whatif}.rs`. - Background error checking: a constant whose text would be a number gets Excel's green corner, a warning button naming the problem, and Convert to Number (`formulas.convertToNumber`) — new at v0.11.0 (#1994); `crates/ui-egui/src/grid.rs`, `crates/engine/src/cmd/formulas.rs`. - AutoSave switch in the title bar, now persisted across restarts; it saves only workbooks that already have a file. Closing the window with unsaved work asks first (`crates/ui-egui/src/{lib,ribbon}.rs`). - Slicers exist as in-sheet filter widgets over one table column (`insert.slicer`, `slicer.toggle|selectAll|delete`), but are not written to XLSX (`crates/engine/src/cmd/slicer.rs`). ### Formulas and calculation - 513 of Excel's 523 worksheet functions by name, 504 working (96.4%), including dynamic arrays and spilling, LET/LAMBDA, MAP/REDUCE/SCAN/BYROW/BYCOL/MAKEARRAY, GROUPBY/PIVOTBY, structured table references, iterative calculation for circular references — `docs/function-parity.md` ("Measured" line), `crates/functions/`, `crates/calc/`. - Evaluate without editing: `gridcraft-cli eval '=SUM(A1:A9)' --in book.xlsx` or `formulas.evaluate`. A formula that could not be typed into a cell (parse error, wrong argument count) is an error that says why, not a silent `#VALUE!` (`crates/engine/src/cmd/formulas.rs::evaluate`; `apps/gridcraft-cli/src/main.rs::eval`). - Calculation settings travel with the workbook: automatic / automaticExceptTables / manual, iterative on/off, max iterations and max change (`formulas.calculationOptions`; `crates/model/src/workbook.rs`). ### Files it reads and writes - **`.xlsx` is native read/write**: cells, shared/array/dynamic formulas, styles, themes (including per-script fonts), merges, conditional formats, validation, tables, notes (with box position and size) and threaded comments, hyperlinks, names, freeze panes, outlines, print settings, pictures (shared media written once), shapes incl. ink, sparklines, PivotTables, sheet/workbook protection and Allow Edit Ranges, calc settings, `` — `crates/engine/src/io.rs`, `crates/xlsx/src/{read,write,sheet_read,sheet_write}.rs`, `docs/file-format-parity.md`. - **Pass-through on save** (kept byte-for-byte when their owner survives): custom XML, external workbook links (never followed or refreshed), data connections, sheet query tables, printer settings, form/ActiveX controls, OLE objects, sheet backgrounds with their VML, header/footer pictures, and chart sheets — `crates/xlsx/src/passthrough.rs`. - `.xlsm` / `.xltm` keep their VBA project byte-for-byte; macros are **never executed**. `.xltx`/`.xltm` save with the template content type — `crates/xlsx/src/lib.rs` (`XlsxKind`), `crates/xlsx/src/write.rs`, test `macros_are_saved_only_into_xlsm` in `crates/engine/src/io.rs`. - **Import-only**: `.xls`/`.xlt` (BIFF8: values, formulas, number formats, merges, sizes, names, calc and sheet-display settings; chart/macro/dialog sheets skipped), `.xlsb` and `.ods` (worksheet values and cached formula results only) — `crates/xlsx/src/xls/`, `crates/xlsx/src/{xlsb,ods}.rs`, `docs/{xlsb,ods}-import.md`. - **Text/data**: CSV and TSV/TXT/TAB with delimiter/encoding detection (UTF-8/UTF-16, likely Windows-1256 Arabic, otherwise Windows-1252); writes the *displayed* text, keeps the separator a file was opened with, refuses output over 512 MiB; `file.open {csvAsText:true}` keeps every field as text — `crates/xlsx/src/csv.rs`, `crates/engine/src/io.rs::csv`. `.json` is a debug serde dump of the internal model (unstable, not an interchange format). HTML exports one sheet as a table (pictures as data-URI images, charts as inline SVG; refuses more than 100,001 rows) — `crates/engine/src/io.rs::to_html` (`HTML_EXPORT_MAX_ROWS`). - **`.pdf` export**: own PDF 1.7 writer (no dependencies); `file.exportPdf {path?, sheets?: active|all, range?, fitToPage?}` returns `{pages, bytes, path}` or base64; `file.print` returns the same PDF; the CLI `convert` now accepts `.pdf` as an output extension. `http(s)` hyperlinks and internal cell destinations become real PDF link annotations; `file:` links are omitted — `crates/pdf/src/lib.rs`, `crates/engine/src/cmd/print.rs`, `apps/gridcraft-cli/src/main.rs::convert`. - **Password-encrypted `.xlsx` open** (Agile AES and Standard encryption, [MS-OFFCRYPTO]) via a `password` param; the workbook opens with no save path and always saves **unencrypted**. RC4/Extensible and encrypted `.xls` are refused — `crates/xlsx/src/crypto.rs`, `crates/engine/src/io.rs`. - **Save is refused** for `.xls`, `.xlsb`, `.ods` with an explanatory message (`crates/engine/src/io.rs::save_bytes_as`). Content wins over the extension: an ODS/XLSB package is imported as what it is; an XLSX package is never misread as ODS/XLSB. - Hard caps: 512 MB per decompressed XLSX part and 1 GB per package (`crates/xlsx/src/package.rs`), 2 GB per file read, 100,001 HTML rows, 512 MiB CSV/TSV output, 16,000,000 cells per array result (`crates/calc/src/eval.rs`). ### Charts, PivotTables and analysis - 25 `ChartKind`s (column/bar/line/pie/doughnut/area/scatter/bubble/radar/histogram/waterfall/funnel/treemap/sunburst/box-whisker/stock/combo and subtypes), chartex parts for histogram/box-whisker/waterfall/funnel/treemap/sunburst, six trendline types, PivotCharts (`insert.pivotChart`), Recommended Charts, Select Data, Switch Row/Column, Change Type/Colours/Layout — `crates/model/src/features.rs` (`ChartKind`), `crates/xlsx/src/{chart,chartex}.rs`, `crates/engine/src/cmd/{insert,extra}.rs`, `docs/chart-parity.md`. - Chart objects move and resize: drag the bottom-right corner or use `chart.set {at, width, height}` (resize landed after v0.10.0; `crates/ui-egui/src/grid.rs` `Drag::Object`, `crates/ui-egui/src/panes.rs`). All 2-D kinds survive the XLSX round trip. - PivotTables: field list, Filters/Rows/Columns/Values areas, report filters, layouts, date grouping, show-values-as, calculated fields, values on rows, grand totals, styles, refresh, change source; round-trip to/from XLSX — `crates/engine/src/cmd/pivot.rs`, `crates/xlsx/src/pivot.rs`. - Data tools: sort (multi-key), AutoFilter (values/colour/top-10/custom), Advanced Filter (criteria ranges, copy-to, unique), remove duplicates, text-to-columns, Flash Fill, group/ungroup/subtotals, consolidate, scenario manager, Goal Seek, data table — `crates/engine/src/cmd/{data,whatif}.rs`, `docs/parity-checklist.md` Data 23/28. - Solver (`data.solver`: Simplex LP with integer/binary branch-and-bound, augmented-Lagrangian local nonlinear, Evolutionary; Answer and Limits reports), Forecast Sheet with hindcast (`data.forecastSheet`), Analysis ToolPak (13 of Excel's 19 tools) — `crates/engine/src/cmd/{solver,forecast,analysis}.rs`. - Printing: native macOS/Windows/Linux printing through the pinned shared `craft-print` library (printer choice, copies, duplex, grayscale), Page Setup, Page Break Preview, Page Layout view with rulers, draggable margins and in-place header/footer editing — `apps/gridcraft/Cargo.toml`, `apps/gridcraft/src/print.rs`, `crates/engine/src/cmd/print.rs`, `docs/ui-parity.md`, `docs/hardware-parity.md`. ### Automation surface (the reason to read this skill) Counts at this tag, with v0.10.0 in brackets: **346 engine commands** (341); **275/291 catalog ids** (274/290); **21 MCP tools** (21, unchanged); **11 CLI subcommands** (11; `convert` gained `.pdf`); **31 documented control-channel methods** plus `ui.menu.invoke` and `ui.message.dismiss` in code (set unchanged); **68 shortcut bindings on command specs** (65; added `Ctrl+6`, `Ctrl+[`, `Ctrl+]`); **365 key-tip sequences** (364); **19 interface languages** (11); **25 chart kinds** (25); **513/523 functions** (513/523). - **CLI `gridcraft-cli`** (headless; the app bundle ships no CLI): `info`, `convert`, `eval`, `cat`, `check`, `run`, `commands`, `functions`, `mcp`, `send`, `version` — `apps/gridcraft-cli/src/main.rs` (USAGE), `docs/cli.md`. `check` is the important one: it recalculates every formula against the file's Excel-cached values (skipping volatile formulas and `fullCalcOnLoad` files), then writes and re-reads the workbook through GridCraft's own XLSX writer, comparing 14 categories — package, sheets, values, formulas, numFmts, merges, names, tables, condFormats, validations, charts, comments, hyperlinks, pivots — and validating the package (content types, relationship targets/ids). Exit 1 on any difference, 2 on a usage error; `--json` emits schema `gridcraft-check/1`; discovery caps at depth 32 and 100,000 files and reports omissions as failures (`apps/gridcraft-cli/src/check.rs`). - **MCP server** over stdio, protocol `2025-06-18` (older `2025-03-26`/`2024-11-05` clients are answered in their own version); headless (`--in FILE | --sample NAME`) or remote (`--connect PORT`). 21 tools: | Tool | Does | |---|---| | `execute_command` | any command id + params | | `list_commands` | ids, labels, ribbon paths, shortcuts, param docs; `search?` | | `inspect_workbook` | sheets, used ranges, tables, charts, names, selection, history | | `read_range` | `range?`, `sheet?`, `formulas?`, `formatted?` | | `write_range` | `range`, 2-D `values`; strings starting `=` are formulas | | `set_cell` / `get_cell` | enter one cell / value, formula, display text, style, merge, comment, link | | `evaluate_formula` | `formula`, optional `cell`; never changes the sheet | | `select` | `range`, `active?` (comma-separated areas allowed) | | `format_range` | bold, italic, underline, font name/size/colour, fill, number format, alignment, wrap, border presets | | `insert_chart` | `range`, `type`, `subtype?`, `title?`, `at?` | | `create_table` | `range`, `style?`, `header?`, `name?` | | `sort_range` | `keys` (`"B"`, `"B desc"` or `{column, order}`), `range?`, `header?` | | `filter` | `column`, `range?`, `values?`, `custom?`, `top?`, `blanks?`, `clear?` | | `open_workbook` / `save_workbook` / `new_workbook` | path / path? / sample? | | `undo` / `redo` | `steps?` | | `screenshot` | `path`; remote/desktop only | | `list_functions` | `search?`, `category?` | Resources: `gridcraft://workbook`, `gridcraft://commands`, `gridcraft://functions`; `prompts/list` is empty. `gridcraft-mcp` is also a library (`Server::new(Box::new(Headless::new()))`, `Remote::connect`) — `crates/mcp/src/{tools,server,headless,backend}.rs`, `docs/mcp.md`. - **Control channel**: the app started with `--control ` (or `GRIDCRAFT_CONTROL_PORT`) accepts newline-delimited JSON on `127.0.0.1`; each line gets one reply line. Read state: `engine.execute`, `engine.commands` (also lists UI-only ids), `engine.journal` (10,000 entries / 64 MB, passwords stripped), `document.inspect`, `sheet.read`, `cell.get`, `ui.inspect`. Drive: `ui.click|drag|move`, `ui.cell.click|drag`, `ui.key|text`, `ui.edit.begin|text|commit|cancel`, `ui.ribbon`, `ui.dialog|set|confirm|cancel`, `ui.message.dismiss`, `ui.menu.invoke`. Window/app: `ui.screenshot` (PNG, animations settled), `ui.set`, `ui.resize`, `ui.focus`, `app.open|save|quit`. `ui.backstage {page: home|new|open|info|saveAs|print|export|options|account|close}` and `ui.ribbonTab` are commands. Any other method that is a command id runs that command — `crates/ui-egui/src/control.rs`, `docs/control-protocol.md`. - **UI-only commands** reachable over `engine.execute`/MCP: `view.theme {mode: system|light|dark}`, `view.darkMode`, `view.animations`, `view.interfaceScale {percent: 75–200|"auto"}`, `view.collapseRibbon`, `options.autoComplete`, `app.language.set`, `ui.printSettings`, `ui.printSubmit` — `crates/ui-egui/src/{lib,control}.rs`. - **Recorded scripts** (Automate tab): `automate.recordActions {stop?, name?}` records the command journal, `automate.newScript {name, commands}`, `automate.allScripts` (also reports a preserved `(VBA)` project as never executed), `automate.runScript {name, trusted?}`, `automate.deleteScript {name}`. New in v0.11.0: `automate.trustScripts {trusted?}` plus a trust gate — a workbook opened from a file that carries scripts starts untrusted and `runScript` refuses until trusted for the session; steps may not call `file.*`/`link.*` or pass a `path`, and they run inside a filesystem sandbox. Scripts are stored in the workbook as a hidden defined name `_sc_scripts`, so they round-trip XLSX — `crates/engine/src/cmd/extra.rs`, `crates/engine/src/io.rs::ScriptSandbox`. - **Web build**: same UI crate via eframe web runner, `trunk build --release` → `dist/web`; URL flags `?sample=`, `?webgl`, `?host=parent&author=`; preferences in `localStorage`; no TCP control channel (Open uses the browser picker, Save downloads) — `apps/gridcraft-web/src/main.rs`. - **Programmatic calls never open dialogs**: `file.open`/`file.save`/`data.getData`/`data.fromTextCsv` without a file path return "missing `path`…: programmatic calls never open dialogs" (`crates/engine/src/lib.rs::execute_headless`). - **Interface languages**: 19 (`Language::ALL`): en, es, el, zh, ja, ko, ru, pt, de, cs, fr, sr, tr, pl, it, uk, vi, nl, ro — up from 11. Seven catalogs are near-complete (ja ~963, ro ~976, el/it/pl/uk ~955, pt ~949 entries); cs ~524, nl ~505; the rest 390–450. Untranslated strings fall back to English; command ids, document text, formulas and number formats stay English/en-US. `app.language.set {language|code}` switches at runtime; the desktop follows the system language until a choice is saved (`crates/ui-egui/src/i18n.rs`, `crates/ui-egui/src/i18n/*.rs`). ## Known limitations and not-implemented - **Partial:** `.xls` import covers values, formulas, number formats, merges, sizes, names, calc and sheet-display settings; no fonts, fills, borders, charts, pictures, comments, conditional formats, validation, hyperlinks or freeze panes; chart/macro/dialog sheets are skipped, BIFF5 and FILEPASS files refused. `.xlsb`/`.ods` import values and cached formula results only. None of the three is ever written (`crates/xlsx/src/xls/mod.rs`, `crates/xlsx/src/{xlsb,ods}.rs`, `crates/engine/src/io.rs`). - **Encryption is read-only**: Agile and Standard `.xlsx` open with a password; saves are always unencrypted and have no save path, so Save asks where to go. RC4/Extensible and encrypted `.xls` are refused (`crates/xlsx/src/crypto.rs`, `docs/gaps.md` §7). - **Macros never run.** VBA is carried byte-for-byte only into `.xlsm`/`.xltm`; any other save drops it. GridCraft's recorded scripts are not VBA (`crates/engine/src/io.rs` test `macros_are_saved_only_into_xlsm`). - **Excel-repair-free output is unproven**: no real corpus and no Excel verification. Unmodelled content is dropped when its owner is rewritten — slicers and slicer caches, timelines and caches, the data model, query tables attached to tables, unmodelled `extLst`; chart sheets are passed through unchanged but cannot be viewed, edited or created (`docs/gaps.md` §1/§3, `crates/xlsx/src/passthrough.rs`). - **Slicers/timelines:** slicers can be created and clicked in-sheet but are not saved to XLSX; timelines are catalogued (`insert.timeline`) but not implemented (`crates/engine/src/cmd/slicer.rs`, `docs/parity-checklist.md`). - **Charts are shallow:** no 3-D types, no axis scaling (min/max/log), no error bars, no per-point formatting; data labels and gridlines are just booleans; chart sheets are not editable. Move and resize do work; all 2-D kinds round-trip (`docs/chart-parity.md`, `crates/model/src/features.rs`, `crates/xlsx/src/chartex.rs`). - **PivotTables:** no calculated items, `GETPIVOTDATA`, timelines, value/label filters, number grouping or data-model pivots; XLSX round-trip has not been checked in Excel (`crates/engine/src/cmd/pivot.rs`, `docs/function-parity.md`). - **No Power Query or data model:** Get & Transform is only From Text/CSV (`data.fromTextCsv`), Get Data (`data.getData`: CSV/TSV or a JSON array of objects) and From Table/Range; Queries & Connections lists imported tables; Refresh All refreshes PivotTables only. No From Web, Stocks, Geography, Relationships or Analyze Data (`crates/engine/src/cmd/extra.rs`, `docs/parity-checklist.md`). - **Scale:** recalculation is single-threaded; the project reports ~100 MB workbooks failing to open (#175). Whole-range work is capped and refuses with an error instead of hanging (see the file caps above; `crates/calc/src/eval.rs` `MAX_CELLS = 16_000_000`). - **Text:** no complex shaping (Arabic, Devanagari, Thai) and no bidi; a right-to-left sheet mirrors the grid, but text stays LTR inside its box and printing/PDF are not mirrored. PDF export sets characters outside WinAnsi in a predefined, **non-embedded** Adobe-GB1 CID font (STSong-Light / UniGB-UTF16-H): Chinese is tested and no longer becomes `?`; Japanese/Korean coverage depends on that font (uncertain — inspect the PDF); Arabic/Devanagari/Thai have no glyphs there (`crates/pdf/src/lib.rs`, `crates/pdf/src/tests.rs`, `docs/localization-parity.md`, `docs/hardware-parity.md`). - **One OS window:** `view.newWindow` clones the workbook into another document (title suffix `:2`); `view.arrangeAll` does nothing (`crates/engine/src/cmd/extra.rs`). - **Accessibility:** AccessKit is enabled but grid cells and the ribbon are not exposed as an accessible tree; Check Accessibility (`review.checkAccessibility`) is a basic scan (missing alt text, merged cells, default sheet names); no high-contrast mode (`docs/gaps.md` §18, `crates/engine/src/cmd/review.rs`). - **No VBA/Office Scripts/add-in or custom-function API, no collaboration/co-authoring, no mobile build, no in-app AI** (`docs/gaps.md` §16/§21–23). - **Functions:** 18 of Excel's 523 names are absent (including GETPIVOTDATA, IMAGE, STOCKHISTORY, TRANSLATE, DETECTLANGUAGE, CALL, REGISTER.ID, RTD, COPILOT, PY) and 9 are error stubs (7 CUBE functions, WEBSERVICE, FILTERXML) — `docs/function-parity.md`, `crates/functions/src/info.rs`. - **HTML is export-only:** opening `.html`/`.htm` with `file.open` falls through to the CSV/TSV reader, so a saved web page opens as delimited text, not as a table (`crates/engine/src/io.rs::open_plain`). - **Objects:** inserted icons lose their artwork on XLSX save (#551); Office InkML is not imported; pictures must be PNG/JPEG (`docs/gaps.md` §17, `crates/engine/src/cmd/insert.rs`). - **Save semantics:** only `.xlsx` and `.json` saves clear the dirty flag and become the document's file; `.csv/.tsv/.html/.pdf` are exports that leave the workbook dirty. `file.close {force:true}` and the control-channel `app.quit` discard unsaved changes without asking (`crates/engine/src/cmd/file.rs::save`, `crates/ui-egui/src/control.rs`, `crates/ui-egui/src/lib.rs::guard_window_close`). - **Stale repo prose:** README's key-tip paragraph still says "initial Home-only"; `docs/gaps.md` §5 (PDF fonts), §8 (PivotCharts/slicers), §19 (CSV raw values, template content type) and `docs/control-protocol.md`'s language list (11) lag the code; `docs/ui-parity.md` still says 59 shortcuts/364 keytips. Prefer code and the generated `docs/parity-checklist.md`. ## How to operate ### macOS launch, flags, environment - `open -a GridCraft`; `open -a GridCraft book.xlsx` — Finder double-clicks and `open` arrive as Apple events, and files dropped on the window open too (`apps/gridcraft/src/apple_events.rs`, `apps/gridcraft/src/main.rs`). - The binary takes only these flags: `/Applications/GridCraft.app/Contents/MacOS/GridCraft [--control PORT] [--sample budget|sales|grades] [files…]`; `--version` prints `GridCraft 0.11.1`. There is no other CLI surface in the bundle (`apps/gridcraft/src/main.rs`). - Environment: `GRIDCRAFT_CONTROL_PORT=` (same as `--control`), `GRIDCRAFT_NO_PREFS=1` (reads/writes no `ui.json`/`prefs.json` and keeps no log file — the mode for agent test runs), `GRIDCRAFT_NO_NATIVE_MENU`, `RUST_LOG` (env_logger-style directives; default gridcraft crates `info`, everything else `warn`). - Settings and logs live under `Library/Application Support/GridCraft/` in the user's home: `ui.json`, `prefs.json`, and `logs/gridcraft.log`, rotated to `.1`/`.2` at each start, 16 MiB cap (`apps/gridcraft/src/{main,logging}.rs`, README.md §Logs). ### The CLI (installed separately) The bundle ships no CLI. Install with `cargo install --path apps/gridcraft-cli` from a source checkout, or the release zip `gridcraft-cli--macos-universal.zip` (README.md Downloads; `docs/cli.md`). ```sh gridcraft-cli info book.xlsx [--json] gridcraft-cli convert in.xls out.xlsx [--sheet Sales] # .xlsx/.csv/.tsv/.json/.html/.pdf by extension gridcraft-cli eval '=XLOOKUP("b",{"a","b"},{1,2})' # → 2 gridcraft-cli cat book.xlsx --range A1:F20 [--formulas|--csv] gridcraft-cli run --in book.xlsx --cmd 'cell.set={"cell":"D2","input":"=B2*C2"}' \ --cmd 'edit.fillDown={"range":"D2:D20"}' --out book.xlsx --print A1:D5 gridcraft-cli check corpus/ --json # calc oracle + XLSX round-trip fidelity gridcraft-cli commands --search chart # every command and its params doc gridcraft-cli functions --category statistical # function list with signatures gridcraft-cli send 7979 engine.execute '{"command":"home.bold","params":{"range":"A1:C1"}}' ``` - `run` flags: `--in FILE | --sample NAME`, repeated `--cmd`, `--script FILE`, `--out FILE`, repeated `--print RANGE|used`, `--sheet`, `--quiet`, `--csv`, `--formulas`. A `--cmd` is `id`, `id={json}` or `id {json}`; a script has one step per line in the same forms or as `{"command":…,"params":…}` objects; blank and `#` lines are skipped. The first failing step stops the run with a non-zero exit (`apps/gridcraft-cli/src/main.rs::run`). - `convert` refuses an unknown output extension; `.pdf` goes through `file.exportPdf` and reports bytes/pages. ### MCP ```sh claude mcp add gridcraft -- gridcraft-cli mcp # headless in-process session claude mcp add gridcraft-app -- gridcraft-cli mcp --connect 7979 # drive the visible app ``` Results are one text block holding pretty JSON; failures set `isError: true`. Unknown tools, missing/wrong arguments are JSON-RPC `-32602`; malformed JSON `-32700`; unknown methods `-32601` (`crates/mcp/src/server.rs`, `docs/mcp.md`). The remote backend uses a 30 s socket timeout: after a timeout, re-read the state instead of retrying blind (`crates/mcp/src/backend.rs`). ### Control channel (drive the running app) ```sh /Applications/GridCraft.app/Contents/MacOS/GridCraft --sample sales --control 7979 # then, newline-delimited JSON to 127.0.0.1:7979: {"id":1,"method":"engine.execute","params":{"command":"cell.set","params":{"cell":"B2","input":"=SUM(A1:A9)"}}} {"id":2,"method":"ui.screenshot","params":{"path":"shot.png"}} ``` - Run `ui.inspect` first (ribbon tab, editor, open dialog, Backstage page, message, grid rect, scroll, perf) and act on what it shows; `ui.inspect` also reports `documents` and the active index. `ui.screenshot` needs a presented frame: if the window is hidden/minimised it answers "no frame was presented before the screenshot timeout; make the window visible, use `ui.focus`, then retry" (`crates/ui-egui/src/control.rs`). - Limits: 64 MiB per request line; 10,000 queued synthetic pointer events; the server waits 60 s for the UI, then reports a timeout. A request the client abandoned is dropped unrun; if the app had already started it, the reply says the outcome is unknown — read the cell/state before retrying (`apps/gridcraft/src/control_server.rs`, `crates/ui-egui/src/control.rs`). - The port is unauthenticated and binds localhost only. Do not expose it; any local process can run every command. - `ui.dialog.confirm` sends exactly what the dialog's OK sends (fixed in v0.11.0); `ui.dialog.cancel` closes it; dialogs without an OK command return "this dialog has no OK command; drive it with its own commands". ### Document model and save/export flow - One window, several documents; the Window menu (`view.switchWindows`, `window.activate`, `view.hideWindow`) switches/hides them. Sheet tabs at the bottom. File opens the Backstage with 9 pages: home, new (three samples), open (recents), info, saveAs, print, export, options, account (`crates/ui-egui/src/backstage.rs`). - Save (`file.save`, `file.saveAs`, ⌘S, ⇧⌘S): the extension picks the format — `.xlsx` (default), `.csv`, `.tsv`, `.json`, `.html`, `.pdf`; a `.pdf` save exports the sheet and leaves the document dirty, unsaved and pointing at its old file. `file.saveBytes {format}` returns base64 without writing (formats: xlsx/csv/tsv/json/html) (`crates/engine/src/cmd/file.rs`). - Exports: `file.exportPdf {path?, sheets?: active|all}` (no path → base64 + page count), `file.exportCsv {path, sheet?}`, `file.exportHtml {path}`, `file.printPreview {page?, sheets?}`, and on the desktop `ui.printSettings` / `ui.printSubmit` (native jobs via craft-print; poll `ui.printSettings` until not busy) (`crates/engine/src/cmd/{file,print}.rs`, `docs/control-protocol.md`). - Opening a `.xls`/`.xlsb`/`.ods` produces a document titled ` (imported).xlsx` with no save path; opening an already-open path just switches to it; a password-decrypted workbook also has no save path (`crates/engine/src/cmd/file.rs::open`). ### Keyboard essentials (verified) - 68 shortcut bindings on command specs (65 at v0.10.0), plus a wider keymap table for number formats, borders, F-keys and Alt/Option combinations. Essentials: ⌘S save, ⇧⌘S Save As, ⌘O open, ⌘N new, ⌘W close, ⌘Z undo, ⌘Y redo; ⌘B/⌘I/⌘U; ⌘1 Format Cells (Ctrl+1 on Windows); ⌘D fill down, ⌘R fill right; ⌃E Flash Fill (⌘E centres); ⌘T table; ⌘K link; Ctrl+Shift+L filter; F2 edit; Ctrl+Shift+4 currency; Ctrl+Shift+7 outline border; Ctrl+` show formulas; F9 calculate; Ctrl+[ / Ctrl+] select precedents/dependents (add Shift for every level); Ctrl+6 hide/show objects — `crates/ui-egui/src/{ribbon,keymap,grid}.rs`, `docs/ui-parity.md` §Shortcut audit. - Key tips: F10 on any platform (Fn+F10 if needed) or left Alt on Windows/Linux/BSD, then sequence letters; 365 sequences cover every ribbon tab, including `F` → File view. README's "initial Home-only" sentence is stale (`crates/ui-egui/src/keytips/keytips.json`, `crates/ui-egui/src/keytips.rs`). - The macOS native menu has Tools ▸ Command Palette… (⌘⇧P), which opens the `commandSearch` dialog (`apps/gridcraft/src/native_menu.rs`, `crates/ui-egui/src/dialogs.rs`). ## Working with an AI agent **Prefer headless over GUI.** For read/write/convert/verify jobs use `gridcraft-cli` (or MCP) on files: no window, no preferences (set `GRIDCRAFT_NO_PREFS=1` if you launch the app), deterministic. Drive the GUI over the control channel only when the task is genuinely about the UI: dialogs with no command equivalent, visual state, screenshots, native printing. Never drive blind — `ui.inspect`/`ui.screenshot` before and after, and act on what they show. Legitimate agent work: - **Prepare inputs.** Build `.xlsx` from commands (`gridcraft-cli run --script steps.jsonl`), convert `.xls`/`.xlsb`/`.ods`/CSV/TSV into `.xlsx`, or generate CSV/TSV/JSON and import with `data.fromTextCsv`/`data.getData`. Use `file.open {csvAsText:true}` when leading zeros and digit-only identifiers must survive. Remember an import opens as an unsaved "(imported).xlsx". - **Interpret/repair files.** XLSX is native and documented in code (`crates/xlsx/src/`); the `.json` workbook is a debug serialization, not a long-lived interchange format. "Repair" means: open in GridCraft, inspect (`info`, `check`), fix with commands or formulas, save as `.xlsx`. Do not promise recovery of parts GridCraft does not model (slicers, timelines, data model, chart-sheet editing). - **Verify exports honestly.** Run `gridcraft-cli check` on round-tripped files, compare `cat`/`info` output against expectations, check PDF page counts and links. A zero exit from `check` means GridCraft agrees with itself and with the file's cached values; it does **not** prove Excel will open the file without a repair prompt (explicitly unverified, `docs/gaps.md` §1). - **Scripts.** Recorded scripts are a convenience layer over the same command ids, not a separate API. A workbook received from elsewhere carries its scripts as a hidden name; nothing runs until the workbook is trusted (`automate.trustScripts`, or `runScript {trusted:true}` once), and script steps cannot touch files or open links — run those commands directly. Must NOT attempt: - Writing `.xls`/`.xlsb`/`.ods`, or saving password protection; expecting macros to run; expecting slicers/timelines to survive a save; assuming HTML import; assuming multiple windows per workbook. - Raw XML surgery on `.xlsx` files that contain unmodelled parts (slicer caches, VML, custom XML): GridCraft's own writer is the supported path, and even it drops parts it does not model once it rewrites them. Prefer read-only analysis of such files. - Treating formulas as locale-independent without checking `docs/formula-input.md`: Spanish input/display exists, but files, commands and APIs use canonical English names and `,` separators. - Promising PDF output for Arabic, Devanagari or Thai (no glyphs in the CID font, no shaping); verify CJK output visually first. - Calling `app.quit` or `file.close {force:true}` while a workbook has unsaved changes: both discard them silently. Save first. ## Verification protocol (alpha discipline) 1. **Throwaway round-trip before real work**: new workbook → the exact edit → save `.xlsx` → reopen (or `gridcraft-cli info`/`cat`) → `gridcraft-cli check file.xlsx`. Add the source file itself to `check` when testing formula fidelity: it recalculates and compares against Excel-cached values. 2. **Never trust a silent export.** CSV/HTML/PDF are one-shot exports with no diff UI. Re-read or re-import the artifact (`cat`, `--json`, PDF page count/links, open the PDF elsewhere). Remember PDF export cannot be assumed to render Arabic/Devanagari/Thai. 3. **Version and back up.** Keep the previous copy of any workbook you edit; autosave covers only workbooks that already have a file, and there is no crash-recovery soak (`docs/gaps.md` §10). For agent runs, save after each logical step (`--out`) rather than at the end. 4. **Update between projects, not during.** The app auto-updates through the ArtCraft Launcher; update, then re-run your round-trip before a new task. The repo at a tag is the source of truth for what a version can do. 5. **After a control/MCP timeout, re-read state** (`cell.get`, `sheet.read`, `document.inspect`) before retrying: a queued request is dropped, but one already taken may still finish. 6. **Trust deliberately.** Do not call `automate.trustScripts` on a workbook you did not create unless the user asked you to run its scripts. ## Sources & evidence - Repo: https://github.com/storytold/gridcraft — inspected at tag **v0.11.1**, commit `ac8da7d49cbeb4be6aa1ad5869f3d29fe2da8cd9` ("Release 0.11.1", 2026-10-22). The installed `/Applications/GridCraft.app` reports `0.11.1` and its binary prints `GridCraft 0.11.1`; `GridCraftBuildCommit` matches the tag. If your installed version differs, verify against it. - Date of inspection: 2026-10-23. Repo treated read-only (not built or modified). - Key files read: `README.md`, `ROADMAP.md`, `AGENTS.md`, `Cargo.toml`, `docs/{cli,mcp,control-protocol,parity-checklist,function-parity,chart-parity,file-format-parity,gaps,ui-parity,localization-parity,hardware-parity,target-app-parity,cell-pictures,formula-input,xlsb-import,ods-import}.md`, `apps/gridcraft-cli/src/{main.rs,check.rs}`, `apps/gridcraft/src/{main.rs,control_server.rs,logging.rs,apple_events.rs,native_menu.rs}`, `apps/gridcraft-web/src/main.rs`, `crates/engine/src/{io.rs,lib.rs,sample.rs,catalog.rs}`, `crates/engine/src/cmd/*.rs`, `crates/xlsx/src/{lib.rs,read.rs,write.rs,csv.rs,crypto.rs,passthrough.rs,pivot.rs,chart.rs,chartex.rs,package.rs}`, `crates/xlsx/src/{xls,xlsb.rs,ods.rs}`, `crates/pdf/src/{lib.rs,tests.rs}`, `crates/mcp/src/{tools.rs,server.rs,backend.rs}`, `crates/ui-egui/src/{control.rs,keymap.rs,ribbon.rs,lib.rs,dialogs.rs,grid.rs,panes.rs,i18n.rs,backstage.rs}`, `crates/ui-egui/src/i18n/*.rs`, `crates/ui-egui/src/keytips/keytips.json`, `crates/model/src/{features.rs,workbook.rs,sheet.rs}`, `crates/functions/src/`, `crates/calc/src/eval.rs`, `apps/gridcraft/Cargo.toml`. - Shared library: `craft-print` pinned from `storytold/craft-libs` at revision `d27646a5f7c8b4fc85d9dd3213b8c88b58e0088d` (`apps/gridcraft/Cargo.toml`) for native print submission; PDF generation stays in GridCraft (`crates/pdf`). - Deeper per-topic reference (repo docs): `docs/target-app-parity.md` (authoritative assessment), `docs/gaps.md` (ranked work list, partly stale), `docs/architecture.md` (layering), `docs/roadmap.md` (beta gates), `docs/parity-checklist.md` (generated from the catalog).