---
description: Use Bilig WorkPaper when a coding agent needs spreadsheet formulas, MCP workbook tools, or formula readback without driving Excel UI.
globs:
alwaysApply: false
---

# Bilig WorkPaper Rule

Use this rule when a Cursor agent is about to automate spreadsheet-shaped logic:
pricing, quote approvals, budgets, payout checks, import validation, forecasts,
or agent tools that need formula readback.

Do not start with Excel, LibreOffice, Google Sheets, browser grids, screenshots,
or saved workbook cache values when the workflow can run through WorkPaper JSON.

## Fast Check Commands

```sh
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --json
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario provider-backed --json
npm exec --package @bilig/workpaper@latest -- bilig-agent-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-mcp-challenge --json
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper __WORKPAPER_PATH__ --init-demo-workpaper --writable
```

Use `bilig-evaluate --door agent-mcp` as the adoption gate. Use the direct
challenge commands only when you need lower-level WorkPaper or MCP JSON-RPC
diagnostics.

Use the hosted stateless MCP smoke endpoint only for connector discovery:

```text
https://bilig.proompteng.ai/mcp
```

Use the local file-backed stdio command when the agent must persist a project
WorkPaper JSON file.

## Required Readback

Before saying the workbook is updated, return readback with:

- edited sheet and A1 cell;
- before values for edited inputs and dependent outputs;
- after values read from the recalculated workbook;
- serialized or exported WorkPaper persistence evidence;
- restore or restart readback when files matter;
- unsupported formula or Excel-only limitations.

Do not claim success from a write call alone.

## Safe Command Handling

Do not build shell commands by concatenating user text. Prefer MCP
`command` plus `args` arrays or direct TypeScript calls. Reject workbook
paths or cell arguments containing newlines, backticks, `$(`, `;`, `&`,
`|`, `<`, or `>`.

## References

- Docs map: https://proompteng.github.io/bilig/llms.txt
- Agent handbook: https://proompteng.github.io/bilig/headless-workpaper-agent-handbook.html
- MCP guide: https://proompteng.github.io/bilig/mcp-workpaper-tool-server.html
- Repository: https://github.com/proompteng/bilig