\n $\"bilig$ \n

\n\n## Try It In 90 Seconds\n\nThis uses the published npm package. It builds a workbook, changes one input,\nreads the calculated value, saves JSON, restores the workbook, and prints the\nsame value again.\n\n```sh\nnpm create @bilig/workpaper@latest pricing-workpaper\ncd pricing-workpaper\nnpm install\nnpm run smoke\n```\n\nExpected output includes these fields:\n\n```json\n{\n \"before\": {\n \"summary\": {\n \"decision\": \"review\"\n },\n \"inputCells\": {\n \"units\": \"Inputs!B2\",\n \"listPrice\": \"Inputs!B3\"\n }\n },\n \"edit\": {\n \"before\": {\n \"decision\": \"review\"\n },\n \"after\": {\n \"decision\": \"approved\"\n },\n \"restored\": {\n \"decision\": \"approved\"\n },\n \"checks\": {\n \"decisionChanged\": true,\n \"formulasPersisted\": true,\n \"restoredMatchesAfter\": true,\n \"serializedBytes\": 1242\n }\n },\n \"verified\": true\n}\n```\n\nThe generated starter uses the same WorkPaper fields as the\npublic mirror at and\n[`examples/headless-workpaper/npm-eval.ts`](https://github.com/proompteng/bilig/blob/main/examples/headless-workpaper/npm-eval.ts).\nThe exact byte count can change between package versions; `verified: true`,\n`decisionChanged`, `formulasPersisted`, and `restoredMatchesAfter` are the\nchecks.\n\nFor a route-shaped quote approval API today, run the maintained example:\n\n```sh\ngit clone --depth 1 https://github.com/proompteng/bilig.git\ncd bilig\npnpm --dir examples/serverless-workpaper-api install --ignore-workspace\npnpm --dir examples/serverless-workpaper-api run smoke\n```\n\nFor a generated project from a blank directory, run\n`npm create @bilig/workpaper@latest pricing-workpaper` through the\n`@bilig/create-workpaper` package. The package source lives in\n[`packages/create-workpaper`](https://github.com/proompteng/bilig/blob/main/packages/create-workpaper), and the publish gate\nis documented in [create a Bilig WorkPaper starter](https://github.com/proompteng/bilig/blob/main/docs/create-bilig-workpaper.md).\nFor an agent-ready project with `AGENTS.md`, `CONVENTIONS.md`,\n`.aider.conf.yml`, `CLAUDE.md`, `GEMINI.md`,\nCopilot / Cursor / Kiro / Roo Code / Trae / Zed / Junie / OpenHands / OpenCode / Aider / Cline / Continue / Windsurf rules, MCP client\nconfigs, and an `agent:verify` script, run\n`npm create @bilig/workpaper@latest pricing-agent -- --agent`.\nFor an existing repo, run\n`npm create @bilig/workpaper@latest . -- --add-agent`; it adds Bilig agent and\nMCP instructions without replacing your app template or editing `package.json`.\nIf an agent policy already exists, it writes `BILIG_WORKPAPER_INSTALL.md` with\nthe skipped paths and a short handoff block.\n\nIf that proof almost matches a service or agent workflow you maintain, the useful next\nstep is concrete feedback: open or answer one adoption blocker in\n[Discussions](https://github.com/proompteng/bilig/discussions/new?category=general):\nformula coverage, stale XLSX cached values, persistence shape, MCP/agent\nwriteback, or benchmark coverage.\n\n## TypeScript API Shape\n\nMost integrations are just this: build a workbook, write an input, read the\ncalculated value, and save the workbook state. When a workflow writes more than\none input, use `editManyAndReadback()` so the edits are applied atomically and\nthe proof compares typed readback values, persisted restore output, and formula\ndiagnostics.\n\n```ts\nimport { buildA1WorkPaper } from '@bilig/workpaper'\n\nconst book = buildA1WorkPaper({\n Inputs: [\n ['Metric', 'Value'],\n ['Customers', 20],\n ['Average revenue', 1200],\n ],\n Summary: [\n ['Metric', 'Value'],\n ['Revenue', '=Inputs!B2*Inputs!B3'],\n ],\n})\n\nconst proof = book.editAndReadback('Inputs!B2', 32, {\n readbackRange: 'Summary!B2',\n})\n\nconsole.log({\n editedCell: proof.editedCell,\n revenue: proof.afterReadback.displayValues[0]?.[0],\n persistedDocumentBytes: proof.persistedDocumentBytes,\n verified: proof.verified,\n})\n\nbook.dispose()\n```\n\nThe lower-level `WorkPaper` runtime is still exported for engine integrations,\nbut the A1 facade is the default service and agent path. Use\n`book.set()`, `book.setMany()`, `book.readMany()`, `book.display()`, and\n`book.saveJson()` when a full readback proof is not needed. Use\n`book.editManyAndReadback()` when several inputs should be committed and proven\nas one atomic workbook edit.\n\n## When To Reach For It\n\nUse `@bilig/workpaper` when:\n\n- a Node service owns a workbook-shaped calculation;\n- an agent needs tools such as `readRange` and `setInputCell`, with computed\n before/after values instead of screenshots;\n- tests need deterministic spreadsheet state and formula readback;\n- a workflow needs to save the edited workbook as JSON and restore it later.\n\nUse something else when you need a visual spreadsheet grid, Office macros,\ndesktop Excel automation, or a one-off arithmetic helper. Do not treat embedded\nXLSX cached formula values as truth; use the Excel oracle workflow when accuracy\nmatters.\n\n## Package Boundary\n\n\n\nCurrent checked npm footprint for `@bilig/headless@0.164.1`:\n\n- Pack dry run: `860 kB` tarball, `5.24 MB` unpacked, `835` package entries.\n- Boundary: the main import is the WorkPaper formula/JSON runtime; XLSX\n import/export stays behind the `@bilig/headless/xlsx` subpath; MCP is the\n `bilig-workpaper-mcp` binary wrapper; reduced workbook reports use the\n `bilig-formula-clinic` binary.\n- Cold-start gate: Node imports the main entrypoint, builds a two-sheet\n WorkPaper, and reads `24000` under `1000 ms` without importing\n the XLSX subpath.\n- Runtime: Node `>=22.0.0`; Node 22 compatibility is covered by the runtime package workflow.\n\n\n## Published Package Trust\n\n`@bilig/headless` is published with npm registry signatures and SLSA provenance\nattestations. Verify the package version you are about to adopt:\n\n```sh\nnpm view @bilig/headless version dist.attestations dist.signatures --json\n```\n\nAfter installing, npm can verify the current dependency tree:\n\n```sh\nnpm audit signatures\n```\n\nThe current package trust path is documented in\n[npm provenance and package trust](https://github.com/proompteng/bilig/blob/main/docs/npm-provenance-package-trust.md).\nRepository security posture is tracked by\n[OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig)\nand uploaded to GitHub code scanning on every `main` update.\n\n## Deeper Evaluation Paths\n\nAfter the first proof in [Start Here](#start-here), use the deeper guide that\nmatches the next job.\n\n1. Run the [90-second npm eval](#try-it-in-90-seconds) in a blank project.\n2. Run the flagship\n [serverless WorkPaper API](https://github.com/proompteng/bilig/blob/main/examples/serverless-workpaper-api) example:\n `npm run quote-approval-api`.\n3. If the workflow starts with an XLSX file, run the\n [XLSX formula recalculation in Node](https://github.com/proompteng/bilig/blob/main/examples/xlsx-recalculation-node):\n `npm start`.\n4. If an agent needs workbook tools, start with the\n [headless WorkPaper agent handbook](https://github.com/proompteng/bilig/blob/main/docs/headless-workpaper-agent-handbook.md),\n then use the [MCP server guide](https://github.com/proompteng/bilig/blob/main/docs/mcp-workpaper-tool-server.md) when the\n caller is an MCP client.\n5. If a real workbook almost works, start with the\n [formula bug clinic](https://github.com/proompteng/bilig/blob/main/docs/formula-bug-clinic.md). For stale XLSX caches, run\n `xlsx-cache-doctor ./reduced.xlsx --json` and include the exact cell,\n cached value, and recalculated value. If the fixture is already reduced and\n public, submit the structured\n [fixture form](https://github.com/proompteng/bilig/blob/main/docs/submit-workbook-fixture.md) so the blocker can become a\n test, example, or corpus case instead of private feedback.\n .\n If you are still reducing the case, discuss the shape first:\n .\n\nThe rest of the docs are an index, not a prerequisite.\n\nFor comparison and integration details, use the\n[plain-language fit guide](https://github.com/proompteng/bilig/blob/main/docs/why-use-bilig.md),\n[screenshot automation boundary](https://github.com/proompteng/bilig/blob/main/docs/stop-driving-spreadsheets-with-screenshots.md),\n[Google Sheets API boundary](https://github.com/proompteng/bilig/blob/main/docs/google-sheets-api-alternative-node-workpaper.md),\n[Google Sheets QUERY/SORTN in Node](https://github.com/proompteng/bilig/blob/main/docs/google-sheets-query-sortn-node-workpaper.md),\n[workbook automation examples](https://github.com/proompteng/bilig/blob/main/docs/workbook-automation-examples-node.md),\nthe [formula workbooks proof page](https://github.com/proompteng/bilig/blob/main/docs/formula-workbooks-node-services-agent-tools.md),\nthe [Node spreadsheet formula engine guide](https://github.com/proompteng/bilig/blob/main/docs/node-spreadsheet-formula-engine.md),\n[server-side spreadsheet automation](https://github.com/proompteng/bilig/blob/main/docs/server-side-spreadsheet-automation-node.md),\n[framework adapters](https://github.com/proompteng/bilig/blob/main/docs/node-framework-workpaper-adapters.md),\n[formula bug clinic](https://github.com/proompteng/bilig/blob/main/docs/formula-bug-clinic.md),\n[workbook fixture submissions](https://github.com/proompteng/bilig/blob/main/docs/submit-workbook-fixture.md),\n[OpenAI Agents SDK tools](https://github.com/proompteng/bilig/blob/main/docs/openai-agents-sdk-workpaper-tool.md),\n[Browser Use formula tool](https://github.com/proompteng/bilig/blob/main/docs/browser-use-workpaper-formula-tool.md),\n[Google ADK MCP tools](https://github.com/proompteng/bilig/blob/main/docs/google-adk-workpaper-mcp.md),\n[OpenHands MCP setup](https://github.com/proompteng/bilig/blob/main/docs/openhands-workpaper-mcp.md),\n[OpenCode MCP setup](https://github.com/proompteng/bilig/blob/main/docs/opencode-workpaper-mcp.md),\n[Microsoft Agent Framework MCP tools](https://github.com/proompteng/bilig/blob/main/docs/microsoft-agent-framework-workpaper-mcp.md),\n[Goose MCP recipe](https://github.com/proompteng/bilig/blob/main/docs/goose-workpaper-mcp.md),\n[Agent WorkPaper proof matrix](https://github.com/proompteng/bilig/blob/main/docs/agent-proof-matrix.md),\n[MCP spreadsheet formula server for coding agents](https://github.com/proompteng/bilig/blob/main/docs/mcp-spreadsheet-formula-server-for-coding-agents.md),\n[Vercel AI SDK formula readback](https://github.com/proompteng/bilig/blob/main/docs/vercel-ai-sdk-spreadsheet-tool-formula-readback.md),\n[AI SDK and LangChain tools](https://github.com/proompteng/bilig/blob/main/docs/vercel-ai-sdk-langchain-spreadsheet-tool.md),\n[CrewAI adapter](https://github.com/proompteng/bilig/blob/main/docs/crewai-workpaper-spreadsheet-tool.md),\nthe [headless WorkPaper agent handbook](https://github.com/proompteng/bilig/blob/main/docs/headless-workpaper-agent-handbook.md),\nthe [MCP server guide](https://github.com/proompteng/bilig/blob/main/docs/mcp-workpaper-tool-server.md),\n[spreadsheet MCP server comparison](https://github.com/proompteng/bilig/blob/main/docs/spreadsheet-mcp-server-comparison.md),\n[MCP directory status](https://github.com/proompteng/bilig/blob/main/docs/mcp-spreadsheet-server-directory.md),\n[MCP client setup](https://github.com/proompteng/bilig/blob/main/docs/mcp-client-setup.md),\n[Gemini CLI extension](https://github.com/proompteng/bilig/blob/main/docs/gemini-cli-workpaper-extension.md),\n[FastMCP Python client](https://github.com/proompteng/bilig/blob/main/docs/fastmcp-workpaper-client.md),\n[Claude Desktop MCPB bundle](https://github.com/proompteng/bilig/blob/main/docs/claude-desktop-mcpb-workpaper.md),\n[npm provenance and package trust](https://github.com/proompteng/bilig/blob/main/docs/npm-provenance-package-trust.md),\n[JavaScript library comparison](https://github.com/proompteng/bilig/blob/main/docs/javascript-spreadsheet-library-headless-node.md),\n[headless spreadsheet engine for Node services and agents](https://github.com/proompteng/bilig/blob/main/docs/headless-spreadsheet-engine-node-services-agents.md),\n[XLSX formula recalculation in Node.js](https://github.com/proompteng/bilig/blob/main/docs/xlsx-formula-recalculation-node.md),\n[agent XLSX formula recalculation without LibreOffice](https://github.com/proompteng/bilig/blob/main/docs/agent-xlsx-formula-recalculation-without-libreoffice.md),\n[Excel file as a Node calculation engine](https://github.com/proompteng/bilig/blob/main/docs/excel-file-calculation-engine-node.md),\n[stale XLSX formula cache in Node.js](https://github.com/proompteng/bilig/blob/main/docs/stale-xlsx-formula-cache-node.md),\n[stale formula readback chooser](https://github.com/proompteng/bilig/blob/main/docs/stale-formula-readback-chooser.md),\n[XLSX formula support answers](https://github.com/proompteng/bilig/blob/main/docs/xlsx-formula-support-answers.md),\n[SheetJS formula result not updating in Node.js](https://github.com/proompteng/bilig/blob/main/docs/sheetjs-formula-result-not-updating-node.md),\n[ExcelJS formula result not updating after Node edits](https://github.com/proompteng/bilig/blob/main/docs/exceljs-formula-result-not-updating-after-node-edits.md),\n[Microsoft Graph Excel recalculation in Node.js](https://github.com/proompteng/bilig/blob/main/docs/microsoft-graph-excel-recalculation-node.md),\n[xlsx-calc alternative for Node workbook recalculation](https://github.com/proompteng/bilig/blob/main/docs/xlsx-calc-alternative-node-workbook-recalculation.md),\n[ExcelJS formula recalculation in Node.js](https://github.com/proompteng/bilig/blob/main/docs/exceljs-formula-recalculation-node.md),\n[ExcelJS shared formulas in Node.js](https://github.com/proompteng/bilig/blob/main/docs/exceljs-shared-formula-recalculation-node.md),\n[SheetJS/ExcelJS boundary](https://github.com/proompteng/bilig/blob/main/docs/sheetjs-exceljs-alternative-formula-workbook-api.md),\nand [headless engine comparison](docs/head","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Developer Tools","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":104},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124],"license","MIT","language","TypeScript","registryName","io.github.proompteng/bilig-workpaper","homepage","https://proompteng.github.io/bilig/","agent-tools","ai-agents","excel","excel-formulas","formula-engine","formula-recalculation","headless-spreadsheet","mcp","mcp-server","model-context-protocol","spreadsheet","spreadsheet-api","spreadsheet-automation","spreadsheet-engine","spreadsheet-formulas","typescript","workbook-api","xlsx","xlsx-formulas","xlsx-recalculation","ENV",{"_127":128,"_129":130,"_131":132},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]