@spinabot/brigade 1.16.0 → 1.17.1

package/dist/core/ws-subscription-filter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws-subscription-filter.d.ts","sourceRoot":"","sources":["../../src/core/ws-subscription-filter.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,SAAS;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CACjC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,EAC1C,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,EAC5C,IAAI,EAAE,SAAS,GACb,OAAO,CAOT;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAO5D"}
+{"version":3,"file":"ws-subscription-filter.d.ts","sourceRoot":"","sources":["../../src/core/ws-subscription-filter.ts"],"names":[],"mappings":"AAcA,MAAM,WAAW,SAAS;IACzB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/B;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CACjC,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,EAC1C,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,EAC5C,IAAI,EAAE,SAAS,GACb,OAAO,CAkBT;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAO5D"}

package/dist/core/ws-subscription-filter.js

@@ -20,8 +20,19 @@ export function shouldDeliverFrame(agentSubs, sessionSubs, tags) {
         return true;
     if (agentId && agentSubs?.has(agentId))
         return true;
-    if (sessionId && sessionSubs?.has(sessionId))
-        return true;
+    if (sessionId && sessionSubs) {
+        // Exact match OR a sub-agent DESCENDANT session. A spawned sub-agent runs
+        // under a child key (`<parent>:subagent:<id>`, see routing/session-key.ts),
+        // so its pi frames + approval prompts must still reach the operator
+        // watching the parent turn — otherwise sub-agent activity is invisible and
+        // its `bash` approval prompt never surfaces (the turn then hangs on the
+        // approval timeout). The trailing ":" stops a sibling like `…:main2` from
+        // matching `…:main`.
+        for (const sub of sessionSubs) {
+            if (sessionId === sub || sessionId.startsWith(`${sub}:`))
+                return true;
+        }
+    }
     return false;
 }
 /** Cheap discriminator: pulls optional agentId/sessionId off a payload. */

package/dist/core/ws-subscription-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ws-subscription-filter.js","sourceRoot":"","sources":["../../src/core/ws-subscription-filter.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,uEAAuE;AACvE,qEAAqE;AACrE,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,sEAAsE;AAOtE,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CACjC,SAA0C,EAC1C,WAA4C,EAC5C,IAAe;IAEf,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IACpC,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,CAAC,SAAS,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,OAAO,IAAI,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,SAAS,IAAI,WAAW,EAAE,GAAG,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,OAAO,KAAK,CAAC;AACd,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAChD,MAAM,GAAG,GAAG,OAA4D,CAAC;IACzE,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAChE,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QAAE,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;IACtE,OAAO,IAAI,CAAC;AACb,CAAC"}
+{"version":3,"file":"ws-subscription-filter.js","sourceRoot":"","sources":["../../src/core/ws-subscription-filter.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,uEAAuE;AACvE,qEAAqE;AACrE,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,0EAA0E;AAC1E,0EAA0E;AAC1E,uEAAuE;AACvE,sEAAsE;AAOtE,qEAAqE;AACrE,MAAM,UAAU,kBAAkB,CACjC,SAA0C,EAC1C,WAA4C,EAC5C,IAAe;IAEf,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC;IACpC,IAAI,CAAC,OAAO,IAAI,CAAC,SAAS;QAAE,OAAO,IAAI,CAAC;IACxC,IAAI,CAAC,SAAS,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,OAAO,IAAI,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC;IACpD,IAAI,SAAS,IAAI,WAAW,EAAE,CAAC;QAC9B,0EAA0E;QAC1E,4EAA4E;QAC5E,oEAAoE;QACpE,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,qBAAqB;QACrB,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC/B,IAAI,SAAS,KAAK,GAAG,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC;gBAAE,OAAO,IAAI,CAAC;QACvE,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAChD,MAAM,GAAG,GAAG,OAA4D,CAAC;IACzE,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAc,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;QAAE,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAChE,IAAI,OAAO,GAAG,CAAC,SAAS,KAAK,QAAQ;QAAE,IAAI,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;IACtE,OAAO,IAAI,CAAC;AACb,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spinabot/brigade",
-  "version": "1.16.0",
+  "version": "1.17.1",
   "description": "Brigade — your personal AI crew",
   "homepage": "https://brigade.spinabot.com",
   "author": "Spinabot <hello@brigade-agent.ai>",

package/skills/docx/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: docx
+description: Create and edit Microsoft Word (.docx) documents to a professional standard — reports, proposals, contracts, letters, memos — with custom styles, multi-level lists, styled/merged tables, headers/footers, table of contents, hyperlinks, footnotes, tracked changes and comments. Use when the user asks Brigade to make, write, draft, fill, redline, or edit a Word document or .docx file.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📝"
+      }
+  }
+---
+
+# docx — professional Word documents
+
+Pick the lightest path that meets the need. **Never declare a document done without opening/validating the result at least once** (see *Verify*).
+
+| Need | Path |
+|------|------|
+| Simple structured doc (headings, paragraphs, bullets, a basic table, an image) | **Path 1 — `make_document` tool** |
+| Anything richer (custom styles, numbered/multi-level lists, merged/shaded table cells, headers/footers, TOC, hyperlinks, footnotes, inline bold/italic/color, tracked changes, comments) | **Path 2 — script the `docx` library via `brigade exec-node`** |
+| Fill / redline an EXISTING branded `.docx` without disturbing its styling | **Path 3 — OOXML round-trip** |
+| Markdown → branded Word inheriting a corporate template | **Path 4 — `pandoc` (optional)** |
+
+---
+
+## Path 1 — quick structured doc (`make_document` tool)
+
+```
+make_document(format="docx", content={ title, sections:[{heading, level, paragraphs, bullets, table:{rows}, image:{path}}] })
+```
+Good for a fast first draft. It is deliberately limited (single-level bullets, string-only tables, no inline formatting). The moment you need more, go to Path 2 — don't fight the schema.
+
+## Path 2 — full power: script the `docx` library
+
+Brigade bundles the **`docx`** library (dolanmiu/docx). Write a CommonJS script and run it with **`brigade exec-node`**, which makes Brigade's bundled libraries `require()`-able from anywhere (no install):
+
+1. `write` a file `gen.cjs`.
+2. Run: `brigade exec-node gen.cjs`
+
+```js
+// gen.cjs — illustrative; adapt to the content
+const fs = require("node:fs");
+const {
+  Document, Packer, Paragraph, TextRun, HeadingLevel, AlignmentType,
+  Table, TableRow, TableCell, WidthType, BorderStyle, ShadingType,
+  LevelFormat, Header, Footer, PageNumber, TableOfContents, ExternalHyperlink,
+} = require("docx");
+
+const doc = new Document({
+  styles: { default: { document: { run: { font: "Calibri", size: 22 } } },     // size is half-points (22 = 11pt)
+    paragraphStyles: [{ id: "Body", name: "Body", run: { size: 22 }, paragraph: { spacing: { after: 160 } } }] },
+  numbering: { config: [{ reference: "nums", levels: [{ level: 0, format: LevelFormat.DECIMAL, text: "%1.", alignment: AlignmentType.START }] }] },
+  sections: [{
+    properties: { page: { size: { width: 12240, height: 15840 } } },           // US Letter, in DXA (1440 = 1 inch)
+    headers: { default: new Header({ children: [new Paragraph("Acme Corp — Confidential")] }) },
+    footers: { default: new Footer({ children: [new Paragraph({ children: [new TextRun("Page "), new TextRun({ children: [PageNumber.CURRENT] })] })] }) },
+    children: [
+      new Paragraph({ text: "Q3 Business Review", heading: HeadingLevel.TITLE }),
+      new TableOfContents("Contents", { hyperlink: true, headingStyleRange: "1-3" }),
+      new Paragraph({ text: "Summary", heading: HeadingLevel.HEADING_1 }),
+      new Paragraph({ children: [ new TextRun("Revenue was "), new TextRun({ text: "$1.2M", bold: true }), new TextRun(" — up 18%.") ] }),
+      new Paragraph({ text: "First item", numbering: { reference: "nums", level: 0 } }),
+      new Paragraph({ children: [ new ExternalHyperlink({ children: [new TextRun({ text: "Full data", style: "Hyperlink" })], link: "https://example.com" }) ] }),
+      new Table({
+        columnWidths: [4680, 4680],                                            // DXA, sum = content width
+        rows: [
+          new TableRow({ tableHeader: true, children: ["Metric","Value"].map((t) =>
+            new TableCell({ width: { size: 4680, type: WidthType.DXA }, shading: { type: ShadingType.CLEAR, fill: "D9E2F3" },
+              children: [new Paragraph({ children: [new TextRun({ text: t, bold: true })] })] })) }),
+          new TableRow({ children: ["Revenue","$1.2M"].map((t) =>
+            new TableCell({ width: { size: 4680, type: WidthType.DXA }, children: [new Paragraph(t)] })) }),
+        ],
+      }),
+    ],
+  }],
+});
+Packer.toBuffer(doc).then((buf) => { fs.writeFileSync(process.argv[2] || "out.docx", buf); console.log("wrote", process.argv[2] || "out.docx"); });
+```
+
+The `docx` library also supports: footnotes (`FootnoteReferenceRun` + `footnotes`), comments, **tracked changes** (`InsertedTextRun`/`DeletedTextRun` with `author`/`date`), multi-section layouts, page breaks, columns, internal bookmarks, and images inside table cells. Read its API as needed — anything Word can express, this can author.
+
+## Path 3 — fill / redline an EXISTING `.docx` (highest fidelity)
+
+To fill a branded company template or surgically edit a real document **without regenerating it** (which would drop the theme), use the OOXML round-trip — unzip, edit the XML, rezip. For plain placeholder/text swaps the **`edit_document` tool** (`replace_text` / `fill_template` / `append`) already does exactly this and is the first choice.
+
+For edits beyond text, script it via `brigade exec-node` with **`fflate`**:
+
+```js
+// edit.cjs — unzip → edit word/document.xml → rezip (styles/headers/theme untouched)
+const fs = require("node:fs");
+const { unzipSync, zipSync, strToU8, strFromU8 } = require("fflate");
+const zip = unzipSync(fs.readFileSync(process.argv[2]));
+let xml = strFromU8(zip["word/document.xml"]);
+xml = xml.replaceAll("{{client}}", "Acme Corp");          // fill placeholders in <w:t> runs
+zip["word/document.xml"] = strToU8(xml);
+fs.writeFileSync(process.argv[3], zipSync(zip));
+```
+
+Rules for raw OOXML edits:
+- Safe: replacing text inside `<w:t>`; pointing a run/paragraph at an **already-defined** `styleId`; appending `<w:p>`/`<w:r>` that reference existing styles.
+- **Do NOT** add a new part (image, hyperlink target, header) by hand — that also needs `[Content_Types].xml` + the matching `_rels/*.rels` updated atomically, or Word reports corruption. For those, regenerate with the `docx` library instead.
+- Tracked changes are `<w:ins>`/`<w:del>` as *siblings* of `<w:r>` (never inside a run); copy the original `<w:rPr>` into the change runs; keep edits minimal so an "accept all" yields exactly the intended text. Author yourself as "Brigade".
+
+## Path 4 — Markdown → branded Word (optional, needs `pandoc`)
+
+For long prose where the brand styling lives in a corporate `.docx`, if `pandoc` is installed it inherits every style/margin/header:
+```bash
+command -v pandoc >/dev/null 2>&1 && pandoc input.md --reference-doc=brand-template.docx -o out.docx
+```
+Detect first; else fall back to Path 2. `pandoc` is GPL — a separate program shelled out to, never bundled.
+
+## Conventions that make output professional
+
+- **Page size is explicit** — US Letter `12240×15840` DXA (1440 DXA = 1"); landscape = portrait dims + `orientation` flip.
+- **Tables:** give both `columnWidths` (table) and per-cell `width` in **`WidthType.DXA`** (PERCENTAGE breaks some viewers), summing to content width; `ShadingType.CLEAR` (never SOLID → black boxes); add cell margins; never use a table as a horizontal rule (use a paragraph bottom border).
+- **Lists:** real numbering config for numbered/multi-level lists; never paste literal "1." / "•" characters.
+- Prefer bullets + tables over walls of text; one `TITLE`, then `HEADING_1..3` with proper outline levels (required for a working TOC).
+- Use typographic quotes (' ' " ") and en/em dashes.
+
+## Verify (required)
+
+After writing, confirm the file exists and is non-trivial. If LibreOffice is available, render to PDF and **look at it** — fix overflow/placeholder leftovers, then re-verify:
+```bash
+command -v soffice >/dev/null 2>&1 && soffice --headless --convert-to pdf out.docx
+```
+TOC/page-number fields show blank until Word (or a `soffice` convert) recalculates them — note this to the user if you can't run the convert. Never declare success without at least one look-and-fix pass.

package/skills/pdf/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: pdf
+description: Create and edit PDFs to a professional standard — generate from content, draw vector/precise layouts, embed custom (incl. CJK/Unicode) fonts, CREATE and fill AcroForm fields (text/checkbox/radio/dropdown), flatten, merge/split/rotate, stamp/watermark, encrypt, and extract text. Use when the user asks Brigade to make a PDF, fill or build a PDF form, or combine/split/stamp/secure PDFs.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📄"
+      }
+  }
+---
+
+# pdf — professional PDFs
+
+| Need | Path |
+|------|------|
+| Simple content PDF (title, headings, paragraphs, image) | **Path 1 — `make_document` tool** |
+| Fill an existing form, merge/split/stamp/watermark | **Path 2 — `edit_document` tool** |
+| Form-field CREATION, vector drawing, embedded fonts (bold/CJK), precise layout, encryption, page surgery | **Path 3 — script `@cantoo/pdf-lib` via `brigade exec-node`** |
+| Pixel-perfect, brand-styled layout from HTML/CSS | **Path 4 — HTML→PDF (optional binary)** |
+
+> Note: PDF is a *final* format with no reflow engine. If the recipient must edit, deliver the editable source (`.docx`/`.xlsx`) **and** the PDF.
+
+---
+
+## Path 1 — quick content PDF (`make_document` tool)
+
+```
+make_document(format="pdf", content={ title, pages:[{ heading, paragraphs, image:{path} }] })
+```
+Flow layout, US-Letter, single column, word-wrapped. Good for reports/summaries/letters. For forms, precise layout, or custom fonts → Path 3.
+
+## Path 2 — edit an existing PDF (`edit_document` tool)
+
+- `fill_form {fields}` — fill existing AcroForm fields by name (text/checkbox/dropdown).
+- `merge {pdfs}` / `add_pages {pdfs}` · `split {pages}` · `remove_pages {pages}`.
+- `stamp {text}` · `watermark {text}` (45° translucent).
+
+**Form decision:** first detect whether the PDF has real fillable fields. If it does → fill them (clean, type-validated). If it's a flat/scanned form (no fields) → you must draw text at coordinates instead (Path 3, annotations) — never assume fields exist.
+
+## Path 3 — full power: script `@cantoo/pdf-lib`
+
+Brigade bundles **`@cantoo/pdf-lib`** (a maintained pdf-lib fork — note the scoped name) plus **`@pdf-lib/fontkit`** (custom-font embedding) and **`unpdf`** (text extraction). `write` a `gen.cjs`, run `brigade exec-node gen.cjs`:
+
+```js
+// gen.cjs — illustrative
+const fs = require("node:fs");
+const { PDFDocument, StandardFonts, rgb } = require("@cantoo/pdf-lib");
+
+(async () => {
+  const pdf = await PDFDocument.create();
+
+  // embed a custom font (real bold / CJK / Unicode) — requires fontkit
+  // const fontkit = require("@pdf-lib/fontkit"); pdf.registerFontkit(fontkit);
+  // const font = await pdf.embedFont(fs.readFileSync("Brand-Bold.ttf"));
+  const font = await pdf.embedFont(StandardFonts.HelveticaBold);
+
+  const page = pdf.addPage([612, 792]);                 // US Letter; origin is BOTTOM-LEFT, y-up
+  page.drawText("Invoice", { x: 54, y: 720, size: 22, font, color: rgb(0.1, 0.1, 0.1) });
+  page.drawRectangle({ x: 54, y: 700, width: 504, height: 1, color: rgb(0.8, 0.8, 0.8) }); // vector rule
+
+  // CREATE fillable form fields
+  const form = pdf.getForm();
+  const name = form.createTextField("client.name");
+  name.addToPage(page, { x: 120, y: 640, width: 300, height: 18 });
+  const agree = form.createCheckBox("agree");
+  agree.addToPage(page, { x: 54, y: 600, width: 14, height: 14 });
+  // form.flatten();                                     // bake fields into static content if no further filling
+
+  fs.writeFileSync(process.argv[2] || "out.pdf", await pdf.save());
+  console.log("wrote");
+})();
+```
+
+`@cantoo/pdf-lib` covers: draw text/lines/rects/ellipses/SVG paths/images; embed custom TTF/OTF fonts (subset, full Unicode); **create AND fill** AcroForm text/checkbox/radio/dropdown/option-list fields; flatten; copy/merge/split/rotate pages; metadata; **password encryption** (the reason this fork is bundled). Extract text/structure with `unpdf`.
+
+**Coordinate gotcha:** pdf-lib origin is **bottom-left, y-up**. If you author field positions from a top-left image/spec, convert: `y_pdf = pageHeight - y_top - height`. One coordinate convention per script.
+
+## Path 4 — pixel-perfect / branded PDF from HTML+CSS (optional)
+
+pdf-lib has **no HTML/CSS layout engine** — for a designed, brand-styled document, render HTML→PDF. Use whatever is present (detect first):
+```bash
+command -v soffice >/dev/null 2>&1 && soffice --headless --convert-to pdf brand.html      # LibreOffice route
+```
+A headless browser (Puppeteer/Playwright `page.pdf()`) is the higher-fidelity alternative if installed. Prefer Path 1/3 unless the brand design genuinely requires CSS.
+
+## Conventions
+
+- Use real AcroForm fields when filling a fillable PDF; only fall back to drawn-text annotations for flat/scanned forms.
+- Embed a font for anything beyond basic Latin — standard PDF fonts lack bold-as-a-face and all CJK/emoji (missing glyphs render as boxes).
+- Keep ≥0.5" margins; align to a grid; don't rely on text reflowing (there's no engine — you place it).
+
+## Verify (required)
+
+Confirm the output exists and opens. For filled/created forms, re-open and read back the field values (or render to an image with `soffice`/a viewer and look at placement) before declaring done — never fill or place blind.

package/skills/xlsx/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: xlsx
+description: Build and edit professional Excel (.xlsx) spreadsheets, workbooks, and simple financial models — live formulas, number/date/currency formats, cell styling, conditional formatting, data-validation dropdowns, named ranges, frozen panes, merged cells, multi-sheet. Use when the user asks Brigade to make, fill, update, model, or edit a spreadsheet, workbook, or .xlsx file.
+metadata:
+  {
+    "brigade":
+      {
+        "emoji": "📊"
+      }
+  }
+---
+
+# xlsx — professional spreadsheets & models
+
+| Need | Path |
+|------|------|
+| Simple table / multi-sheet dump (headers + rows, optional per-column number format) | **Path 1 — `make_document` tool** |
+| Live formulas, cell styling, conditional formatting, dropdowns, named ranges, freeze panes, merged cells, dates | **Path 2 — script the `exceljs` library via `brigade exec-node`** |
+| Surgical edits to an existing workbook | **Path 3 — `edit_document` tool** |
+| Guarantee no formula errors / get computed values | **Path 4 — recalc-verify loop (optional `soffice`)** |
+
+**The two non-negotiable rules** (they separate a real model from a hack):
+1. **Formulas, never hardcoded results.** Write the Excel formula string (`=B5*(1+$B$6)`), never compute the number in code and paste a literal — so the sheet stays live when inputs change. This applies to every total, percentage, ratio, and growth.
+2. **Numbers are numbers.** Store `1200000`, format for display (`$#,##0`) — never the string `"$1.2M"`, or it won't sum or sort.
+
+---
+
+## Path 1 — quick table (`make_document` tool)
+
+```
+make_document(format="xlsx", content={ sheets:[{ name, header, rows, numberFormats }] })
+```
+Cells may be `string | number | {formula, numFmt}`. Fine for a straight data table. For styling, validation, charts, or a model → Path 2.
+
+## Path 2 — full power: script the `exceljs` library
+
+Brigade bundles **`exceljs`**. `write` a `gen.cjs`, then run `brigade exec-node gen.cjs`:
+
+```js
+// gen.cjs — illustrative
+const ExcelJS = require("exceljs");
+const wb = new ExcelJS.Workbook();
+const ws = wb.addWorksheet("Model", { views: [{ state: "frozen", ySplit: 1 }] });   // freeze header row
+
+ws.columns = [
+  { header: "Item", key: "item", width: 28 },
+  { header: "FY24 ($)", key: "v", width: 16, style: { numFmt: "$#,##0" } },
+];
+ws.getRow(1).font = { bold: true };
+ws.getRow(1).fill = { type: "pattern", pattern: "solid", fgColor: { argb: "FFD9E2F3" } };
+
+// Assumptions block — blue font marks hardcoded INPUTS (banker convention)
+ws.getCell("E1").value = "Growth"; ws.getCell("E2").value = 0.18;
+ws.getCell("E2").numFmt = "0.0%"; ws.getCell("E2").font = { color: { argb: "FF0000FF" } };
+wb.definedNames.add("Model!$E$2", "growth");                                        // named range
+
+ws.addRow({ item: "Revenue", v: 1200000 });
+ws.addRow({ item: "Next year", v: { formula: "B2*(1+growth)" } });                  // FORMULA, references the named input
+ws.getCell("B3").font = { color: { argb: "FF000000" } };                            // black = formula
+
+// dropdown + conditional formatting
+ws.getCell("A6").dataValidation = { type: "list", allowBlank: false, formulae: ['"Low,Med,High"'] };
+ws.addConditionalFormatting({ ref: "B2:B3", rules: [
+  { type: "cellIs", operator: "lessThan", formulae: ["0"], style: { font: { color: { argb: "FFFF0000" } } } } ]});
+
+wb.xlsx.writeFile(process.argv[2] || "out.xlsx").then(() => console.log("wrote"));
+```
+
+`exceljs` covers: number/date formats, font/fill/border/alignment, conditional formatting, data-validation dropdowns, named ranges, freeze panes, autofilter, merged cells, images, sheet protection, multi-sheet. Dates: pass a real `new Date(...)` and set a date `numFmt` (don't pass a string).
+
+## Path 3 — edit an existing workbook (`edit_document` tool)
+
+- `set_cells {sheet?, cells:[{ref|row,col, value, numFmt?}]}` — surgical edits; other sheets untouched.
+- `append_rows {sheet?, rows}` — grow a table.
+When editing someone's workbook, **match its existing conventions exactly** (column order, units, formats) — the template always wins over the defaults here.
+
+## Path 4 — recalc-verify loop (the quality guarantee)
+
+`exceljs` stores formula **strings but does not evaluate them** — a typo (`#REF!`, `#DIV/0!`) is invisible until the file is opened. If LibreOffice is present, force a recalc and inspect; otherwise hand-check ranges and keep formulas simple.
+
+```bash
+command -v soffice >/dev/null 2>&1 && soffice --headless --convert-to pdf --outdir /tmp out.xlsx   # then read the PDF: no #REF!/#DIV/0! anywhere
+```
+Loop: build → recalc → if any error token appears, fix the formula → recalc again. Target: **zero formula errors** in the delivered file.
+
+## Conventions (banker-grade, optional but professional)
+
+- Cell-color convention: **blue font = hardcoded inputs**, black = formulas, green = links to other sheets, red = links to external files; yellow fill = key assumptions.
+- Isolate assumptions in their own cells and reference them **absolutely** (`$B$6`) or by **named range**; document any sourced hardcode in a cell comment ("Source: 10-K FY24 p.45").
+- Number formats: currency `$#,##0` with units in the header; percentages `0.0%`; multiples `0.0x`; negatives in parentheses; years as text.
+
+## Verify (required)
+
+Re-open with `edit_document`/read or confirm the file unzips with the expected sheet names; if you used formulas, run the Path-4 recalc and confirm zero errors before declaring done.