bilig

# bilig

[![CI](https://github.com/proompteng/bilig/actions/workflows/ci.yml/badge.svg)](https://github.com/proompteng/bilig/actions/workflows/ci.yml)
[![npm: @bilig/xlsx-formula-recalc](https://img.shields.io/npm/v/@bilig/xlsx-formula-recalc?label=%40bilig%2Fxlsx-formula-recalc)](https://www.npmjs.com/package/@bilig/xlsx-formula-recalc)
[![npm: @bilig/headless](https://img.shields.io/npm/v/@bilig/headless?label=%40bilig%2Fheadless)](https://www.npmjs.com/package/@bilig/headless)
[![npm: @bilig/workpaper](https://img.shields.io/npm/v/@bilig/workpaper?label=%40bilig%2Fworkpaper)](https://www.npmjs.com/package/@bilig/workpaper)
[![CodeQL](https://github.com/proompteng/bilig/actions/workflows/codeql.yml/badge.svg)](https://github.com/proompteng/bilig/actions/workflows/codeql.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/proompteng/bilig/badge)](https://scorecard.dev/viewer/?uri=github.com/proompteng/bilig)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

**Run workbook rules from Node, with formula readback you can verify.**

Bilig is for workbook logic that has to run from code. If your service or agent
should own the workbook model, start with `@bilig/workpaper`: edit cells,
recalculate formulas, read outputs, and persist JSON. If an existing `.xlsx`
file is still the contract, use the XLSX tools to find stale cached formula
values and refresh readback.

Start with the boundary you actually have. Do not drive Excel, LibreOffice,
Google Sheets, or a screenshot UI just to learn whether a formula value is
fresh.

Run the no-clone checks:

```sh
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door workbook-compatibility --json
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- bilig-evaluate --door xlsx-cache --json
```

Evaluate a real workbook before integrating it:

```sh
npm exec --yes --package @bilig/xlsx-formula-recalc@latest -- workbook-compatibility-report workbook.xlsx --json
```

The report lists unsupported functions, external links, VBA payloads, pivots,
volatile formulas, stale cached formulas, and concrete risk reasons. It is not
an Excel compatibility certification and does not print a compatibility score.

Expected WorkPaper service result:

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

Need the full formula-cache report for a real workbook?

```sh
npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-cache-doctor pricing.xlsx --json
npm exec --package @bilig/xlsx-formula-recalc@latest -- xlsx-recalc pricing.xlsx --read Summary!B2 --out pricing.recalculated.xlsx --json
```

For pull requests with XLSX fixtures, start with the GitHub Action in report
mode and let it show stale cached formulas before it blocks anything:

```yaml
- uses: actions/setup-node@v6
  with:
    node-version: '22'
    package-manager-cache: false
- uses: proompteng/bilig@v1
  with:
    workbooks: '**/*.xlsx'
    changed-files-only: 'true'
    package-version: '0.164.1'
    fail-on-stale: 'false'
```

For TypeScript services that should own the workbook model:

```sh
npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify
```

For lower-level runtime imports:

```sh
npm install @bilig/headless
```

Direct diagnostic commands remain available:

```sh
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-challenge --json
npm exec --yes --package @bilig/workpaper@latest -- bilig-mcp-challenge --json
```

Evaluator examples live in
[`examples/bilig-evaluator-proof`](examples/bilig-evaluator-proof).
Agent and framework evaluators are ranked in the
[Agent WorkPaper proof matrix](docs/agent-proof-matrix.md).
The [agent proof transcripts](docs/agent-proof-transcripts.md) show the
successful prompt, tool call, workbook state change, formula readback, JSON
export, and restart verification shape.
The [XLSX Cache Doctor proof transcript](docs/xlsx-cache-doctor-proof-transcript.md)
shows the stale cached formula value, recalculated value, exact cell address,
and suggested read target before a service or CI job trusts a saved workbook.
The [Workbook Compatibility Report](docs/workbook-compatibility-report.md)
shows the local risk report for an actual `.xlsx` before a Node service or
coding agent trusts Bilig with it.
Use the [coding agent rule chooser](docs/agent-rule-chooser.md) when you need
the exact instruction, rule, prompt, or MCP config file for Codex, Claude Code,
GitHub Copilot, VS Code, Cursor, Kiro, Roo Code, Trae, Qodo IDE, Zed, Junie, OpenHands, OpenCode, Aider,
Goose, Windsurf/Cascade, Cline, Continue, or Gemini CLI.

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

## Start Here

Pick the path that matches the job:

| You have...                                                                                             | Start with                                                                       | You should see                                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You are not sure whether XLSX, SheetJS, ExcelJS, xlsx-populate, CI, WorkPaper, or an agent owns the fix | [Stale formula readback chooser](docs/stale-formula-readback-chooser.md)         | the smallest proof command for the boundary, plus when not to use it.                                                                                                                       |
| You need to know whether a specific workbook has Bilig integration risks                                | [Workbook Compatibility Report](docs/workbook-compatibility-report.md)           | unsupported functions, external links, macros, pivots, volatile formulas, cache risks, and no compatibility score.                                                                          |
| A coding agent already has a real `.xlsx` and needs MCP before edits                                    | [Agent XLSX risk preflight](docs/agent-xlsx-risk-preflight.md)                   | `analyze_workbook_risk`, `Inputs!B3`, `Summary!B3`, `60000 -> 96000`, export, and `verified: true`.                                                                                         |
| A real `.xlsx` file has stale formula results after Node edits                                          | [XLSX Cache Doctor evaluator](docs/eval-xlsx-cache-doctor.md)                    | stale cells, cached values, recalculated values, suggested reads, and JSON output.                                                                                                          |
| You need to see the exact stale-cache output before adopting                                            | [XLSX Cache Doctor proof transcript](docs/xlsx-cache-doctor-proof-transcript.md) | `Summary!B2` and `Sheet1!B61` cached-vs-recalculated proof, plus CI boundary.                                                                                                               |
| Pull requests can commit XLSX fixtures with stale cached values                                         | [XLSX Cache Doctor GitHub Action](docs/xlsx-cache-doctor-github-action.md)       | report-only workbook findings before the workflow blocks anything.                                                                                                                          |
| 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`.                                                                                                      |
| A coding agent or MCP client needs workbook tools without UI automation                                 | [Agent MCP evaluator](docs/eval-agent-mcp.md)                                    | tool discovery, cell edit, formula readback, export, restart check, and `verified: true`.                                                                                                   |
| A coding agent needs the right repo rule or MCP config file                                             | [Coding agent rule chooser](docs/agent-rule-chooser.md)                          | the exact Bilig file for Codex, Claude Code, Copilot, VS Code, Cursor, Kiro, Roo Code, Trae, Qodo IDE, Zed, Junie, OpenHands, OpenCode, Aider, Goose, Windsurf, Cline, Continue, or Gemini. |
| You are comparing Excel MCP servers, hosted spreadsheet agents, or file-first XLSX tools                | [Spreadsheet MCP server comparison](docs/spreadsheet-mcp-server-comparison.md)   | the account/session/file/runtime boundary before an agent trusts formula readback.                                                                                                          |
| You need to choose among agent, MCP, AI SDK, OpenAI, LangGraph, Semantic Kernel, or XLSX proof          | [Agent WorkPaper proof matrix](docs/agent-proof-matrix.md)                       | the smallest command or example for