# Bilig agent start

Use this when a coding agent is about to drive Excel, LibreOffice, Google Sheets, or a browser grid for workbook-shaped logic.

## First command

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

The first command prints the decision card. The second command proves the MCP path.

Use Bilig when the task needs exact workbook cells, formula recalculation, readback, and saved state. Do not use a spreadsheet UI just to learn whether a formula changed.

## Add this to another agent

Print a compact rule for the agent surface you use:

```sh
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules codex
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules claude
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules copilot
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules cursor
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules cline
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules continue
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules windsurf
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules gemini
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules vscode-mcp
npm exec --yes --package @bilig/workpaper@latest -- bilig-agent-start --rules opencode
```

Current source also has rule packs for `aider`, `junie`, `openhands`, `qodo`, `trae`, `zed`. They are not listed as `@latest` commands here until npm publishing catches up, because this page is for commands that a new user can run successfully today.

For an existing repo that should receive the full starter overlay, run:

```sh
npm create @bilig/workpaper@latest . -- --add-agent
```

Suggested files: `AGENTS.md`, `CONVENTIONS.md`, `.aider.conf.yml`, `CLAUDE.md`, `GEMINI.md`, `.agents/skills/bilig-workpaper/SKILL.md`, `.github/copilot-instructions.md`, `.github/instructions/bilig-workpaper.instructions.md`, `.github/prompts/bilig-workpaper-proof.prompt.md`, `.vscode/mcp.json`, `opencode.jsonc`, `.opencode/agents/bilig-workpaper.md`, `.cursor/rules/bilig-workpaper.mdc`, `.kiro/steering/bilig-workpaper.md`, `.kiro/settings/mcp.json`, `.junie/mcp/mcp.json`, `.trae/mcp.json`, `.trae/rules/bilig-workpaper.md`, `.zed/settings.json`, `.devin/rules/bilig-workpaper.md`, `.clinerules/bilig-workpaper.md`, `.continue/rules/bilig-workpaper.md`, `.continue/mcpServers/bilig-workpaper.yaml`, `.windsurf/rules/bilig-workpaper.md`, `gemini-extension.json`, and `gemini-workpaper-context.md`.

## Provider-backed formulas

If the workbook uses `IMPORTRANGE`, `GOOGLEFINANCE`, `IMPORTDATA`, `IMPORTFEED`, `IMPORTHTML`, `IMPORTXML`, `FILTERXML`, `STOCKHISTORY`, or another provider-backed formula, run:

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

Without an adapter, provider-backed formulas should fail closed with `#BLOCKED!` instead of pretending the result is available.

## Evidence to return

A useful answer includes:

- `schemaVersion: "bilig-evaluator.v1"`
- `door: "agent-mcp"`
- `verified: true`
- `editedCell`
- `before`
- `after`
- `afterRestore` or `afterRestart`
- `persistedDocumentBytes` or exported WorkPaper JSON size
- `limitations`

Do not claim success from a write call alone. Read the dependent calculated cell after the edit, export or serialize the WorkPaper, restore or restart when file state matters, and report the blocker if readback fails.

## Local MCP server

```sh
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./.bilig/pricing.workpaper.json --init-demo-workpaper --writable
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx
npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx --workpaper ./.bilig/pricing.workpaper.json --writable
```

Expected tools: `list_sheets`, `read_range`, `read_cell`, `set_cell_contents`, `set_cell_contents_and_readback`, `get_cell_display_value`, `export_workpaper_document`, and `validate_formula`.
When started through the `@bilig/workpaper@latest` `--from-xlsx` path, `tools/list` also includes `analyze_workbook_risk`, a fixed-source diagnostic for the imported XLSX file. It reports workbook risk indicators and does not certify Excel compatibility. Without `--workpaper --writable`, edits stay in memory; add a WorkPaper JSON path only when the task needs persisted file state.
For a maintained transcript that starts from a real XLSX, call `analyze_workbook_risk`, then prove `Inputs!B3` -> `Summary!B3` readback and export with `pnpm --dir examples/headless-workpaper run agent:mcp-xlsx-risk-preflight`.

## More context

- Compact map: https://proompteng.github.io/bilig/llms.txt
- Full agent context: https://proompteng.github.io/bilig/llms-full.txt
- Agent rule chooser: https://proompteng.github.io/bilig/agent-rule-chooser.html
- Agent XLSX risk preflight: https://proompteng.github.io/bilig/agent-xlsx-risk-preflight.html
- Agent instructions: https://proompteng.github.io/bilig/AGENTS.md
- Agent manifest: https://proompteng.github.io/bilig/.well-known/agent.json
- Agent handoff checklist: https://proompteng.github.io/bilig/agent-adoption-kit.html
- Skill discovery: `npx --yes skills@latest add https://bilig.proompteng.ai --list`
- Skill manifest: https://bilig.proompteng.ai/.well-known/agent-skills/bilig-workpaper/SKILL.txt