proompteng/bilig

**Keep the workbook model. Run the rule in Node.**
Bilig is a TypeScript-native, headless WorkPaper runtime for Node.js services,
tests, and AI agents. Set inputs, recalculate formulas, read computed outputs,
persist WorkPaper JSON, restore it, and verify the result—without driving Excel
or a browser grid.
Docs ·
Quick start ·
TypeScript API ·
MCP ·
Examples ·
Discussions
> [!NOTE]
> Bilig is a headless workbook runtime, not a visual spreadsheet app or a claim
> of full Excel compatibility. If an .xlsx file is your contract, start with
> the compatibility report.
Quick Start
Node runtime
Prove the published package before installing it:
The evaluator edits Inputs!B2, recalculates Summary!B2, saves the WorkPaper,
restores it, and compares the restored value:
verified: true means the write, formula readback, JSON export, and restored
readback all passed. It is stronger evidence than a successful write call.
Use It From TypeScript
For ordinary operations, use set(), setMany(), readMany(), display(),
and saveJson(). Use editManyAndReadback() when multiple inputs must be
committed and verified as one edit. The complete public API is documented in
packages/workpaper/README.md.
The lifecycle is deliberately small:
inputs → formula recalculation → typed readback → JSON persistence → restore verification
Why Bilig
| Capability | What it gives you |
| ------------------------ | ------------------------------------------------------------------------------------------- |
| Workbook-shaped models | Sheets, A1 addresses, formulas, ranges, and named expressions without a spreadsheet UI. |
| Verified mutations | Before/after computed values plus persistence and restore checks. |
| Service-owned state | Portable WorkPaper JSON for routes, queues, tests, tools, and audit trails. |
| Agent-safe tools | Narrow read/write tools with exact cells, computed readback, and writable-sheet boundaries. |
| Explicit file boundaries | Separate XLSX import, export, risk inspection, and Excel-oracle workflows. |
Use Bilig for pricing, quote approval, payouts, forecasts, validation rules,
formula-backed workflows, and tests where a service or tool should own the
model. Choose a spreadsheet application or hosted spreadsheet API when you
need visual editing, collaboration, macros, interactive pivots or charts, or
desktop fidelity.
Agents And MCP
Agents should first ask which system owns state, then run the smallest matching
proof. For a tool host or MCP client:
The MCP evaluator proves tool discovery, mutation, recalculated readback, JSON
export, disk persistence, process restart, and restored readback. For a local,
writable WorkPaper:
Use that local stdio path for private or persistent project state. The hosted
https://bilig.proompteng.ai/mcp endpoint is request-local and only intended
for stateless connector discovery and smoke tests; do not send private workbook
data to it.
The server exposes list_sheets, read_range, read_cell,
set_cell_contents, set_cell_contents_and_readback,
get_cell_display_value, export_workpaper_document, and validate_formula.
It also publishes MCP resources and prompts so capable hosts can discover the
workflow before editing cells.
Machine-readable entry points:
| Need | Entry point |
| ------------------------ | -------------------------------------------------------------------- |
| A compact routing card | docs/agent-start.txt |
| A concise model index | docs/llms.txt |
| Full agent documentation | docs/llms-full.txt |
| Installation context | docs/llms-install.md |
| Structured capabilities | docs/agent.json |
| Reusable skill | skills/bilig-workpaper/SKILL.md |
| Proof and host matrix | docs/agent-adoption-kit.md |
The published package also carries AGENTS.md and SKILL.md, so an agent can