@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/xlsx/docs/conventions-guide.md

@@ -0,0 +1,217 @@
+# conventions-guide — financial-model conventions for Excel outputs
+
+> The full rationale behind the tables in [`SKILL.md`](../SKILL.md) §5 —
+> color coding, number formatting, hardcode source documentation, formula
+> construction discipline, and template-preservation rules. Anything that
+> reviewers would otherwise ask "why this and not that" goes here so the
+> SKILL stays a quick scan and the deeper material is one click away.
+
+## 1. Color coding
+
+Default palette unless the user or the existing template overrides it.
+Black is intentionally listed first: a reviewer scanning the workbook
+should see one color signaling "this is computed", one signaling "this
+is an input I can change", and three signaling links of increasing
+risk. The anti-pattern column captures the way each color is most often
+misused in the wild.
+
+| Color | RGB | Meaning | Anti-pattern |
+|---|---|---|---|
+| Black | `0,0,0` | Every formula and computed result | Setting `=A1+B1` to blue makes the reviewer think it is a manual input |
+| Blue | `0,0,255` | Hard-coded inputs and scenario assumptions | Setting `=Sheet2!A1` (a sheet link) to blue makes it look like an assumption |
+| Green | `0,128,0` | Same-workbook cross-sheet links | Setting `=[Other.xlsx]Sheet1!A1` to green hides the external dependency signal |
+| Red | `255,0,0` | Cross-file external links | Setting same-sheet `=A1` to red implies a fake external dependency |
+| Yellow (fill) | `255,255,0` background | Critical assumptions awaiting review | Coloring every cell yellow drowns out the cells that actually need a second look |
+
+Why "Black first": when a reviewer opens a model the first thing they
+look for is whether any formula was accidentally typed as a number.
+Putting black at the top of the legend mirrors that scan order.
+
+## 2. Number formatting
+
+Default formats unless the existing template specifies otherwise.
+"Rationale" is what to point at when a reviewer asks why a column looks
+the way it does.
+
+| Type | Format | Rationale |
+|---|---|---|
+| Year | text (`"FY2025"`) | Numeric `2025` gets thousands-separated to `2,025` by the corporate template; storing as text disables the auto-format |
+| Currency | `$#,##0` or `¥#,##0` with the unit (`mm` / `bn` / `k`) in the header | The unit belongs in one place per column, not repeated on every cell — header `ARR (¥mm)` keeps the cells uncluttered |
+| Zero | `"$#,##0;($#,##0);-"` (or the `0.0%` equivalent) | A literal `0` reads as data; an em-dash reads as "zero by intent" — separates a missing value from a real zero |
+| Percentage | `0.0%` | One decimal is enough for reviewer scanning; `0.00%` reads as false precision, `0%` loses sign on small movements |
+| Multiple | `0.0x` | Used for valuation multiples (EV/EBITDA, P/S, P/E) and ratio-style headers like `Token unit price 1.2x` |
+| Negative | `(123)` (parentheses) | Accounting convention; minus signs blend into table grids and read as dashes at small font sizes |
+| Hardcode | `Source: …` annotation in the next column or as a cell comment (see §3) | Reviewer can audit every input back to its source without scrolling around |
+
+MiniMax-flavored sample headers: `ARR (¥mm)` / `Tokens (bn)` / `MAU
+(mm)` / `Token unit price 1.2x` / `MAU YoY 0.0%`. Keep the unit in the
+header, not in the cell.
+
+## 3. Hardcode `Source:` documentation
+
+Every hard-coded number should carry its provenance — either as a cell
+comment or as a string in the adjacent column. The grammar is fixed so
+downstream automation can grep for it:
+
+```
+Source: <system or document>, <date>, <locator>, <URL optional>
+```
+
+Five reference examples, spanning the source types reviewers see most:
+
+| Source type | Example string |
+|---|---|
+| 10-K filing | `Source: AAPL 10-K FY2024, 2024-11-01, "Net sales by segment" table, https://www.sec.gov/...` |
+| 10-Q filing | `Source: AAPL 10-Q FY2025 Q2, 2025-05-02, "Operating expenses" line 12` |
+| Internal BI dashboard | `Source: MiniMax internal BI - MAU Dashboard, 2025-09-30, "moonshot-mau" view` |
+| Interview transcript | `Source: User interview INT-2025-117, 2025-09-12, interviewee Z, page 4` |
+| Market data terminal | `Source: Wind Terminal, 2025-08-15, AAPL.O closing price` / `Source: Bloomberg, 2025-08-15, AAPL US Equity PX_LAST` |
+
+Date format is ISO `YYYY-MM-DD`; the locator must let a reader find the
+exact cell in the source within ~30 seconds.
+
+## 4. Formula construction rules
+
+**The foundational rule: every computed value is a formula, not a
+literal number.** Anything derivable from other cells — totals,
+averages, ratios, percent changes, growth projections, lookups,
+cross-sheet references — must be written as a live `=…` formula. Hard
+numbers belong in §3 inputs only. Pasting a pre-computed total
+(`125_430` instead of `=SUM(B2:B12)`) silently breaks the workbook
+the moment any input cell changes; recalc cannot detect this because
+the literal value evaluates fine — it just no longer reflects the
+data. The four sub-rules below build on top of this principle and add
+checks the model passes **before** running `scripts/recalc.py`.
+recalc only catches errors that have already crystallised into a
+`#REF!` / `#DIV/0!` marker; these checks catch the class of bugs that
+produce a *wrong but not erroring* number.
+
+**This rule applies regardless of how the value was computed during
+authoring.** Even if pandas / polars / numpy / a one-line list
+comprehension already produced the number in Python, the cell must
+still hold the `=` formula referencing the source cells, not the
+pre-computed result. The most common slip is loading raw data with
+pandas, computing a derived column (`df["arr"] = df["mau"] *
+df["price"]`), and writing the whole frame back with
+`df.to_excel(...)`; that ships static numbers and undoes every
+benefit of delivering a spreadsheet over a CSV. The right pattern is
+to write only the **input columns** with pandas (or skip pandas
+entirely and use openpyxl for everything), then emit each derived
+column as `=B2*C2` etc. on the openpyxl side.
+
+### 4.1 Assumption placement
+
+All adjustable inputs live in a single dedicated **Assumptions** block
+(usually a leading sheet or a clearly headlined region of the main
+sheet). Downstream formulas reference these cells with `$`-locked
+addresses so a fill-down does not silently skip them.
+
+```
+WRONG:  =B5 * 1.05                            // 5% growth hard-coded
+RIGHT:  =B5 * (1 + $B$6)                      // 5% growth lives in $B$6 (Assumptions)
+```
+
+Sensitivity analysis (changing one assumption and watching the model
+react) is impossible if the assumption is buried inside a formula.
+
+### 4.2 Off-by-one sanity check
+
+Every range in a `SUM`, `AVERAGE`, `COUNTIF`, etc. should be counted
+literally. `SUM(B2:B12)` covers eleven rows (`12 - 2 + 1`), not ten.
+The most common bug is summing only the first ten rows of an eleven-row
+table because the model author counted the gap rather than the cells.
+
+Quick check: open the formula bar, click into the range reference,
+LibreOffice highlights the cells — confirm the highlight matches the
+data block.
+
+### 4.3 Boundary value testing
+
+Before delivery, replace the lead inputs with edge cases and recalc:
+
+| Input | Why test |
+|---|---|
+| `0` | Catches `#DIV/0!` and "any percentage of zero is still zero" semantics |
+| Negative | Catches `LOG(<0)`, `SQRT(<0)`, and IRR convergence failures |
+| Very large | Catches integer overflow in xlsxwriter and float underflow in `LOG10` chains |
+| `NaN` (blank) | Catches `IFERROR` gaps and pandas → openpyxl conversion losses |
+| Empty string | Catches `VALUE("")` failures and silent string concatenation |
+
+Run `scripts/recalc.py` after each substitution. A real `errors_found`
+JSON is the cheapest signal — far cheaper than a reviewer noticing a
+silently-wrong percentile column three days later.
+
+### 4.4 Circular reference avoidance
+
+LibreOffice's `calculateAll()` fails loudly on circular references —
+`recalc.py` will surface a `Circular reference detected` JSON before
+ever returning a `total_formulas` count. Pre-check with openpyxl
+before saving any model that wires inputs back into outputs:
+
+```python
+from openpyxl import load_workbook
+
+book = load_workbook("model.xlsx")
+seen = set()
+for sheet in book.worksheets:
+    for row in sheet.iter_rows():
+        for cell in row:
+            if isinstance(cell.value, str) and cell.value.startswith("="):
+                seen.add(f"{sheet.title}!{cell.coordinate}")
+# Then walk references with a graph library (e.g. networkx) to find cycles.
+```
+
+Iteration budget should always be the result of an explicit decision —
+never leave "Iterative calculation" enabled by default.
+
+## 5. Preserve existing templates
+
+When updating someone else's template, **observe before edit**. Walk
+the checklist below before changing a single cell:
+
+- **Colors** — sample the current font / fill / border colors and
+  reuse the exact RGB triplets, even if they violate this skill's
+  defaults.
+- **Column widths** — note the existing widths; resizing for "tidiness"
+  always breaks something downstream (a chart, a print layout, a
+  conditional format range).
+- **Fonts** — if the template uses 宋体 / SimSun / a custom corporate
+  font, do not switch to Calibri.
+- **Merged cells** — record every merged region before mutating the
+  sheet (see [`create-edit-guide.md`](create-edit-guide.md) §9).
+- **Number formats** — copy the existing format string verbatim;
+  reformatting a cell will replace it.
+- **Conditional formatting** — list the rules with `for cf in
+  sheet.conditional_formatting:` before editing the range; insertions
+  shift the rule's anchor.
+
+Customer template conventions always override this skill's defaults.
+
+## 6. Code style for Python operating Excel
+
+These rules apply to the Python that drives openpyxl / xlsxwriter, not
+to the Excel files themselves.
+
+- **No tutorial comments.** Comments explain *why*, not *what* — the
+  reader knows what `book.save("foo.xlsx")` does.
+- **No `print` debugging in committed code.** Use `logging.debug` or
+  return values; `print` lines pollute downstream stdout that callers
+  parse for JSON.
+- **Business-named variables.** `book` / `sheet` / `frame` for the
+  workbook / worksheet / DataFrame. The terse `wb` / `ws` / `df`
+  reads as scratch-pad code; the full names match the financial-model
+  vocabulary the reviewer is already in.
+- **List comprehensions over manual `for` accumulators** when the body
+  is a single expression — keeps the code at one screen.
+
+## 7. Cell comment style
+
+For the comments inside the workbook (right-click → Insert Comment):
+
+- **Never use ALL CAPS.** Reviewers scanning the thumbnail interpret
+  all-caps as an error warning, even when the content is benign.
+- **Font size 9–10 pt.** Smaller is unreadable on retina displays;
+  larger crops the comment box and looks shouty.
+- **Cap at ~200 characters.** If the rationale is longer, link to a
+  shared doc or memo (`See: BI/MAU forecast methodology, 2025-09`)
+  rather than pasting the full text into the cell.

package/server/assets/skills/xlsx/docs/create-edit-guide.md

@@ -0,0 +1,410 @@
+# create-edit-guide — openpyxl + xlsxwriter cookbook
+
+> Detailed recipes for the two write-side libraries. The minimal
+> one-liners live in [`SKILL.md`](../SKILL.md) §3; this file is for
+> when a one-liner is not enough — full styling, charts, conditional
+> formatting, in-place edits, and the merged-cell / shared-strings
+> gotchas.
+
+## 1. Creating a new workbook (openpyxl)
+
+A workbook with formulas, named range, headline styling, and tuned
+column widths — the smallest end-to-end example covering everything
+`recalc.py` will validate later:
+
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Alignment, Font, PatternFill
+from openpyxl.workbook.defined_name import DefinedName
+
+book = Workbook()
+sheet = book.active
+sheet.title = "MAU_Forecast"
+
+# Assumptions block — single source of truth for tunable inputs.
+# Live in $G$1 so $-locked references in row formulas survive a fill-down.
+sheet["F1"], sheet["G1"] = "Take-rate", 0.85
+
+headers = ["Quarter", "MAU (mm)", "Tokens (bn)", "ARR (¥mm)"]
+for col_idx, label in enumerate(headers, start=1):
+    sheet.cell(row=1, column=col_idx, value=label)
+
+rows = [("2025Q3", 148, 27), ("2025Q4", 165, 31), ("2026Q1", 188, 36)]
+for r_idx, (quarter, mau, tokens) in enumerate(rows, start=2):
+    sheet.cell(row=r_idx, column=1, value=quarter)
+    sheet.cell(row=r_idx, column=2, value=mau)
+    sheet.cell(row=r_idx, column=3, value=tokens)
+    # Derived ARR — references inputs B/C and the Assumptions cell $G$1
+    # ($-locked so a fill-down doesn't drift). Never hard-code 0.85 in
+    # the formula — putting it in $G$1 lets the user run sensitivity by
+    # editing one cell instead of every row.
+    sheet.cell(row=r_idx, column=4, value=f"=B{r_idx}*C{r_idx}*$G$1")
+
+title = sheet.cell(row=1, column=1)
+title.font = Font(bold=True, color="000000")
+title.fill = PatternFill("solid", start_color="DDEBF7")
+title.alignment = Alignment(horizontal="center")
+
+for letter, width in zip("ABCDEFG", (10, 12, 14, 14, 4, 12, 8)):
+    sheet.column_dimensions[letter].width = width
+
+book.defined_names["MAU_Forecast_Range"] = DefinedName(
+    name="MAU_Forecast_Range",
+    attr_text="MAU_Forecast!$A$1:$D$4",
+)
+
+book.save("mau_forecast.xlsx")
+```
+
+The four building blocks — header row, data rows, headline styling,
+named range — are the four things almost every output workbook needs.
+Note the take-rate lives in `$G$1` (the Assumptions cell), not embedded
+in the formula as a literal `0.85`; this is the rule from
+[`conventions-guide.md`](conventions-guide.md) §4.1 in action.
+
+## 2. Editing an existing workbook (openpyxl)
+
+Open with `load_workbook`, mutate, save back. `data_only=False` (the
+default) is the only safe mode for read-modify-write — see §7.
+
+```python
+from openpyxl import load_workbook
+
+book = load_workbook("mau_forecast.xlsx")
+sheet = book.active                          # also: book["MAU_Forecast"]
+
+for name in book.sheetnames:
+    print("discovered sheet:", name)
+
+sheet.insert_rows(idx=3, amount=1)
+sheet.delete_cols(idx=4, amount=1)
+sheet.cell(row=3, column=1, value="2025Q4")
+
+detail = book.create_sheet(title="Detail", index=1)
+detail.cell(row=1, column=1, value="Cohort")
+detail.cell(row=1, column=2, value="Retention")
+
+book.remove(book["Sheet1"]) if "Sheet1" in book.sheetnames else None
+book.save("mau_forecast_v2.xlsx")
+```
+
+Insertions and deletions shift formulas referencing the moved range —
+re-run `scripts/recalc.py` after every structural edit and resolve any
+`#REF!` flagged in the JSON.
+
+## 3. Cell styling deep dive
+
+```python
+from openpyxl.styles import Alignment, Border, Font, PatternFill, Side
+
+cell = sheet["B2"]
+cell.font      = Font(name="Calibri", size=11, bold=True, color="000000")
+cell.fill      = PatternFill("solid", start_color="FFF2CC")
+cell.alignment = Alignment(horizontal="right", vertical="center", wrap_text=True)
+cell.border    = Border(
+    left=Side(style="thin", color="999999"), right=Side(style="thin", color="999999"),
+    top=Side(style="medium", color="333333"), bottom=Side(style="medium", color="333333"),
+)
+cell.number_format = "¥#,##0.00;(¥#,##0.00);-"
+```
+
+Styles are immutable per cell — a new `Font(...)` replaces the previous
+one, not merge fields. Build one `Font` / `Fill` / `Border` and assign
+the same instance across many cells.
+
+## 4. Conditional formatting
+
+```python
+from openpyxl.formatting.rule import (
+    ColorScaleRule, DataBarRule, FormulaRule,
+)
+from openpyxl.styles import PatternFill
+
+# 4.1 Color scale — gradient by value, useful for cohort heatmaps
+sheet.conditional_formatting.add(
+    "B2:B100",
+    ColorScaleRule(start_type="min", start_color="F8696B",
+                   mid_type="percentile", mid_value=50, mid_color="FFEB84",
+                   end_type="max", end_color="63BE7B"),
+)
+
+# 4.2 Data bar — inline bar inside the cell
+sheet.conditional_formatting.add(
+    "C2:C100",
+    DataBarRule(start_type="min", end_type="max", color="638EC6"),
+)
+
+# 4.3 Custom formula — highlight rows where ARR drops vs prior period
+fill_red = PatternFill("solid", start_color="FFC7CE")
+sheet.conditional_formatting.add(
+    "A2:D100",
+    FormulaRule(formula=["$D2<$D1"], fill=fill_red),
+)
+```
+
+Custom formulas use the **active row** as the reference (`$D2<$D1` =
+"current row's D less than previous row's D"); double-check by
+extending the range manually in Excel before delivery.
+
+## 5. Charts
+
+```python
+from openpyxl.chart import BarChart, LineChart, Reference
+
+# 5.1 BarChart — quarterly MAU comparison
+bar = BarChart()
+bar.title = "MAU by Quarter"
+bar.y_axis.title, bar.x_axis.title = "MAU (mm)", "Quarter"
+data   = Reference(sheet, min_col=2, min_row=1, max_col=2, max_row=5)
+labels = Reference(sheet, min_col=1, min_row=2, max_row=5)
+bar.add_data(data, titles_from_data=True)
+bar.set_categories(labels)
+sheet.add_chart(bar, "F2")
+
+# 5.2 LineChart — ARR trend
+line = LineChart()
+line.title = "ARR Trend"
+arr_ref = Reference(sheet, min_col=4, min_row=1, max_col=4, max_row=5)
+line.add_data(arr_ref, titles_from_data=True)
+line.set_categories(labels)
+sheet.add_chart(line, "F18")
+```
+
+`Reference` ranges include the header row when `titles_from_data=True`;
+forgetting that flag is the most common source of "the legend says
+Series 1 instead of MAU".
+
+## 6. xlsxwriter for write-only throughput
+
+Faster than openpyxl on six-figure-row writes; cannot reopen what it
+wrote. Use it when the workbook is the **terminal** output of a
+pipeline.
+
+```python
+import xlsxwriter
+
+book = xlsxwriter.Workbook("big_table.xlsx")
+sheet = book.add_worksheet("Tokens")
+
+bold       = book.add_format({"bold": True, "bg_color": "#DDEBF7", "align": "center"})
+money      = book.add_format({"num_format": "¥#,##0;(¥#,##0);-"})
+input_blue = book.add_format({"font_color": "#0000FF"})                  # §5.2 inputs
+
+# Assumptions block (E1) — ¥ per million tokens; flip this one cell to
+# re-run the model. Inputs carry input_blue per conventions §5.2.
+sheet.write(0, 3, "Price (¥/Mtok)", bold)
+sheet.write_number(0, 4, 1.20, input_blue)
+
+headers = ["Date", "Tokens (Mtok)", "Revenue (¥mm)"]
+sheet.write_row(0, 0, headers, bold)
+for r, (date, tokens) in enumerate(rows, start=1):
+    sheet.write_string(r, 0, date)
+    sheet.write_number(r, 1, tokens, input_blue)                          # raw input
+    # Derived revenue — formula referencing tokens (B) and Price ($E$1).
+    # NEVER pre-compute `tokens * 1.20` in Python and write_number it;
+    # that ships a static snapshot the user cannot rerun. money carries
+    # the default black font, so derived cells are §5.2-compliant.
+    sheet.write_formula(r, 2, f"=B{r + 1}*$E$1", money)
+
+# Footer total — also a formula, never a Python sum().
+sheet.write_formula(len(rows) + 1, 2, f"=SUM(C2:C{len(rows) + 1})", money)
+sheet.autofilter(0, 0, len(rows), len(headers) - 1)
+sheet.freeze_panes(1, 0)
+book.close()
+```
+
+Reuse the same `Format` object across cells — re-creating one per cell
+inflates the file and slows the writer down by an order of magnitude.
+xlsxwriter writes formulas just as cleanly as openpyxl
+(`write_formula`); the throughput advantage is no excuse to skip them.
+
+## 7. Read-modify-write loops — `data_only=True` is dangerous
+
+`load_workbook(..., data_only=True)` returns the **last cached
+calculation** instead of the formula string. Saving such a workbook
+permanently replaces every formula with its number.
+
+```python
+# WRONG — formulas vanish after save
+book = load_workbook("model.xlsx", data_only=True)
+book["Inputs"]["B2"] = 0.05
+book.save("model.xlsx")                      # =SUM(...) replaced by numbers
+
+# RIGHT — keep formulas, then re-run recalc.py to refresh cached values
+book = load_workbook("model.xlsx")           # data_only defaults to False
+book["Inputs"]["B2"] = 0.05
+book.save("model.xlsx")
+# subprocess: python scripts/recalc.py model.xlsx
+```
+
+Use `data_only=True` only when the workbook is **read-only** and you
+need the cached numeric values for downstream analysis.
+
+> **Reading back a workbook that just went through `recalc.py`.** Some
+> source files force LibreOffice to rewrite their `<mergeCell>` XML in
+> a form openpyxl cannot parse — `load_workbook` then raises
+> `TypeError: expected <class 'int'>` from `cell_range.py` regardless
+> of `data_only`. The file is fine; openpyxl's default parser is the
+> bottleneck. Two readback paths sidestep it:
+>
+> ```python
+> # easiest — streaming reader skips merged-cell parsing entirely.
+> # Streaming mode rejects subscript access like ws["B4"].value;
+> # use iter_rows() instead.
+> book = load_workbook("model.xlsx", read_only=True, data_only=True)
+> for row in book["Sheet"].iter_rows(values_only=True):
+>     ...
+>
+> # escape hatch — when you also need formula strings, or want to
+> # inspect the zip without instantiating openpyxl objects, use the
+> # raw-XML pattern in §11 (same technique recalc.py uses internally)
+> ```
+>
+> See `docs/recalc-guide.md` §9 for why LibreOffice triggers the bug
+> and how `recalc.py` already handles its own internal scan.
+
+## 8. Performance tips
+
+- `read_only=True` streams sheets row-by-row — drop into it for any
+  input file above ~100k rows.
+- `write_only=True` does the inverse for outputs; with `WriteOnlyCell`
+  it keeps memory flat while writing million-row sheets.
+- Iterate with `sheet.iter_rows(min_row=2, values_only=True)` instead
+  of nested `cell.value` access — values-only iteration skips the
+  per-cell object construction.
+- Avoid `sheet.cell(row=r, column=c).value = x` inside hot loops; the
+  attribute access has measurable overhead on large workbooks.
+
+## 9. Merged-cells gotcha
+
+`iter_rows()` returns the merged region's anchor cell at the top-left
+position and `None` everywhere else. Flattening the sheet into a
+DataFrame loses the merged value silently:
+
+```python
+book = load_workbook("merged.xlsx")
+sheet = book.active
+
+for row in sheet.iter_rows(min_row=1, max_row=3, values_only=True):
+    print(row)
+# (None, 'Q3 Summary', None, None)   <- only the anchor cell has the value
+# (None, None, None, None)
+# ('SKU', 'Units', 'Price', 'Total')
+```
+
+Unmerge before processing, broadcast the anchor value into the cleared
+cells, then re-merge if layout matters:
+
+```python
+ranges = [str(r) for r in sheet.merged_cells.ranges]
+for rng in ranges:
+    top, left, bottom, right = sheet[rng].bounds
+    anchor = sheet.cell(row=top, column=left).value
+    sheet.unmerge_cells(rng)
+    for r in range(top, bottom + 1):
+        for c in range(left, right + 1):
+            sheet.cell(row=r, column=c, value=anchor)
+```
+
+## 10. Shared-strings index drift gotcha
+
+The `.xlsx` zip stores text values in `xl/sharedStrings.xml` and
+references them by integer index from `xl/worksheets/sheetN.xml`.
+Manually editing the inner XML (e.g. string-replacing a value with a
+shorter one) reorders the dictionary on the next read and silently
+mis-renders every cell on the sheet.
+
+If a workbook arrives with mangled text, do **not** keep editing the
+XML — load it through openpyxl once and resave. openpyxl rebuilds the
+shared-strings table from cell values, restoring indexing invariants:
+
+```python
+book = load_workbook("mangled.xlsx")
+book.save("rebuilt.xlsx")                    # shared-strings reindexed
+```
+
+Then run `scripts/recalc.py rebuilt.xlsx` to verify no `#VALUE!` /
+`#REF!` showed up after the rewrite.
+
+## 11. Inject cached values without LibreOffice recalc
+
+Excel and LibreOffice compute the cached `<v>` next to each formula on
+their own first open; spreadsheet readers that ignore stored formulas
+(some viewers, some pipelines, the openpyxl `data_only=True` path) only
+ever see the cached value. When `scripts/recalc.py` is unavailable —
+sandboxed environment, no LibreOffice on disk, the rare workbook the
+fallback in `recalc-guide.md` §9 cannot rescue either — you can write
+the cached value yourself by editing the `<v>` element next to each
+`<f>` element you just emitted with openpyxl.
+
+```python
+import os, re, shutil, tempfile, zipfile
+
+def inject_cached_values(xlsx_path, sheet_name, cell_values):
+    """Write `<v>computed</v>` next to the `<f>...</f>` of each cell.
+
+    `cell_values` is a dict like `{"B4": 722589, "B5": 26.2}`. The
+    function rewrites the workbook in place, preserving every other
+    archive entry byte-for-byte.
+    """
+    with zipfile.ZipFile(xlsx_path) as zin:
+        wb_xml   = zin.read("xl/workbook.xml").decode()
+        rels_xml = zin.read("xl/_rels/workbook.xml.rels").decode()
+
+        rid = re.search(
+            rf'<sheet[^/]*name="{re.escape(sheet_name)}"[^/]*r:id="(rId\d+)"',
+            wb_xml,
+        ).group(1)
+        target = None
+        for rel in re.finditer(r"<Relationship\b[^>]*/?>", rels_xml):
+            if f'Id="{rid}"' in rel.group(0):
+                raw = re.search(r'Target="([^"]+)"', rel.group(0)).group(1)
+                raw = raw.lstrip("./").lstrip("/")
+                target = raw if raw.startswith("xl/") else f"xl/{raw}"
+                break
+
+        sheet_xml = zin.read(target).decode()
+        for ref, value in cell_values.items():
+            pattern = (
+                rf'(<c r="{re.escape(ref)}"[^>]*>)'
+                rf'(<f[^>]*>[^<]*</f>)'
+                rf'(<v\s*/>|<v[^>]*>[^<]*</v>)?'
+                rf'(</c>)'
+            )
+            sheet_xml, count = re.subn(
+                pattern, rf"\1\2<v>{value}</v>\4", sheet_xml,
+            )
+            assert count == 1, f"no formula cell found for {ref}"
+
+        names = zin.namelist()
+        infos = {info.filename: info for info in zin.infolist()}
+        payload = {name: zin.read(name) for name in names}
+        payload[target] = sheet_xml.encode()
+
+    fd, tmp = tempfile.mkstemp(suffix=".xlsx")
+    os.close(fd)
+    with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as zout:
+        for name in names:
+            zout.writestr(infos[name], payload[name])
+    shutil.move(tmp, xlsx_path)
+
+
+# Usage after openpyxl wrote the formulas:
+inject_cached_values(
+    "summary.xlsx",
+    "Executive_Summary",
+    {"B4": 722589, "B5": 26.2, "B6": 19.7, "B7": 44.3, "B8": 76.5},
+)
+```
+
+The pattern matches both the openpyxl-written `<v />` self-closing form
+and the populated `<v>...</v>` form, and refuses to touch a cell that
+does not already contain an `<f>` (the assertion guards against typos in
+the ref). The asserted count of `1` is intentional — silently rewriting
+nothing is the failure mode that ships an empty workbook.
+
+Use this only as a substitute for `scripts/recalc.py`. When LibreOffice
+is reachable, the recalc path is still preferable because it computes
+every formula in the workbook (not just the ones you happen to enumerate
+in `cell_values`) and surfaces the seven error tokens.
+