Create a Bilig WorkPaper starter

Use this path when you want a runnable project instead of a pasted snippet.

The starter package is @bilig/create-workpaper, exposed by npm create @bilig/workpaper@latest. Use it when you want the quote approval WorkPaper API shape without cloning the full monorepo.

The starter creates a quote approval API with @bilig/workpaper. It uses the A1 facade, writes quote inputs through one atomic editManyAndReadback proof, recalculates workbook formulas, persists the WorkPaper as JSON, restores it, and verifies that the restored formula output still matches the live result. Generated projects pin @bilig/workpaper to the generator package version and use exact dev-tool versions instead of latest, so the smoke proof is reproducible.

Run It

Generated-project path:

npm create @bilig/workpaper@latest pricing-workpaper
cd pricing-workpaper
npm install
npm run smoke

MCP-enabled project with host integration files:

npm create @bilig/workpaper@latest pricing-agent -- --agent
cd pricing-agent
npm install
npm run agent:verify
npm run mcp:server

Existing Node project:

npm create @bilig/workpaper@latest . -- --add-agent
npm exec --yes --package @bilig/workpaper@latest -- bilig-evaluate --door agent-mcp --scenario revenue-plan --json
npm exec --yes --package @bilig/workpaper@latest -- bilig-workpaper-mcp --workpaper ./.bilig/pricing.workpaper.json --init-demo-workpaper --writable

--add-agent only adds Bilig MCP and host-integration instructions. It keeps your existing app template and README.md, writes BILIG_WORKPAPER.md, keeps WorkPaper state under ./.bilig/pricing.workpaper.json, does not edit package.json, and skips existing files unless you pass --force. If an existing host policy blocks part of the overlay, the CLI writes BILIG_WORKPAPER_INSTALL.md with the skipped paths and a compact handoff snippet for your current policy file. For npm create @bilig/workpaper@latest . -- --add-agent, the overlay labels BILIG_WORKPAPER.md from your existing package.json name instead of ..

Full-repo flagship example:

git clone --depth 1 https://github.com/proompteng/bilig.git
cd bilig
pnpm --dir examples/serverless-workpaper-api install --ignore-workspace
pnpm --dir examples/serverless-workpaper-api run smoke

Expected output includes:

{
  "verified": true
}

The generated project also includes a local API server:

npm run dev
curl http://localhost:8788/api/quote/approval
curl -X POST http://localhost:8788/api/quote/approval \
  -H 'content-type: application/json' \
  -d '{"units":40,"listPrice":1200,"discount":0.05,"unitCost":760,"minimumMargin":0.3}'

What It Proves

• a real service shape, not only a formula evaluator snippet;
• atomic input writes into named workbook cells through A1 addresses;
• formula readback after mutation;
• JSON persistence and restore;
• a narrow API surface that an MCP tool, host integration, or backend route can own.
• an optional integration starter with AGENTS.md, CONVENTIONS.md, .aider.conf.yml, CLAUDE.md, GEMINI.md, host rule files, project-root MCP configs, and an agent:verify command that runs the service smoke plus the package-owned basic and revenue-plan MCP evaluator proofs. The revenue-plan evaluator checks MCP tool discovery, mutation, recalculated SUM, SUMIF, XLOOKUP, FILTER, a named expression, persistence, and restart readback. Use npm run mcp:challenge only when you need the lower-level JSON-RPC transcript.

Representative host config files include .kiro/settings/mcp.json, .trae/mcp.json, .zed/settings.json, .junie/mcp/mcp.json, and mcp/bilig-workpaper.mcp.json.

Source

• package source: packages/create-workpaper
• generated API source: packages/create-workpaper/template/src/index.ts
• generated host integration overlay: packages/create-workpaper/agent-overlay
• full flagship example: quote approval WorkPaper API

If this starter almost matches a service or integration workflow you maintain, open one concrete implementation gap so the package becomes easier to evaluate: https://github.com/proompteng/bilig/discussions/new?category=general.

If the proof already matches your workflow, watch releases for API and formula compatibility updates: https://github.com/proompteng/bilig/subscription.