@particle-academy/holy-sheet 2.9.0 → 2.10.1

package/dist/index.d.cts

@@ -264,7 +264,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.9.0";
+declare const VERSION = "2.10.1";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -327,6 +327,12 @@ declare const Agent: {
      * `meta.created` and its written copy.
      */
     equivalent(a: Any$6, b: Any$6): boolean;
+    /**
+     * The agent guide: what makes this kind of file professional, and the schema
+     * idioms that produce it. Give it to a model with the schema; it works with any
+     * agent loop. Byte-identical to the PHP package's agent-guide/professional-workbooks.md.
+     */
+    guide(): string;
     version(): string;
 };
 
@@ -336,7 +342,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.9.0";
+    static readonly VERSION = "2.10.1";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;

package/dist/index.d.ts

@@ -264,7 +264,7 @@ interface SetMetaOp {
 }
 
 /** This package's own version, pinned to package.json by `version.test.ts`. */
-declare const VERSION = "2.9.0";
+declare const VERSION = "2.10.1";
 type Any$6 = any;
 /**
  * Agent — the structured-tool surface for Holy Sheet. Mirrors PHP `Agent`.
@@ -327,6 +327,12 @@ declare const Agent: {
      * `meta.created` and its written copy.
      */
     equivalent(a: Any$6, b: Any$6): boolean;
+    /**
+     * The agent guide: what makes this kind of file professional, and the schema
+     * idioms that produce it. Give it to a model with the schema; it works with any
+     * agent loop. Byte-identical to the PHP package's agent-guide/professional-workbooks.md.
+     */
+    guide(): string;
     version(): string;
 };
 
@@ -336,7 +342,7 @@ type Any$5 = any;
  * over `Agent`. Provided for parity / DI ergonomics; most callers use `Agent`.
  */
 declare class HolySheet {
-    static readonly VERSION = "2.9.0";
+    static readonly VERSION = "2.10.1";
     validate(schema: Any$5): ValidationError[];
     toBytes(schema: Any$5): Uint8Array;
     write(schema: Any$5, path: string): Promise<WriteResult>;

package/dist/index.js

@@ -1,3 +1,8 @@
+// src/agent-guide.json
+var agent_guide_default = {
+  guide: '# Agent guide: professional workbooks with holy-sheet\n\n<!--\n  The agent guide for holy-sheet: what makes a workbook professional, and the\n  schema idioms that produce it. Canonical copy: the PHP package\'s\n  agent-guide/professional-workbooks.md; the Node and Python packages carry the same\n  bytes (a test in each pins the hash). Distilled from rubric-judged builds in\n  the Fancy document lab -- every rule here moved a measured score.\n-->\n\n## How to use this guide\n\nIt is written for an agent and works with any agent loop. Give it to the model\nas part of its instructions (a system prompt, a skill, a rules file), together\nwith the package\'s JSON schema (`Agent::toolDefinition()` / `Agent.toolDefinition()` / `tool_definition()`). Then the procedure is:\n\n1. Read the schema once and plan a workbook in full: structure, every figure,\n   every derived number, computed and checked before anything is written.\n2. Build the whole JSON in one go, following the recipes below.\n3. Check it: `Agent::validate` (PHP), `Agent.validate` (Node) or `validate` (Python) returns errors with a hint each.\n4. Write it (`Agent::write` / `Agent.toBytes` / `to_bytes`). If you can render the file and look at it, do,\n   but repair only what you can see is wrong: one-shot "improvements" made\n   blind regressed more documents than they fixed.\n\nYou are building a workbook a CFO would forward to the board UNCHANGED. Meeting the\nbrief is the floor. A table of the given numbers is a data dump; a professional\nsheet tells the reader what it is, what the numbers mean, and how they were derived.\n\n## The bar (every item is required)\n\n1. **Title block.** Row 1: what the sheet is. Row 2: period, units/currency, source\n   and as-of date. A reader who sees only this sheet knows exactly what it shows.\n2. **Analysis, not just data.** Add the columns a reader needs to interpret the\n   figures: share of total, variance vs average or target, rank. All as FORMULAS.\n3. **Formulas for everything derived.** Totals, averages, shares, variances. Never a\n   typed number where a formula belongs.\n4. **Headers sit over their data.** Text columns left-aligned, numeric columns\n   right-aligned, header cells aligned the same way as the data below them.\n5. **Totals are distinct.** Bold, a top border, a light fill, and a clear label\n   ("Total", "Average growth (simple)").\n6. **Formats.** Currency with the right decimals (whole dollars for millions-scale\n   board figures unless cents matter), percentages to 1 decimal, ISO or written dates.\n   Negative values in a warning colour.\n7. **Usable.** Frozen panes below the header row, widths that fit every value (never ####),\n   a notes block stating method and definitions.\n\n## Never ship\n\n- A placeholder ("TBD", "[date]"). Name the period instead.\n- Rounded figures that disagree with the source. Board figures given to the cent show\n  cents (decimals 2) unless you round consistently AND say "rounded" in the title block.\n- A sheet that prints across two pages. Keep the used width within ~7 inches\n  (about 650 px of columnWidths in total) and keep every text cell short: one note per\n  row, at most ~95 characters, so nothing spills past the table\'s right edge.\n\n## Layout: use the `cells` model for a professional sheet\n\n`columns` forces the header into row 1, which leaves no room for a title block. Build\nthe sheet from `cells` (keys are A1 addresses) instead:\n\n- A1 title: `{value:"Q3 2026 Revenue by Region", format:{bold:true, fontSize:16, color:"#111827"}}`,\n  merged across the table: `mergedRegions:[{start:"A1", end:"E1"}]`.\n- A2 subtitle: `{value:"Quarter ended 30 Sep 2026 | USD | Source: management accounts", format:{italic:true, color:"#6B7280"}}`, merged A2:E2.\n- Row 4 header: each cell `{value:"Revenue", format:{bold:true, color:"#FFFFFF", backgroundColor:"#1F2937", textAlign:"right"}}`\n  (textAlign "left" for text columns).\n- Data rows from row 5: `{value:1250000.5, format:{displayFormat:"currency", decimals:0}}`,\n  `{value:0.184, format:{displayFormat:"percentage", decimals:1}}`.\n- Derived cells: `{formula:"B5/B$8", format:{displayFormat:"percentage", decimals:1}}`\n  (formula WITHOUT a leading "=").\n- Total row: `{formula:"SUM(B5:B7)", format:{bold:true, displayFormat:"currency", decimals:0, borderTop:"#111827", backgroundColor:"#F3F4F6"}}`,\n  and style the label and blank cells in that row the same way so the band is continuous.\n- Notes last (below the chart, when there is one): `{value:"Notes", format:{bold:true}}`\n  then one definition per row in `#4B5563` (dark enough to read; not pale grey italic).\n- `frozenRows: 4` (title block + header stay visible), `columnWidths` in pixels:\n  labels ~180, currency ~150, percentages ~110, dates ~120.\n- Breathing room: `rowHeights` in pixels by row NUMBER -- title row 36, header row 30,\n  data rows 24, total row 28: `{"1": 36, "4": 30, "5": 24, "6": 24, "7": 24, "8": 28}`.\n  Packed default rows read as a data dump.\n- Banding: give alternate data rows a very light fill (`backgroundColor:"#F9FAFB"`) and\n  every data row a hairline bottom border (`borderBottom:"#E5E7EB"`), so the eye can\n  follow a row across.\n- Print: a one-page summary (table, key point, chart, notes) is\n  `print:{orientation:"portrait", fitToPage:true, footer:{left:"Q3 2026 Revenue Review",\n  right:"Page {page} of {pages}"}}` -- `fitToPage` scales the whole sheet onto ONE page,\n  so the page break can never cut the chart in half. Only a long data table (more than\n  ~40 rows) uses `fitToWidth:true` instead, and then its chart goes on its own sheet.\n  Use landscape when the table is wider than ~650px. Every workbook carries a print setup.\n\n## A chart, whenever the point is a comparison\n\nA board reader sees a comparison faster in a chart than in a column of figures, and\nreviewers mark a comparison sheet down when it has none. Add ONE native chart per\ncomparison (a real Excel chart over the cells, not a picture: it updates when the\nfigures change):\n\n```\ncharts: [{\n  type: "bar",\n  title: "EMEA delivered 48% of Q3 revenue",\n  categories: "A5:A7",\n  series: [{name: "Revenue", values: "B5:B7", color: "#94A3B8",\n            points: [{index: 2, color: "#1F3A5F"}]}],\n  dataLabels: true,\n  format: "$#,##0.00",\n  position: {from: "A11", to: "F27"}\n}]\n```\n\n- **Highlight the point the title is about.** Every bar one colour does not say\n  which bar matters. Give the series a muted colour (`#94A3B8`) and the subject of\n  the title -- the leader, the outlier, the line over budget -- the strong colour\n  with `points: [{index, color}]` (index is 0-based within `values`). Flag\n  over-budget or missed-target points in red (`#DC2626`).\n- **Labels show what the table shows.** The chart\'s `format` uses the SAME decimals\n  as the cells it plots: a table in cents and a label rounded to dollars read as two\n  different numbers. For millions, label in millions and say so in the title\n  ("$M") -- never a rounded label beside an exact cell.\n\n- **Type.** `bar` (horizontal) for categories with names longer than a word, and for\n  ranking; `column` for up to ~6 short categories; `line` for a trend over time\n  periods; `pie` only for 2-5 parts of one whole, and never when a value is negative.\n- **Ranges are the data rows only**, never the header or the total row: a total\n  plotted beside its parts dwarfs them.\n- **Title states the finding**, like the key point ("EMEA led Q3 revenue"), not\n  the axis ("Revenue by region").\n- **One series, one colour** (the sheet\'s header colour). Add a second series only\n  when the comparison is between the two series; the legend appears by itself.\n- **dataLabels: true** with `format` matching the cells (`"$#,##0"`, `"0.0%"`), so\n  the reader does not have to read values off an axis.\n- **Place it directly below the key point**, starting in column A, about 6 columns\n  wide and 16 rows tall (`from: "A{row}"`, `to: "F{row+16}"`), and put the notes\n  BELOW the chart. The chart sits next to the table it summarises; the notes\n  that define terms come last. Beside the table it widens the printed page; on top\n  of cells it hides them. With `fitToPage` the whole stack prints on one page.\n\n## Recipes\n\n- **Board summary sheet:** title block; a table with value, share of total, change and\n  variance vs average; total row; a one-line "Key point" cell above the notes stating\n  the finding in words (e.g. "EMEA delivered 48.5% of revenue and grew fastest").\n- **Model with inputs:** an "Inputs" block (light yellow fill #FEF9C3 on input cells,\n  labelled), calculations referencing the inputs by cell, outputs in a separate\n  clearly labelled block. Use separate sheets when the model is larger than one screen.\n- **Detail + summary:** a "Summary" sheet first (the one that opens), a "Data" sheet with\n  the full table; the summary\'s figures are formulas into Data.\n\n## Failures we have seen (do not repeat)\n\n- No title, period, units or source: a CFO cannot forward it. -> Title block, always.\n- Header labels left-aligned over right-aligned numbers. -> Align headers with data.\n- Only the given numbers, nothing derived. -> Add share, variance, rank.\n- An "average growth" that is an unweighted mean presented as if it were the total\n  growth. -> Label it precisely, or compute the weighted figure.\n- Footnote in tiny grey italics as the only context. -> Title block plus notes.\n- A column repeating the same value on every row (a date already in the subtitle). -> Drop it.\n- One label doing two jobs ("Total revenue / average growth"). -> One row per measure,\n  each with its own label and styling.\n- A long "key point" sentence in one cell running across the page. -> Merge it across\n  the table width (mergedRegions) and keep it to one line of the table\'s width.\n\n- A chart split across two printed pages. -> `fitToPage: true`.\n- All bars one colour, so the flagged or leading item does not stand out. -> `points`.\n- A threshold "input" cell whose flag colours did not follow it (fills are static).\n  -> Add an input only when everything it drives is a FORMULA (a Status column\n  `IF(D6>$B$3,"Over","Within")`); state the threshold in the notes otherwise.\n- A total row with blank cells under columns that have a year-end or overall value.\n  -> Fill every column of the total row with its overall figure, or a dash, never blank.\n- A "vs average" column of percentages with no unit. -> Name percentage points in the\n  header ("vs avg (pp)").\n- Two versions of one measure (simple and weighted average) with no headline. -> Label\n  one as the headline and say why in the notes.\n\n## Before you write the workbook, check\n\nTitle and subtitle present and merged; every derived value a formula with a correct\nrange; header alignment matches data; totals band continuous; widths fit; frozen\npanes set; negative figures coloured; a chart for the comparison over the data rows\nonly, with its subject highlighted and labels matching the cells; `fitToPage` on a\none-page summary; numbers re-added by hand once. Then write once.\n'
+};
+
 // src/util.ts
 function isNumericString(v) {
   if (typeof v === "number") return Number.isFinite(v);
@@ -4472,7 +4477,8 @@ var ChartXml = {
     } else {
       plot = `<c:barChart><c:barDir val="${type === "bar" ? "bar" : "col"}"/><c:grouping val="clustered"/><c:varyColors val="0"/>` + series + labels + '<c:gapWidth val="80"/><c:axId val="10"/><c:axId val="20"/></c:barChart>';
     }
-    const axesXml = type === "pie" ? "" : axes(type === "bar", chart.format);
+    const zeroBase = type !== "line" && nonNegative(chart, workbook);
+    const axesXml = type === "pie" ? "" : axes(type === "bar", chart.format, zeroBase);
     const legend = chart.legend ?? (chart.series.length > 1 || type === "pie");
     const title = chart.title !== null ? `<c:title><c:tx><c:rich><a:bodyPr/><a:lstStyle/><a:p><a:pPr><a:defRPr sz="1200" b="1"/></a:pPr><a:r><a:rPr lang="en-US" sz="1200" b="1"/><a:t>${text(chart.title)}</a:t></a:r></a:p></c:rich></c:tx><c:overlay val="0"/></c:title><c:autoTitleDeleted val="0"/>` : '<c:autoTitleDeleted val="1"/>';
     return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><c:chartSpace xmlns:c="${NS_C}" xmlns:a="${NS_A}" xmlns:r="${NS_R}"><c:roundedCorners val="0"/><c:chart>` + title + "<c:plotArea><c:layout/>" + plot + axesXml + "</c:plotArea>" + (legend ? '<c:legend><c:legendPos val="b"/><c:overlay val="0"/></c:legend>' : "") + '<c:plotVisOnly val="1"/><c:dispBlanksAs val="gap"/></c:chart><c:spPr><a:noFill/><a:ln><a:noFill/></a:ln></c:spPr>' + textProps("595959", 900) + "</c:chartSpace>";
@@ -4533,11 +4539,14 @@ function dataLabels(type, format) {
   const pos = type === "line" ? "t" : type === "pie" ? "bestFit" : "outEnd";
   return "<c:dLbls>" + (format !== null ? `<c:numFmt formatCode="${attr2(format)}" sourceLinked="0"/>` : "") + "<c:spPr><a:noFill/><a:ln><a:noFill/></a:ln></c:spPr>" + textProps("404040", 900) + `<c:dLblPos val="${pos}"/><c:showLegendKey val="0"/><c:showVal val="1"/><c:showCatName val="0"/><c:showSerName val="0"/><c:showPercent val="0"/><c:showBubbleSize val="0"/></c:dLbls>`;
 }
-function axes(horizontal, format) {
+function nonNegative(chart, workbook) {
+  return chart.series.every((s) => values(s.values, workbook).every((v) => typeof v !== "number" || !(v < 0)));
+}
+function axes(horizontal, format, zeroBase = false) {
   const catPos = horizontal ? "l" : "b";
   const valPos = horizontal ? "b" : "l";
   const numFmt = format !== null ? `<c:numFmt formatCode="${attr2(format)}" sourceLinked="0"/>` : '<c:numFmt formatCode="General" sourceLinked="1"/>';
-  return `<c:catAx><c:axId val="10"/><c:scaling><c:orientation val="${horizontal ? "maxMin" : "minMax"}"/></c:scaling><c:delete val="0"/><c:axPos val="${catPos}"/><c:numFmt formatCode="General" sourceLinked="1"/><c:majorTickMark val="none"/><c:minorTickMark val="none"/><c:tickLblPos val="low"/><c:spPr><a:ln w="9525"><a:solidFill><a:srgbClr val="BFBFBF"/></a:solidFill></a:ln></c:spPr><c:crossAx val="20"/><c:crosses val="autoZero"/><c:auto val="1"/><c:lblAlgn val="ctr"/><c:lblOffset val="100"/><c:noMultiLvlLbl val="0"/></c:catAx><c:valAx><c:axId val="20"/><c:scaling><c:orientation val="minMax"/></c:scaling><c:delete val="0"/><c:axPos val="${valPos}"/><c:majorGridlines><c:spPr><a:ln w="9525"><a:solidFill><a:srgbClr val="E5E7EB"/></a:solidFill></a:ln></c:spPr></c:majorGridlines>` + numFmt + `<c:majorTickMark val="none"/><c:minorTickMark val="none"/><c:tickLblPos val="nextTo"/><c:spPr><a:ln><a:noFill/></a:ln></c:spPr><c:crossAx val="10"/><c:crosses val="${horizontal ? "max" : "autoZero"}"/><c:crossBetween val="between"/></c:valAx>`;
+  return `<c:catAx><c:axId val="10"/><c:scaling><c:orientation val="${horizontal ? "maxMin" : "minMax"}"/></c:scaling><c:delete val="0"/><c:axPos val="${catPos}"/><c:numFmt formatCode="General" sourceLinked="1"/><c:majorTickMark val="none"/><c:minorTickMark val="none"/><c:tickLblPos val="low"/><c:spPr><a:ln w="9525"><a:solidFill><a:srgbClr val="BFBFBF"/></a:solidFill></a:ln></c:spPr><c:crossAx val="20"/><c:crosses val="autoZero"/><c:auto val="1"/><c:lblAlgn val="ctr"/><c:lblOffset val="100"/><c:noMultiLvlLbl val="0"/></c:catAx><c:valAx><c:axId val="20"/><c:scaling><c:orientation val="minMax"/>` + (zeroBase ? '<c:min val="0"/>' : "") + `</c:scaling><c:delete val="0"/><c:axPos val="${valPos}"/><c:majorGridlines><c:spPr><a:ln w="9525"><a:solidFill><a:srgbClr val="E5E7EB"/></a:solidFill></a:ln></c:spPr></c:majorGridlines>` + numFmt + `<c:majorTickMark val="none"/><c:minorTickMark val="none"/><c:tickLblPos val="nextTo"/><c:spPr><a:ln><a:noFill/></a:ln></c:spPr><c:crossAx val="10"/><c:crosses val="${horizontal ? "max" : "autoZero"}"/><c:crossBetween val="between"/></c:valAx>`;
 }
 function textProps(color2, size) {
   return `<c:txPr><a:bodyPr/><a:lstStyle/><a:p><a:pPr><a:defRPr sz="${size}"><a:solidFill><a:srgbClr val="${color2}"/></a:solidFill></a:defRPr></a:pPr><a:endParaRPr lang="en-US"/></a:p></c:txPr>`;
@@ -6120,7 +6129,7 @@ var holy_sheet_schema_default = {
 };
 
 // src/agent.ts
-var VERSION = "2.9.0";
+var VERSION = "2.10.1";
 function toU8(input) {
   return input instanceof Uint8Array ? input : new Uint8Array(input);
 }
@@ -6224,6 +6233,14 @@ var Agent = {
   equivalent(a, b) {
     return SheetDiff.equivalent(a, b);
   },
+  /**
+   * The agent guide: what makes this kind of file professional, and the schema
+   * idioms that produce it. Give it to a model with the schema; it works with any
+   * agent loop. Byte-identical to the PHP package's agent-guide/professional-workbooks.md.
+   */
+  guide() {
+    return agent_guide_default.guide;
+  },
   version() {
     return VERSION;
   }