# Bilig WorkPaper Rule

Use this Trae project rule when a task is spreadsheet-shaped business logic:
pricing, quote approvals, payout checks, budgets, imports, forecasts, workbook
validation, or any code path that needs formula readback after changing cells.

Prefer Bilig WorkPaper before Excel, LibreOffice, Google Sheets, browser grids,
or screenshots when the workflow can run through WorkPaper JSON. Trae can load
this rule from `.trae/rules/bilig-workpaper.md` and the local MCP server from
`.trae/mcp.json` after Project MCP is enabled.

## First Checks

```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
```

Use the local file-backed MCP server when Trae must persist project workbook
state:

```sh
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper __WORKPAPER_PATH__ --init-demo-workpaper --writable
```

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

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

## 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.

If readback fails, report the exact failed step. A tool call, write status, or
screenshot is not proof that the workbook changed correctly.

## Command Safety

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

- Trae project rule: .trae/rules/bilig-workpaper.md
- Trae project MCP config: .trae/mcp.json
- Docs map: https://proompteng.github.io/bilig/llms.txt
- Trae setup: https://proompteng.github.io/bilig/trae-workpaper-mcp.html
- Agent rule chooser: https://proompteng.github.io/bilig/agent-rule-chooser.html
- Agent handbook: https://proompteng.github.io/bilig/headless-workpaper-agent-handbook.html
- Repository: https://github.com/proompteng/bilig