From ee7040a340e01ff50428c99b3531a7b6653694fc Mon Sep 17 00:00:00 2001
From: prxnvt <53838599+prxnvt@users.noreply.github.com>
Date: Wed, 21 Oct 2026 15:29:54 -0400
Subject: [PATCH] Docs: macro format and storage

---
 docs/macros.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 docs/macros.md

diff --git a/docs/macros.md b/docs/macros.md
new file mode 100644
index 000000000..99050b0aa
--- /dev/null
+++ b/docs/macros.md
@@ -0,0 +1,60 @@
+# Macros
+
+> **Last updated:** 2026-10-21 · **Change:** major (created: the macro format and storage)
+
+GridCraft macros are typed, declarative lists of commands, not VBA. Every step runs a GridCraft
+command (the same ids the ribbon, CLI and MCP use) or one of three bounded control steps. A macro
+declares the inputs it works on.
+
+This page describes the macro format and how macros are saved in a workbook. Step parameters
+can hold tokens such as `Input` and `Output`; the engine does not resolve or run them in this
+version.
+
+## A macro
+
+```json
+{
+  "name": "Totals",
+  "description": "Adds a total next to the amounts",
+  "inputs": [{"name": "Input", "header": true, "cols": [2, 2], "colTypes": ["text", "number"]}],
+  "output": {"anchor": "Input.right(2).cell(1,2)", "onConflict": "ask"},
+  "steps": [
+    {"type": "command", "id": "cell.set", "params": {"cell": "Output", "input": "Total"}},
+    {"type": "command", "id": "cell.set", "params": {"cell": "Output.offset(1,0)", "input": "=SUM({{Input.data.col(2)}})"}},
+    {"type": "repeat", "over": "Input.data", "of": "rows", "max": 1000, "body": [
+      {"type": "if", "cell": "Row.cell(1,2)", "op": "gt", "value": 100,
+       "then": [{"type": "command", "id": "home.bold", "params": {"range": "Row"}}]}
+    ]},
+    {"type": "stop", "message": "Done."}
+  ],
+  "permissions": []
+}
+```
+
+- **Steps**: `command` (`id`, `params`), `repeat` (each row or column of `over`, at most `max`
+  times), `if` (`cell` compared with `value` by `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `empty`,
+  `notEmpty` or `contains`; `then` and `else` lists) and `stop` (`message`; `rollback: true`
+  undoes the run). Every step can carry `enabled`, `breakpoint` and `note`. The short form
+  `{"command": "cell.set", "params": {…}}` is accepted for a command step.
+- **Inputs**: `kind` (`cell` or `range`), `rows` and `cols` as `[min, max]` (0 for no maximum;
+  rows exclude the header), `header`, `colTypes` (`number`, `text`, `date`, `bool`, `any`),
+  `nonEmpty` and `defaultRef`. A run binds each input to the range it is given, its default, or
+  (for the first input) the selection, and refuses with messages that name the cells:
+  "Input column 2 (Amount) must hold numbers; C4 holds text."
+- **Limits**: 1,000 macros a workbook, 10,000 steps a macro, and Repeat and If nested 4 deep.
+
+## Storage
+
+Macros are saved in the workbook: as a field in GridCraft's JSON format, and in xlsx as hidden
+defined names (`_gc_macro_<n>_<k>`, the macro's JSON split into string literals within Excel's
+limits), which other spreadsheet applications keep but do not run.
+
+## Automate scripts and VBA
+
+Automate scripts (`automate.recordActions`, `newScript`, `allScripts`, `runScript`,
+`deleteScript`) are an older, separate feature. They keep their commands, parameters, storage
+(`_sc_scripts`) and results, and View › Macros (`view.macros`) still lists them. Macros neither
+read nor change them; a workbook can hold a script and a macro with the same name.
+
+A VBA project in an `.xlsm` or `.xltm` file is preserved on save and never run. GridCraft macros
+are stored apart from it.