agentcad-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{agentcad_cli-0.1.2 → agentcad_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentcad-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: Agent-first CAD workflow runtime
 Author: AgentCAD contributors
 License-Expression: MIT
@@ -21,15 +21,15 @@ so the agent can iterate on CAD models with measurable feedback instead of
 visual intuition.
 
 ```text
-design contract -> precheck -> params/source -> build
-                  -> measure -> render -> validate -> review -> deliver
+discovery -> concept -> design contract -> precheck -> params/source -> build
+          -> measure -> render -> validate -> review -> quality review -> deliver
 ```
 
 ## What's in the box
 
 | Stage | Command | Purpose |
 |---|---|---|
-| Init | `agentcad init [--model <name>]` | Initialize workspace scaffold (optionally create first model) |
+| Init | `agentcad init <workspace> [--model <name>]` | Initialize workspace scaffold (optionally create first model) |
 | Scaffold | `agentcad new <model>` | Create model folder inside an existing workspace |
 | Sync | `agentcad sync` | Refresh workspace scaffold from latest templates |
 | Precheck | `agentcad precheck <model>` | Solve `design.json` statically (schema, feature coverage, `min_clearance`) **before** part.py is written |
@@ -38,14 +38,13 @@ design contract -> precheck -> params/source -> build
 | Render | `agentcad render <model>` | Iso/front/top/side/back SVG previews + Z/X/Y cross-section SVGs |
 | Probe | `agentcad probe <model>` | Cross-section diameter / bbox / void at specified Z, X, Y; `--scan` to discover step changes |
 | Inspect | `agentcad inspect <model>` | Three-axis scan + automatic section SVGs + suggested probes |
-| Validate | `agentcad validate <model>` | Build + measure + render + design checks + feature coverage; auto-emits debug SVGs on failure |
-| Review | `agentcad review <model>` | Pre-delivery checklist with pairwise relations matrix and must-view SVG list |
+| Validate | `agentcad validate <model>` | Build + measure + render all orthographic previews + design checks + feature coverage; auto-emits debug SVGs on failure |
+| Review | `agentcad review <model>` | Pre-delivery checklist with pairwise relations matrix, hole-access enforcement, and must-view SVG list |
 | Deliver | `agentcad deliver <model>` | Delivery manifest |
 | Report | `agentcad report <model>` | Markdown summary of validation result |
 
-Every command prints JSON by default for stable machine-readable output;
-add `--text` for human-readable output. Failures include `stage`,
-`error.type`, and `error.message`.
+Every command prints stable machine-readable JSON output. Failures include
+`stage`, `error.type`, and `error.message`.
 
 ## Validation check types
 
@@ -62,7 +61,7 @@ add `--text` for human-readable output. Failures include `stage`,
 | `diameter_decreases_along_z` | post-build | Monotonicity for tapers / lead-ins |
 | `volume_range` | post-build | Volume sanity bounds |
 | `min_clearance` | **design-time + post-build** | Pure-shape edge-to-edge clearance between two declared shapes (no STL required) |
-| `hole_accessibility` | post-build | Annular clearance around a hole at the working plane |
+| `hole_accessibility` | post-build | Annular clearance around a hole at the working plane; supports X/Y/Z access axes |
 | `min_wall_thickness` | post-build | Minimum point-pair distance inside a defined region |
 | `feature_position` | post-build | Assert a 3D point is `solid` or `void` |
 | `feature_coverage` | automatic | Every declared feature must reference at least one check |
@@ -71,6 +70,11 @@ The four "geometric relation" checks (last block) close the historical gap
 where `inner_diameter_at_z` would happily report a 4.5 mm hole that was
 half-covered by an adjacent wall.
 
+`agentcad review` now treats missing hole-access checks as blocking when holes
+are declared, and always requires iso/front/top/side/back previews. The side
+view requirement came from a real e2e failure where a retaining lip existed in
+the contract but was effectively floating in side projection.
+
 ## Quick start
 
 ```bash
@@ -81,20 +85,12 @@ agentcad --help
 Create a workspace and start modeling:
 
 ```bash
-mkdir my-agentcad-project
+agentcad init my-agentcad-project --model demo
 cd my-agentcad-project
-agentcad init --model demo
+claude
 ```
 
-Then open this directory in Claude Code / Cursor and continue from
-`models/demo/part.py`.
-
-`--project` is optional. Use it only when you run commands outside the
-workspace root, for example:
-
-```bash
-agentcad init --model demo --project /tmp/agentcad-demo
-```
+Then ask Claude to design your target model (for example: "Design an adapter from an 8025 fan to a round duct") — it will read `CLAUDE.md` in this workspace and follow the workflow automatically.
 
 For local development:
 
@@ -106,16 +102,16 @@ uv run agentcad --help
 ## Quick example
 
 ```bash
-agentcad init --model bracket --project /tmp/my-cad-project
-cd /tmp/my-cad-project
+agentcad init my-cad-project --model bracket
+cd my-cad-project
 
-# 1. Design-time: solve the contract before writing geometry
+# 1. Design-time: choose the concept, then solve the contract before geometry
 agentcad precheck bracket
 
 # 2. Implement part.py, then run the post-build pipeline
 agentcad validate bracket
 
-# 3. Pre-delivery review (relations matrix + must-view SVGs)
+# 3. Pre-delivery review (relations matrix + must-view SVGs), then quality review
 agentcad review bracket
 
 # 4. Deliver
@@ -133,13 +129,14 @@ common-error catalog live in `AGENTS.md`, `CLAUDE.md`, and `references/`
 | `examples/fan-adapter-8025/` | Two validated models: a fan-to-duct adapter and a magnetic outlet plate |
 | `examples/iphone15pro-case/` | Real-world phone case with multi-cutouts + section validation |
 | `examples/e2e-test/` | Sub-agent end-to-end test: design → precheck → build → validate → review on a mounting bracket |
+| `examples/e2e-real-cable-hook/` | Real e2e surface-mounted cable hook with concept + quality review artifacts |
 
 Re-run any example:
 
 ```bash
 cd examples/fan-adapter-8025
-uv run agentcad validate fan_duct_adapter_8025
-uv run agentcad review fan_duct_adapter_8025
+agentcad validate fan_duct_adapter_8025
+agentcad review fan_duct_adapter_8025
 ```
 
 ## Tests
@@ -148,7 +145,7 @@ uv run agentcad review fan_duct_adapter_8025
 uv run pytest -v
 ```
 
-125 tests at last count, covering CLI dispatch, workspace scaffolding, STL
+144 tests at last count, covering CLI dispatch, workspace scaffolding, STL
 reading and measurement, section extraction and SVG rendering, JSON IO,
 post-build validation checks, weak-check warnings, stale build detection,
 geometric primitives, and `precheck` / `review` integration.

{agentcad_cli-0.1.2 → agentcad_cli-0.1.4}/README.md

@@ -9,15 +9,15 @@ so the agent can iterate on CAD models with measurable feedback instead of
 visual intuition.
 
 ```text
-design contract -> precheck -> params/source -> build
-                  -> measure -> render -> validate -> review -> deliver
+discovery -> concept -> design contract -> precheck -> params/source -> build
+          -> measure -> render -> validate -> review -> quality review -> deliver
 ```
 
 ## What's in the box
 
 | Stage | Command | Purpose |
 |---|---|---|
-| Init | `agentcad init [--model <name>]` | Initialize workspace scaffold (optionally create first model) |
+| Init | `agentcad init <workspace> [--model <name>]` | Initialize workspace scaffold (optionally create first model) |
 | Scaffold | `agentcad new <model>` | Create model folder inside an existing workspace |
 | Sync | `agentcad sync` | Refresh workspace scaffold from latest templates |
 | Precheck | `agentcad precheck <model>` | Solve `design.json` statically (schema, feature coverage, `min_clearance`) **before** part.py is written |
@@ -26,14 +26,13 @@ design contract -> precheck -> params/source -> build
 | Render | `agentcad render <model>` | Iso/front/top/side/back SVG previews + Z/X/Y cross-section SVGs |
 | Probe | `agentcad probe <model>` | Cross-section diameter / bbox / void at specified Z, X, Y; `--scan` to discover step changes |
 | Inspect | `agentcad inspect <model>` | Three-axis scan + automatic section SVGs + suggested probes |
-| Validate | `agentcad validate <model>` | Build + measure + render + design checks + feature coverage; auto-emits debug SVGs on failure |
-| Review | `agentcad review <model>` | Pre-delivery checklist with pairwise relations matrix and must-view SVG list |
+| Validate | `agentcad validate <model>` | Build + measure + render all orthographic previews + design checks + feature coverage; auto-emits debug SVGs on failure |
+| Review | `agentcad review <model>` | Pre-delivery checklist with pairwise relations matrix, hole-access enforcement, and must-view SVG list |
 | Deliver | `agentcad deliver <model>` | Delivery manifest |
 | Report | `agentcad report <model>` | Markdown summary of validation result |
 
-Every command prints JSON by default for stable machine-readable output;
-add `--text` for human-readable output. Failures include `stage`,
-`error.type`, and `error.message`.
+Every command prints stable machine-readable JSON output. Failures include
+`stage`, `error.type`, and `error.message`.
 
 ## Validation check types
 
@@ -50,7 +49,7 @@ add `--text` for human-readable output. Failures include `stage`,
 | `diameter_decreases_along_z` | post-build | Monotonicity for tapers / lead-ins |
 | `volume_range` | post-build | Volume sanity bounds |
 | `min_clearance` | **design-time + post-build** | Pure-shape edge-to-edge clearance between two declared shapes (no STL required) |
-| `hole_accessibility` | post-build | Annular clearance around a hole at the working plane |
+| `hole_accessibility` | post-build | Annular clearance around a hole at the working plane; supports X/Y/Z access axes |
 | `min_wall_thickness` | post-build | Minimum point-pair distance inside a defined region |
 | `feature_position` | post-build | Assert a 3D point is `solid` or `void` |
 | `feature_coverage` | automatic | Every declared feature must reference at least one check |
@@ -59,6 +58,11 @@ The four "geometric relation" checks (last block) close the historical gap
 where `inner_diameter_at_z` would happily report a 4.5 mm hole that was
 half-covered by an adjacent wall.
 
+`agentcad review` now treats missing hole-access checks as blocking when holes
+are declared, and always requires iso/front/top/side/back previews. The side
+view requirement came from a real e2e failure where a retaining lip existed in
+the contract but was effectively floating in side projection.
+
 ## Quick start
 
 ```bash
@@ -69,20 +73,12 @@ agentcad --help
 Create a workspace and start modeling:
 
 ```bash
-mkdir my-agentcad-project
+agentcad init my-agentcad-project --model demo
 cd my-agentcad-project
-agentcad init --model demo
+claude
 ```
 
-Then open this directory in Claude Code / Cursor and continue from
-`models/demo/part.py`.
-
-`--project` is optional. Use it only when you run commands outside the
-workspace root, for example:
-
-```bash
-agentcad init --model demo --project /tmp/agentcad-demo
-```
+Then ask Claude to design your target model (for example: "Design an adapter from an 8025 fan to a round duct") — it will read `CLAUDE.md` in this workspace and follow the workflow automatically.
 
 For local development:
 
@@ -94,16 +90,16 @@ uv run agentcad --help
 ## Quick example
 
 ```bash
-agentcad init --model bracket --project /tmp/my-cad-project
-cd /tmp/my-cad-project
+agentcad init my-cad-project --model bracket
+cd my-cad-project
 
-# 1. Design-time: solve the contract before writing geometry
+# 1. Design-time: choose the concept, then solve the contract before geometry
 agentcad precheck bracket
 
 # 2. Implement part.py, then run the post-build pipeline
 agentcad validate bracket
 
-# 3. Pre-delivery review (relations matrix + must-view SVGs)
+# 3. Pre-delivery review (relations matrix + must-view SVGs), then quality review
 agentcad review bracket
 
 # 4. Deliver
@@ -121,13 +117,14 @@ common-error catalog live in `AGENTS.md`, `CLAUDE.md`, and `references/`
 | `examples/fan-adapter-8025/` | Two validated models: a fan-to-duct adapter and a magnetic outlet plate |
 | `examples/iphone15pro-case/` | Real-world phone case with multi-cutouts + section validation |
 | `examples/e2e-test/` | Sub-agent end-to-end test: design → precheck → build → validate → review on a mounting bracket |
+| `examples/e2e-real-cable-hook/` | Real e2e surface-mounted cable hook with concept + quality review artifacts |
 
 Re-run any example:
 
 ```bash
 cd examples/fan-adapter-8025
-uv run agentcad validate fan_duct_adapter_8025
-uv run agentcad review fan_duct_adapter_8025
+agentcad validate fan_duct_adapter_8025
+agentcad review fan_duct_adapter_8025
 ```
 
 ## Tests
@@ -136,7 +133,7 @@ uv run agentcad review fan_duct_adapter_8025
 uv run pytest -v
 ```
 
-125 tests at last count, covering CLI dispatch, workspace scaffolding, STL
+144 tests at last count, covering CLI dispatch, workspace scaffolding, STL
 reading and measurement, section extraction and SVG rendering, JSON IO,
 post-build validation checks, weak-check warnings, stale build detection,
 geometric primitives, and `precheck` / `review` integration.

{agentcad_cli-0.1.2 → agentcad_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agentcad-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "Agent-first CAD workflow runtime"
 readme = "README.md"
 requires-python = ">=3.11,<3.13"

{agentcad_cli-0.1.2 → agentcad_cli-0.1.4}/src/agentcad/__init__.py

@@ -1,3 +1,3 @@
 """Agent-first CAD workflow runtime."""
 
-__version__ = "0.1.0"
+__version__ = "0.1.4"

{agentcad_cli-0.1.2 → agentcad_cli-0.1.4}/src/agentcad/_templates/model/README.md

@@ -20,6 +20,16 @@ agentcad review {name}       # 5. pre-delivery checklist + relations matrix
 agentcad deliver {name}      # 6. write delivery manifest
 ```
 
+Before writing `design.json`, run the Discovery Gate in
+`../../references/discovery.md`. If mating dimensions, manufacturing target,
+tolerances, orientation, or topology choices are unclear, ask 2-3 focused
+questions with concrete options and wait for the user's answer.
+
+For non-trivial parts, write a short `concept.md` using
+`../../references/concept-design.md` before committing `design.json`. After
+`validate` and `review` pass, apply
+`../../references/design-quality-review.md` before delivery.
+
 ## Common errors to design *against*
 
 For every hole declared in `params.json`, also declare a `min_clearance` check
@@ -40,7 +50,26 @@ wall" bug at design time, before any code is written.
 }
 ```
 
-See `../references/validation-strategy.md` for a complete catalog of design
+Also declare a `hole_accessibility` check for the real approach plane. For a
+Y-axis screw driven from the front of a vertical plate, the center is `[x, z]`:
+
+```json
+{
+  "id": "left_hole_tool_access",
+  "type": "hole_accessibility",
+  "axis": "y",
+  "y": -10.0,
+  "center": [hole_x, hole_z],
+  "hole_diameter": 4.5,
+  "clearance_diameter": 12.0
+}
+```
+
+For attached load-bearing features, add a connection/root check. A retaining
+lip, rib, boss, tab, arm, or flange needs proof that the base interface exists,
+not only proof that the feature body exists somewhere.
+
+See `../../references/validation-strategy.md` for a complete catalog of design
 errors and the check types that catch them.
 
 Generated artifacts go to `outputs/`.

agentcad_cli-0.1.4/src/agentcad/_templates/workspace/CLAUDE.md

@@ -0,0 +1,124 @@
+# AgentCAD Workspace
+
+You are working in an AgentCAD workspace. Your job is to create and refine CAD
+models using the `agentcad` CLI and build123d geometry library.
+
+## Workflow (13 stages, do not skip)
+
+1. **Understand**: read the user request, identify every feature, and pass the
+   Discovery Gate in `references/discovery.md`.
+2. **Concept**: when the model is non-trivial, compare 2-3 topology concepts
+   using `references/concept-design.md`. Commit to one concept before writing
+   the contract.
+3. **Contract**: write `models/<name>/design.json` with features and checks.
+   Load `references/contract-design.md` before editing the contract.
+4. **Params**: put tunable dimensions in `models/<name>/params.json`.
+5. **Precheck**: run `agentcad precheck <name>`. Do not write `part.py` while
+   precheck fails.
+6. **Implement**: write `models/<name>/part.py` using build123d. The final
+   object must be assigned to global variable `result`.
+7. **Build**: run `agentcad build <name>`.
+8. **Measure**: run `agentcad measure <name>`.
+9. **Render**: run `agentcad render <name> --views iso,front,top,side,back`.
+10. **Validate**: run `agentcad validate <name>`. It must pass.
+11. **Review**: run `agentcad review <name>` and inspect every `must_view`
+    artifact.
+12. **Quality Review**: apply `references/design-quality-review.md`. If the
+    model is merely valid but not good, revise the concept, contract, or
+    geometry and repeat validation.
+13. **Deliver**: run `agentcad deliver <name>` only after review and quality
+    review pass.
+
+Do not manually export STEP/STL from `part.py`. The runner owns all exports.
+
+## Stage References
+
+Read only the references needed for the current stage.
+
+| Stage | Reference |
+|---|---|
+| Requirements, ambiguity, user choices | `references/discovery.md` |
+| Topology options, tradeoffs, concept choice | `references/concept-design.md` |
+| `design.json`, feature coverage, check selection | `references/contract-design.md` |
+| Checks-first implementation loop | `references/cad-tdd.md` |
+| Check details, tolerances, probe usage, validation failures | `references/validation-strategy.md` |
+| build123d API patterns and geometry construction | `references/build123d-guide.md` |
+| Build/debug triage and external docs lookup | `references/debugging.md` |
+| Post-validation design quality critique | `references/design-quality-review.md` |
+
+## Hard Rules
+
+- Units are millimeters unless the user explicitly says otherwise.
+- Coordinate convention: +X right, +Y back, +Z up.
+- Do not write generated artifacts outside `models/<name>/outputs/`.
+- Treat `design.json` as the design contract: source of truth for what the
+  model should be.
+- Treat CLI JSON output as the source of truth for what the model actually is.
+- Do not claim a model is complete until `agentcad validate` and
+  `agentcad review` both pass and the quality review has no blocking issues.
+- Every requested feature must have at least one validation check.
+- bbox + watertight alone are not sufficient: they pass even when features are
+  missing or hidden.
+- Every hole needs a `min_clearance` check for each surrounding wall, adjacent
+  solid, or relevant edge.
+- Every hole also needs a `hole_accessibility` check on the real tool/fastener
+  approach plane.
+- Every load-bearing attached feature needs at least one interface/root check
+  in addition to a body-exists check. A lip, rib, boss, tab, wall, hook, or
+  bracket arm that only touches at an edge is a blocker even if validate passes.
+- Inspect side, front, top, back, and iso previews. A feature that looks
+  detached in any orthographic view is not deliverable until the contract
+  contains a check that would catch that failure.
+- Reason edge-to-edge, never center-to-face.
+
+## Workspace Layout
+
+```text
+models/<name>/
+  design.json    Feature contract: features list + checks
+  params.json    Tunable dimensions
+  part.py        build123d geometry (assign to `result`)
+  metadata.json  (auto-generated if part.py defines `metadata`)
+  outputs/
+    build.json          Build report
+    geometry.json       STL measurement report
+    validation.json     Validation results
+    precheck.json       Static contract report
+    review.json         Pre-delivery review report
+    deliverable.json    Delivery manifest
+    preview.iso.svg     SVG preview
+    <name>.step         STEP export
+    <name>.stl          STL export
+```
+
+## CLI Quick Reference
+
+```bash
+agentcad init <workspace> [--model <model>]
+agentcad new <model>
+agentcad precheck <model>
+agentcad build <model>
+agentcad build <model> --force
+agentcad measure <model>
+agentcad render <model>
+agentcad render <model> --views iso,front,top,side,back
+agentcad validate <model>
+agentcad review <model>
+agentcad deliver <model>
+agentcad probe <model> --z <z>
+agentcad probe <model> --z <z> "--center=cx,cy"
+agentcad probe <model> --z <z> --region x0,y0,x1,y1
+agentcad probe <model> --x <x>
+agentcad probe <model> --y <y>
+agentcad probe <model> --scan
+agentcad probe <model> --scan --axis x
+agentcad probe <model> --scan --axis y
+agentcad render <model> --section-z <z>
+agentcad render <model> --section-x <x>
+agentcad render <model> --section-y <y>
+agentcad inspect <model>
+agentcad report <model>
+```
+
+All commands output machine-readable JSON by default. Read the JSON before
+deciding the next action.

agentcad_cli-0.1.4/src/agentcad/_templates/workspace/references/cad-tdd.md

@@ -0,0 +1,83 @@
+# CAD TDD
+
+Use this reference before writing `part.py`.
+
+Every feature must have a check that can pass or fail before the final geometry
+is written. The order is not negotiable: checks first, geometry second.
+
+## Per-Feature Planning Table
+
+Fill this table before implementing a feature:
+
+| Feature | Shape | Center (cx, cy) | Z slice | Expected value | Check type |
+|---|---|---|---|---|---|
+| Outer shell | rectangle | - | - | [w, h, t] | `bbox_size` |
+| Camera hole | W x H rectangle | (cx, cy) | wall_back / 2 | min(W, H) | `inner_diameter_at_z` |
+| Inner cavity | void | center | wall_back + 2 | `void` | `section_bbox_at_z` |
+| USB-C port | W x H rectangle | (0, y) | z_mid | min(W, H) | `inner_diameter_at_z` |
+
+If you cannot fill in all columns for a feature, ask a focused question or
+revise the contract before coding. Do not start `part.py` while a feature has
+no measurable check strategy.
+
+## Red Phase
+
+After finishing `design.json`, write a minimal `part.py` that produces the
+outer envelope only, no internal features. Then run:
+
+```bash
+agentcad validate <model>
+```
+
+Expected outcome:
+
+- `bbox_size` passes.
+- Section, diameter, clearance, or position checks for missing internal
+  features fail.
+
+If a section check passes while its feature is missing, the check is wrong.
+Return to the planning table and redesign it.
+
+## Green Phase
+
+Implement one feature at a time and rerun `agentcad validate` immediately.
+Watch the matching check flip from failing to passing. Do not batch multiple
+features before validating.
+
+## Feature To Check Cheat Sheet
+
+| Feature type | Check type | Z slice | Expected value | Tolerance |
+|---|---|---|---|---|
+| Circular hole diameter D | `inner_diameter_at_z` | mid-Z of hole | D | 0.3 |
+| Rectangular hole W x H | `inner_diameter_at_z` | mid-Z of hole | min(W, H) | 3-5 |
+| Rectangular void region | `section_bbox_at_z` expected=`void` | mid-Z of feature | - | - |
+| Solid face, boss, or back panel | `section_bbox_at_z` expected=`solid` | mid-Z of face | - | - |
+| Outer envelope | `bbox_size` | - | [total_w, d, h] | 0.5 |
+| Taper or lead-in | `diameter_decreases_along_z` | z_range | monotonic | - |
+| Hole vs adjacent solid | `min_clearance` | - | descriptors | min_mm=0 |
+| Bolt assembly hole | `hole_accessibility` | working plane Z | hole and clearance radius | - |
+| Thin wall or rib | `min_wall_thickness` | section Z | min_mm=1.0 | 0.1 |
+| Direction marker | `feature_position` | point | `solid` or `void` | 0.5 |
+| Attached lip/rib/boss/arm root | `section_bbox_at_z` | attachment/interface Z | `solid` | - |
+
+Z slice formula: if a feature occupies `[z_bottom, z_top]`, slice at
+`z = (z_bottom + z_top) / 2`.
+
+When you do not know the expected value, run `agentcad build`, then
+`agentcad probe <model> --z <z>`. The `suggested_checks` field is ready to
+paste into `design.json`.
+
+When you do not know which Z to probe, run `agentcad probe <model> --scan` to
+surface step changes such as cavity starts and wall transitions.
+
+## Connection Red Phase
+
+For attached features, write two checks before coding:
+
+- body check: the feature exists at its main section
+- root check: the feature has material at the interface where it must transfer
+  load into the parent body
+
+In the red phase, deliberately build only the parent body and confirm both
+checks fail. In the green phase, make sure the root check flips only when the
+feature is actually connected through a meaningful contact area.

agentcad_cli-0.1.4/src/agentcad/_templates/workspace/references/concept-design.md

@@ -0,0 +1,88 @@
+# Concept Design
+
+Use this after discovery and before writing `design.json` for any non-trivial
+part. The goal is to choose a good topology before the validation contract
+locks the agent into a mediocre geometry.
+
+Skip this only for simple primitives, direct dimension edits, or fixes where
+the topology is already established.
+
+## Required Output
+
+Create a short concept note in the conversation before editing files. For
+persistent work, also save it as `models/<name>/concept.md`.
+
+The concept note must include:
+
+1. User goal and operating context.
+2. 2-3 topology concepts.
+3. Tradeoffs for each concept.
+4. Chosen concept and reason.
+5. Key dimensions and assumptions that will become `params.json`.
+6. Feature list and validation strategy that will become `design.json`.
+
+## Topology Concepts
+
+Each concept should describe the actual CAD structure, not just styling.
+
+For each option, cover:
+
+- load path and likely weak points
+- assembly sequence and tool access
+- manufacturing target and print/machining orientation
+- minimum wall/rib assumptions
+- support material or overhang risk for FDM
+- which dimensions are mating-critical
+- which checks will prove the concept works
+- what would make the concept fail
+
+Example:
+
+```markdown
+## Concept Options
+
+### A. Single-piece plate with two raised bosses
+- Best for: fast FDM prototype and simple screw mounting.
+- Risk: bosses concentrate stress unless filleted and tied into ribs.
+- Validation: bbox, boss positions, hole diameters, hole-wall clearance,
+  bolt accessibility, min wall thickness around bosses.
+
+### B. Folded L-bracket with triangular ribs
+- Best for: higher bending stiffness under vertical load.
+- Risk: more overhang and harder support removal.
+- Validation: upright position, rib solids, transverse hole access,
+  min wall thickness, section checks through both ribs.
+
+### C. Two-piece clamp with captured nut pocket
+- Best for: adjustable assembly.
+- Risk: more parts and tighter tolerance stack-up.
+- Validation: nut pocket void, screw path, clamp gap, clearance around tool.
+
+Chosen: B, because the load is a cantilever and stiffness matters more than
+print simplicity.
+```
+
+## When To Ask The User
+
+Ask for a concept choice when multiple concepts satisfy the request but differ
+in topology, assembly, manufacturing, cost, or visual form.
+
+Use 2-3 options with a recommended default. Stop and wait for the answer unless
+the user explicitly delegated design choice.
+
+Proceed without asking only when one concept clearly dominates because of the
+user's constraints. State why the other options were rejected.
+
+## Concept Quality Bar
+
+Before writing `design.json`, check the chosen concept:
+
+- Can every important feature be validated with an existing check type?
+- Are mating dimensions explicit or conservatively parameterized?
+- Are holes accessible by fasteners/tools?
+- Are wall thickness and clearances manufacturable?
+- Is the load path plausible, not just visually plausible?
+- Are there section views that will expose hidden mistakes?
+
+If the answer is no, revise the concept or ask a focused question before
+writing the contract.