[furilo]

Second PR from #13. It adds benchup, a command-line tool that reads and edits .bup projects from a shell or an AI coding agent, and serves the same tools over MCP. It builds on benchup-tools from #40, whose commits it also contains until that PR is merged.

The CLI

benchup guide                          # conventions, workflow and woodworking recipes for agents
benchup new shelf.bup --name "Shelf"
benchup scene shelf.bup                # objects, joints, dimensions, materials
benchup call shelf.bup create_board '{"name":"Side","origin_mm":[0,0,0],"size_mm":[18,300,900]}'
benchup call shelf.bup --batch ops.jsonl --dry-run   # many calls, one undo step, all-or-nothing
benchup call shelf.bup check_model     # problems to fix before building
benchup undo shelf.bup
benchup mcp shelf.bup                  # the same tools over MCP (stdio)
benchup open shelf.bup                 # open it in the desktop app

• Every change is one undo step, labelled Agent: ….
• Saves are atomic, and the CLI refuses to overwrite a file that changed on disk.
• Shared projects are refused unless --allow-shared is passed.
• In a batch, a call can use earlier results with references such as "$1.created[0]".

User documentation is in docs/cli.md. docs/agent-guide.md is compiled into the binary and printed by benchup guide. A Claude Code skill is included in crates/benchup-cli/skill/.

How it was shaped

I ran 12 furniture tasks four times with coding agents that knew only benchup --help. The tasks included editing the example project, drawers with dovetails, a back in a rabbet, a curved bedside table, a leaning shelf, dimensions and cut lists. After each round, I fixed the tools and the guide. Across the 12 tasks:

Round	Commands	Errors
1	~701	72
2	285	21
3	218	3
4	~245	~7

The remaining errors come from limits in the core, listed below. Agents now check their work with a dry run ending in check_model.

Per task: commands (errors) in each round

Task	Round 1	Round 2	Round 3	Round 4
Lengthen the desk in Example.bup	43 (3)	27 (0)	19 (1)	~61 (0), filled the notch in front of the post and searched for walls
Bookcase: 5 to 4 shelves per bay, keeping the joints	21 (3), orphaned joints	22 (0)	16 (0)	14 (0)
Dining table with mortise-and-tenon aprons	22 (0), joints reversed	18 (0)	15 (0)	15 (0)
Chest of 3 drawers, dovetailed fronts, one component	46 (3)	32 (9)	19 (0)	14 (0)
Back panel in a rabbet and a set-back plinth	14 (0)	27 (5)	17 (0)	18 (0)
Remake the bookcase in 19 mm solid oak	24 (3), no material	25 (0)	17 (0)	17 (1)
Bedside table: curved side edges, chamfered top	~261 (35)	26 (1)	24 (0)	36 (4), curve segment count
Leaning ladder shelf at 15°	~91 (16)	45 (1)	32 (0)	22 (0)
Dimensions and a label for the workshop	21 (1)	13 (0)	12 (0)	11 (0)
Modules, one shelf component, tags	~142 (8), joints broken	31 (5)	27 (2)	19 (~2), stopped short on purpose
Cut list and sheets to buy	8 (0)	12 (0)	8 (0)	8 (0)
A 1200 mm shelf in a 473 mm bay	8 (0)	7 (0)	12 (0)	10 (0), stopped and asked

The shelf-component task cannot be done fully: a board inside a component instance cannot be joined to the sides outside it. The agents now explain this and offer an alternative.

The resulting changes to benchup-tools:

• Joints:
  • roles are documented (a carries the tenon or tongue, b receives it);
  • add_joint picks the woodworking orientation, validates the ranges the core uses, and refuses joints that cannot be cut, naming the joints a new one collides with;
  • get_object on a joint shows its settings and status;
  • new remove_joint and flip_joint tools;
  • erasing a board removes its joints, which works around Erasing a board leaves its wood joints pointing at a missing id #36.
• check_model: reports boards that cut another in two, overlaps without a joint (checked against the real solids), joints that cannot be cut or look reversed, thickness that does not match the material, open solids and loose geometry.
• New tools: get_cut_list, create_stock_material, move_to and get_guide. resize_board takes an anchor, and add_dimension can measure along an axis.
• Faces: outward normals use a ray-parity test instead of "away from the part's centre", which flipped faces of concave parts (push_pull can create a side face with an inverted normal #37). push_pull and draw_polyline return the ids they create.
• Groups: editing tools reach parts inside groups without enter_object.
• Scene: it lists the axes (the front faces -Y), dimensions, texts, loose geometry, component definitions and inherited materials.

Changes outside the new crates

benchup-app now uses benchup_tools::files for the .bup format. The format had been implemented twice, and the copies had drifted: the tools could not read the PNG previews the app now saves. The CLI keeps a file's container when saving. cargo check -p benchup-app is clean, and the app's project and desktop-file tests pass.

.github/workflows/pr.yml runs the tests of both crates. site/llms.txt now mentions the command, noting that it is built from source for now, and links to its documentation.

Still to do

• The live bridge and the in-app Agent connection, for a later PR reusing Add an MCP server and optional agent add-ons (Agent connection, Build with MIRA) #3.
• Core issues found along the way:
  • Full-thickness push_pull leaves stray faces and edges (board stops being a closed solid) #39 (full-thickness push/pull leaves stray faces);
  • Erasing a board leaves its wood joints pointing at a missing id #36 (erased boards keep their joints);
  • joints between a component instance and outside boards;
  • boolean precision with curves of many segments.

Testing

cargo test --locked -p benchup-tools -p benchup-cli passes: 49 tests in the tools and 17 in the CLI.

🤖 Generated with Claude Code

[furilo]

I reviewed this PR and fixed what came up in d6edc76:

Bugs

• $N references: these are now resolved only in batches, and only when the text is exactly a reference. "$12.50 hardware", "$5 shelf" and "$3.99" are kept as written, and a single call never resolves references.
• Lists in references: a referenced list is spliced into a list only when it holds ids. A point such as "$1.faces[0].center_mm" in points_mm stays one item.
• MCP after a save in BenchUp: the server now reads the file again before each call if it changed on disk. Before, every later change failed with CHANGED_ON_DISK until the server was restarted. A group opened with enter_object stays open if it still exists.
• Materials with the same name: check_model and get_cut_list now use the assigned stock material instead of the first one with that name. Two "Plywood" materials of different sizes no longer cause false thickness_mismatch warnings or share one cut list group. stock_mm now includes the thickness.
• PNG projects: bytes after IEND are ignored when reading and rewriting. The old app decoder accepted them, but the shared decoder failed with truncated_chunk.
• benchup open on Windows: the \\?\ prefix is removed from the path, and the file opens through explorer.exe instead of cmd /C start, so & and % in paths are not interpreted. Explorer exits with 1 even when it opens the file, so on Windows the exit code is ignored. This is not tested on Windows yet.

Smaller fixes

• New projects get the usual permissions under the user's umask instead of a forced 0644.
• Agent history entries use the translatable label "Agent edit" (cli.agent_edit, added to all catalogs and registered as a history label in benchup-core/build.rs). They no longer include the tool name, because history labels can't take parameters.
• Read-only calls no longer copy the document, and calls that change it copy only the model, not the history. check_model evaluates joints once instead of twice.

New tests cover references, MCP after an outside save, same-named materials, trailing PNG bytes and permissions under the umask. docs/cli.md and docs/agent-guide.md are updated. Locally, cargo test -p benchup-tools -p benchup-cli passes; benchup-app was not built.

🤖 Generated with Claude Code