# Agent Instructions

Use `@bilig/workpaper` as the source of truth for workbook logic in this
project. Do not open Excel, LibreOffice, Google Sheets, or a browser grid for
primary formula work unless a human explicitly asks for visual review.

## Verify First

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

That command is the package-owned proof gate. A valid run includes
`verified: true` and covers `SUM`, `SUMIF`, `XLOOKUP`, `FILTER`, a named
expression, persistence, and restart readback. Generated starters also include
`npm run agent:verify`.

## Agent Surfaces

This starter includes project instructions for common coding agents:

- Claude Code: `CLAUDE.md`, `.claude/skills/bilig-workpaper/SKILL.md`,
  and `.claude/commands/bilig-workpaper-proof.md`
- Codex and other AGENTS-aware tools: `AGENTS.md`
- Gemini CLI: `GEMINI.md`
- GitHub Copilot and VS Code agent mode:
  `.github/copilot-instructions.md`,
  `.github/instructions/bilig-workpaper.instructions.md`,
  `.github/prompts/bilig-workpaper-proof.prompt.md`, and `.vscode/mcp.json`
- Cursor: `.cursor/rules/bilig-workpaper.mdc` and `.cursor/mcp.json`
- Kiro: `.kiro/steering/bilig-workpaper.md` and `.kiro/settings/mcp.json`
- Roo Code: `.roo/rules/bilig-workpaper.md` and `.roo/mcp.json`
- Trae: `.trae/rules/bilig-workpaper.md` and `.trae/mcp.json`
- Qodo IDE: paste the `bilig-workpaper` JSON from the public Qodo setup guide
  into Qodo Agentic Tools MCP settings; keep root `AGENTS.md` as policy
- OpenHands: `.agents/skills/bilig-workpaper/SKILL.md`
- OpenCode: `opencode.jsonc` and `.opencode/agents/bilig-workpaper.md`
- Aider: `CONVENTIONS.md` loaded by `.aider.conf.yml`
- Cascade/Devin: `.devin/rules/bilig-workpaper.md`
- Cline: `.clinerules/bilig-workpaper.md`
- Continue: `.continue/rules/bilig-workpaper.md` and
  `.continue/mcpServers/bilig-workpaper.yaml`
- Windsurf/Cascade fallback: `.windsurf/rules/bilig-workpaper.md`

## Preferred Agent Loop

1. Read the relevant sheet, range, or API output before editing.
2. Name the exact sheet and A1 cell target.
3. Validate formulas before writing them.
4. Prefer `set_cell_contents_and_readback` for one-call edit plus dependent
   output readback.
5. Otherwise, write one small input or formula change and then read the
   dependent calculated output after recalculation.
6. Export or serialize the WorkPaper document.
7. Report `editedCell`, `before`, `after`, `afterRestore` or persistence
   evidence, `verified`, and known limitations.

Do not claim success from a write call alone. Success requires computed
readback plus persisted WorkPaper state.

## MCP Server

Start the persistent project-local MCP server with:

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

It launches:

```sh
bilig-workpaper-mcp --workpaper __WORKPAPER_PATH__ --init-demo-workpaper --writable
```

Expected tools:

- `list_sheets`
- `read_range`
- `read_cell`
- `set_cell_contents`
- `set_cell_contents_and_readback`
- `get_cell_display_value`
- `export_workpaper_document`
- `validate_formula`

Use `bilig://workpaper/agent-handoff` or the `edit_and_verify_workpaper`
prompt first when the MCP client supports resources or prompts.