The Product Approach

The business idea formalized in TASK-113 is simple:

• Atomic tools are the implementation substrate. They stay small, precise, and mostly hidden from the normal public surface.
• Macro tools are the preferred LLM-facing layer for meaningful task-sized work.
• Workflow tools are bounded multi-step process tools with explicit reporting, not open-ended "do anything" endpoints.
• Goal-first orchestration keeps sessions anchored to an active intent instead of making the model rediscover context on every turn.
• Vision assists interpretation, while deterministic measurement and assertions provide the final truth layer.
• Pluggable vision runtimes now cover local MLX plus external OpenRouter and Google AI Studio / Gemini provider paths, with model-family-specific external contract profiles for prompt/schema/parser behavior.

This is what turns the project from "Blender tools exposed over MCP" into a usable AI control product for modeling pipelines.

LLM-Guided Public Surface

llm-guided is the default production-oriented surface. It is intentionally small, search-first, and designed around goal-aware sessions.

Normal guided flow:

1. router_set_goal(...)
2. browse_workflows, search_tools, or call_tool
3. use grouped/public tools such as check_scene, inspect_scene, or configure_scene
4. verify with inspection plus scene_measure_* and scene_assert_*

Prompting rule:

• use the prompt-library assets in _docs/_PROMPTS/README.md as the canonical guided operating instructions
• when a client drifts, prepend guided_session_start as the generic search-first stabilizer
• if a tool is not already directly visible on the current surface/phase, use search_tools(...) before call_tool(...)

When a bounded modeling intent matches, the default public working layer should be the macro layer:

• macro_cutout_recess for recesses, openings, and cutter-driven cutouts
• macro_relative_layout for align/place/contact-gap part layout
• macro_attach_part_to_surface for seating one part onto another object's surface/body
• macro_align_part_with_contact for minimal repair nudges on pairs that almost fit
• macro_place_symmetry_pair for mirrored pair placement/correction around an explicit mirror plane
• macro_place_supported_pair for mirrored pair placement/correction against one shared support surface
• macro_cleanup_part_intersections for bounded pairwise overlap cleanup without free-form collision solving
• macro_adjust_relative_proportion for bounded ratio repair between related objects
• macro_adjust_segment_chain_arc for bounded arc adjustment on ordered segment chains
• macro_finish_form for preset-driven bevel/subdivision/solidify finishing
• reference_images for goal-scoped reference intake before bounded visual comparison
• reference_guided_creature_build as a native prompt asset for staged generic creature work on llm-guided
• recommended_prompts can now steer creature-oriented guided sessions toward that prompt path by using active goal/session context
• guided_reference_readiness on router_set_goal, router_get_status, and staged reference compare/iterate payloads so clients can see whether reference-driven stage work is actually ready
• reference_compare_stage_checkpoint for deterministic multi-view stage comparison against attached references during manual iterative work
• reference_iterate_stage_checkpoint for a session-aware staged correction loop that remembers prior focus, can escalate into inspect/validate when the same correction repeats, and can now target one object, many objects, a collection, or the full assembled silhouette
• stage compare/iterate now also expose deterministic silhouette_analysis metrics, typed action_hints, and an advisory-only part_segmentation placeholder that stays disabled unless a separate sidecar is explicitly enabled
• scene_scope_graph for one explicit read-only structural scope artifact with anchor/core/accessory role hints
• scene_relation_graph for one explicit read-only pair-relation artifact derived from the current truth layer
• scene_view_diagnostics for one explicit read-only view-space artifact with projected extent, frame coverage, centering, and visible/partial/occluded/off-frame verdicts for named cameras or USER_PERSPECTIVE
• those spatial graph/view diagnostics tools are now part of the default visible llm-guided support set so the model can keep one explicit 3D orientation layer available instead of inferring spatial state only from names, screenshots, or partial loop payloads

Current guided bootstrap surface:

• router_set_goal
• router_get_status
• browse_workflows
• reference_images
• scene_scope_graph
• scene_relation_graph
• scene_view_diagnostics
• search_tools
• call_tool
• optional prompt bridge tools when MCP_PROMPTS_AS_TOOLS_ENABLED=true:
  • list_prompts
  • get_prompt

Prompt-capable clients should prefer native MCP prompts. The prompt bridge is a compatibility layer for tool-only clients and can be disabled for Streamable HTTP profiles that already consume native prompt components.

Current guided utility prep path:

• bootstrap/planning search can now reach:
  • scene_get_viewport
  • scene_clean_scene
• these utility actions stay bounded and do not reopen the full legacy surface
• the canonical guided discovery wrapper is call_tool(name=..., arguments=...)
• the canonical cleanup argument shape on llm-guided is keep_lights_and_cameras; older split flags are compatibility-only and should not be used as the documented public form
• reference_images(action="attach", source_path=...) is one-reference-per-call; batch-like shapes now fail with guided recovery guidance instead of raw schema noise
• collection_manage(action=..., collection_name=...) stays the canonical public form; legacy name is only a narrow compatibility alias
• modeling_create_primitive(...) stays limited to primitive_type, radius/size, location, rotation, and optional name; unsupported shortcuts such as scale, segments, rings, subdivisions, or primitive-time collection_name now fail with actionable guidance on both direct and proxy guided paths
• build goals should still start from router_set_goal(...), but screenshot / viewport / scene-reset requests should use the guided utility path instead
• if stale scene state is discovered only after entering the guided build surface, scene_clean_scene(...) is also available there as a bounded recovery hatch; cleanup before the goal is still the preferred path
• build-phase cleanup is still allowed when recovery is needed

Current public aliases on llm-guided:

Why that matters:

• the guided profile starts from a compact visible bootstrap set instead of the full catalog
• grouped/public tools stay easy to discover
• hidden atomic tools remain available as infrastructure, not as the default public mental model
• specialist families stay out of the normal guided entry layer until the macro surface is broader

Atomic Foundations And Docs

The root README.md is intentionally not the full tool catalog anymore.

The detailed tool inventory and atomic family docs should stay in docs, not on the front page. That is the right long-term structure after TASK-113.

Use these docs depending on what you need:

• Tool Layering Policy
  • Canonical policy for atomic / macro / workflow, hidden atomic tools, goal-first usage, and vision/assert boundaries.
• MCP Server Docs
  • Surface profiles, guided aliases, versioned contracts, and runtime/platform guidance.
• MCP Client Config Examples
  • Ready-to-paste local MCP client config examples for guided/manual surfaces plus MLX, OpenRouter, and Gemini vision variants.
• Vision Layer Docs
  • Runtime/backends, capture bundles, reference images, macro/workflow vision integration notes, and repo-tracked real viewport eval bundles for both direct user-view and fixed camera-perspective captures.
• LLM Guide v2
  • Strategy doc for a typed spatial-intelligence layer, compact relation state, and bounded next-step handoffs for guided operation.
• Spatial Intelligence Research Brief
  • External research handoff for LLM/VLM spatial reasoning, multi-view reasoning, and geometry-aware planning.
• Spatial Intelligence Upgrade Proposal
  • Research-driven upgrade proposal for scene graphs, symbolic relation notation, and supporting g