{"id":50979807,"url":"https://proompteng.github.io/bilig/","last_synced_at":"2026-07-07T11:00:29.911Z","repository":{"id":344142005,"uuid":"1180482213","full_name":"proompteng/bilig","owner":"proompteng","description":"Formula workbooks for Node services: edit inputs, recalculate formulas, read outputs, persist WorkPaper JSON, and expose MCP tools.","archived":false,"fork":false,"pushed_at":"2026-07-03T23:30:42.000Z","size":114480,"stargazers_count":33,"open_issues_count":0,"forks_count":21,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-04T01:21:41.303Z","etag":null,"topics":["formula-engine","formula-recalculation","formula-workbook","mcp","mcp-server","mcp-tools","model-context-protocol","node-formulas","node-services","nodejs","server-side-formulas","typescript","workbook-api","workbook-automation","workbook-formulas","workbook-runtime","workflow-automation","workpaper","workpaper-json","workpaper-runtime"],"latest_commit_sha":null,"homepage":"https://proompteng.github.io/bilig/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/proompteng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-13T04:50:28.000Z","updated_at":"2026-07-03T23:30:46.000Z","dependencies_parsed_at":null,"dependency_job_id":"4c13db80-dfc9-481b-afeb-e8516da88c95","html_url":"https://github.com/proompteng/bilig","commit_stats":null,"previous_names":["proompteng/bilig"],"tags_count":518,"template":false,"template_full_name":null,"purl":"pkg:github/proompteng/bilig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/proompteng","download_url":"https://codeload.github.com/proompteng/bilig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/proompteng%2Fbilig/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35111450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-04T02:00:05.987Z","response_time":113,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["formula-engine","formula-recalculation","formula-workbook","mcp","mcp-server","mcp-tools","model-context-protocol","node-formulas","node-services","nodejs","server-side-formulas","typescript","workbook-api","workbook-automation","workbook-formulas","workbook-runtime","workflow-automation","workpaper","workpaper-json","workpaper-runtime"],"created_at":"2026-06-19T13:00:56.996Z","updated_at":"2026-07-07T11:00:29.882Z","avatar_url":"https://github.com/proompteng.png","language":"TypeScript","funding_links":[],"categories":["Libraries"],"sub_categories":[],"readme":"# bilig\n\n[![CI](https://github.com/proompteng/bilig/actions/workflows/ci.yml/badge.svg)](https://github.com/proompteng/bilig/actions/workflows/ci.yml)\n[![npm: @bilig/workpaper](https://img.shields.io/npm/v/@bilig/workpaper?label=%40bilig%2Fworkpaper)](https://www.npmjs.com/package/@bilig/workpaper)\n[![CodeQL](https://github.com/proompteng/bilig/actions/workflows/codeql.yml/badge.svg)](https://github.com/proompteng/bilig/actions/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/proompteng/bilig/badge)](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\n**Run workbook-shaped business rules inside Node.**\n\nBilig gives services, queue workers, tests, MCP servers, and tool integrations a\ntyped WorkPaper object: write inputs, recalculate formulas, read outputs,\npersist JSON, restore, and verify. It fits pricing models, quote approval,\npayout checks, import validation, forecasts, and formula-backed workflow steps.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/github-social-preview.png\" alt=\"bilig WorkPaper runtime preview\" /\u003e\n\u003c/p\u003e\n\nRun the no-project service check from any Node project:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json\n```\n\nExpected WorkPaper service result:\n\n```json\n{\n  \"schemaVersion\": \"bilig-evaluator.v1\",\n  \"door\": \"workpaper-service\",\n  \"verified\": true,\n  \"evidence\": {\n    \"editedCell\": \"Inputs!B2\",\n    \"dependentCell\": \"Summary!B2\",\n    \"before\": 24000,\n    \"after\": 38400,\n    \"afterRestore\": 38400,\n    \"persistedDocumentBytes\": 999\n  }\n}\n```\n\nFor TypeScript services that should own the workbook model:\n\n```sh\nnpm create @bilig/workpaper@latest pricing-workpaper\ncd pricing-workpaper\nnpm install\nnpm run smoke\n```\n\nFor MCP clients or other tool integrations, run the same proof loop through the\nMCP evaluator before adding host-specific config:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json\n```\n\nEvaluator examples live in\n[`examples/bilig-evaluator-proof`](examples/bilig-evaluator-proof). Integration\nmatrix docs and host-specific config files are available when a team needs\nthem, but the public proof starts with WorkPaper service readback. File\ncompatibility diagnostics are a separate path for import/export boundaries, not\nthe default runtime story.\n\nProject site: \u003chttps://proompteng.github.io/bilig/\u003e\n\n## Start Here\n\nPick the path that matches the job:\n\n| You have...                                                      | Start with                                                             | You should see                                                                                         |\n| ---------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| A Node service, route, queue, test, or tool needs workbook logic | [Node service WorkPaper evaluator](docs/eval-workpaper-service.md)     | input edit, recalculated output, serialized JSON, restore check, and `verified: true`.                 |\n| An MCP client or tool integration needs workbook commands        | [MCP tool evaluator](docs/eval-agent-mcp.md)                           | tool discovery, cell edit, formula readback, export, restart check, and `verified: true`.              |\n| You want a starter project with the runtime installed            | [90-second Node quickstart](docs/try-bilig-headless-in-node.md)        | a local package smoke test that edits one input, recalculates, saves JSON, and restores the WorkPaper. |\n| An imported file is the integration boundary                     | [Workbook Compatibility Report](docs/workbook-compatibility-report.md) | unsupported functions, external links, macros, pivots, volatile formulas, and import/export risks.     |\n\nIf you are not sure which one fits, start with the thing that owns state. Use\nWorkPaper when your service or tool should own the workbook model. Use file\ndiagnostics only when import/export compatibility is the actual contract.\n\nGood fits: pricing, quote approval, payout checks, import validation, forecasts,\nCI fixtures, formula-backed workflow steps, and tool integrations that need exact\ncell addresses plus readback. Bad fits: manual spreadsheet editing, Office\nmacros, desktop Excel automation, or one-off arithmetic where a workbook would\nbe ceremony.\n\n## If You Only Try One Thing\n\nRun the WorkPaper service proof at the top of this README first. It is the\nshortest proof that Bilig gives backend code a workbook object it can change,\nrecalculate, read back, save, and restore without driving Excel, LibreOffice,\nGoogle Sheets, or a browser grid.\n\nIf an MCP client or tool integration owns the workflow, run the MCP door:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json\n```\n\nTrust boundaries:\n\n- Runs locally in Node or in your GitHub Actions runner; no hosted workbook\n  upload is required.\n- Does not claim Excel parity. Start with\n  [where Bilig is not Excel-compatible yet](docs/where-bilig-is-not-excel-compatible-yet.md)\n  before using it for irreversible workflows.\n- File import/export diagnostics are available when an imported file is the\n  contract, but they are a separate path from service-owned WorkPaper state.\n\n## Which Path Should I Install?\n\n| Problem you have right now                                                        | Install or use                 | First proof                                                            |\n| --------------------------------------------------------------------------------- | ------------------------------ | ---------------------------------------------------------------------- |\n| Formula workbook state belongs inside a Node service, route, queue, test, or tool | `npm install @bilig/workpaper` | [Node service WorkPaper evaluator](docs/eval-workpaper-service.md)     |\n| An MCP client or tool integration needs workbook tools with computed readback     | `npm install @bilig/workpaper` | [MCP tool evaluator](docs/eval-agent-mcp.md)                           |\n| Import/export compatibility is the integration boundary                           | compatibility diagnostics      | [Workbook Compatibility Report](docs/workbook-compatibility-report.md) |\n\nAdvanced adapters are still available when the boundary is already specific:\n[SheetJS](docs/sheetjs-formula-result-not-updating-node.md),\n[ExcelJS](docs/exceljs-formula-recalculation-node.md),\n[external workbooks](docs/external-workbook-recalc-proof.md),\n[MCP/tool integrations](docs/ai-agent-spreadsheet-tool-node.md),\n[`@bilig/workbook`](docs/workbook-runtime-intent-api.md) when a runtime needs\ntransport-neutral plan data and command receipts, and\n[runtime provenance](docs/npm-provenance-package-trust.md).\n\n## MCP And Tool Integrations\n\nUse the [WorkPaper host handoff](docs/agent-adoption-kit.md) when a tool host\nneeds workbook reads, writes, recalculation, JSON export, and restore proof.\nThe first check is always the no-key MCP evaluator:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json\n```\n\nThat evaluator starts the published WorkPaper tool server, discovers tools,\nedits an input, reads the dependent formula, exports JSON, restarts, restores,\nand returns `verified: true`. Use\n[`llms-install.md`](llms-install.md) when a host wants one install file, and use\nthe [tool-host evaluator matrix](docs/agent-proof-matrix.md) when the host matters\nmore than the package boundary.\n\nThe published package also carries `AGENTS.md` and `SKILL.md` so hosts\ninspecting `node_modules/@bilig/workpaper` can find the same proof locally.\nCloned checkouts keep host-specific config indexed in\n[agent rule chooser](docs/agent-rule-chooser.md): `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`. The public manifest is\n`docs/.well-known/agent.json`.\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## Integration Recipes After The Proof\n\nRun one evaluator first. Then use the recipe that matches the platform boundary:\n\n- Open WebUI WorkPaper MCP:\n  \u003chttps://proompteng.github.io/bilig/open-webui-workpaper-mcp.html\u003e.\n- OpenAI Agents SDK with direct tools, stdio MCP, or\n  `MCPServerStreamableHttp`:\n  \u003chttps://proompteng.github.io/bilig/openai-agents-sdk-workpaper-tool.html\u003e.\n- ChatGPT Apps WorkPaper MCP:\n  \u003chttps://proompteng.github.io/bilig/chatgpt-apps-workpaper-mcp.html\u003e.\n- Hugging Face Gradio MCP Space:\n  \u003chttps://proompteng.github.io/bilig/huggingface-workpaper-space.html\u003e.\n- n8n self-hosted workflows can use `@bilig/n8n-nodes-workpaper`; Pipedream\n  formula readback is documented at\n  \u003chttps://proompteng.github.io/bilig/pipedream-workpaper-formula-readback.html\u003e\n  and sourced from `docs/pipedream-workpaper-formula-readback.md`.\n- Directus Persisted Calculated Fields:\n  \u003chttps://proompteng.github.io/bilig/directus-workpaper-flow-operation.html\u003e.\n- Trigger.dev Durable Formula Tasks and Dagster Formula Assets are covered in\n  the workflow recipe docs.\n- ELT validation recipes: `airbyte-workpaper-validation` and\n  `meltano-workpaper-utility`.\n\n## Choose An Evaluation Path\n\n| If you are evaluating...          | Start here                                                                                                                                                                                                                                                                                                   | What should be true before you adopt                                                                      |\n| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |\n| Node service formulas             | [Node service WorkPaper evaluator](docs/eval-workpaper-service.md)                                                                                                                                                                                                                                           | A starter writes one input, recalculates, persists JSON, restores, and prints `verified: true`.           |\n| MCP tool contract                 | [MCP workbook evaluator](docs/eval-agent-mcp.md)                                                                                                                                                                                                                                                             | MCP tool discovery, input edit, formula readback, persistence, and restart proof all pass.                |\n| Integration proof chooser         | [Tool-host evaluator matrix](docs/agent-proof-matrix.md), [MCP spreadsheet tool server](docs/mcp-spreadsheet-formula-server-for-coding-agents.md), and [Vercel AI SDK formula readback](docs/vercel-ai-sdk-spreadsheet-tool-formula-readback.md) | The integration path starts with the smallest verified proof and avoids write-only or UI-only claims.     |\n| Runtime intent adapters           | [Workbook runtime intent API](docs/workbook-runtime-intent-api.md) and [runtime intent example](https://github.com/proompteng/bilig/tree/main/examples/workbook-agent-model)                                                                                                                                 | A model prepares transport-neutral plan data, strict runtime proof, command receipts, and check evidence. |\n| Basic fit                         | [Why use Bilig?](docs/why-use-bilig.md)                                                                                                                                                                                                                                                                      | The problem is workbook-shaped business logic that needs API readback and persistence.                    |\n| Published npm package             | [90-second Node quickstart](docs/try-bilig-headless-in-node.md)                                                                                                                                                                                                                                              | `@bilig/workpaper` edits one input, recalculates, persists JSON, restores, and prints `verified: true`.   |\n| Backend service shape             | [Quote approval WorkPaper API](docs/quote-approval-workpaper-api.md)                                                                                                                                                                                                                                         | A realistic route-style workflow returns formula readback and `restoredMatchesAfter: true`.               |\n| MCP clients and host integrations | [WorkPaper host handbook](docs/headless-workpaper-agent-handbook.md), [MCP spreadsheet tool server](docs/mcp-workpaper-tool-server.md), [Gemini CLI extension](docs/gemini-cli-workpaper-extension.md), and [Claude Desktop MCPB bundle](docs/claude-desktop-mcpb-workpaper.md)                              | The host installs a tool path, follows the handoff guide, then proves write/readback/persist.             |\n| Technical WorkPaper review        | [WorkPaper maintainer proof note](docs/show-hn-formula-workbooks-node-services.md)                                                                                                                                                                                                                           | One compact page has the npm check, benchmark caveat, known limits, and open questions.                   |\n| Trust and compatibility           | [npm provenance](docs/npm-provenance-package-trust.md), [compatibility limits](docs/where-bilig-is-not-excel-compatible-yet.md), and [Workbook Compatibility Report](docs/workbook-compatibility-report.md)                                                                                                  | npm shows SLSA provenance, and workbook behavior is checked through deterministic evaluator and XLSX gates. |\n| Imported files                    | [Workbook Compatibility Report](docs/workbook-compatibility-report.md), [file formula recalculation](docs/xlsx-formula-recalculation-node.md), and [ExcelJS formula recalculation](docs/exceljs-formula-recalculation-node.md)                                                                               | The file boundary is inspected before a service, CI job, or workflow trusts imported formulas.            |\n| Almost a fit                      | [implementation gap discussion](https://github.com/proompteng/bilig/discussions/new?category=general)                                                                                                                                                                                                        | Name the formula, import/export, persistence, framework, MCP, package, or benchmark gap.                  |\n| Formula or import bug             | [formula bug clinic](docs/formula-bug-clinic.md) and [submit a workbook fixture](docs/submit-workbook-fixture.md)                                                                                                                                                                                            | Share one reduced public case that can become a fixture.                                                  |\n\nReduced workbook already in hand? If the blocker is an import, formula, or\npersistence gap, generate the fixture report:\n\n```sh\nnpm exec --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells \"Summary!B7,Inputs!B2\"\n```\n\nHanding a workbook task to an MCP client or host integration? Start with the\n[host handoff guide](docs/headless-workpaper-agent-handbook.md#copy-paste-prompt-for-another-agent)\nbefore opening Excel, LibreOffice, Google Sheets, or a screenshot UI. That\nsection keeps the host handoff prompt for clients that require copy-paste\ninstructions.\nTo prove the package-owned MCP loop without cloning the repo:\n\n```sh\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json\nnpm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json\nnpm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json\n```\n\nTool hosts that support skill manifests can start from\n[`skill.md`](docs/skill.md) or the well-known index at\n[`docs/.well-known/agent-skills/index.json`](docs/.well-known/agent-skills/index.json).\nClaude Desktop users can install the released MCPB bundle directly:\n\u003chttps://github.com/proompteng/bilig/releases/latest/download/bilig-workpaper.mcpb\u003e.\nFor host-specific project files, use the\n[agent rule chooser](docs/agent-rule-chooser.md).\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 \u003chttps://proompteng.github.io/bilig/npm-eval.ts\u003e and\n[`examples/headless-workpaper/npm-eval.ts`](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`](packages/create-workpaper), and the publish gate\nis documented in [create a Bilig WorkPaper starter](docs/create-bilig-workpaper.md).\nFor an MCP-enabled project with host integration files, MCP client configs, and\nan `agent:verify` script, run\n`npm create @bilig/workpaper@latest pricing-agent -- --agent`.\nRepresentative host files include `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`,\n`.claude/skills/bilig-workpaper/SKILL.md`, `.cursor/rules/bilig-workpaper.mdc`,\n`.trae/mcp.json`, and `.zed/settings.json`.\nFor an existing repo, run\n`npm create @bilig/workpaper@latest . -- --add-agent`; it adds Bilig MCP and\nhost instructions without replacing your app template or editing\n`package.json`. If a host policy already exists, it writes\n`BILIG_WORKPAPER_INSTALL.md` with the skipped paths and a short handoff block.\n\nIf that proof almost matches a service or integration workflow you maintain, the\nuseful next step is a concrete gap report in\n[Discussions](https://github.com/proompteng/bilig/discussions/new?category=general):\nformula coverage, service persistence, MCP setup, agent writeback, import/export\nboundary, 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 stored formula results as truth; use the Excel oracle workflow when\naccuracy matters.\n\n## Package Boundary\n\nCurrent checked npm metadata for `@bilig/workpaper@latest`:\n\n- Published package: `57.7 kB` unpacked, `49` package entries.\n- Boundary: the public package owns WorkPaper starters, evaluators, MCP command\n  wrappers, formula clinic reports, JSON persistence, and restored readback.\n- Runtime: Node `\u003e=22.0.0`; Node 22 compatibility is covered by the runtime\n  package workflow.\n\n## Published Package Trust\n\n`@bilig/workpaper` 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/workpaper 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](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](examples/serverless-workpaper-api) example:\n   `npm run quote-approval-api`.\n3. If the workflow starts with a saved workbook file, run the\n   [XLSX formula recalculation in Node](examples/xlsx-recalculation-node):\n   `npm start`.\n4. If a tool host needs workbook tools, start with the\n   [headless WorkPaper host handbook](docs/headless-workpaper-agent-handbook.md),\n   then use the [MCP server guide](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](docs/formula-bug-clinic.md). Include the exact cell,\n   expected value, actual value, and command output.\n   If the fixture is already reduced, submit the structured\n   [fixture form](docs/submit-workbook-fixture.md) so the blocker can become a\n   test, example, or corpus case instead of private feedback.\n   \u003chttps://github.com/proompteng/bilig/issues/new?template=workbook_fixture.yml\u003e.\n   If you are still reducing the case, discuss the shape first:\n   \u003chttps://github.com/proompteng/bilig/discussions/414\u003e.\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](docs/why-use-bilig.md),\n[screenshot automation boundary](docs/stop-driving-spreadsheets-with-screenshots.md),\n[Google Sheets API boundary](docs/google-sheets-api-alternative-node-workpaper.md),\n[Google Sheets QUERY/SORTN in Node](docs/google-sheets-query-sortn-node-workpaper.md),\n[workbook automation examples](docs/workbook-automation-examples-node.md),\nthe [formula workbooks proof page](docs/formula-workbooks-node-services-agent-tools.md),\nthe [Node spreadsheet formula engine guide](docs/node-spreadsheet-formula-engine.md),\n[server-side spreadsheet automation](docs/server-side-spreadsheet-automation-node.md),\n[framework adapters](docs/node-framework-workpaper-adapters.md),\n[formula bug clinic](docs/formula-bug-clinic.md),\n[workbook fixture submissions](docs/submit-workbook-fixture.md),\n[OpenAI Agents SDK tools](docs/openai-agents-sdk-workpaper-tool.md),\n[Browser Use formula tool](docs/browser-use-workpaper-formula-tool.md),\n[Google ADK MCP tools](docs/google-adk-workpaper-mcp.md),\n[OpenHands MCP setup](docs/openhands-workpaper-mcp.md),\n[OpenCode MCP setup](docs/opencode-workpaper-mcp.md),\n[Microsoft Agent Framework MCP tools](docs/microsoft-agent-framework-workpaper-mcp.md),\n[Goose MCP recipe](docs/goose-workpaper-mcp.md),\n[tool-host evaluator matrix](docs/agent-proof-matrix.md),\n[MCP spreadsheet formula server for tool hosts](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[AI SDK and LangChain tools](docs/vercel-ai-sdk-langchain-spreadsheet-tool.md),\n[CrewAI adapter](docs/crewai-workpaper-spreadsheet-tool.md),\nthe [WorkPaper host handbook](docs/headless-workpaper-agent-handbook.md),\nthe [MCP server guide](docs/mcp-workpaper-tool-server.md),\n[spreadsheet MCP server comparison](docs/spreadsheet-mcp-server-comparison.md),\n[MCP directory status](docs/mcp-spreadsheet-server-directory.md),\n[MCP client setup](docs/mcp-client-setup.md),\n[Gemini CLI extension](docs/gemini-cli-workpaper-extension.md),\n[FastMCP Python client](docs/fastmcp-workpaper-client.md),\n[Claude Desktop MCPB bundle](docs/claude-desktop-mcpb-workpaper.md),\n[npm provenance and package trust](docs/npm-provenance-package-trust.md),\n[JavaScript library comparison](docs/javascript-spreadsheet-library-headless-node.md),\n[Node spreadsheet formula engine guide](docs/node-spreadsheet-formula-engine.md),\n[server-side spreadsheet automation](docs/server-side-spreadsheet-automation-node.md),\n[saved-workbook formula recalculation](docs/xlsx-formula-recalculation-node.md),\n[XLSX formula support answers](docs/xlsx-formula-support-answers.md),\n[SheetJS/ExcelJS boundary](docs/sheetjs-exceljs-alternative-formula-workbook-api.md),\n[ExcelJS formula result boundary](docs/exceljs-formula-result-not-updating-after-node-edits.md),\n[Microsoft Graph Excel boundary](docs/microsoft-graph-excel-recalculation-node.md),\nand [engine comparison](docs/headless-spreadsheet-engine-comparison.md).\n\nUseful deeper examples: [invoice totals](examples/headless-workpaper#invoice-totals),\n[budget variance alerts](examples/headless-workpaper#budget-variance-alerts),\n[fulfillment capacity plan](examples/headless-workpaper#fulfillment-capacity-plan),\n[quote approval threshold](examples/headless-workpaper#quote-approval-threshold),\n[subscription MRR forecast](examples/headless-workpaper#subscription-mrr-forecast),\n[agent framework adapters](examples/headless-workpaper#agent-framework-adapters),\n[MCP tool server shape](examples/headless-workpaper#mcp-tool-server-shape),\n[XLSX formula recalculation in Node](examples/xlsx-recalculation-node),\nand [serverless quote approval](examples/serverless-workpaper-api). Run\n`npm run quote-approval-api`, `npm run agent:openai-agents-sdk`,\n`npm run agent:framework-adapters`,\n`npm run agent:mcp-tools`, `npm run agent:mcp-transcript`,\n`npm run agent:mcp-file-transcript`, `npm run agent:mcp-stdio`, or\n`npm exec --package @bilig/workpaper -- bilig-workpaper-mcp` when that is the\npath you are evaluating.\n\nSaved workbook diagnostics stay available when a file is the integration\nboundary:\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 --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc --demo --json\nnpm exec --package @bilig/sheetjs-formula-recalc@latest -- sheetjs-recalc --demo --json\n```\n\nThe serverless example also includes `npm run next-route-handler`,\n`npm run next-server-action`, `npm run next-server-action-formdata`,\n`npm run hono-route`, `npm run framework-adapters`, and\n`npm run persistence-adapters` for\nframework-specific boundary checks.\n\nThe MCP server is also listed in the official registry:\n\u003chttps://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper\u003e.\nClients that support Streamable HTTP MCP can also smoke-test the stateless\nhosted endpoint at `https://bilig.proompteng.ai/mcp`; use the local stdio server\nwhen the agent needs to persist a project WorkPaper JSON file.\n\n## Examples You Can Run\n\nThe runnable examples are TypeScript files. Some source imports end in `.js`\nbecause Node ESM resolves compiled package output that way; the files you edit\nand run are still `.ts`.\n\nFrom a cloned checkout:\n\n```sh\npnpm --dir examples/headless-workpaper install --ignore-workspace\npnpm --dir examples/headless-workpaper run start\npnpm --dir examples/headless-workpaper run json-records\npnpm --dir examples/headless-workpaper run csv-shaped\npnpm --dir examples/headless-workpaper run invoice-totals\npnpm --dir examples/headless-workpaper run budget-variance\npnpm --dir examples/headless-workpaper run fulfillment-capacity\npnpm --dir examples/headless-workpaper run quote-approval\npnpm --dir examples/headless-workpaper run subscription-mrr\npnpm --dir examples/headless-workpaper run persistence\n```\n\nThe most useful entry points:\n\n- [JSON records input](examples/headless-workpaper#json-records-input)\n- [CSV shaped input](examples/headless-workpaper#csv-shaped-input)\n- [invoice totals](examples/headless-workpaper#invoice-totals)\n- [budget variance alerts](examples/headless-workpaper#budget-variance-alerts)\n- [fulfillment capacity plan](examples/headless-workpaper#fulfillment-capacity-plan)\n- [quote approval threshold](examples/headless-workpaper#quote-approval-threshold)\n- [subscription MRR forecast](examples/headless-workpaper#subscription-mrr-forecast)\n- [SheetJS, xlsx-populate, and ExcelJS recalculation bridge](examples/recalc-bridge-workflows)\n\nFor tool integrations:\n\n```sh\npnpm --dir examples/headless-workpaper run agent:verify\npnpm --dir examples/headless-workpaper run agent:tool-call\npnpm --dir examples/headless-workpaper run agent:openai-agents-sdk\npnpm --dir examples/headless-workpaper run agent:openai-agents-sdk-mcp\npnpm --dir examples/headless-workpaper run agent:openai-agents-sdk-hosted-mcp\npnpm --dir examples/headless-workpaper run agent:openai-responses\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:framework-adapters\npnpm --dir examples/serverless-workpaper-api run hono-route\npnpm --dir examples/mastra-workpaper-tool run smoke\npnpm --dir examples/langgraph-workpaper-tool-state run smoke\npnpm --dir examples/langchain-mcp-workpaper-toolnode run smoke\npnpm --dir examples/headless-workpaper run agent:mcp-tools\npnpm --dir examples/headless-workpaper run agent:mcp-file-transcript\npnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight\npnpm --dir examples/headless-workpaper run agent:mcp-stdio\n```\n\nThe AI SDK example uses\n[`ai-sdk-generate-text-tool-smoke.ts`](examples/headless-workpaper/ai-sdk-generate-text-tool-smoke.ts).\nThe OpenAI Agents SDK guide is\n[`docs/openai-agents-sdk-workpaper-tool.md`](docs/openai-agents-sdk-workpaper-tool.md).\nIt includes direct `tool()` wrapping, private `MCPServerStdio` discovery, and\nhosted stateless `MCPServerStreamableHttp` discovery through the WorkPaper MCP\ntool loop.\nThe ChatGPT Apps Developer Mode setup is\n[`docs/chatgpt-apps-workpaper-mcp.md`](docs/chatgpt-apps-workpaper-mcp.md).\nIt shows the public `/mcp` endpoint as a data/tool-only remote MCP app and keeps\ncustom Apps SDK component UI as future scope.\nThe OpenAI Responses guide is\n[`docs/openai-responses-workpaper-tool-call.md`](docs/openai-responses-workpaper-tool-call.md).\nThe agent framework guide is\n[`docs/vercel-ai-sdk-langchain-spreadsheet-tool.md`](docs/vercel-ai-sdk-langchain-spreadsheet-tool.md).\nThe Mastra guide includes a real `@mastra/core` `createTool()` smoke:\n[`docs/mastra-workpaper-spreadsheet-tool.md`](docs/mastra-workpaper-spreadsheet-tool.md).\nThe LangGraph.js ToolNode proof is\n[`docs/langgraph-workpaper-toolnode-spreadsheet.md`](docs/langgraph-workpaper-toolnode-spreadsheet.md).\nIt includes a no-key `@langchain/mcp-adapters` smoke that discovers the\npublished WorkPaper MCP stdio tools and executes them through `ToolNode`.\n\nThe package also ships the MCP stdio binary:\n\n```sh\nnpm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json\nnpm exec --package @bilig/workpaper@latest -- bilig-formula-clinic ./reduced.xlsx --cells \"Summary!B7,Inputs!B2\"\nnpm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json\nnpm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp\nnpm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./pricing.workpaper.json --init-demo-workpaper --writable\nnpm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx\nnpm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx --workpaper ./.bilig/pricing.workpaper.json --writable\npnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight\ndocker build --target bilig-workpaper-mcp -t bilig-workpaper-mcp:local .\n```\n\n`bilig-agent-challenge` prints the same edit, formula readback, WorkPaper JSON\nexport, restore, and `verified: true` proof object used by the agent workbook\nchallenge page.\n\n`bilig-mcp-challenge` proves the file-backed MCP path end to end: initialize\nJSON-RPC, list tools/resources/prompts, edit `Inputs!B3`, read recalculated\n`Summary!B3`, export the WorkPaper JSON, restart from disk, and return\n`verified: true`.\n\n`bilig-formula-clinic` imports a reduced XLSX locally, samples formulas, reads\nrequested cells through WorkPaper, and prints a Markdown issue body. It does not\nupload workbook contents.\n\nWithout `--workpaper`, the binary starts the built-in demo workbook. With\n`--workpaper`, it loads your persisted WorkPaper JSON and exposes\n`list_sheets`, `read_range`, `read_cell`, `set_cell_contents`,\n`set_cell_contents_and_readback`, `get_cell_display_value`,\n`export_workpaper_document`, and `validate_formula`; `--writable` persists\n`set_cell_contents` or `set_cell_contents_and_readback` edits back to the same\nfile. If you already have an XLSX, `--from-xlsx ./pricing.xlsx` imports it into\nan in-memory WorkPaper server for readback, throwaway edits, and\n`analyze_workbook_risk` without writing a sidecar. Add `--workpaper ... --writable`\nonly when the agent needs persisted file state. It also\nexposes MCP resources and prompts for `bilig://workpaper/agent-handoff`,\n`bilig://workpaper/current-document`, `edit_and_verify_workpaper`, and\n`debug_workpaper_formula`, so capable clients can discover the workflow before\ncalling tools.\nFor a maintained real-XLSX transcript, run\n`pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight`.\nIt calls `analyze_workbook_risk`, edits `Inputs!B3`, verifies `Summary!B3`\nchanges from `60000` to `96000`, exports WorkPaper JSON, and keeps\n`excelParity: \"not_proven\"`.\nThe Docker target is for MCP directory scanners: it seeds a demo WorkPaper JSON\ninside the image and starts the file-backed `--writable` tool surface so\n`tools/list`, `resources/list`, and `prompts/list` return the general WorkPaper\nagent surface without cloning this monorepo. For remote MCP clients, the app\nruntime exposes `https://bilig.proompteng.ai/mcp` as a stateless JSON-only\nStreamable HTTP endpoint for tool discovery and write/readback smoke tests.\n\nIt is published in the official MCP Registry as\n`io.github.proompteng/bilig-workpaper`:\n\u003chttps://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper\u003e.\nIt is also live on Glama with `Try in Browser`, A-grade tool pages, and the\nfile-backed WorkPaper tools:\n\u003chttps://glama.ai/mcp/servers/proompteng/bilig\u003e.\n\n## Proof You Can Reproduce\n\n- The 90-second TypeScript check above edits one input, restores the saved JSON\n  document, and verifies the dependent formula result.\n- For a service evaluator path, run the\n  [quote approval WorkPaper API proof](docs/quote-approval-workpaper-api.md).\n  It starts from an empty Node directory, downloads one maintained TypeScript\n  route smoke, writes quote inputs, recalculates an approval decision, persists\n  JSON, and verifies restored readback.\n- For a shorter evaluation page, read\n  [formula workbooks for Node services and tool integrations](docs/formula-workbooks-node-services-agent-tools.md).\n  It compresses the WorkPaper boundary, MCP file-backed mode, benchmark caveat,\n  and alternative-tool guidance into one evaluation path.\n- For a compact review note, use the\n  [WorkPaper maintainer proof note](docs/show-hn-formula-workbooks-node-services.md).\n  It keeps the empty npm-project command, `verified: true` output, benchmark\n  caveat, known limits, and open questions together.\n- For saved-file integration, run the XLSX formula recalculation example:\n  [`examples/xlsx-recalculation-node`](examples/xlsx-recalculation-node). It\n  imports a generated XLSX pricing workbook, edits input cells, reads the\n  recalculated approval decision, exports XLSX, reimports it, and verifies the\n  formulas survived the round trip. The public decision page is\n  [XLSX formula recalculation in Node.js](docs/xlsx-formula-recalculation-node.md).\n- Read the [compatibility limits](docs/where-bilig-is-not-excel-compatible-yet.md)\n  before importing real Excel workbooks.\n- Use the\n  [production adoption checklist](docs/production-adoption-checklist-headless-workpaper.md)\n  before promoting a WorkPaper-backed workflow beyond evaluation.\n- For XLSX accuracy audits, use the\n  [Excel oracle harness](docs/xlsx-corpus-verifier-walkthrough.md#run-the-excel-oracle-harness).\n  It separates import success, timeouts, cached workbook values, and fresh\n  Microsoft Excel recalculation results.\n- The WorkPaper MCP server is listed in the\n  [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.proompteng%2Fbilig-workpaper)\n  and on [Glama](https://glama.ai/mcp/servers/proompteng/bilig). The\n  [directory status page](docs/mcp-spreadsheet-server-directory.md) keeps the\n  npm command, remote endpoint, static MCP server card, and directory evidence\n  in one place.\n- Public feedback threads:\n  [workflow questions](https://github.com/proompteng/bilig/discussions/157),\n  [service examples](https://github.com/proompteng/bilig/discussions/213),\n  [persistence adapters](https://github.com/proompteng/bilig/discussions/307),\n  [JavaScript spreadsheet library guide](https://github.com/proompteng/bilig/discussions/308),\n  [OpenAI Responses tool calls](https://github.com/proompteng/bilig/discussions/335),\n  and [benchmark critique](https://github.com/proompteng/bilig/discussions/340).\n\nIf you are evaluating Bilig runtime packages for production and want release\nnotifications, watch releases:\n\u003chttps://github.com/proompteng/bilig/subscription\u003e.\n\n## XLSX Accuracy Policy\n\nCached formula values embedded in `.xlsx` files are cache diagnostics, not an\naccuracy verdict. A Bilig correctness bug should only be claimed when the\nexpected value came from a fresh Excel recalculation oracle.\n\n```sh\nOUT=.cache/excel-oracle-evaluation\npnpm workpaper:xlsx-oracle -- prepare-oracle /path/to/xlsx-corpus \"$OUT\"\npnpm workpaper:xlsx-oracle -- evaluate-cache /path/to/xlsx-corpus \"$OUT\"\npnpm workpaper:xlsx-oracle -- evaluate-oracle /path/to/xlsx-corpus \"$OUT/recalculated\" \"$OUT\"\npnpm workpaper:xlsx-oracle -- summarize \"$OUT\"\n```\n\n`evaluate-cache` writes `cache-diagnostic.json` and stays non-authoritative.\n`evaluate-oracle` writes `excel-oracle-report.json`, and `summarize` writes\n`summary.md`. If Excel automation is unavailable, cells are classified as\n`missing_excel_oracle` instead of being promoted to bugs.\n\n## What Is In This Repo\n\n- `packages/workpaper`: public WorkPaper package, starters, evaluator binaries,\n  and MCP wrappers.\n- `packages/headless`: lower-level WorkPaper runtime that backs the public\n  package.\n- `packages/excel-import`: saved-workbook import/export boundary.\n- `packages/formula`: formula parser, binder, compiler, and evaluator.\n- `packages/core`: workbook engine, snapshots, mutation flow, and scheduler.\n- `packages/grid` and `apps/web`: browser spreadsheet shell.\n- `apps/bilig`: fullstack monolith runtime, API surface, and static asset\n  server.\n- `packages/renderer`: React workbook renderer.\n- `packages/protocol`, `packages/binary-protocol`, `packages/agent-api`, and\n  `packages/worker-transport`: protocol and integration boundaries.\n- `packages/wasm-kernel`: AssemblyScript/WASM numeric fast path.\n- `packages/benchmarks`: benchmark harness and performance contracts.\n\nFor XLSX import/export from TypeScript:\n\n```ts\nimport { WorkPaper } from '@bilig/workpaper'\nimport { exportXlsx, importXlsx } from '@bilig/workpaper/xlsx'\n```\n\nUse `WorkPaper.buildFromSnapshot(imported.snapshot)` after import and\n`workbook.exportSnapshot()` before `exportXlsx()`.\n\n## Local Development\n\nUse Node `24+`, Bun, and `pnpm@10.32.1`.\n\n```sh\npnpm install\npnpm dev:web\npnpm dev:web-local\npnpm dev:sync\n```\n\nFor a full local preflight:\n\n```sh\npnpm lint\npnpm typecheck\npnpm test\npnpm test:browser\npnpm run ci\n```\n\nGenerated sources and deterministic public docs are checked:\n\n```sh\npnpm protocol:check\npnpm formula-inventory:check\npnpm workspace-resolution:check\npnpm docs:discovery:check\n```\n\n## For Coding Agents\n\nStart with the public package boundary unless the task is explicitly engine\nwork.\n\n1. Read `packages/workpaper/README.md` before touching public WorkPaper behavior.\n2. Read `docs/AGENTS.md`, `docs/skill.md`, or `docs/llms-full.txt` when\n   building an agent-facing integration from outside the repo.\n3. Use public exports from `@bilig/workpaper`; do not reach into `src/` or\n   `dist/` when writing consumer examples.\n4. Keep examples TypeScript-first.\n5. Do not call embedded XLSX stored formula results an accuracy oracle.\n6. Add focused tests before changing formulas, persistence, range bounds,\n   config rebuilds, events, row/column moves, or sheet lifecycle.\n7. Run the focused package tests first, then broaden to `pnpm run ci`.\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. If this is your\nfirst patch, start with the\n[new contributor guide](docs/new-contributor-guide.md) and then claim a scoped\nstarter issue.\n\nGood first patches usually fit one of these shapes:\n\n- formula fixtures with clear expected behavior;\n- small WorkPaper examples that prove a real service or agent workflow;\n- focused correctness fixes with regression tests;\n- grid accessibility and keyboard-behavior improvements;\n- docs that turn an existing architecture note into a runnable command.\n\nThe shortest public on-ramp is the\n[`starter issues`](docs/starter-issues.md) queue. It keeps code/test picks,\nexample tasks, adapters, and focused docs work in one current list, with small\nacceptance commands for first patches.\n\nIf this is your first contribution to `bilig`, use the\n[`first-timers-only`](https://github.com/proompteng/bilig/issues?q=is%3Aissue%20state%3Aopen%20label%3Afirst-timers-only)\nfilter.\n\n## Security And Support\n\nRead [SECURITY.md](SECURITY.md) before sharing vulnerability details, private\nworkbook data, tokens, credentials, or exploit reproductions. Security reports\nshould use GitHub private vulnerability reporting when available, or\n\u003csecurity@proompteng.ai\u003e when the private flow is not visible.\n\nUse [SUPPORT.md](SUPPORT.md) for the fastest public support path. Good reports\ninclude the package version, Node version, OS, exact formula or workbook input,\nexpected value, actual value, and the smallest command or script that reproduces\nthe issue.\n\n## CI\n\nForgejo Actions is the primary CI surface via\n`.forgejo/workflows/forgejo-ci.yml`. GitHub Actions mirrors the verification\ncontract in `.github/workflows/ci.yml`.\n\nThe strict gate includes frozen lockfile install, full `pnpm run ci`, artifact\nbudget checks, browser smoke, and tracked-file cleanliness checks.\n\n## License\n\nMIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/proompteng.github.io%2Fbilig%2F","html_url":"https://awesome.ecosyste.ms/projects/proompteng.github.io%2Fbilig%2F","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/proompteng.github.io%2Fbilig%2F/lists"}