{
"markdown": "# Bilig\n\n[](https://github.com/proompteng/bilig/actions/workflows/ci.yml)\n[](https://www.npmjs.com/package/@bilig/workpaper)\n[](packages/workpaper/package.json)\n[](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig)\n[](LICENSE)\n\n**Keep the workbook model. Run the rule in Node.**\n\nBilig is a TypeScript-native, headless WorkPaper runtime for Node.js services,\ntests, and AI agents. Set inputs, recalculate formulas, read computed outputs,\npersist WorkPaper JSON, restore it, and verify the result—without driving Excel\nor a browser grid.\n\n[Docs](https://proompteng.github.io/bilig/) ·\n[Quick start](#quick-start) ·\n[TypeScript API](#use-it-from-typescript) ·\n[MCP](#agents-and-mcp) ·\n[Examples](#examples-and-deeper-guides) ·\n[Discussions](https://github.com/proompteng/bilig/discussions)\n\n
\n \n
\n\n> [!NOTE]\n> Bilig is a headless workbook runtime, not a visual spreadsheet app or a claim\n> of full Excel compatibility. If an `.xlsx` file is your contract, start with\n> the [compatibility report](docs/workbook-compatibility-report.md).\n\n## Quick Start\n\nProve the published package before installing it:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json\n```\n\nThe evaluator edits `Inputs!B2`, recalculates `Summary!B2`, saves the WorkPaper,\nrestores it, and compares the restored value:\n\n```json\n{\n \"schemaVersion\": \"bilig-evaluator.v1\",\n \"door\": \"workpaper-service\",\n \"evidence\": {\n \"editedCell\": \"Inputs!B2\",\n \"dependentCell\": \"Summary!B2\",\n \"before\": 24000,\n \"after\": 38400,\n \"afterRestore\": 38400\n },\n \"verified\": true\n}\n```\n\n`verified: true` means the write, formula readback, JSON export, and restored\nreadback all passed. It is stronger evidence than a successful write call.\n\n## Use It From TypeScript\n\n```sh\nnpm install @bilig/workpaper\n```\n\n```ts\nimport { buildA1WorkPaper } from \"@bilig/workpaper\";\n\nconst pricing = buildA1WorkPaper({\n Inputs: [\n [\"Metric\", \"Value\"],\n [\"Units\", 20],\n [\"Price\", 1200],\n ],\n Summary: [\n [\"Metric\", \"Value\"],\n [\"Revenue\", \"=Inputs!B2*Inputs!B3\"],\n ],\n});\n\nconst proof = pricing.editAndReadback(\"Inputs!B2\", 32, {\n readbackRange: \"Summary!B2\",\n});\n\nconsole.log(proof.afterReadback.displayValues[0]?.[0]); // 38400\nconsole.log(proof.verified); // true\n\npricing.dispose();\n```\n\nFor ordinary operations, use `set()`, `setMany()`, `readMany()`, `display()`,\nand `saveJson()`. Use `editManyAndReadback()` when multiple inputs must be\ncommitted and verified as one edit. The complete public API is documented in\n[`packages/workpaper/README.md`](packages/workpaper/README.md).\n\nThe lifecycle is deliberately small:\n\n`inputs → formula recalculation → typed readback → JSON persistence → restore verification`\n\n## Why Bilig\n\n| Capability | What it gives you |\n| --- | --- |\n| Workbook-shaped models | Sheets, A1 addresses, formulas, ranges, and named expressions without a spreadsheet UI. |\n| Verified mutations | Before/after computed values plus persistence and restore checks. |\n| Service-owned state | Portable WorkPaper JSON for routes, queues, tests, tools, and audit trails. |\n| Agent-safe tools | Narrow read/write tools with exact cells, computed readback, and writable-sheet boundaries. |\n| Explicit file boundaries | Separate XLSX import, export, risk inspection, and Excel-oracle workflows. |\n\nUse Bilig for pricing, quote approval, payouts, forecasts, validation rules,\nformula-backed workflows, and tests where a service or tool should own the\nmodel. Choose a spreadsheet application or hosted spreadsheet API when you\nneed visual editing, collaboration, macros, interactive pivots or charts, or\ndesktop fidelity.\n\n## Agents And MCP\n\nAgents should first ask which system owns state, then run the smallest matching\nproof. For a tool host or MCP client:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --json\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json\n```\n\nThe MCP evaluator proves tool discovery, mutation, recalculated readback, JSON\nexport, disk persistence, process restart, and restored readback. For a local,\nwritable WorkPaper:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable\n```\n\nUse that local stdio path for private or persistent project state. The hosted\n`https://bilig.proompteng.ai/mcp` endpoint is request-local and only intended\nfor stateless connector discovery and smoke tests; do not send private workbook\ndata to it.\n\nThe server exposes `list_sheets`, `read_range`, `read_cell`,\n`set_cell_contents`, `set_cell_contents_and_readback`,\n`get_cell_display_value`, `export_workpaper_document`, and `validate_formula`.\nIt also publishes MCP resources and prompts so capable hosts can discover the\nworkflow before editing cells.\n\nMachine-readable entry points:\n\n| Need | Entry point |\n| --- | --- |\n| A compact routing card | [`docs/agent-start.txt`](docs/agent-start.txt) |\n| A concise model index | [`docs/llms.txt`](docs/llms.txt) |\n| Full agent documentation | [`docs/llms-full.txt`](docs/llms-full.txt) |\n| Installation context | [`docs/llms-install.md`](docs/llms-install.md) |\n| Structured capabilities | [`docs/agent.json`](docs/agent.json) |\n| Reusable skill | [`skills/bilig-workpaper/SKILL.md`](skills/bilig-workpaper/SKILL.md) |\n| Proof and host matrix | [`docs/agent-adoption-kit.md`](docs/agent-adoption-kit.md) |\n\nThe published package also carries `AGENTS.md` and `SKILL.md`, so an agent can\ndiscover the same proof contract from `node_modules`. Install or inspect the\npublic skill with either source:\n\n```sh\nnpx --yes skills@latest add https://bilig.proompteng.ai --list\nnpx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list\n```\n\n\nHost-specific project files\n\nUse the [agent rule chooser](docs/agent-rule-chooser.md) or the\n[host handoff prompt](docs/headless-workpaper-agent-handbook.md#copy-paste-prompt-for-another-agent).\nThe repository includes `CLAUDE.md`,\n`.claude/skills/bilig-workpaper/SKILL.md`,\n`.claude/commands/bilig-workpaper-proof.md`,\n`.cursor/rules/bilig-workpaper.mdc`, `.devin/rules/bilig-workpaper.md`,\n`.windsurf/rules/bilig-workpaper.md`, `.clinerules/bilig-workpaper.md`,\n`.continue/rules/bilig-workpaper.md`, `.zed/settings.json`, `opencode.jsonc`,\nand `.opencode/agents/bilig-workpaper.md`.\n\n\n\n## Integration Recipes After The Proof\n\nRun an evaluator first, then use the recipe owned by your host:\n\n- [OpenAI Agents SDK](https://proompteng.github.io/bilig/openai-agents-sdk-workpaper-tool.html): direct tools, `MCPServerStdio`, and `MCPServerStreamableHttp`.\n- [OpenAI Responses API](https://proompteng.github.io/bilig/openai-responses-workpaper-tool-call.html): function-call readback with explicit before/after evidence.\n- [Vercel AI SDK](https://proompteng.github.io/bilig/vercel-ai-sdk-langchain-spreadsheet-tool.html): `generateText()` and `streamText()` tool loops.\n- [Open WebUI](https://proompteng.github.io/bilig/open-webui-workpaper-mcp.html): local or hosted MCP discovery.\n- [n8n](https://proompteng.github.io/bilig/n8n-workpaper-formula-readback.html): the `@bilig/n8n-nodes-workpaper` community node.\n\n## Choose An Evaluation Path\n\n| Your state owner | Start here | Evidence to require |\n| --- | --- | --- |\n| TypeScript application | `npm install @bilig/workpaper` | direct A1 API and focused application tests |\n| Node service, route, queue, or test | `bilig-evaluate --door workpaper-service --json` | edit, recalculation, JSON export, restore, `verified: true` |\n| MCP client or tool host | `bilig-evaluate --door agent-mcp --json` | discovery, readback, disk persistence, restart |\n| Imported `.xlsx` is the contract | `workbook-compatibility-report workbook.xlsx --json` | unsupported formulas and workbook risk reasons for that file |\n| Cached `.xlsx` values look stale | `xlsx-cache-doctor workbook.xlsx --json` | stale-cache diagnosis, recalculation, and readback for that file |\n\nThe `workbook-compatibility` and `xlsx-cache` evaluator doors use bundled demo\nworkbooks to smoke-test the published package; they do not inspect your file.\nDo not treat any evaluator as proof of desktop Excel parity.\n\n## Examples And Deeper Guides\n\nStart with one maintained example, not the whole monorepo:\n\n- [`examples/headless-workpaper`](examples/headless-workpaper): pricing,\n invoice, budget, fulfillment, subscription, persistence, and agent examples.\n- [`examples/serverless-workpaper-api`](examples/serverless-workpaper-api):\n quote approval through Hono, Next.js, and persistence adapters.\n- [`examples/xlsx-recalculation-node`](examples/xlsx-recalculation-node): import,\n recalculate, export, reimport, and verify an XLSX workbook.\n- [`examples/recalc-bridge-workflows`](examples/recalc-bridge-workflows): focused\n bridges for existing SheetJS, xlsx-populate, and ExcelJS workflows.\n\nUseful decision guides:\n\n- [Formula workbooks proof page](docs/formula-workbooks-node-services-agent-tools.md)\n- [Agent evaluator matrix](docs/agent-proof-matrix.md)\n- [MCP spreadsheet server for coding agents](docs/mcp-spreadsheet-formula-server-for-coding-agents.md)\n- [Vercel AI SDK formula readback](docs/vercel-ai-sdk-spreadsheet-tool-formula-readback.md)\n- [OpenAI Responses tool calls](docs/openai-responses-workpaper-tool-call.md)\n- [ExcelJS formula result boundary](docs/exceljs-formula-result-not-updating-after-node-edits.md)\n- [Google Sheets `QUERY` and `SORTN`](docs/google-sheets-query-sortn-node-workpaper.md)\n- [Microsoft Graph Excel boundary](docs/microsoft-graph-excel-recalculation-node.md)\n- [XLSX formula support answers](docs/xlsx-formula-support-answers.md)\n- [Production adoption checklist](docs/production-adoption-checklist-headless-workpaper.md)\n\n\nRunnable integration and diagnostic commands\n\n```sh\npnpm --dir examples/headless-workpaper run agent:ai-sdk-generate-text\npnpm --dir examples/headless-workpaper run agent:ai-sdk-stream-text\npnpm --dir examples/headless-workpaper run agent:openai-responses\npnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight\npnpm --dir examples/serverless-workpaper-api run hono-route\npnpm --dir examples/serverless-workpaper-api run next-server-action\npnpm --dir examples/serverless-workpaper-api run next-server-action-formdata\n```\n\nThe AI SDK `generateText()` smoke lives at\n[`ai-sdk-generate-text-tool-smoke.ts`](examples/headless-workpaper/ai-sdk-generate-text-tool-smoke.ts).\nThe OpenAI example is documented in\n[`openai-responses-workpaper-tool-call`](docs/openai-responses-workpaper-tool-call.md).\n\nFor a reduced formula or import bug:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells \"Summary!B7,Inputs!B2\"\n```\n\n\n\n## XLSX And Excel Compatibility\n\nBilig can import and export workbook files, but cached formula values inside an\n`.xlsx` are diagnostics—not an accuracy oracle. Inspect the file before trusting\nit:\n\n```sh\nnpm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json\nnpm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json\nnpm exec --yes --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor workbook.xlsx --json\n```\n\nThe first command is a package smoke test over a bundled demo. The next two\ninspect the named file. The compatibility report identifies unsupported\nfunctions, external links, macros, pivots, volatile formulas, and other risks;\nit does not certify Excel compatibility. When correctness matters, compare\nagainst a workbook freshly recalculated by Excel. See the\n[compatibility limits](docs/where-bilig-is-not-excel-compatible-yet.md) and\n[Excel oracle walkthrough](docs/xlsx-corpus-verifier-walkthrough.md).\n\n## Packages And Repository Map\n\n| Path | Role |\n| --- | --- |\n| [`packages/workpaper`](packages/workpaper) | Recommended `@bilig/workpaper` API, evaluators, AI SDK adapter, MCP server, and XLSX boundary. |\n| [`packages/headless`](packages/headless) | Lower-level WorkPaper runtime and integration primitives. |\n| [`packages/xlsx-formula-recalc`](packages/xlsx-formula-recalc) | Real-file compatibility and stale-cache diagnostics. |\n| [`packages/formula`](packages/formula) | Formula parser, binder, compiler, and evaluator. |\n| [`packages/core`](packages/core) | Workbook state, mutations, snapshots, and scheduling. |\n| [`apps/web`](apps/web) | Browser spreadsheet shell. |\n| [`apps/bilig`](apps/bilig) | Full-stack runtime, APIs, and static site host. |\n\nThe public package requires Node.js `>=22`. Local monorepo development uses\nNode.js 24+, Bun, and `pnpm@10.32.1`.\n\nPublished releases include npm registry signatures and provenance attestations:\n\n```sh\nnpm view @bilig/workpaper version dist.attestations dist.signatures --json\nnpm audit signatures\n```\n\n## Development\n\nChoose one long-running development server:\n\n```sh\npnpm dev:web\npnpm dev:web-local\n```\n\nInstall and validate the repository with:\n\n```sh\npnpm install\npnpm build\npnpm lint\npnpm typecheck\npnpm test\npnpm run ci\n```\n\nArchitecture lives in [`docs/architecture.md`](docs/architecture.md). Read\n[`CONTRIBUTING.md`](CONTRIBUTING.md) before opening a pull request; first-time\ncontributors can start with the [new contributor guide](docs/new-contributor-guide.md)\nand [starter issues](docs/starter-issues.md). All participation follows the\n[`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).\n\n## Support And Security\n\n- Ask adoption and design questions in\n [Discussions](https://github.com/proompteng/bilig/discussions).\n- Follow versioned changes through\n [GitHub Releases](https://github.com/proompteng/bilig/releases/latest).\n- Report reproducible bugs through\n [Issues](https://github.com/proompteng/bilig/issues); reduced workbooks can use\n the [formula bug clinic](docs/formula-bug-clinic.md) and\n [fixture form](docs/submit-workbook-fixture.md).\n- Read [`SUPPORT.md`](SUPPORT.md) for the evidence that makes a report actionable.\n- Follow [`SECURITY.md`](SECURITY.md) for private vulnerability reporting. Never\n attach private workbook data, credentials, or tokens to a public issue.\n\nIf Bilig fits one of your services or agent workflows,\n[star the repository](https://github.com/proompteng/bilig) to follow releases\nand help other Node developers find it. Tell us what proof or formula is still\nmissing.\n\n## License\n\n[MIT](LICENSE)\n",
"bytes": 15021,
"sha": "eafff35f063bf6481db1012bc5152dd39ae134a03bdd0eb4fdb72d02ea7a28f3",
"repo_slug": "proompteng/bilig",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_proompteng_bilig_workpaper_05f74bfb/readme"
}
![\"A](\"docs/assets/bilig-hero-workbook-api.png\")
\n