feat: publish HoloLake model-native living system source

product-source/hololake-platform/site/concepts/spreadsheets.md

@@ -0,0 +1,138 @@
+# Spreadsheets
+
+HoloLake Era sheets are spreadsheet notes. They keep the same file-first model as other notes, but a note with `_display: sheet` opens in a spreadsheet editor instead of the rich text editor. The note's `type` remains available for organization.
+
+The durable file is still Markdown with YAML frontmatter. The body is CSV-like text containing cell inputs and formulas, and spreadsheet presentation state is stored as plain YAML under `_sheet`.
+
+## Read Next
+
+- [Use Spreadsheets](/guides/use-spreadsheets) for the editing workflow.
+- [Spreadsheet File Format](/reference/spreadsheet-format) for the plain-text storage contract.
+- [Spreadsheet Formulas](/reference/spreadsheet-functions) for formula syntax, autocomplete, and IronCalc function families.
+
+## Why Sheet Notes
+
+Sheets are useful when information is better modeled as rows, columns, and formulas than as prose. Examples include budgets, revenue models, inventories, editorial calendars, lightweight trackers, and analytical scratchpads.
+
+HoloLake Era does not store sheets as opaque workbook binaries. A sheet should remain:
+
+- readable in a text editor
+- diffable in Git
+- editable by humans and AI agents
+- available offline
+- connected to the rest of the vault through types, properties, relationships, and wikilinks
+
+## One Note, One Sheet
+
+A sheet note is a single sheet. HoloLake Era does not expose multiple tabs inside one note.
+
+When a model needs more than one table, create more than one sheet note and connect them with wikilinks or cross-sheet formulas. This keeps each file small, legible, and aligned with HoloLake Era's graph model.
+
+For example:
+
+- `newsletter-revenue.md`
+- `sponsorship-pipeline.md`
+- `refactoring-business-plan.md`
+
+Each can be a normal `_display: sheet` note, and formulas can reference cells in another sheet note with HoloLake Era's wikilink cell syntax.
+
+## Editing
+
+The interactive sheet editor is backed by IronCalc. HoloLake Era uses IronCalc for spreadsheet behavior and formula evaluation, then adapts the workbook back to HoloLake Era's plain-text note format.
+
+In the sheet editor:
+
+- cell inputs that start with `=` are formulas
+- non-formula cells can contain normal text, numbers, dates, and `[[wikilinks]]`
+- typing `[[` in a cell opens the same note autocomplete concept used elsewhere in HoloLake Era
+- typing a formula function name opens inline formula autocomplete for the bundled IronCalc function catalog
+- right-clicking a selection exposes core formatting controls such as number formats, decimal precision, bold, italic, and clear formatting
+
+Keyboard basics follow spreadsheet conventions:
+
+- arrow keys move the active cell
+- `Shift` with arrows extends the selection
+- `Enter` starts editing the active cell
+- `Escape` exits cell editing while keeping focus in the sheet
+- `Delete` or `Backspace` clears the selected range
+- copy and paste should preserve formulas, including HoloLake Era cross-sheet references
+
+## Wikilinks In Cells
+
+Wikilinks in non-formula cells are stored as normal HoloLake Era wikilinks:
+
+```csv
+Project,Owner,Status
+[[website-redesign]],[[person/alice]],Active
+[[sponsorship-pipeline]],[[person/matteo]],Review
+```
+
+The cell still behaves like a spreadsheet cell, but the value remains a vault link that HoloLake Era can understand.
+
+## Note Reference Formulas
+
+HoloLake Era adds a sheet-note reference syntax on top of IronCalc formulas:
+
+```txt
+=[[newsletter-revenue]].B5
+=SUM(B2:D2)+[[sponsorship-pipeline]].E12
+=[[refactoring-business-plan]].$C$18
+```
+
+The target before the dot is a normal HoloLake Era wikilink target. For another sheet note, the part after the dot is an A1-style cell address.
+
+Relative and absolute references work like spreadsheet references when copied:
+
+- `[[revenue]].B5` can shift when pasted to another cell
+- `[[revenue]].$B$5` stays fixed
+- `[[revenue]].B$5` fixes the row
+- `[[revenue]].$B5` fixes the column
+
+This is not the same as an IronCalc workbook tab reference. It is HoloLake Era-specific syntax for referencing another sheet note in the vault.
+
+Current cross-sheet formulas resolve single cells. Ranges across sheet notes are not a stable file-format feature yet, so prefer composing them from explicit cell references or keeping range formulas inside the same sheet note.
+
+Sheet formulas can also read scalar frontmatter properties from a note:
+
+```txt
+=[[device]].power.watts
+=[[project-alpha]].status
+```
+
+This keeps sheet models connected to ordinary HoloLake Era metadata without requiring a saved view or query. Unresolved, ambiguous, or non-scalar property references show spreadsheet errors.
+
+## Storage
+
+A minimal sheet note looks like this:
+
+```md
+---
+type: Project
+_display: sheet
+status: Draft
+belongs_to:
+  - "[[business-plan]]"
+_sheet:
+  frozen_rows: 1
+  columns:
+    A:
+      width: 180
+  cells:
+    E6:
+      num_fmt: "0.00%"
+---
+Metric,January,February,March,Q1 Total
+Subscriptions,1200,1350,1500,=SUM(B2:D2)
+Services,800,900,750,=SUM(B3:D3)
+Expenses,650,700,760,=SUM(B4:D4)
+Net,=B2+B3-B4,=C2+C3-C4,=D2+D3-D4,=SUM(B5:D5)
+Growth,,=(C5-B5)/B5,=(D5-C5)/C5,=(E5-B5)/B5
+```
+
+Normal frontmatter stays normal HoloLake Era metadata. `_sheet` is system metadata for the spreadsheet editor and is hidden from normal property editing.
+
+For the full storage contract, see [Spreadsheet File Format](/reference/spreadsheet-format).
+
+## Formulas
+
+HoloLake Era delegates formula calculation to IronCalc. IronCalc aims for Excel-compatible formulas, while its project documentation still describes it as work in progress. For HoloLake Era-specific formula behavior and the autocomplete function catalog, see [Spreadsheet Formulas](/reference/spreadsheet-functions).