GameCult.Geometry.Csg/docs/brush-tree-target.md

Brush tree: target

Campaign brush-tree, area geometry, owned by the Aetheria/Ghostlight Self (aetheria-release:ruling:brokkr-ctl-job-to-ag-self). Drafted by Imagination (imagination-brush-tree-target, session self-2026-10-10-ag2) on 2026-10-10. This is step 0: the ends, not the means. It contains no cut plan.

• Title: Brush tree: OpenSCAD-shaped CSG trees authored in Blender through brokkr-ctl.
• Repos: GameCult/GameCult.Geometry.Csg (the truth and the kernel), GameCult/Brokkr (the agent's hands in Blender), GameCult/Aetheria (the first consumer), and GameCult/CultLib, only if a ruling sends work there (the cultcache-py directory store, Q blender-transport). All four remotes are GitHub today; Aetheria moves to Forgejo under aetheria-release:ruling:forgejo-primary-github-mirror.
• Working branch: eureka/brush-tree in each repo it touches.
• This document's home: GameCult.Geometry.Csg/docs/brush-tree-target.md. The crate owns the truth the campaign builds, and two of the four research passes already live beside it in docs/research/.

Rationale

The operator rebuilds Tripo-generated hard-surface hulls by hand: retopology, seams and bevels, at about 30 minutes per part. The campaign replaces that with a collaborative loop in Blender. The work is split by what each party does well:

• The operator points at part of the messy hull, using her Edit Mode selection plus the viewport framing.
• The model proposes a parametric form, or builds the one she names ("these pipes are tubes", "a sphere, solidified, with a prism cut out"). It does the naming, grouping, symmetry and composition.
• A classical fitter does the numbers: least-squares or RANSAC primitive fitting, plus GlobFit-style relations.
• Feedback is a deviation heatmap plus a viewport render, iterated.

The output is a typed CSG brush tree. From that one tree come the lowered mesh, its UVs, its topology near cuts and its microbevels.

Why this shape, by the evidence:

• Model fluency. CAD-Recode and MeshCoder emit code (CadQuery, Blender Python) precisely because language models write code fluently (CultLib docs/research/inverse-procedural-modelling-prior-art.md §1, 6bdc23c9). OpenSCAD is a CSG tree written as text, with a large public corpus.
• Text-only loops fall short. BlenderGym shows the best VLM still far behind humans on geometry editing (Chamfer 1.120 vs 0.334, same doc §4). BenchCAD reports single-literal errors at high IoU. That is why numbers go to a fitter and judgement goes to the model and the operator, not to unaided generation.
• Failure without coherence. VibeGeometry's recorded failure was "local plausibility without global coherence" (same doc §0b). The defence here is a typed tree with one owner, scored against the target by one distance function.
• Brushes are the durable design surface. The crate's own doctrine says "the brush tree is the authority; the mesh is cache and evidence" (docs/realtime-csg-doctrine.md, Core Model). This campaign makes that true of persisted state, not only of the in-memory assembler.
• The bar is the Blender MCP servers, and Brokkr exceeds it. They offer viewport sight, code execution and API docs, but none reads selected Edit Mode geometry, and none has auth or admission (Brokkr docs/research/blender-mcp-capability-bar.md §A(b), §B(b), f97d4dc). Brokkr already has typed intents, receipts and admission on its Unity side (docs/provider-contract.md, Admission).

Body facts the target rests on (probed 2026-10-10)

• GameCult.Geometry.Csg (main at 5b5dc34):
  • Five primitives: Box, OrientedBox, CylinderZ, DomeCapZ, FloretArm (src/brush.rs).
  • The polygon kernel runs CSG only for Box and OrientedBox cutters. It skips other cutters with SubtractIgnoredForNonBox / IntersectIgnoredForNonBox (src/assembler.rs ~803, ~836).
  • The assembler and field.rs consume one flat ordered stream in which Intersect is global. CsgTree branches exist in src/tree.rs, but the assembler does not honour them as scoped nodes.
  • field.rs lowers the stream to a signed-distance bound for every op on every primitive. It has no smooth blend.
  • TriangleMesh gives every quad 0-1 UVs. It carries per-triangle material only: no brush id, surface id, smoothing or tangent (src/mesh.rs).
  • Brush and Primitive derive no serde.
  • The "CultCache records" in src/cult_geometry.rs are rmp_serde msgpack tuples with schema-string constants. They are not written through CultLib's cultcache-rs, and no record holds brushes.
• Brokkr (main at f97d4dc):
  • The Blender add-on admits eight object-level commands (surfaces/blender/brokkr_bridge/blender_target.py:402-423). Its snapshot reports mesh counts only (:568-575). It has no render, no mesh read, no Edit Mode read and no code execution.
  • Its store is the cultcache-py single-file store. cultcache-py has no directory store (CultLib/packages/cultcache-py/src/cultcache_py/stores.py:22,85).
  • Its optional CultNet server binds 127.0.0.1 with no auth token (blender_target.py:288-350).
  • brokkr-command is a .NET, Unity-only caller (brokkr-command/Program.cs). brokkr-ctl does not exist.
  • The Unity side's rulings F4 to F6 settle a file transport, a sink that is off by default, and single-use command ids (docs/brokkr-adoption-cut.md, Rulings).
• CultMath: BoundedLeastSquares exists in C# (CultLib/packages/cultmath/src/CultMath/BoundedLeastSquares.cs).
• Mesh probe: the probe running under rulings mesh-probe-exploit-not-measure and mesh-probe-both-vocabularies has not written run1/RESULT.md yet. Its scratch demo-hull.scad already shows the model reaching for top-level variables, module, hull(), minkowski(), polyhedron, mirror and cylinder(r1, r2).

Design truths the campaign produces

1. Each hull rebuilt through the loop exists as one typed brush-tree document in CultCache. Everything else is derived from it: text, mesh, UVs, bevels, heatmap, projections into Blender.
2. The model reads and writes that tree as OpenSCAD-shaped text. The operator reads and writes it through Blender. Both edits land through one commit path.
3. An agent drives Blender with brokkr-ctl blender look | selection | fit <primitive> | run <script>. Every call is a typed, admitted Brokkr intent with a receipt, and --help is the schema.
4. Geometry.Csg lowers the tree to a mesh whose faces know their brush and surface. The mesh carries the UVs and seams the brushes declare, and smooth microbevels at cuts derived from the same tree's field.
5. Aetheria receives the lowered hull through its existing ship pipeline.

Invariants

• I1. One truth. The typed CultCache brush tree is the only authority for a hull's shape, surfaces and structure. OpenSCAD-shaped text, Blender objects, meshes, fields, heatmaps and impostors are derived. None of them is read back as truth except through I3.
• I2. Text is a surface, not a store. The OpenSCAD-shaped syntax is an authoring and lowering surface. A tree prints to text deterministically. Printing a tree and parsing it back yields the same tree (round-trip). Any text the parser accepts, which also renders in OpenSCAD, means the same solid in both. Where our extensions add surface data, OpenSCAD ignores it and still renders the same solid.
• I3. One commit primitive. Every change to a tree goes through one commit that names the revision it was based on. That covers parsed text, an operator edit in Blender, an accepted fit and a scripted change. A stale base is refused, never merged silently. No second writer exists: no Blender-side cache, no CLI-side tree and no daemon copy.
• I4. One distance per primitive. Each primitive's signed distance is defined once, in Geometry.Csg. The fit residual, the deviation heatmap, the microbevel blend and field-based scoring all evaluate that one definition. A fitter that minimised a different distance would fit a shape the kernel does not build.
• I5. No silent skips. Every primitive and operation the authoring surface accepts is honoured by every lowering that claims to build the tree: the polygon kernel and the field. Anything a lowering cannot honour is refused at parse or commit, never dropped with a warning.
• I6. The tree is a tree. A branch's operation applies to its children only. Nested difference inside union means what OpenSCAD means by it. The flat global-Intersect stream may survive as an internal lowering, but it cannot change meaning.
• I7. Brushes own their surfaces.
  • Each brush declares its surfaces: material, UV parameterisation and seams, smoothing, and bevel or blend radius.
  • Every emitted face carries the id of the brush and the surface it came from. Output UVs are evaluated from that surface's parameterisation.
  • No face gets default 0-1 UVs.
  • Who owns a cut face is one explicit policy (Q cut-face-surface), not array order.
• I8. Topology is regenerable. The tree carries enough to regenerate good topology wherever a consumer needs it, without hand retopology: edge flow on curved primitives, strips at cuts, and LOD. The mesh is a cache. It is never hand-edited and never read back.
• I9. Microbevels come from the tree. The fine bevels at brush cuts are derived from the same tree's signed-distance field, smooth-min style, with radii that are brush or tree parameters. The field stays a distance bound, never an overestimate, because sign tests and Newton projection depend on that (src/field.rs header).
• I10. Stable identity. Brushes and surfaces keep their identity across print, parse and Blender edits (Q brush-identity). A receipt, a fit or a heatmap that names a brush still names the same brush after a round-trip.
• I11. Brokkr's authority map holds.
  • Blender owns Blender truth: the source mesh, selection, viewport and undo.
  • Brokkr owns the contract, admission and receipts.
  • brokkr-ctl is a caller. It owns no state, no policy and no receipt ledger (docs/agent-access-cut.md Cut 5, authority map).
  • The exit code derives from the receipt, never from "the write succeeded".
  • Agent commands are off until the operator enables them, as on the Unity side (F5).
  • Command ids are single-use (F6).
  • Every mutating Blender command is one undo step.
• I12. Brokkr is better than the MCP bar, not equal to it. Brokkr matches the bar on viewport sight, code execution and API docs. It reads Edit Mode selection live. On top of that it adds typed admitted intents with receipts, undo-safe transactions, and a transport that does not admit arbitrary local processes.
• I13. A CLI, not an MCP server. The agent's hands are a stupid-simple CLI whose --help is the schema, and whose outputs are paths and plain text.
• I14. Source is evidence. The Tripo mesh is read-only reference. The loop never edits it. The Tripo-mesh-as-bake-source rule of the Aetheria release map stands.
• I15. One consumer path into Aetheria. The lowered hull reaches Aetheria through the existing ship pipeline, Blender add-on Package into the ship .cc (aetheria-release:ruling:schematic-is-designated-mesh). This campaign adds no second exporter.
• I16. Open and general.
  • Everything is open source (eureka-body:ruling:always-open-source).
  • Geometry.Csg stays a general library with a clean public API. A capability a reasonable consumer expects is not cut because Aetheria does not use it.
  • The library does not acquire Aetheria vocabulary.

Settled direction (rulings in the mind, campaign brush-tree)

• Mesh CSG is the main representation.
• Octahedral impostors are a far-LOD tier only.
• Brick-map marching of interval-pruned tapes stays CultMath research.
• Unity's built-in pipeline is used by choice, with our own shaders. Its deprecation is never counted as a cost.

Not in scope, and not consumers

• Hull panel decals. A separate later campaign (aetheria-release:ruling:panel-lines-mesh-decals).
• The Aetheria/Hull shader. It belongs to aetheria-release. This campaign emits UVs and normals the shader can use. It does not edit the shader.
• Brick-map or tape SDF rendering, and runtime raymarching. These stay CultMath research (docs/cultmath-tape-target.md, parked).
• Impostor generation. It is named as a derived far-LOD tier. Whether this campaign builds it is Q impostor-scope, recommended out.
• Unity agent access. Unity's brokkr-command and its intents are not consumers and are not changed. brokkr-ctl blender must not fork the Unity contract.
• CultCache Studio. It may display the tree .cc like any CultCache document. It gains no brush-tree editor in this campaign (aetheria-release:ruling:studio-is-the-authoring-pane covers hull data, not brush authoring).
• The prefab CDN pipeline and the Unity-Blender sync organ. Not consumers.
• Training models. The loop uses a frontier model with tools it builds and uses (aetheria-release:ruling:mesh-probe-exploit-not-measure). Learned encoders of the CAD-Recode or MeshCoder kind are prior art, not scope.
• Benchmarking the model's unaided spatial reasoning. Explicitly not a goal (same ruling).
• VibeGeometry's deleted scene-generation tree. Read for its scars, not revived.

Canonical implementations

• The brush tree types, the text printer and parser, the kernel, the field, per-primitive distance, and the fitter math (subject to Q fitting-home): GameCult.Geometry.Csg, Rust.
• Persistence: through CultLib packages/cultcache-rs, not hand-rolled rmp_serde tuples.
• Agent CLI and Blender adapter: Brokkr. brokkr-ctl and the surfaces/blender/brokkr_bridge add-on, over a Blender command contract extending brokkr.blender.command_intent.v0 and .command_receipt.v0.
• Consumer: Aetheria's tools/blender/aetheria_ships add-on, through its existing Package.

Evidence (DocRefs)

• GameCult/GameCult.Geometry.Csg docs/research/brush-surfaces-and-sdf-bricks-prior-art.md @ df89568
• GameCult/GameCult.Geometry.Csg docs/research/octahedral-impostors-prior-art.md @ 5b5dc34
• GameCult/CultLib docs/research/inverse-procedural-modelling-prior-art.md @ 6bdc23c9
• GameCult/Brokkr docs/research/blender-mcp-capability-bar.md @ f97d4dc
• GameCult/GameCult.Geometry.Csg docs/realtime-csg-doctrine.md @ 5b5dc34
• GameCult/Brokkr docs/agent-access-cut.md, docs/brokkr-adoption-cut.md, docs/provider-contract.md @ f97d4dc
• Pending: the mesh probe's run1/RESULT.md. Self commits it into Brokkr or the crate's docs/research/ and cites it once it exists.