When building a design agent product, it is tempting to treat the current host-application scene as the system state. If SketchUp already shows the model, why maintain a separate design_model.json?

The answer is that the SketchUp scene is the live execution view. It is not the right long-term truth layer for agent reasoning, validation, repair, and replay.

In SAH, design_model.json is not an export cache. It is the editable truth of the design project, and it has to stand before the SketchUp scene.

A live scene is poor at answering engineering questions

A SketchUp scene can display a model, but it does not naturally answer:

  • Which objects came from an imported source, and which were manually edited?
  • Where are a component’s dimensions, anchors, clearances, provenance, and redistribution metadata?
  • Can the current model regenerate the same bridge trace?
  • If visual feedback is accepted, which space, wall, component, rule, or material should change?
  • Which entities were generated by the latest replay, and which are stale?
  • When comparing two versions, should the agent compare pixels, scene files, or structured facts?

These are not display questions. They are state-management questions. Agents need readable, validated, diffable, patchable state. They cannot rely only on what the host application currently shows.

The project truth boundary

SAH splits a design project into several file contracts:

  • design_model.json: spaces, walls, openings, components, lighting, semantic anchors, execution metadata;
  • design_rules.json: project rules, preferences, and constraints;
  • component_library.json: project-local component semantics;
  • assets.lock.json: the component assets actually referenced by the project;
  • imports/: source material, manifests, evidence, and extracted interpretation;
  • snapshots/manifest.json: provenance for screenshots, renders, and visual feedback;
  • versions/: snapshots of structured truth.

Together, these files form the agent operating surface. The SketchUp scene is one execution artifact in that system, not the only state.

Why structured truth is better for agents

The agent does not merely need to see a model. It needs to know what can be safely changed.

design_model.json lets the agent:

  • inspect project state through MCP tools;
  • validate whether current truth can generate a complete execution trace;
  • understand the provenance of objects;
  • add, move, or remove components structurally;
  • save and compare versions;
  • write bridge entity IDs back to the corresponding objects;
  • convert accepted visual feedback into structured changes.

If this information only exists in the SketchUp scene, the agent has to infer design intent from geometry after the fact. That is usually unreliable.

Snapshots and renders are artifacts too

Visual outputs are useful, but they should be recorded as review artifacts.

In SAH’s visual loop, snapshots, renders, and visual feedback live in snapshots/manifest.json with provenance. They can guide design decisions, but they do not replace design_model.json.

If the user accepts a visual suggestion, the agent should convert it into structured action: component change, lighting change, material change, rule change, note, or a model change through a dedicated geometry tool.

The key is this: pixels do not directly become geometry truth. Pixels should trigger changes to truth.

Execution metadata belongs in truth

When the Ruby bridge executes successfully, returned entity IDs, operation status, spatial deltas, and operation IDs should not remain only in logs.

They need to go back into design_model.json.

Then later agent calls can know:

  • which component instance maps to which SketchUp entity;
  • which wall side has been executed;
  • which hosted openings were generated;
  • which bridge operations belong to the current replay;
  • which old execution metadata should be replaced.

Without execution feedback in truth, future edits depend on guessing. The agent may duplicate objects or target stale entities.

Versions should compare structured facts

Design projects change repeatedly. If version comparison only uses scene files or screenshots, it is hard to explain what changed.

Structured truth can compare spaces, walls, openings, component instances, rules, assets, and visual artifacts. That kind of diff is suitable for agent explanation, rollback planning, and next operations.

Git can store file history, but domain-level comparison still needs structured models such as design_model.json.

This does not make SketchUp less important

Putting design_model.json first does not make SketchUp unimportant. SketchUp remains the professional modeling and visual execution environment. It is where designers see, inspect, and continue working with the model.

But for an agent harness, SketchUp is best understood as the live execution view. It should not alone own project truth, source evidence, runtime memory, version comparison, and repair planning.

A healthier split is:

design_model.json owns editable truth
MCP server owns tools, validation, planning
Ruby bridge owns host execution
SketchUp scene owns live visual result
snapshots and renders own review artifacts

For a maintainable design agent product, that split matters more than the first moment when “the model appears.”

Source trace