Bilig

bilig

Run workbook-shaped business rules inside Node.

Bilig gives services, queue workers, tests, MCP servers, and tool integrations a typed WorkPaper object: write inputs, recalculate formulas, read outputs, persist JSON, restore, and verify. It fits pricing models, quote approval, payout checks, import validation, forecasts, and formula-backed workflow steps.

Run the no-project service check from any Node project:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json

Expected WorkPaper service result:

{
  "schemaVersion": "bilig-evaluator.v1",
  "door": "workpaper-service",
  "verified": true,
  "evidence": {
    "editedCell": "Inputs!B2",
    "dependentCell": "Summary!B2",
    "before": 24000,
    "after": 38400,
    "afterRestore": 38400,
    "persistedDocumentBytes": 999
  }
}

For TypeScript services that should own the workbook model:

npm create @bilig/workpaper@latest pricing-workpaper
cd pricing-workpaper
npm install
npm run smoke

For MCP clients or other tool integrations, run the same proof loop through the MCP evaluator before adding host-specific config:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

Evaluator examples live in examples/bilig-evaluator-proof. Integration matrix docs and host-specific config files are available when a team needs them, but the public proof starts with WorkPaper service readback. File compatibility diagnostics are a separate path for import/export boundaries, not the default runtime story.

Project site: https://proompteng.github.io/bilig/

Start Here

Pick the path that matches the job:

If you are not sure which one fits, start with the thing that owns state. Use WorkPaper when your service or tool should own the workbook model. Use file diagnostics only when import/export compatibility is the actual contract.

Good fits: pricing, quote approval, payout checks, import validation, forecasts, CI fixtures, formula-backed workflow steps, and tool integrations that need exact cell addresses plus readback. Bad fits: manual spreadsheet editing, Office macros, desktop Excel automation, or one-off arithmetic where a workbook would be ceremony.

If You Only Try One Thing

Run the WorkPaper service proof at the top of this README first. It is the shortest proof that Bilig gives backend code a workbook object it can change, recalculate, read back, save, and restore without driving Excel, LibreOffice, Google Sheets, or a browser grid.

If an MCP client or tool integration owns the workflow, run the MCP door:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

Trust boundaries:

• Runs locally in Node or in your GitHub Actions runner; no hosted workbook upload is required.
• Does not claim Excel parity. Start with where Bilig is not Excel-compatible yet before using it for irreversible workflows.
• File import/export diagnostics are available when an imported file is the contract, but they are a separate path from service-owned WorkPaper state.

Which Path Should I Install?

Advanced adapters are still available when the boundary is already specific: SheetJS, ExcelJS, external workbooks, MCP/tool integrations, @bilig/workbook when a runtime needs transport-neutral plan data and command receipts, and runtime provenance.

MCP And Tool Integrations

Use the WorkPaper host handoff when a tool host needs workbook reads, writes, recalculation, JSON export, and restore proof. The first check is always the no-key MCP evaluator:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json

That evaluator starts the published WorkPaper tool server, discovers tools, edits an input, reads the dependent formula, exports JSON, restarts, restores, and returns verified: true. Use llms-install.md when a host wants one install file, and use the tool-host evaluator matrix when the host matters more than the package boundary.

The published package also carries AGENTS.md and SKILL.md so hosts inspecting node_modules/@bilig/workpaper can find the same proof locally. Cloned checkouts keep host-specific config indexed in agent rule chooser: CLAUDE.md, .claude/skills/bilig-workpaper/SKILL.md, .claude/commands/bilig-workpaper-proof.md, .cursor/rules/bilig-workpaper.mdc, .devin/rules/bilig-workpaper.md, .windsurf/rules/bilig-workpaper.md, .clinerules/bilig-workpaper.md, .continue/rules/bilig-workpaper.md, .zed/settings.json, opencode.jsonc, and .opencode/agents/bilig-workpaper.md. The public manifest is docs/.well-known/agent.json.

npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list

Integration Recipes After The Proof

Run one evaluator first. Then use the recipe that matches the platform boundary:

• Open WebUI WorkPaper MCP: https://proompteng.github.io/bilig/open-webui-workpaper-mcp.html.
• OpenAI Agents SDK with direct tools, stdio MCP, or MCPServerStreamableHttp: https://proompteng.github.io/bilig/openai-agents-sdk-workpaper-tool.html.
• ChatGPT Apps WorkPaper MCP: https://proompteng.github.io/bilig/chatgpt-apps-workpaper-mcp.html.
• Hugging Face Gradio MCP Space: https://proompteng.github.io/bilig/huggingface-workpaper-space.html.
• n8n self-hosted workflows can use @bilig/n8n-nodes-workpaper; Pipedream formula readback is documented at https://proompteng.github.io/bilig/pipedream-workpaper-formula-readback.html and sourced from docs/pipedream-workpaper-formula-readback.md.
• Directus Persisted Calculated Fields: https://proompteng.github.io/bilig/directus-workpaper-flow-operation.html.
• Trigger.dev Durable Formula Tasks and Dagster Formula Assets are covered in the workflow recipe docs.
• ELT validation recipes: airbyte-workpaper-validation and meltano-workpaper-utility.

Choose An Evaluation Path

…