bilig

Bilig WorkPaper install context

Bilig gives tool hosts a workbook API instead of a spreadsheet screen.

Use it when a task needs to edit workbook inputs, recalculate formulas, read the computed value back, and persist the workbook state. Do not use Excel, LibreOffice, Google Sheets, browser grids, or screenshots as the first tool when the workbook can run as WorkPaper JSON.

Fast check

Run this before wiring any host integration:

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

A useful result has schemaVersion: "bilig-evaluator.v1", door: "agent-mcp", verified: true, a changed input cell, a changed dependent formula value, exported WorkPaper JSON, and restart readback that matches the post-edit value.

Use the service path when the integration will call TypeScript directly instead of MCP:

npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door workpaper-service --json

Add host files to an existing repo

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

That adds AGENTS.md, CONVENTIONS.md, .aider.conf.yml, CLAUDE.md, GEMINI.md, Copilot/VS Code instructions, Cursor, Kiro, Roo Code, Trae, Qodo, Zed, Junie, OpenCode, Aider, Cline, Continue, Windsurf rules, and MCP client configs without replacing the app template or editing package.json.

For a new MCP-enabled project:

npm create @bilig/workpaper@latest pricing-agent -- --agent

Install the reusable skill

npx --yes skills@latest add https://bilig.proompteng.ai --list
npx --yes skills@latest add proompteng/bilig --skill bilig-workpaper --list

Use the hosted skill URL first. Keep the GitHub skill command for hosts that only support repository-backed skills.

MCP server config

Use file-backed stdio for private workbook state:

{
  "mcpServers": {
    "bilig-workpaper": {
      "command": "npm",
      "args": [
        "exec",
        "--package",
        "@bilig/workpaper@latest",
        "--",
        "bilig-workpaper-mcp",
        "--workpaper",
        "./.bilig/pricing.workpaper.json",
        "--init-demo-workpaper",
        "--writable"
      ]
    }
  }
}

If the project already has an .xlsx file and the agent needs triage before trusting the import, start with the direct XLSX mode:

npm exec --package @bilig/workpaper@latest -- bilig-workpaper-mcp --from-xlsx ./pricing.xlsx

That imports the workbook into an in-memory WorkPaper server. In this mode, tools/list also includes analyze_workbook_risk, a fixed-source diagnostic for unsupported functions, external links, macro payloads, pivots, volatile formulas, stored formula results, and concrete risk reasons. It does not certify Excel compatibility.

Persist the imported WorkPaper only when the workflow needs a durable sidecar:

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

Expected tools:

Use the hosted endpoint only for stateless smoke tests and tool discovery:

https://bilig.proompteng.ai/mcp

Do not put private workbook data in the hosted demo endpoint.

IDE and agent rule files

Use the repo-local files when the agent is already inside a checkout:

Rule chooser: https://proompteng.github.io/bilig/agent-rule-chooser.html

Direct TypeScript path

Use direct imports for services, queues, route handlers, and tests:

npm install @bilig/workpaper

import {
  WorkPaper,
  exportWorkPaperDocument,
  serializeWorkPaperDocument,
} from "@bilig/workpaper";

const workbook = WorkPaper.buildFromSheets({
  Inputs: [
    ["Metric", "Value"],
    ["Customers", 20],
    ["Average revenue", 1200],
  ],
  Summary: [
    ["Metric", "Value"],
    ["Revenue", "=Inputs!B2*Inputs!B3"],
  ],
});

const inputs = workbook.getSheetId("Inputs");
const summary = workbook.getSheetId("Summary");
if (inputs === undefined || summary === undefined) {
  throw new Error("missing sheets");
}

workbook.setCellContents({ sheet: inputs, row: 2, col: 1 }, 4800);

const after = workbook.getCellDisplayValue({ sheet: summary, row: 1, col: 1 });
const saved = serializeWorkPaperDocument(
  exportWorkPaperDocument(workbook, { includeConfig: true }),
);

console.log({ after, persistedDocumentBytes: saved.length });

Agent task contract

Ask the agent for workbook evidence, not a write status:

Use Bilig WorkPaper tools instead of spreadsheet UI automation. Read the input
and output cells first, set one input cell, read the dependent formula cell
after recalculation, export or serialize the WorkPaper document, restore it when
a file boundary matters, and return editedCell, before, after, afterRestore,
persistedDocumentBytes, verified, and limitations.

Reject answers that only say a cell was written.

More context