diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63c97138..3c6682c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- **`create_sketch` takes `face_point`** (#206): a point in mm on a flat
+ face of the body, in place of `plane`. The sketch opens on that face and
+ moves with it when the model changes, so a pocket cut from it follows a
+ height edited later. Give exactly one of `plane` and `face_point`; a point
+ in the air or on a curved face fails with `invalid_input`.
+
+### Fixed
+
+Found building the monitor stand demo (#206):
+
+- **`list_features` returns rows in tree order.** When SolidWorks stopped
+ the forward walk at the system folders, the rest came newest first.
+- **`verify_model` counts a plane the agent made.** It skipped the first
+ three reference planes in row order, so with rows newest first it counted
+ `Front Plane` and skipped `Plane1`.
+- **`list_model_dimensions` lists each dimension once, under its own
+ feature.** It walks the tree the way `list_features` does, and takes each
+ dimension's feature from its full name: `D1@Plane1` is listed under
+ `Plane1`, never also under a cut sketched on that plane.
+- **`export_stl` keeps its STL options.** `SaveAs2` was called with six
+ arguments of the wrong types, so it always failed with a type mismatch
+ and `SaveAs3` wrote the file without merging the bodies. It now gets its
+ eight arguments; if it still writes nothing, `SaveAs3` writes the file and
+ the reply's `warning` says the options weren't applied.
+
+### Changed
+
+- **The monitor stand demo** sketches its pocket on the stand's top face,
+ with no reference plane, and its camera turns to an isometric view after
+ each feature (`--look` in the script).
+
## [2.0.0] - 2026-11-12
### Added
diff --git a/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif b/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif
index 2e26b6f7..3b3c9b8e 100644
Binary files a/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif and b/docs/assets/demos/monitor-stand/test_monitor_stand_from_prompt_to_part-motion.gif differ
diff --git a/docs/assets/progress/progress.json b/docs/assets/progress/progress.json
index 2bacb41f..9b125dbd 100644
--- a/docs/assets/progress/progress.json
+++ b/docs/assets/progress/progress.json
@@ -440,7 +440,7 @@
"family": "sketching",
"level": "stable",
"reason": "",
- "summary": "Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities."
+ "summary": "Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities."
},
{
"name": "create_sweep",
diff --git a/docs/assets/progress/tables.html b/docs/assets/progress/tables.html
index c1edd96d..1f4cc1a5 100644
--- a/docs/assets/progress/tables.html
+++ b/docs/assets/progress/tables.html
@@ -63,7 +63,7 @@
create_reference_point | modeling | stable | Add a reference point on an edge (at a distance or percentage along it) or at the centre of a face. |
create_revolve | modeling | stable | Revolve a closed sketch around an axis, adding a solid to the active part. |
create_section_view | drawing | planned no adapter implements it yet. | Cut a section view along a line across a drawing view. |
-create_sketch | sketching | stable | Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities. |
+create_sketch | sketching | stable | Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities. |
create_sweep | modeling | stable | Sweep a closed profile sketch along a path sketch to make a solid (Insert > Boss/Base > Sweep). |
create_technical_drawing | drawing | stable | Place a model's three standard views (front, top and side) on the active drawing sheet in one call. |
create_template | automation | planned no adapter implements it yet. | Create a part, assembly or drawing template file (.prtdot, .asmdot, .drwdot) with standard settings. |
diff --git a/docs/demos.md b/docs/demos.md
index 7352b474..3702a498 100644
--- a/docs/demos.md
+++ b/docs/demos.md
@@ -146,8 +146,9 @@ powershell -ExecutionPolicy Bypass -File tests\scripts\live_demo.ps1 `
The recording opens on the prompts, then replays the build as the script
below runs it, at the sizes the stand was finished at by hand (see
-"Finished by hand"): 24 tool calls, each captioned with its result, and the
-finished part in an isometric view. It is sped up five times.
+"Finished by hand"): 23 tool calls, each captioned with its result. The
+camera turns to an isometric view after the block, each cut, the arches and
+the pocket, so each feature shows as it is made. It is sped up five times.
**Printed.** The finished stand on the printer, in PETG, printed on its side
with tree supports (sped up):
@@ -281,16 +282,16 @@ the same legs, arches and pocket outline, cut 11.46 mm deep, comes to
901 762 mm³ by hand. SolidWorks measures 901 769 mm³.
The script below was then updated to reproduce this part: 66 mm, a 26 mm
-top and an 11.46 mm pocket are its defaults. One thing can't be matched:
-the tools can only offset a plane from a named plane, so the script puts
-the pocket's plane at Top Plane offset by the height. The solid is the
-same, but the plane doesn't follow a height edited by hand. To change the
-height, rerun the script.
+top and an 11.46 mm pocket are its defaults. It sketches the pocket on the
+stand's top face (`create_sketch` with `face_point`), as the user did by
+hand, so the pocket follows the height when `D1@Boss-Extrude1` is edited
+later, and no reference plane is needed.
**Rebuild it, or at another size.** The script replays the
calls with every dimension an option, and checks the result the same way.
-At its defaults it makes the 24 calls in the recording; the session's own
-28 calls are listed above.
+At its defaults it makes 22 calls, and 23 with `--stl` as in the recording;
+the session's own 28 calls are listed above. `--look` turns the camera to
+an isometric view after each feature, as the recording does.
```powershell
# The finished stand
@@ -312,7 +313,7 @@ To record the demo again:
```powershell
powershell -ExecutionPolicy Bypass -File tests\scripts\live_demo.ps1 `
- -Test tests/live/test_live_sw_monitor_stand_demo.py `
+ -Test tests/live/test_live_sw_monitor_stand_demo.py::test_monitor_stand_from_prompt_to_part `
-CaptureDir docs/assets/demos/monitor-stand -Record -PromptSeconds 12
```
diff --git a/docs/user-guide/tool-catalog/sketching.md b/docs/user-guide/tool-catalog/sketching.md
index 4307afe2..4d8d8f0a 100644
--- a/docs/user-guide/tool-catalog/sketching.md
+++ b/docs/user-guide/tool-catalog/sketching.md
@@ -10,18 +10,22 @@ Build 2-D sketch geometry (lines, circles, arcs, splines, polygons) and apply ge
### `create_sketch`
-Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities.
+Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities.
**Prerequisite:** Active part document, no active sketch
-**Parameters:**
+**Parameters:** give exactly one of `plane` and `face_point`.
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
-| `plane` | `str` | ✅ | `` | Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ') |
-| `sketch_name` | `str?` | — | `None` | Sketch name alias |
+| `plane` | `str?` | one of | `None` | Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ', or a plane made by `create_reference_plane`) |
+| `face_point` | `list[float]?` | one of | `None` | `[x, y, z]` in mm on a flat face of the body; the sketch opens on that face and moves with it when the model changes |
+| `sketch_name` | `str?` | — | `None` | Name `exit_sketch` gives the sketch when it closes it |
-**Sample call:**
+A `face_point` that is not on a flat face of the body (in the air, or on a
+fillet) fails with `error_type: "invalid_input"` and opens no sketch.
+
+**Sample calls:**
```json
{
@@ -29,6 +33,12 @@ Open a new sketch on a plane of the active part, ready for lines, circles and ot
}
```
+```json
+{
+ "face_point": [0, 20, 0]
+}
+```
+
---
### `add_line`
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/.openspec.yaml b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/.openspec.yaml
new file mode 100644
index 00000000..55ab199b
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-12
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/design.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/design.md
new file mode 100644
index 00000000..c1df4293
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/design.md
@@ -0,0 +1,144 @@
+## Context
+
+See proposal.md for the six faults. Where each one comes from:
+
+- **`list_features`' traversal:** the real adapter walks with
+ `FirstFeature` and `GetNextFeature`, then always adds a
+ `FeatureByPositionReverse(0..GetFeatureCount(True)-1)` pass. The forward
+ walk can stop at the system folders. The second pass then finds the
+ remaining features newest first, and they are appended in that order.
+ The rows are de-duplicated but never sorted.
+- **`verify_model`:** `_count_modelling_features` skips the first three
+ `RefPlane` rows it meets, in row order. On the monitor stand the rows came
+ newest first, so it skipped `Plane1`, `Right Plane` and `Top Plane` and
+ counted `Front Plane` (seen in the session's `verify_model` reply).
+- **`list_model_dimensions`:** it has its own forward-only walk, with no
+ reverse pass, and reads `GetFirstDisplayDimension` on every feature,
+ folders included. It found 0 with no name on the monitor stand, and all
+ four when given each feature's name. The same walk serves both calls, so
+ the cause is not proven. A block's full listing does work live
+ (`test_dimensions_list_and_measure`).
+- **`SaveAs2`:** the installed type library gives `IModelDocExtension.SaveAs2(Name,
+ Version, Options, ExportData, ReferencePrefixOrSuffixText As String,
+ AddTextAsPrefix As Boolean, Errors As Long by reference, Warnings As Long by
+ reference)` (eight arguments; a first live run with seven, leaving out
+ `Warnings`, failed with "Parameter not optional"). The adapter
+ calls it with `(path, 0, 2, stl_data, None, "")`.
+- **`create_sketch`:** it selects a plane by name (with locale aliases),
+ then calls `InsertSketch`. Faces are already selected by coordinates
+ elsewhere, for example `create_reference_plane`'s `face_point` and
+ `select_face_edges`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Feature and dimension listings that agree with the tree whatever the walk.
+- A sketch on a face in one call, through the same adapter path as a plane.
+- A demo whose recording shows each feature as it is made.
+
+**Non-Goals:**
+- Sketching on a curved face, or on a face of an assembly component.
+- Changing `export_stl`'s inputs; only the call underneath changes.
+- Finding why `GetNextFeature` stops at the folders. Both passes stay.
+
+## Decisions
+
+### 1. Sort `list_features` rows by tree position, in the adapter
+
+Both passes number features by their place in the top-level tree. The
+forward pass counts from 0, and the reverse pass uses
+`count - reverse_pos - 1`, so a feature found by both gets the same number.
+The adapter sorts each document's rows by `position` before returning
+them, keeping each component's rows together as they are now. Every caller
+then gets tree order: `verify_model`, the classifier, the bitmap, and
+feature-tree diffs.
+
+*Alternative:* sort only in `verify_model`. Rejected: every caller assumes
+tree order, and only one has been caught by it.
+
+### 2. `verify_model` skips default planes by position
+
+Once rows are in tree order, the first three `RefPlane` rows are the
+defaults. To guard against an adapter that doesn't sort, `verify_model`
+also sorts its rows by `position` before counting. This keeps the rule
+language-independent, as now: no plane names are matched.
+
+### 3. `list_model_dimensions` walks with `list_features`
+
+The adapter reads the features with the same two-pass traversal as
+`list_features` (a shared walk, not a copy), then reads each one's display
+dimensions. Folder rows are skipped, as nothing there has dimensions. Each
+dimension is kept once, keyed by `full_name`, with `feature` set from the
+part after `@`. With `feature_name`, the result keeps the dimensions whose
+`feature` matches. A sketch's own dimensions (`D1@Sketch3`) keep the sketch
+as their feature, so asking for the cut no longer returns the plane's offset.
+
+*Live diagnostic:* a test builds the monitor stand at its defaults and
+records, for the old and new walks, how many features each finds and how
+many dimensions each lists. This proves the fix and explains the 0.
+
+### 4. `SaveAs2` with its eight arguments
+
+`ext.SaveAs2(path, 0, swSaveAsOptions_Silent, stl_data, "", False, errors, warnings)`
+with `errors` and `warnings` by-reference Longs (`_byref_long`, as `RunMacro2` uses). When
+`GetExportFileData` gives nothing, `ExportData` is a `VT_DISPATCH` null.
+Success is the file existing. If `SaveAs2` writes nothing, `SaveAs3` runs
+as now, and the tool's reply carries a `warning` that the STL options
+weren't applied. The first `except` that retried `SaveAs2` without the data
+goes: it was a second copy of the same wrong call.
+
+### 5. `create_sketch(face_point=...)`
+
+The input model takes exactly one of `plane` and `face_point`. Today `plane`
+is required, so it becomes optional with the one-of check, and the error
+names both. The adapter method gains `face_point: tuple[float, float, float]
+| None`, through every adapter layer. The real adapter:
+
+1. finds and selects the face with `_select_face_at_point`, the helper
+ `create_reference_plane`'s `face_point` already uses live: it reads the
+ body's faces, takes the one whose closest point is within 0.01 mm,
+ refuses a face with no normal (curved), and selects it with
+ `IFace2.Select4`. It works from the body's geometry, so it needs neither
+ `SelectByID2` nor a rebuild first (decided at implementation, replacing
+ the `SelectByID2` + `IsPlane()` route first planned here);
+2. on no face, a curved face or a refused selection, clears the selection
+ and raises `LookupError("face_point [x, y, z] mm is not on a flat face
+ of the active part ()")`. One rule in `error_classifier.py`
+ matches exactly that message and classifies it `invalid_input`; the
+ shared "No face found at point" message stays `not_found` for
+ `select_face_edges`;
+3. calls `InsertSketch(True)`, and reads the new sketch's name as the
+ plane path does.
+
+The mock records the point and answers a point inside its block's top face
+(mirroring its existing coordinate model), and refuses others.
+
+*Alternative:* `face_name` (`Face<3>`). Rejected: agents don't know face
+names, and every other face input in the tools is a point.
+
+### 6. The demo
+
+`scripts/demo_monitor_stand.py` sketches the pocket with
+`create_sketch({"face_point": ...})` on the top face, at the stand's
+centre, at its height. `create_reference_plane` drops out of the script.
+For the recording, the script turns the camera to isometric and zooms to
+fit after each cut and the fillet. It reuses the README demo's `_look`
+pattern (`ShowNamedView2("", 7)`, `ViewZoomtofit2`), behind a flag the live
+test sets, since it is demo-side COM and not a tool. The GIF is re-recorded
+with `SW_DEMO_RECORD`, and the docs page's call list and count are updated.
+
+## Risks / Trade-offs
+
+- [Sorting changes `list_features`' order for callers that relied on the
+ old order] → Only the broken case changes order: when the forward walk
+ finishes, the rows are already in tree order. Feature-tree diffs key by
+ name.
+- [`SaveAs2` with the right arguments still fails on some versions] → The
+ `SaveAs3` fallback stays, now with a `warning`, so no export is lost. The
+ live test records which path wrote the file.
+- [The diagnostic shows the 0 had another cause] → It runs in the bundle.
+ If the new walk still misses dimensions, that is fixed after the bundle,
+ one at a time, as agreed.
+- [The pocket on the face changes the stand's volume] → No: the face is at
+ the same height the offset plane was. The live test checks the volume
+ against the recorded 901 769 mm³.
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/proposal.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/proposal.md
new file mode 100644
index 00000000..307c11da
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/proposal.md
@@ -0,0 +1,81 @@
+## Why
+
+Building the monitor stand demo (issue #206, queue item 9) turned up five tool
+faults and one missing ability. On a real part, `verify_model` counted
+`Front Plane` and skipped `Plane1`, and `list_model_dimensions` with no
+feature name found nothing. The same dimension was listed under two
+features. Every STL export logged a type mismatch and fell back to a path
+that can't merge bodies. No tool could start a sketch on a face of the body.
+Each one misleads an agent reading a finished part, and the demo recording
+misses the cuts and fillet because the camera never turns.
+
+## What Changes
+
+- **`list_features` returns rows in tree order.** The real adapter walks
+ forward with `GetNextFeature`, then always adds a `FeatureByPositionReverse`
+ pass, because the forward walk can stop at the system folders. When it
+ stops, the remaining rows arrive newest first. The rows are now sorted by
+ `position`, and both passes give the same position to the same feature.
+- **`verify_model` skips the three default planes by tree order**, so a
+ reference plane the agent made (`Plane1`) is counted and `Front Plane` is
+ not, whatever order the rows arrive in.
+- **`list_model_dimensions` finds every dimension with no feature name.**
+ It walks the tree the way `list_features` does (both passes), and lists
+ each dimension once, under the feature its full name's `@` suffix names
+ (`D1@Plane1` under `Plane1`, never also under the cut on that plane). Why
+ the old walk found none is not proven, so a live diagnostic records
+ where it went wrong.
+- **STL export calls `IModelDocExtension.SaveAs2` with its eight arguments**
+ (`Name, Version, Options, ExportData, ReferencePrefixOrSuffixText,
+ AddTextAsPrefix, Errors, Warnings`). The adapter passed six, with the wrong types,
+ so the call always failed with a type mismatch and `SaveAs3` wrote a file
+ without the merged-bodies option. The warning goes, and `SaveAs3` stays
+ only as the fallback for a `SaveAs2` that writes nothing.
+- **`create_sketch` takes `face_point`** (`[x, y, z]` in mm on a flat face
+ of the body) in place of `plane`, and opens the sketch on that face. It
+ must name exactly one of `plane` and `face_point`. A point that is not on
+ a flat face fails with `invalid_input`.
+- **The monitor stand demo** cuts its pocket on a sketch on the stand's top
+ face (via `face_point`), so the pocket follows a hand-edited height as the
+ user's finished part does. Its camera turns to isometric after each cut
+ and the fillet, and the GIF is re-recorded.
+
+No breaking changes: `plane` stays as it is; `face_point` is optional.
+
+## Capabilities
+
+### New Capabilities
+
+- `tools/dimension-listing`: `list_model_dimensions` lists every dimension
+ in the model once, under the feature that owns it.
+- `tools/stl-export`: `export_stl` writes the file through `SaveAs2` with its
+ export options, without a type-mismatch warning.
+- `tools/sketch-on-face`: `create_sketch` opens a sketch on a flat face of
+ the body given a point on it.
+
+### Modified Capabilities
+
+- `tools/list-features`: the rows come in tree order, whichever traversal
+ found them.
+- `tools/model-verification`: the feature count skips the three default
+ planes by tree order, so a plane the agent made is counted.
+
+## Impact
+
+- **COM and adapter code:** this change touches `pywin32_adapter.py`
+ (`list_features`' traversal, `_save_stl_with_extension`),
+ `adapters/solidworks/documentation.py` (`list_model_dimensions`) and
+ `adapters/solidworks/sketch.py` (`create_sketch` on a face). `create_sketch`'s
+ new argument runs through `base.py`, `circuit_breaker.py`,
+ `connection_pool.py` and `mock_adapter.py`. All COM work stays on the
+ connect thread inside `_handle_com_operation`. The `SaveAs2` call needs a
+ by-reference `Errors` VARIANT, and face selection needs the `VT_DISPATCH`
+ null callout (runbook #11) and `ForceRebuild3` first (runbook #13).
+- **Tools:** `sketching.py` (`CreateSketchInput`), `analysis.py`
+ (`_count_modelling_features`), `engineering_data.py` (description only).
+- **Demo:** `scripts/demo_monitor_stand.py`, its live test and
+ `docs/demos.md#monitor-stand`, with the GIF re-recorded.
+- **Docs:** the sketching tool catalog page, the skill's workflow notes on
+ sketching on a face, and the CHANGELOG.
+- **Live tests:** one bundled set run at the end; failures are fixed one by
+ one afterwards.
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/dimension-listing/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/dimension-listing/spec.md
new file mode 100644
index 00000000..79939ddd
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/dimension-listing/spec.md
@@ -0,0 +1,34 @@
+## Purpose
+
+`list_model_dimensions` lists every dimension in the active part or assembly
+once, under the feature that owns it, so an agent can find a dimension by
+name before reading or changing it.
+
+## ADDED Requirements
+
+### Requirement: Every dimension is listed with no feature name
+`list_model_dimensions` with no `feature_name` SHALL return every dimension
+of every feature in the active part or assembly: sketch dimensions, feature
+dimensions such as an extrude's depth, and reference-plane offsets. It SHALL
+return the same dimensions the per-feature calls return, together.
+
+#### Scenario: The monitor stand
+- **WHEN** a part holds an extrude, two cuts, a fillet, `Plane1` and a cut
+ sketched on `Plane1`, and `list_model_dimensions` is called with no
+ `feature_name`
+- **THEN** the result holds each dimension that a call naming each feature
+ in turn returns, and no fewer
+
+### Requirement: Each dimension is listed once, under its own feature
+Each dimension SHALL appear once in the result, and its `feature` SHALL be
+the feature its `full_name` names after the `@`.
+
+#### Scenario: A plane's offset seen from the cut on it
+- **WHEN** a cut is sketched on `Plane1`, and SolidWorks also reports
+ `D1@Plane1` among the cut's dimensions
+- **THEN** `D1@Plane1` appears once, with `feature` `Plane1`
+
+#### Scenario: Asking for one feature
+- **WHEN** `list_model_dimensions` is called with `feature_name` `Cut-Extrude3`
+- **THEN** only dimensions whose `full_name` ends in `@Cut-Extrude3` (or its
+ sketch's own name, for a sketch) are returned, not `D1@Plane1`
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/list-features/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/list-features/spec.md
new file mode 100644
index 00000000..96fab221
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/list-features/spec.md
@@ -0,0 +1,26 @@
+## MODIFIED Requirements
+
+### Requirement: Response is always a flat list of feature descriptors
+`list_features` SHALL always return a single flat list of feature
+descriptors, regardless of document type. Each descriptor SHALL contain
+`name`, `type`, `suppressed`, and `position`, exactly as it does today for
+Part documents. The response SHALL NOT be restructured into a nested
+object (for example, separate `components`/`assembly_features`
+collections) for any document type, because existing callers (feature-tree
+diffing, feature-family classification, and the MCP tool's `count` field)
+depend on the result being a flat list. Within each document, the
+descriptors SHALL be in feature-tree order (oldest first), each feature
+SHALL appear once, and its `position` SHALL be its place in that order,
+however SolidWorks was walked to find it.
+
+#### Scenario: Listing features on a Part
+- **WHEN** `list_features` is called with the active document being a
+ `.SLDPRT` Part
+- **THEN** the result is a flat list of that Part's own feature
+ descriptors, in the same shape as before this change
+
+#### Scenario: The forward walk stops early
+- **WHEN** SolidWorks stops the feature walk at the system folders, so the
+ remaining features are found newest first
+- **THEN** the result is still in tree order: the default planes come
+ before `Plane1`, and `Plane1` before the cut sketched on it
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/model-verification/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/model-verification/spec.md
new file mode 100644
index 00000000..3389f754
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/model-verification/spec.md
@@ -0,0 +1,25 @@
+## MODIFIED Requirements
+
+### Requirement: Feature count counts modelling features only
+`feature_count` SHALL count the document's own unsuppressed features, and
+excludes:
+- sketches;
+- the origin;
+- folder entries;
+- the three default reference planes, which are the first three reference
+ planes in tree order, whatever their names;
+- the mate group.
+
+A reference plane the agent made SHALL be counted. The agent can then
+predict the number from the features it created.
+
+#### Scenario: Part with two extrudes and a fillet
+- **WHEN** a part's tree holds the default entries, two sketches, two
+ extrudes and one fillet
+- **THEN** the measured feature count is 3
+
+#### Scenario: A part with a plane the agent made
+- **WHEN** a part holds an extrude, `Plane1` offset from Top Plane, and a
+ cut sketched on `Plane1`
+- **THEN** the measured feature count is 3, and the counted features are
+ the extrude, `Plane1` and the cut, never `Front Plane`
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/sketch-on-face/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/sketch-on-face/spec.md
new file mode 100644
index 00000000..427e6127
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/sketch-on-face/spec.md
@@ -0,0 +1,46 @@
+## Purpose
+
+`create_sketch` opens a sketch on a flat face of the body, given a point on
+that face, so a feature can follow the face when the model's dimensions
+change.
+
+## ADDED Requirements
+
+### Requirement: A sketch opens on the flat face at a point
+`create_sketch` SHALL accept `face_point`, `[x, y, z]` in millimetres in
+model coordinates, in place of `plane`. It SHALL open the sketch on the flat
+face of the active part at that point, and reply with the sketch's name
+as it does for a plane.
+
+#### Scenario: Sketching on the top face
+- **WHEN** a part has a 20 mm tall block whose top face is at y = 20 mm, and
+ `create_sketch` is called with `face_point` `[0, 20, 0]`
+- **THEN** a sketch opens on that face, and a cut drawn there and extruded
+ 3 mm leaves the block 3 mm lower at the cut
+
+#### Scenario: The sketch follows the face
+- **WHEN** the block's height is changed afterwards and the model rebuilt
+- **THEN** the sketch, and the cut made from it, move with the top face
+
+### Requirement: Exactly one of plane and face_point
+`create_sketch` SHALL fail with `invalid_input` when both `plane` and
+`face_point` are given, or neither, or `face_point` does not have three
+numbers.
+
+#### Scenario: Both given
+- **WHEN** `create_sketch` is called with `plane` `Top` and a `face_point`
+- **THEN** the call fails with `invalid_input`, and nothing is opened
+
+### Requirement: A point that is not on a flat face fails
+When `face_point` is not on a face of the active part, or is on a curved
+face, `create_sketch` SHALL fail with `invalid_input`, name the point, and
+open no sketch.
+
+#### Scenario: A point in the air
+- **WHEN** `face_point` is 50 mm above the part
+- **THEN** the call fails with `invalid_input` naming the point, and no
+ sketch is open afterwards
+
+#### Scenario: A point on a fillet
+- **WHEN** `face_point` lies on a filleted (curved) face
+- **THEN** the call fails with `invalid_input` saying the face is not flat
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/stl-export/spec.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/stl-export/spec.md
new file mode 100644
index 00000000..cdeade50
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/specs/tools/stl-export/spec.md
@@ -0,0 +1,23 @@
+## Purpose
+
+`export_stl` writes the active part or assembly as an STL file through
+SolidWorks' export call with its STL options, so a multibody part or an
+assembly comes out as one merged file.
+
+## ADDED Requirements
+
+### Requirement: STL export uses its export options without a type mismatch
+`export_stl` SHALL write the file with SolidWorks' STL export options (bodies
+merged into one file), and SHALL NOT log a type-mismatch warning on the way.
+A fallback without the options SHALL be used only when the first call
+writes nothing, and the reply SHALL say when it was used.
+
+#### Scenario: A single-body part
+- **WHEN** `export_stl` writes a part with one body
+- **THEN** the file exists, is non-empty, and no type-mismatch warning is
+ logged
+
+#### Scenario: The export call writes nothing
+- **WHEN** the export with options returns without writing the file
+- **THEN** the fallback writes it, and the reply's `warning` says the STL
+ options were not applied
diff --git a/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/tasks.md b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/tasks.md
new file mode 100644
index 00000000..c8cad0cb
--- /dev/null
+++ b/openspec/changes/archive/2026-11-14-monitor-stand-follow-ups/tasks.md
@@ -0,0 +1,42 @@
+## 1. Feature order
+
+- [x] 1.1 Real adapter: `list_features` sorts each document's rows by `position` (both passes numbered by tree place); tests where the forward walk stops early and the reverse pass finds the rest
+- [x] 1.2 Mock adapter: its rows stay in tree order, with a test that `position` rises
+- [x] 1.3 `verify_model`: sort rows by `position` before skipping the three default planes; tests with rows newest first and with `Plane1`
+
+## 2. Dimension listing
+
+- [x] 2.1 Real adapter: `list_model_dimensions` uses `list_features`' walk (shared), skips folders, keeps each `full_name` once with `feature` from the `@` suffix; tests for no name, a name, a plane offset seen from a cut, and a missing feature
+- [x] 2.2 Mock adapter: same de-duplication and `feature` rule; tests
+- [x] 2.3 Tool description: say each dimension is listed once, under its own feature
+
+## 3. STL export
+
+- [x] 3.1 Real adapter: `SaveAs2` with its eight arguments (by-reference `Errors` and `Warnings`, `VT_DISPATCH` null when there is no export data); remove the second wrong call; `SaveAs3` fallback reports that the options weren't applied; tests for each path
+- [x] 3.2 Mock adapter and tool: the fallback's note reaches the reply's `warning`; tests
+
+## 4. Sketch on a face
+
+- [x] 4.1 `CreateSketchInput`: `plane` optional, `face_point` added, exactly one of them; tests for both, neither and a short point
+- [x] 4.2 Adapter interface: `create_sketch(plane, face_point=None)` in `base.py`, `circuit_breaker.py` and `connection_pool.py`; tests
+- [x] 4.3 Real adapter: select the face at the point with `_select_face_at_point` (flat check included), insert the sketch; a `face_point ... is not on a flat face` error, classified `invalid_input`, for no face or a curved face; tests
+- [x] 4.4 Mock adapter: a point on its block's top face opens a sketch; other points are refused; tests
+- [x] 4.5 Docs: the sketching catalog page and the skill's note on sketching on a face
+
+## 5. The monitor stand demo
+
+- [x] 5.1 `scripts/demo_monitor_stand.py`: pocket sketched on the top face with `face_point`; `create_reference_plane` drops out; camera to isometric after each cut and the fillet, behind a flag
+- [x] 5.2 Its live test: the volume matches 901 769 mm³ at the defaults, and the pocket follows a changed height after a rebuild
+- [x] 5.3 `docs/demos.md#monitor-stand`: the call list and count, and drop "one thing can't be matched"
+
+## 6. Live bundle (one set, run together, then fixes one by one)
+
+- [x] 6.1 Live tests (written in `test_live_sw_monitor_stand_follow_ups.py` and `test_live_sw_monitor_stand_demo.py`; run live 2026-11-14, all five pass): feature order and `verify_model` on a part with `Plane1`; the dimension diagnostic (old walk vs new, counts) and the full listing on the stand; STL export path and file size; `create_sketch` on a face, the follow-the-height rebuild, a point in the air and a point on a fillet
+- [x] 6.2 Hand the user the bundle; fix each failure afterwards, one at a time (two failed: `SaveAs2` takes eight arguments, `Warnings` too; the face test read a name `exit_sketch` doesn't return. Both fixed and passed on the re-run)
+- [x] 6.3 Re-record the monitor stand GIF with `SW_DEMO_RECORD`
+
+## 7. Finish
+
+- [x] 7.1 CHANGELOG (Unreleased): Fixed (feature order, `verify_model`, dimension listing, STL), Added (`create_sketch` `face_point`)
+- [x] 7.2 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`, progress files regenerated
+- [x] 7.3 Sign-off, PR (no attribution), archive, and the queue updated
diff --git a/openspec/changes/configuration-tools/.openspec.yaml b/openspec/changes/configuration-tools/.openspec.yaml
new file mode 100644
index 00000000..55ab199b
--- /dev/null
+++ b/openspec/changes/configuration-tools/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-12
diff --git a/openspec/changes/configuration-tools/design.md b/openspec/changes/configuration-tools/design.md
new file mode 100644
index 00000000..0f7cc708
--- /dev/null
+++ b/openspec/changes/configuration-tools/design.md
@@ -0,0 +1,75 @@
+## Context
+
+`list_configurations` reads the names (fixed in 2.0.0 to read
+`IConfiguration.Name` as a property). `set_dimension`'s real adapter calls
+`GetDimension2(0).SetSystemValue3(value_m, 1, None)`: 1 is
+`swSetValue_InThisConfiguration`, so it already changes only the active
+configuration. `suppress_feature` calls `EditSuppress2`/`EditUnsuppress2`
+on the selected feature, which also act on the active configuration.
+
+COM members, from the type library index:
+
+| Need | Member |
+| --- | --- |
+| Create | `IConfigurationManager.AddConfiguration2(Name, Comment, AlternateName, Options, ParentConfigName, Description, Rebuild)` |
+| Activate | `IModelDoc2.ShowConfiguration2(Name)` |
+| Delete | `IModelDoc2.DeleteConfiguration2(Name)` |
+| Active name | `IConfigurationManager.ActiveConfiguration` → `IConfiguration.Name` |
+| Scoped value | `IDimension.SetSystemValue3(NewValue, WhichConfigurations, Config_names)` |
+| Scoped suppression | `IFeature.SetSuppression2(SuppressionState, Config_opt, Config_names)` |
+
+## Goals / Non-Goals
+
+**Goals:**
+- Variants of one model in a few calls, with every change's scope stated.
+- Today's calls keep doing what they do: `this` is the default.
+
+**Non-Goals:**
+- Design tables (Excel), configuration-specific materials or custom
+ properties, assembly component configurations (`set_component_state`
+ covers component suppression).
+- Renaming a configuration.
+
+## Decisions
+
+### 1. One `configurations` input, three forms
+
+`configurations: Literal["this", "all"] | list[str] = "this"`. The adapter
+maps it to the enum both COM calls share in meaning:
+`this` → 1, `all` → 2, a list → 3 with the names as a string array
+(`VARIANT(VT_ARRAY | VT_BSTR, names)`), and `None`/`Missing` for the names
+otherwise. A list is checked against `list_configurations` in the tool
+before any COM call, so an unknown name is `invalid_input`.
+
+### 2. Suppression keeps today's path for `this`
+
+For `this`, `suppress_feature` keeps `EditSuppress2`/`EditUnsuppress2`,
+which are proven live. For `all` or a list, it uses
+`IFeature.SetSuppression2` with `swSuppressFeature` (0) or
+`swUnSuppressFeature` (1), then rebuilds. The reply's `configurations`
+names where it applied.
+
+### 3. Creating doesn't switch unless asked
+
+`AddConfiguration2` makes the new configuration active. When `activate` is
+off, the adapter shows the previous configuration again, so creating a
+configuration doesn't change what the next call acts on. Options: 0 (no
+special behaviour); a `parent` uses `ParentConfigName` for a derived
+configuration.
+
+### 4. Delete guards in the tool
+
+The tool reads the active configuration and the list first and refuses
+the active or the only configuration with `invalid_input`; SolidWorks
+returns False in those cases without a reason.
+
+## Risks / Trade-offs
+
+- [`SetSystemValue3`'s names array marshals wrongly under late binding] →
+ the live bundle sets a value in a named configuration and reads it back
+ in each; if it fails, the adapter activates each named configuration and
+ sets `this`, then restores the active one.
+- [Switching configurations rebuilds a large assembly slowly] → each
+ activation goes through the settle pause; no extra waits are added.
+- [Agents forget the scope] → the default is the same as before, and every
+ reply names the configurations changed.
diff --git a/openspec/changes/configuration-tools/proposal.md b/openspec/changes/configuration-tools/proposal.md
new file mode 100644
index 00000000..60cfaad7
--- /dev/null
+++ b/openspec/changes/configuration-tools/proposal.md
@@ -0,0 +1,66 @@
+## Why
+
+Configurations are how SolidWorks users make size variants of one part (a
+bolt in five lengths, a bracket with and without a slot). An agent can
+only list them today (`list_configurations`). It can't make one, switch to
+one, or change a dimension or suppress a feature in one configuration
+only. Worse, `set_dimension` already changes the active configuration only
+(it passes `swSetValue_InThisConfiguration` to `SetSystemValue3`), and
+`suppress_feature` acts on the active one, and neither says so, so an
+agent editing a part with configurations gets results it can't predict.
+The planned `manage_design_table` is removed by the honest-tool-list change
+(it needs Excel on the machine); these tools give agents the same variants
+without it.
+
+## What Changes
+
+- **`create_configuration`**: adds a configuration to the active part or
+ assembly, by name, optionally as a derived (child) configuration of
+ another, with a description; it can be made active at once.
+- **`activate_configuration`**: makes a configuration active and rebuilds.
+- **`delete_configuration`**: deletes a configuration that isn't active.
+- **`set_dimension` gains `configurations`**: `this` (the default, today's
+ behaviour, now stated), `all`, or a list of names.
+- **`suppress_feature` gains `configurations`**: the same choices, through
+ `IFeature.SetSuppression2`.
+- **`list_configurations`** also reports which configuration is active.
+- The descriptions of `set_dimension`, `suppress_feature` and
+ `get_dimension` say which configuration they act on.
+
+## Capabilities
+
+### New Capabilities
+
+- `tools/configurations`: creating, activating and deleting
+ configurations, and scoping dimension and suppression changes to them.
+
+### Modified Capabilities
+
+- `tools/document-inspection`: `list_configurations` reports the active
+ configuration.
+
+## Impact
+
+- **COM and adapter code, all on the connect thread inside
+ `_handle_com_operation`:**
+ - `IConfigurationManager.AddConfiguration2`,
+ `IModelDoc2.ShowConfiguration2`, `DeleteConfiguration2`;
+ - `IConfigurationManager.ActiveConfiguration` (its `Name` is a property,
+ runbook "properties are still properties");
+ - `IDimension.SetSystemValue3` with `WhichConfigurations` 1, 2 or 3 and
+ the names array;
+ - `IFeature.SetSuppression2` replaces `EditSuppress2`/`EditUnsuppress2`
+ when a scope other than `this` is given.
+ - Three new adapter methods, and `configurations` on two existing ones,
+ through `base.py`, `circuit_breaker.py`, `connection_pool.py` and
+ `mock_adapter.py`.
+- **Tools:** `modeling.py` (`set_dimension`, `suppress_feature`, three new
+ tools), `file_management.py` (`list_configurations`), `tool_hints.py`,
+ `support_levels.py`.
+- **Docs:** catalog pages, the agent skill's note on configurations,
+ CHANGELOG, progress bars.
+- No issue is filed; this is queue item 13.
+- **Depends on the honest-tool-list change (queue item 10)**, merged
+ first: it sets the verb list and runs the design-table probe. If that
+ probe shows design tables work without trouble, `manage_design_table`
+ stays planned and is added to this change's tasks before it starts.
diff --git a/openspec/changes/configuration-tools/specs/tools/configurations/spec.md b/openspec/changes/configuration-tools/specs/tools/configurations/spec.md
new file mode 100644
index 00000000..7ee1c44d
--- /dev/null
+++ b/openspec/changes/configuration-tools/specs/tools/configurations/spec.md
@@ -0,0 +1,70 @@
+## Purpose
+
+An agent makes, switches and deletes configurations, and changes a
+dimension or a feature's suppression in the configurations it names, so
+one model can hold several variants.
+
+## ADDED Requirements
+
+### Requirement: Create a configuration
+`create_configuration` SHALL take `name`, and optionally `parent` (an
+existing configuration, making the new one derived from it),
+`description`, and `activate` (default off). It SHALL add the
+configuration to the active part or assembly and reply with its name and
+whether it is active.
+
+#### Scenario: A long variant
+- **WHEN** a part has only `Default` and `create_configuration` is called
+ with `name` `Long`
+- **THEN** `list_configurations` lists `Default` and `Long`, and `Default`
+ is still active
+
+#### Scenario: A name already used
+- **WHEN** `name` is `Default`
+- **THEN** the call fails with `invalid_input` naming the existing
+ configuration, and nothing is added
+
+### Requirement: Activate a configuration
+`activate_configuration` SHALL take `name`, make it the active
+configuration, rebuild, and reply with the active name.
+
+#### Scenario: Switching and back
+- **WHEN** `Long` is activated, then `Default`
+- **THEN** each reply names the configuration asked for, and
+ `get_model_info` reports it as active
+
+#### Scenario: An unknown name
+- **WHEN** `name` is not a configuration of the model
+- **THEN** the call fails with `invalid_input` listing the configurations
+
+### Requirement: Delete a configuration
+`delete_configuration` SHALL take `name` and delete that configuration. It
+SHALL fail with `invalid_input` when `name` is the active configuration or
+the only one.
+
+#### Scenario: Deleting the active one
+- **WHEN** `Long` is active and `delete_configuration` is called with `Long`
+- **THEN** the call fails, says to activate another configuration first,
+ and `Long` still exists
+
+### Requirement: Dimension and suppression changes name their configurations
+`set_dimension` and `suppress_feature` SHALL take `configurations`: `this`
+(the default: the active configuration only), `all`, or a list of
+configuration names. The change SHALL apply to exactly those
+configurations, and the reply SHALL name them.
+
+#### Scenario: A length in one variant
+- **WHEN** `Long` is active and `set_dimension` sets `D1@Boss-Extrude1` to
+ 80 with `configurations` `this`
+- **THEN** in `Long` the dimension is 80, and after activating `Default`
+ it is still its old value
+
+#### Scenario: A feature suppressed everywhere
+- **WHEN** `suppress_feature` suppresses `Fillet1` with `configurations`
+ `all`
+- **THEN** `Fillet1` is suppressed in `Default` and in `Long`
+
+#### Scenario: A named configuration that doesn't exist
+- **WHEN** `configurations` is `["Short"]` and there is no `Short`
+- **THEN** the call fails with `invalid_input` listing the configurations,
+ and nothing changes
diff --git a/openspec/changes/configuration-tools/specs/tools/document-inspection/spec.md b/openspec/changes/configuration-tools/specs/tools/document-inspection/spec.md
new file mode 100644
index 00000000..17a1ad16
--- /dev/null
+++ b/openspec/changes/configuration-tools/specs/tools/document-inspection/spec.md
@@ -0,0 +1,14 @@
+## MODIFIED Requirements
+
+### Requirement: Every configuration is listed
+
+`list_configurations` SHALL list the name of every configuration of the
+active part or assembly, and SHALL report which one is active as `active`.
+
+#### Scenario: A part with two configurations
+- **WHEN** a part has the configurations "Default" and "Long"
+- **THEN** the reply's `configurations` holds both names and `count` is 2
+
+#### Scenario: The active configuration
+- **WHEN** "Long" is active
+- **THEN** the reply's `active` is "Long"
diff --git a/openspec/changes/configuration-tools/tasks.md b/openspec/changes/configuration-tools/tasks.md
new file mode 100644
index 00000000..9f5da303
--- /dev/null
+++ b/openspec/changes/configuration-tools/tasks.md
@@ -0,0 +1,35 @@
+## 0. Before starting
+
+- [ ] 0.1 Confirm the honest-tool-list change is merged; read its design-table finding (its design decision 8). If `manage_design_table` was kept, add its tasks here (insert, read, update rows) before section 1
+
+## 1. Create, activate, delete
+
+- [ ] 1.1 Inputs and tools `create_configuration`, `activate_configuration`, `delete_configuration`, with the name checks (existing, unknown, active, only); tests
+- [ ] 1.2 Adapter interface for the three through `base.py`, `circuit_breaker.py`, `connection_pool.py`; tests
+- [ ] 1.3 Real adapter: `AddConfiguration2` (restore the previous configuration unless `activate`), `ShowConfiguration2`, `DeleteConfiguration2`; tests
+- [ ] 1.4 Mock adapter: a configuration list with an active one; tests
+
+## 2. The active configuration
+
+- [ ] 2.1 `list_configurations` reports `active` (real: `ActiveConfiguration.Name`); tests
+- [ ] 2.2 Mock adapter: `active` from its state; tests
+
+## 3. Scoped changes
+
+- [ ] 3.1 `configurations` input on `set_dimension` and `suppress_feature`; a list checked against the model's configurations; replies name the configurations; tests
+- [ ] 3.2 Adapter interface: `configurations` on `set_dimension` and `suppress_feature` through every layer; tests
+- [ ] 3.3 Real adapter: `SetSystemValue3` with 1, 2 or 3 and the names array; `SetSuppression2` for `all` or a list, `EditSuppress2` kept for `this`; tests
+- [ ] 3.4 Mock adapter: per-configuration dimension values and suppression; tests
+- [ ] 3.5 Descriptions of `set_dimension`, `suppress_feature` and `get_dimension` say which configuration they act on
+
+## 4. Live bundle (one set, run together, then fixes one by one)
+
+- [ ] 4.1 Live tests: create `Long`, activate it and back; delete refused while active; a length in `Long` only, read in both; `Fillet1` suppressed in `all`; an unknown name refused
+- [ ] 4.2 Hand the user the bundle; fix each failure afterwards, one at a time
+
+## 5. Docs and finish
+
+- [ ] 5.1 Catalog pages; the agent skill's note on configurations (scope defaults to the active one)
+- [ ] 5.2 CHANGELOG (Added; Changed: `list_configurations` reports `active`), progress bars regenerated
+- [ ] 5.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`
+- [ ] 5.4 Sign-off, PR (no attribution), archive, the queue updated
diff --git a/openspec/changes/drawing-pack/.openspec.yaml b/openspec/changes/drawing-pack/.openspec.yaml
new file mode 100644
index 00000000..55ab199b
--- /dev/null
+++ b/openspec/changes/drawing-pack/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-12
diff --git a/openspec/changes/drawing-pack/design.md b/openspec/changes/drawing-pack/design.md
new file mode 100644
index 00000000..153f2d87
--- /dev/null
+++ b/openspec/changes/drawing-pack/design.md
@@ -0,0 +1,114 @@
+## Context
+
+The drawing tools are in `tools/drawing.py` and `tools/drawing_automation.py`;
+the real adapter's drawing work is in `adapters/solidworks/documentation.py`
+and `drawing_standard.py`. Already there and reusable:
+
+- `_sheet_bounds(drawing)`: the sheet's size, used to keep views on it;
+- `title_block_properties(...)` and the DWG NO./TITLE fit in
+ `generate_drawing_package`;
+- `find_sheet_format(adapter, name)`: finds a `.slddrt` by name;
+- `list_drawing_views`, `insert_model_dimensions`, `insert_bom_table`.
+
+The seven tools are registered as `planned`; each raises
+`UnsupportedOperationError` or fails `require_capability`. Their current
+inputs were never used, so they can change.
+
+COM members, from the type library index:
+
+| Need | Member |
+| --- | --- |
+| Section view | `IDrawingDoc.CreateSectionViewAt5(X, Y, Z, SectionLabel, Options, ExcludedComponents, SectionDepth)` |
+| Detail view | `IDrawingDoc.CreateDetailViewAt4(X, Y, Z, Style, Scale1, Scale2, LabelIn, Showtype, FullOutline, JaggedOutline, NoOutline, ShapeIntensity)` |
+| Pick a view | `IDrawingDoc.ActivateView(ViewName)` |
+| One dimension | `IModelDocExtension.AddDimension(X, Y, Z, Direction)` |
+| Auto dimension | `IDrawingDoc.AutoDimension(EntitiesToDimension, HorizontalScheme, HorizontalPlacement, VerticalScheme, VerticalPlacement)` |
+| Sheet format | `ISheet.SetTemplateName(NameIn)`, `ISheet.ReloadTemplate(KeepNoteChanges)`, `ISheet.SetProperties2(...)` |
+| Checks | `IView.GetOutline()`, `IView.GetDimensionCount4()`, `IAnnotation.IsDangling()` |
+
+## Goals / Non-Goals
+
+**Goals:**
+- The seven planned drawing tools work on SolidWorks, and no tool is left
+ `planned`.
+- Every position is in sheet millimetres, the unit the other drawing tools
+ use.
+
+**Non-Goals:**
+- Aligned, half or offset sections; section depth; excluding components.
+- Ordinate dimensions, chamfer dimensions, tolerances on `add_dimension`.
+- The title-block fit for fields other than DWG NO. and TITLE (#158).
+- A drafting-standard score (ASME/ISO rule sets). `check_drawing` checks
+ completeness, not a standard.
+
+## Decisions
+
+### 1. Section line and detail circle are sketched in the parent view
+
+`CreateSectionViewAt5` and `CreateDetailViewAt4` use the selected sketch
+line or circle. The adapter activates the parent view, sketches the line
+(or circle) with the sketch manager in sheet coordinates converted to the
+view's sketch space, selects it, and calls the creator at `position`. If
+the call returns nothing, the sketch entity is deleted so no stray line is
+left. The section line is checked against `IView.GetOutline()` first, and
+`position` plus the parent view's size against `_sheet_bounds`, so the
+common failures are `invalid_input` before any COM change.
+
+### 2. Picks for `add_dimension` are sheet points
+
+`SelectByID2("", "EDGE" | "VERTEX", x, y, 0, append, 0, null_callout, 0)`
+in sheet metres selects view entities on a drawing. The adapter selects
+entity 1, then entity 2 with `append`, then calls
+`IModelDocExtension.AddDimension(x, y, 0, direction)` with the
+direction from `dimension_type` (`swSmartDimensionDirection_e`: horizontal,
+vertical, aligned; radial, diameter and angular use the smart direction).
+The reply reads the new display dimension's `GetDimension2(0).Value`.
+
+*Alternative:* entity names from a view registry, as sketches have. Rejected
+for now: drawing entities have no stable names, and agents can compute
+sheet points from `list_drawing_views`' outlines.
+
+### 3. `auto_dimension_view` counts before and after
+
+The adapter activates and selects the view, calls `AutoDimension` with all
+edges, the scheme for both directions, and placement above/right, then
+reports `GetDimensionCount4()` after minus before. Zero added is a failure,
+so a call that silently does nothing is visible.
+
+### 4. `update_title_block` reuses the package's mapping
+
+It calls `title_block_properties` with the given fields merged over the
+current property values (read first), writes model and drawing properties
+through the adapter's custom-property methods, then reruns the fit for
+DWG NO. and TITLE and rebuilds. It is the same code path
+`generate_drawing_package` uses, moved into one helper both call.
+
+### 5. `update_sheet_format` changes the template in place
+
+`find_sheet_format` resolves the name; the adapter calls
+`SetTemplateName` then `ReloadTemplate(True)`, and `SetProperties2` for a
+new paper size, then checks the views are still listed and on the sheet.
+The live bundle confirms the title block's linked fields survive the
+reload.
+
+### 6. `check_drawing` is read-only and composed from reads
+
+A new adapter method returns, per view: name, type, outline, dimension
+count; plus the sheet size, the title-block properties, whether a BOM
+table exists, and the dangling annotation count. The rules run in the tool
+module as plain functions on that data (unit-tested without COM). The tool
+is the renamed `check_drawing_standards`; the old name was planned and
+never worked, so no deprecation is needed.
+
+## Risks / Trade-offs
+
+- [Sheet-to-view coordinate conversion for the section line] → the
+ conversion uses the view's position and scale (`IView.Position`,
+ `ScaleDecimal`); the live bundle checks a section through a hole's centre.
+- [`AutoDimension` places dimensions over each other] → `arrange_dimensions`
+ already exists; the description points to it.
+- [`ReloadTemplate` drops edited notes] → `KeepNoteChanges` is true; the
+ live test checks the title-block values after the reload.
+- [`SelectByID2` on a drawing picks the wrong view's edge where views
+ overlap] → views are checked to be on the sheet; overlapping views are
+ rare in generated drawings; the error says which entity was picked.
diff --git a/openspec/changes/drawing-pack/proposal.md b/openspec/changes/drawing-pack/proposal.md
new file mode 100644
index 00000000..81616ef7
--- /dev/null
+++ b/openspec/changes/drawing-pack/proposal.md
@@ -0,0 +1,83 @@
+## Why
+
+Drawings are where this server goes further than the comparable servers
+(the closest one declares drawings out of scope). An agent can already make
+a drawing with standard views, a BOM, model dimensions, centre marks, GD&T
+and a filled title block. Seven drawing tools are still `planned`, and
+they are the ones a real drawing package needs next: a section and a detail
+view, editing the title block or sheet format after the drawing exists,
+adding one dimension by hand (#102), automatic dimensions on a view, and a
+check that the drawing is complete. With them, an agent can take a part or
+assembly to a finished, checked drawing.
+
+## What Changes
+
+- **`create_section_view`**: cuts a section through a view along a line
+ given by two points in sheet millimetres, and places the section view at
+ a point on the sheet, with a label (`A`, `B`, ...).
+- **`create_detail_view`**: a detail of a circle (centre and radius in
+ sheet millimetres) in a view, placed on the sheet at a scale, with a
+ label.
+- **`update_title_block`**: sets the title block's fields (title, drawing
+ number, drawn by, date, revision, company) on an existing drawing, with
+ the same field mapping and fit as `generate_drawing_package`.
+- **`update_sheet_format`**: changes the active sheet's format (a format
+ name such as `a3 - iso`, or a `.slddrt` path) and paper size, keeping the
+ views.
+- **`add_dimension`** (#102): one dimension in a view: linear (horizontal,
+ vertical or aligned), radial, diameter or angular, between entities
+ picked by points in sheet millimetres, placed at a point; it replies with
+ the measured value.
+- **`auto_dimension_view`** (#102): SolidWorks' auto-dimension on one view
+ (baseline or chain, horizontal and vertical), replying with how many
+ dimensions it added. Its description says how it differs from
+ `insert_model_dimensions` (reference dimensions vs the model's own).
+- **`check_drawing`** (the planned `check_drawing_standards`, renamed): a
+ read-only check of the active drawing: every view on the sheet, every
+ view dimensioned, the title block's fields filled, no dangling
+ annotations, and a BOM when the model is an assembly. It replies with a
+ list of findings and `passed`.
+- All seven move from `planned` to `stable` after the live bundle, leaving
+ no planned tools.
+
+## Capabilities
+
+### New Capabilities
+
+- `tools/drawing-section-detail`: section and detail views.
+- `tools/drawing-title-block`: `update_title_block` and
+ `update_sheet_format` on an existing drawing.
+- `tools/drawing-dimensions`: `add_dimension` and `auto_dimension_view`.
+- `tools/drawing-check`: `check_drawing`.
+
+### Modified Capabilities
+
+- `tools/support-levels`: no tool is `planned` after this change.
+
+## Impact
+
+- **COM and adapter code, all on the connect thread inside
+ `_handle_com_operation`:**
+ - `adapters/solidworks/documentation.py` gains the view-creation and
+ dimension methods:
+ - `IDrawingDoc.CreateSectionViewAt5`, `CreateDetailViewAt4`,
+ `AutoDimension`, `ActivateView`;
+ - `IModelDocExtension.AddDimension`;
+ - `ISheet.SetTemplateName` and `ReloadTemplate`;
+ - `IView.GetOutline`, `GetDisplayDimensions`;
+ - `IAnnotation.IsDangling`.
+ - The section line and detail circle are sketched in the view before the
+ call; entity picks use `SelectByID2` with the null callout (runbook #11).
+ - New adapter methods through `base.py`, `circuit_breaker.py`,
+ `connection_pool.py` and `mock_adapter.py`.
+- **Tools:** `drawing.py` (the seven tools; `check_drawing_standards`
+ renamed), `tool_hints.py`, `support_levels.py`.
+- **Reuse:** `drawing_standard.title_block_properties` and its fit code,
+ `find_sheet_format`, `_sheet_bounds`.
+- **Docs:** drawing catalog pages, the drawing tutorial's "What is and
+ isn't live today" table, the agent skill's drawing workflow, CHANGELOG,
+ progress bars.
+- Closes #102. From #158 it settles the BOM-on-a-formatted-sheet check (in
+ the live bundle); the title-block fit improvements stay in #158.
+- Depends on the honest-tool-list change (queue item 10), which leaves
+ these seven as the only planned tools.
diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-check/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-check/spec.md
new file mode 100644
index 00000000..37ba635c
--- /dev/null
+++ b/openspec/changes/drawing-pack/specs/tools/drawing-check/spec.md
@@ -0,0 +1,44 @@
+## Purpose
+
+`check_drawing` tells an agent whether the active drawing is complete
+before it is exported, as findings it can act on with the other drawing
+tools.
+
+## ADDED Requirements
+
+### Requirement: Findings for an incomplete drawing
+`check_drawing` SHALL read the active drawing without changing it and
+reply with `passed` and `findings`, each finding having `rule`, `severity`
+(`error` or `warning`), `message` and, where it applies, `view`. The rules:
+
+- `view_off_sheet` (error): a view's outline extends past the sheet;
+- `view_not_dimensioned` (warning): a view, other than an isometric or
+ detail view, has no dimensions;
+- `title_block_field_empty` (warning): a title-block field the standard
+ fills (title, drawn by, revision) is empty;
+- `dangling_annotation` (error): an annotation has lost its reference;
+- `bom_missing` (warning): the drawing's model is an assembly and the
+ sheet has no BOM table.
+
+`passed` SHALL be true when there are no `error` findings.
+
+#### Scenario: A finished package
+- **WHEN** a drawing from `generate_drawing_package` with model dimensions
+ is checked
+- **THEN** `passed` is true and `findings` is empty
+
+#### Scenario: A view dragged off the sheet
+- **WHEN** a view's outline crosses the sheet's edge
+- **THEN** `passed` is false, and a `view_off_sheet` finding names the view
+
+#### Scenario: An assembly drawing with no BOM
+- **WHEN** an assembly's drawing has views but no BOM
+- **THEN** a `bom_missing` warning is listed, and `passed` stays true
+
+### Requirement: Only on a drawing
+`check_drawing` SHALL fail with `invalid_input` when the active document is
+not a drawing.
+
+#### Scenario: A part is active
+- **WHEN** a part is the active document
+- **THEN** the call fails with `invalid_input` saying to activate a drawing
diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-dimensions/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-dimensions/spec.md
new file mode 100644
index 00000000..c178f4b5
--- /dev/null
+++ b/openspec/changes/drawing-pack/specs/tools/drawing-dimensions/spec.md
@@ -0,0 +1,45 @@
+## Purpose
+
+`add_dimension` and `auto_dimension_view` put dimensions on drawing views,
+by hand or automatically, so a drawing with views is a deliverable.
+
+## ADDED Requirements
+
+### Requirement: One dimension between picked entities
+`add_dimension` SHALL take `dimension_type` (`horizontal`, `vertical`,
+`aligned`, `radial`, `diameter` or `angular`), `entity1_point` and, for
+the types that need two entities, `entity2_point` (`[x, y]` in sheet
+millimetres on a view's edges or vertices), and `position` (`[x, y]` in
+sheet millimetres for the text). It SHALL add one dimension and reply with
+its name and measured value in millimetres (degrees for angular).
+
+#### Scenario: A plate's width
+- **WHEN** a front view of a 60 mm wide plate is on the sheet and
+ `add_dimension` is called with `horizontal` and points on its left and
+ right edges
+- **THEN** one dimension is added and its value is 60 within 0.01 mm
+
+#### Scenario: A hole's diameter
+- **WHEN** `add_dimension` is called with `diameter` and a point on a
+ Ø6 mm hole's edge
+- **THEN** the value is 6 within 0.01 mm
+
+#### Scenario: A point on no entity
+- **WHEN** `entity1_point` is on empty sheet
+- **THEN** the call fails with `invalid_input` naming the point, and no
+ dimension is added
+
+### Requirement: Auto-dimension one view
+`auto_dimension_view` SHALL take `view`, `scheme` (`baseline` or `chain`,
+default `baseline`) and apply SolidWorks' auto-dimension to that view's
+edges, horizontally and vertically, replying with the number of
+dimensions added.
+
+#### Scenario: A plate's front view
+- **WHEN** `auto_dimension_view` is called on a plate's front view
+- **THEN** the reply's `added` is at least 2, and the view's dimension
+ count rises by that number
+
+#### Scenario: A view that doesn't exist
+- **WHEN** `view` names no view on the sheet
+- **THEN** the call fails with `invalid_input` listing the views
diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-section-detail/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-section-detail/spec.md
new file mode 100644
index 00000000..bb795aa9
--- /dev/null
+++ b/openspec/changes/drawing-pack/specs/tools/drawing-section-detail/spec.md
@@ -0,0 +1,44 @@
+## Purpose
+
+`create_section_view` and `create_detail_view` add the two derived views a
+drawing package needs to show inside and small features.
+
+## ADDED Requirements
+
+### Requirement: A section view along a line
+`create_section_view` SHALL take `view` (the parent view's name),
+`line_start` and `line_end` (`[x, y]` in sheet millimetres, crossing the
+view), `position` (`[x, y]` in sheet millimetres for the new view) and
+`label` (default the next free letter). It SHALL add a section view cut
+along that line, and reply with the new view's name, label and outline.
+
+#### Scenario: A section through a plate with a hole
+- **WHEN** a drawing has a front view of a plate with a hole, and
+ `create_section_view` is called with a line across the hole's centre
+- **THEN** `list_drawing_views` lists one more view, labelled `A`, and
+ its outline is inside the sheet
+
+#### Scenario: A line that misses the view
+- **WHEN** the line lies wholly outside the parent view's outline
+- **THEN** the call fails with `invalid_input` naming the view, and no view
+ or sketch line is left behind
+
+### Requirement: A detail view of a circle
+`create_detail_view` SHALL take `view`, `center` (`[x, y]` in sheet
+millimetres inside the view), `radius` in millimetres, `position`, `scale`
+(for example `2:1`, default `2:1`) and `label`. It SHALL add a detail view
+and reply with its name, label and scale.
+
+#### Scenario: A detail of a corner
+- **WHEN** `create_detail_view` is called with a circle on a corner of the
+ front view and scale `3:1`
+- **THEN** one more view exists, labelled, at scale 3:1
+
+### Requirement: New views stay on the sheet
+Both tools SHALL refuse a `position` that would put the new view's outline
+off the sheet, before creating it, with `invalid_input` naming the sheet's
+size.
+
+#### Scenario: A position off the sheet
+- **WHEN** `position` is beyond the sheet's right edge
+- **THEN** the call fails with `invalid_input`, and no view is added
diff --git a/openspec/changes/drawing-pack/specs/tools/drawing-title-block/spec.md b/openspec/changes/drawing-pack/specs/tools/drawing-title-block/spec.md
new file mode 100644
index 00000000..d6c1e136
--- /dev/null
+++ b/openspec/changes/drawing-pack/specs/tools/drawing-title-block/spec.md
@@ -0,0 +1,41 @@
+## Purpose
+
+`update_title_block` and `update_sheet_format` change an existing drawing's
+title block and sheet, so an agent can revise a drawing without
+regenerating it.
+
+## ADDED Requirements
+
+### Requirement: Title-block fields on an existing drawing
+`update_title_block` SHALL take any of `title`, `drawing_number`,
+`drawn_by`, `drawn_date`, `revision` and `company` (at least one), write
+each to the property the sheet format reads (the same mapping
+`generate_drawing_package` uses), rebuild, and reply with the fields it
+set. Fields not given SHALL keep their values.
+
+#### Scenario: A new revision
+- **WHEN** a drawing made by `generate_drawing_package` is active and
+ `update_title_block` is called with `revision` `B`
+- **THEN** the title block shows `B`, and the title and drawn-by fields are
+ unchanged
+
+#### Scenario: No fields
+- **WHEN** `update_title_block` is called with no fields
+- **THEN** the call fails with `invalid_input` listing the fields
+
+### Requirement: A different sheet format, keeping the views
+`update_sheet_format` SHALL take `format` (a format name found by
+`find_sheet_format`, or a path to a `.slddrt` file) and optionally
+`paper_size`. It SHALL change the active sheet's format, keep every view,
+and reply with the format's path and the sheet's size.
+
+#### Scenario: From A3 to A2
+- **WHEN** the active sheet uses `a3 - iso` and `update_sheet_format` is
+ called with `a2 - iso`
+- **THEN** the sheet is A2, `list_drawing_views` lists the same views, and
+ the title block's fields still show their values
+
+#### Scenario: A format that doesn't exist
+- **WHEN** `format` names no format SolidWorks can find
+- **THEN** the call fails with `invalid_input` naming the folders searched,
+ and the sheet is unchanged
diff --git a/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md b/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md
new file mode 100644
index 00000000..9286d12f
--- /dev/null
+++ b/openspec/changes/drawing-pack/specs/tools/support-levels/spec.md
@@ -0,0 +1,17 @@
+## MODIFIED Requirements
+
+### Requirement: Levels are consistent with the code
+
+The check SHALL fail when a level contradicts what the code shows. A `planned` tool's reason SHALL name the queue item that builds it.
+
+#### Scenario: Planned means not implemented
+- **WHEN** a tool is `planned`
+- **THEN** its description says "Not available yet", no tool outside `planned` says so, and its reason names a queue item
+
+#### Scenario: Stable means checked live
+- **WHEN** a tool is `stable`
+- **THEN** at least one test under `tests/live/` calls it by name
+
+#### Scenario: After the drawing pack
+- **WHEN** the levels are counted after this change
+- **THEN** no tool is `planned`
diff --git a/openspec/changes/drawing-pack/tasks.md b/openspec/changes/drawing-pack/tasks.md
new file mode 100644
index 00000000..a45a25df
--- /dev/null
+++ b/openspec/changes/drawing-pack/tasks.md
@@ -0,0 +1,47 @@
+## 1. Section and detail views
+
+- [ ] 1.1 New inputs for `create_section_view` (`view`, `line_start`, `line_end`, `position`, `label`) and `create_detail_view` (`view`, `center`, `radius`, `position`, `scale`, `label`); the off-sheet and missed-view checks; tests
+- [ ] 1.2 Adapter interface for both through `base.py`, `circuit_breaker.py`, `connection_pool.py`; tests
+- [ ] 1.3 Real adapter: activate the view, sketch the line or circle in view space, `CreateSectionViewAt5` / `CreateDetailViewAt4`, delete the sketch entity on failure; tests
+- [ ] 1.4 Mock adapter: a new view appended to its view list with a label and outline; tests
+
+## 2. Title block and sheet format
+
+- [ ] 2.1 One title-block helper shared by `generate_drawing_package` and `update_title_block` (mapping, merge over current values, fit); tests
+- [ ] 2.2 `update_title_block` input (at least one field) and tool; tests
+- [ ] 2.3 `update_sheet_format` input and tool; `find_sheet_format` errors name the folders searched; tests
+- [ ] 2.4 Adapter interface for the sheet format through every layer; tests
+- [ ] 2.5 Real adapter: `SetTemplateName`, `ReloadTemplate(True)`, `SetProperties2`; tests
+- [ ] 2.6 Mock adapter: the sheet's format and size change, views kept; tests
+
+## 3. Drawing dimensions (#102)
+
+- [ ] 3.1 `add_dimension` input (type, points, position) and the two-entity rule; tests
+- [ ] 3.2 `auto_dimension_view` input (`view`, `scheme`); tests
+- [ ] 3.3 Adapter interface for both through every layer; tests
+- [ ] 3.4 Real adapter: point picks with the null callout, `AddDimension` with the direction, value read back; `ActivateView`, `AutoDimension`, the count before and after; tests
+- [ ] 3.5 Mock adapter: a dimension's value from its mock geometry; auto-dimension adds two per view; tests
+
+## 4. Drawing check
+
+- [ ] 4.1 Adapter method returning views (name, type, outline, dimension count), sheet size, title-block properties, BOM present, dangling count; through every layer; tests
+- [ ] 4.2 Real adapter: `GetOutline`, `GetDimensionCount4`, `IsDangling`, BOM table lookup; tests
+- [ ] 4.3 Mock adapter: the same report from its drawing state; tests
+- [ ] 4.4 The five rules as plain functions; `check_drawing` replaces `check_drawing_standards`; tests for each rule and for a part being active
+
+## 5. Levels and descriptions
+
+- [ ] 5.1 The seven tools' descriptions rewritten to the standard (no "Not available yet"); `auto_dimension_view` vs `insert_model_dimensions` stated; levels `beta` until the bundle passes
+- [ ] 5.2 The support-level test: no tool `planned`
+
+## 6. Live bundle (one set, run together, then fixes one by one)
+
+- [ ] 6.1 Live tests: a section through a plate's hole and one off the view; a 3:1 corner detail; revision B on a package drawing; A3 to A2 keeping views and title values; width 60 and Ø6 dimensions; auto-dimension on the front view; `check_drawing` on a finished package, a view off the sheet and an assembly with no BOM; `insert_bom_table` on the A3 ISO format, checked on the sheet (#158)
+- [ ] 6.2 Hand the user the bundle; fix each failure afterwards, one at a time; move each tool to stable when its tests pass
+
+## 7. Docs and finish
+
+- [ ] 7.1 Drawing catalog pages, the drawing tutorial's "What is and isn't live today" table, the agent skill's drawing workflow (views, then dimensions, then `check_drawing`, then export)
+- [ ] 7.2 CHANGELOG (Added; Changed: `check_drawing_standards` is now `check_drawing`), progress bars regenerated
+- [ ] 7.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`
+- [ ] 7.4 Sign-off, PR (no attribution) closing #102, a comment on #158 for the BOM check, archive, the queue updated
diff --git a/openspec/changes/honest-tool-list/.openspec.yaml b/openspec/changes/honest-tool-list/.openspec.yaml
new file mode 100644
index 00000000..55ab199b
--- /dev/null
+++ b/openspec/changes/honest-tool-list/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-12
diff --git a/openspec/changes/honest-tool-list/design.md b/openspec/changes/honest-tool-list/design.md
new file mode 100644
index 00000000..1d65e7d2
--- /dev/null
+++ b/openspec/changes/honest-tool-list/design.md
@@ -0,0 +1,127 @@
+## Context
+
+After 2.0.0 the server has 156 tools: 116 `stable`, 40 `planned`
+(`tools/support_levels.py`). Planned tools are registered so their names
+are reserved, and every call returns `not_supported`. Issue #174 lists the
+overlapping clusters; Glama's review (2.3/5) says an agent can't pick the
+intended tool. `ToolRegistrar` (`tools/tool_boundary.py`) already adds a
+level tag, a description opening and a success `warning` from the levels
+table, so a new level costs one table entry per tool.
+
+Each overlapping cluster, compared in the code:
+
+| Cluster | Finding | Decision |
+| --- | --- | --- |
+| `open_model`, `load_part`, `load_assembly` | Same adapter call; the two loaders only check the extension | keep `open_model` |
+| `save_file`, `save_part`, `save_assembly`, `save_as` | `save_part`/`save_assembly` = `save_file` plus `_prepare_save_target`; `save_as` writes other formats | keep `save_file` (with the checks) and `save_as` |
+| `get_mass_properties`, `calculate_mass_properties` | Same adapter call; one takes optional input | keep `get_mass_properties` |
+| `get_model_info`, `get_file_properties` | Different fields: tree and rebuild vs size and dates | keep `get_model_info`, add size and dates |
+| `create_drawing_view`, `add_drawing_view` | Same code; `add_drawing_view`'s description already says so | keep `create_drawing_view` |
+| `create_technical_drawing` | Three views in one call: a different job | keep |
+| `sketch_tutorial_simple_hole`, `tutorial_simple_hole` | Fixed examples; the second never worked | remove the planned one, deprecate the other |
+| `generate_vba_code` and ten `generate_vba_*` | Offline text generators with different inputs | leave to item 14 (an optional toolset) |
+| Seven drawing checks | All planned | remove six; `check_drawing_standards` becomes item 12's `check_drawing` |
+| Macro recording (four) | All planned; the type-library index has no recorder start/stop member | remove |
+| Templates (five, plus `create_template`) | All planned; `set_custom_property`/`set_material` cover applying settings | remove; keep `compare_templates` |
+
+## Goals / Non-Goals
+
+**Goals:**
+- Every registered tool either works or is one of seven named drawing
+ tools that item 12 builds.
+- One tool per job, with a release in which old names still work.
+- A verb list new tools follow.
+
+**Non-Goals:**
+- Renaming stable tools that break the verb list (`pattern_circular`,
+ `mirror_feature`, `select_face_edges`, ...): renames break clients for no
+ gain in function. They are listed as exceptions.
+- Merging the VBA generators, or turning families off: item 14.
+- Building any planned tool.
+
+## Decisions
+
+### 1. `deprecated` is a support level
+
+`SupportLevel.DEPRECATED`, with `Support(level, reason)` where the reason
+is "use ``" or "no replacement", and a new `since` field holding the
+version it was deprecated in. `Support.warning()` returns
+"Deprecated: use ``." for it, so `ToolRegistrar` adds the description
+opening and the success `warning` exactly as it does for beta. The level
+tag is `level:deprecated`. The progress page counts deprecated tools
+separately and leaves them out of the coverage bars.
+
+*Alternative:* a separate aliases table that re-registers the replacement
+under the old name. Rejected: inputs differ (`load_part` checks the
+extension), so each old tool must keep its own body for one release.
+
+### 2. The removal check uses the package version
+
+The support-level test reads `solidworks_mcp.version.__version__`. When its
+major number is above a deprecated tool's `since` major, the test fails.
+This forces the removal at 3.0.0 without a calendar.
+
+### 3. Planned tools name their queue item
+
+The planned reason becomes "planned in queue item 12 (the drawing pack)."
+for the seven left. The test checks that every planned reason names a
+queue item, so a planned tool can't be left without an owner again.
+
+### 4. Removing a tool removes everything that names it
+
+For each removed tool: its function and input model, its `tool_hints.py`
+and `support_levels.py` entries, its tests, its catalog row, and any
+"use ``" sentence in another description. A repo-wide grep for each
+name, run in the tests (the existing description check already fails on a
+backticked name that isn't registered), keeps this honest.
+
+### 5. `save_file` and `get_model_info` gain what their duplicates had
+
+`save_file` calls `_prepare_save_target` when `file_path` is given, with
+the extension taken from the active document's type (the adapter's model
+info already reports it), and gains `overwrite` (default off). This makes
+`save_file` refuse an existing file where it overwrote before; the
+CHANGELOG says so. `get_model_info` adds `size_bytes`, `created` and
+`modified` with the same `os.stat` code `get_file_properties` uses, moved
+into one helper.
+
+### 6. The verb list lives with the description standard
+
+The table goes into `docs/agents/tool-description-standard.md`, with the
+exceptions listed under it, and CONTRIBUTING.md links to it. The existing
+description-standard test gains a naming check.
+
+### 7. Version 2.1.0
+
+Removing tools that never worked is not a break for a working client, so
+the release is 2.1.0. The CHANGELOG lists the removed names under
+"Removed" and the deprecated ones under "Deprecated".
+
+### 8. `manage_design_table` is checked before it goes
+
+It is in the removal list because a design table needs Excel on the
+machine, and item 13's configuration tools give agents the same variants
+without it. That reason is not yet proven on the user's SolidWorks, so a
+live probe (task 2.0) inserts a design table on a scratch part and reads it
+back. If it works, the tool stays `planned` for item 13 and the planned
+count is eight; if not, it is removed and the finding is recorded here.
+
+### 9. Items 11 to 14 depend on this change
+
+`part-feature-depth`, `drawing-pack`, `configuration-tools` and
+`tool-discovery-mode` use the verb list, the `deprecated` level, the
+planned-reason rule and the final family list from this change. None of
+them starts until this change is merged.
+
+## Risks / Trade-offs
+
+- [A client scripted a planned tool's name] → it only ever got
+ `not_supported`; the CHANGELOG lists every removed name.
+- [`save_file` now refuses an existing file without `overwrite`] → this is
+ what `save_as` and `save_part` already do; the error names `overwrite`.
+- [Deprecation warnings add noise to replies] → one sentence, and only on
+ the eight old names.
+- [Removing a family empties a module] → `drawing_analysis.py` keeps
+ `compare_drawing_versions`; `template_management.py` keeps
+ `compare_templates`; `macro_recording.py` keeps `execute_macro`. No module
+ is emptied.
diff --git a/openspec/changes/honest-tool-list/proposal.md b/openspec/changes/honest-tool-list/proposal.md
new file mode 100644
index 00000000..c4e7864d
--- /dev/null
+++ b/openspec/changes/honest-tool-list/proposal.md
@@ -0,0 +1,102 @@
+## Why
+
+The server registers 156 tools, but 40 of them are `planned`: every call
+returns `not_supported`. A client still pays for their schemas on every
+turn, and an agent can pick one and fail. Among the 116 that work, several
+do the same job under different names (`load_part` and `open_model`,
+`get_mass_properties` and `calculate_mass_properties`), so an agent can't
+reliably pick the intended one. Glama's tool-quality review scored the
+server 2.3/5 for exactly this (issue #174). The fix is a list where every
+tool works, does one job, and is named by one verb list.
+
+## What Changes
+
+- **33 planned tools are removed.** Each either duplicates a working tool,
+ is a loop an agent can run itself, or has no SolidWorks API behind it:
+ - analysis: `analyze_geometry`, `get_material_properties`;
+ - automation: `automation_start_macro_recording`,
+ `automation_stop_macro_recording`, `batch_process_files`,
+ `create_template`, `execute_workflow`, `manage_design_table`,
+ `optimize_performance`;
+ - drawing: `add_annotation`;
+ - drawing analysis: `analyze_drawing_annotations`,
+ `analyze_drawing_comprehensive`, `analyze_drawing_dimensions`,
+ `analyze_drawing_views`, `check_drawing_compliance`,
+ `generate_drawing_report`, `validate_drawing_completeness`;
+ - export: `batch_export`;
+ - file management: `batch_file_operations`, `convert_file_format`,
+ `manage_file_properties`;
+ - macros: `analyze_macro`, `batch_execute_macros`,
+ `create_macro_library`, `optimize_macro`, `start_macro_recording`,
+ `stop_macro_recording`;
+ - sketching: `tutorial_simple_hole`;
+ - templates: `apply_template`, `batch_apply_template`,
+ `extract_template`, `list_template_library`,
+ `save_to_template_library`.
+- **The seven planned drawing tools stay planned** for the drawing pack
+ (queue item 12): `add_dimension`, `auto_dimension_view`,
+ `create_section_view`, `create_detail_view`, `update_title_block`,
+ `update_sheet_format`, `check_drawing_standards`. Their reason names that
+ item.
+- **A new support level, `deprecated`**, for a working tool replaced by
+ another. It keeps working for one minor release. Its description opens
+ "Deprecated: use ``.", and a successful result carries the same
+ sentence as `warning`. It is removed in 3.0.0.
+- **Eight stable tools are deprecated**, after their replacement gains what
+ they did:
+ - `load_part`, `load_assembly` → `open_model`;
+ - `save_part`, `save_assembly` → `save_file`, which gains the new-path
+ checks (folder exists, extension matches the document, no overwrite
+ unless asked). `save_assembly`'s `include_references` copy is
+ `pack_and_go_assembly`'s job;
+ - `calculate_mass_properties` → `get_mass_properties`;
+ - `get_file_properties` → `get_model_info`, which gains the file's size
+ and dates;
+ - `add_drawing_view` → `create_drawing_view`;
+ - `sketch_tutorial_simple_hole` → none; it is a fixed example, and its
+ description already points to the real tools.
+- **One verb list**, in CONTRIBUTING.md and the description standard, that
+ new tools follow. Stable tools that break it are listed as exceptions,
+ not renamed.
+- **BREAKING (for clients that call them):** the 33 removed tool names
+ disappear. They never did anything but return `not_supported`, so this
+ ships in 2.1.0. The eight deprecated names keep working until 3.0.0.
+
+## Capabilities
+
+### New Capabilities
+
+- `tools/tool-deprecation`: a deprecated tool keeps working, names its
+ replacement in its description and its results, and is removed at the
+ next major release.
+- `tools/tool-naming`: one verb per meaning, checked for new tools.
+
+### Modified Capabilities
+
+- `tools/support-levels`: a fifth level, `deprecated`; the levels check
+ allows only the seven drawing tools to be `planned`, each naming the
+ queue item that builds it.
+- `tools/file-saving`: `save_file` checks a new path the way `save_part`
+ did.
+- `tools/document-inspection`: `get_model_info` reports the file's size and
+ dates.
+
+## Impact
+
+- **No COM or adapter code changes.** Removed tools have no adapter
+ method; deprecated tools already call the adapter method their
+ replacement calls. `get_model_info`'s size and dates come from the file
+ on disk (`os.stat`), as `get_file_properties` reads them today.
+- **Tools:** `analysis.py`, `automation.py`, `drawing.py`,
+ `drawing_analysis.py`, `export.py`, `file_management.py`,
+ `macro_recording.py`, `sketching.py`, `template_management.py` lose the
+ removed tools and their input models. `support_levels.py`,
+ `tool_hints.py` and `tool_boundary.py` gain `deprecated`.
+- **Docs:** the tool catalog pages, the README's counts and progress bars
+ (regenerated), the agent skill's tool list, CHANGELOG, CONTRIBUTING.md.
+- **Tests:** each removed tool's tests go; the support-level and description
+ checks gain the new rules. No live run is needed for removals; the two
+ replacements that gain behaviour (`save_file`, `get_model_info`) get a
+ live check in one bundle.
+- Issue #174 closes with this change. The VBA generators are left to
+ item 14's optional toolsets, not merged here.
diff --git a/openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md b/openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md
new file mode 100644
index 00000000..a8dc0c9c
--- /dev/null
+++ b/openspec/changes/honest-tool-list/specs/tools/document-inspection/spec.md
@@ -0,0 +1,17 @@
+## ADDED Requirements
+
+### Requirement: Model info includes the file's details
+`get_model_info` SHALL report, besides what it reports today, the active
+document's file size in bytes and its created and modified times, read
+from the file on disk. For a document never saved, they SHALL be `null`.
+
+#### Scenario: A saved part
+- **WHEN** a part saved to disk is active and an agent calls
+ `get_model_info`
+- **THEN** the reply has `size_bytes` above 0 and `created` and `modified`
+ times, as `get_file_properties` reports them
+
+#### Scenario: A new, unsaved part
+- **WHEN** a part never saved is active
+- **THEN** `size_bytes`, `created` and `modified` are `null`, and the call
+ succeeds
diff --git a/openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md b/openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md
new file mode 100644
index 00000000..ede70f1e
--- /dev/null
+++ b/openspec/changes/honest-tool-list/specs/tools/file-saving/spec.md
@@ -0,0 +1,22 @@
+## ADDED Requirements
+
+### Requirement: save_file checks a new path before writing
+When `save_file` is given `file_path`, it SHALL check, before calling
+SolidWorks, that the folder exists and is writable, that the extension
+matches the active document's type (`.sldprt`, `.sldasm`, `.slddrw`), and
+that no file is there unless `overwrite` is on. A failed check SHALL be an
+`invalid_input` error that leaves the disk unchanged.
+
+#### Scenario: A part saved to a missing folder
+- **WHEN** the active document is a part and `save_file` is called with
+ `C:/no/such/folder/bracket.sldprt`
+- **THEN** the call fails with `invalid_input` naming the folder, and
+ SolidWorks is not asked to save
+
+#### Scenario: The wrong extension
+- **WHEN** the active document is an assembly and `file_path` ends `.sldprt`
+- **THEN** the call fails with `invalid_input` naming `.sldasm`
+
+#### Scenario: Saving in place
+- **WHEN** `save_file` is called with no `file_path`
+- **THEN** the document is saved to its own path, as before
diff --git a/openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md b/openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md
new file mode 100644
index 00000000..a485944f
--- /dev/null
+++ b/openspec/changes/honest-tool-list/specs/tools/support-levels/spec.md
@@ -0,0 +1,33 @@
+## MODIFIED Requirements
+
+### Requirement: One support level per tool
+
+Every registered tool SHALL have exactly one support level, `stable`, `beta`, `experimental`, `planned` or `deprecated`, recorded in one table, with a one-line reason for every level other than `stable`. A `deprecated` tool's reason SHALL name its replacement (or say there is none) and the version it was deprecated in.
+
+#### Scenario: A new tool without a level
+- **WHEN** a tool is registered that the table does not list
+- **THEN** the support-level check fails and names the tool
+
+#### Scenario: A listed tool that no longer exists
+- **WHEN** the table lists a name that no registered tool has
+- **THEN** the check fails and names it
+
+#### Scenario: A deprecated tool without a replacement named
+- **WHEN** a tool is `deprecated` and its entry names neither a registered replacement nor "no replacement"
+- **THEN** the check fails and names the tool
+
+### Requirement: Levels are consistent with the code
+
+The check SHALL fail when a level contradicts what the code shows. A `planned` tool's reason SHALL name the queue item that builds it.
+
+#### Scenario: Planned means not implemented
+- **WHEN** a tool is `planned`
+- **THEN** its description says "Not available yet", no tool outside `planned` says so, and its reason names a queue item
+
+#### Scenario: Stable means checked live
+- **WHEN** a tool is `stable`
+- **THEN** at least one test under `tests/live/` calls it by name
+
+#### Scenario: After the clean-up
+- **WHEN** the levels are counted after this change
+- **THEN** exactly seven tools are `planned`, all drawing tools, each naming queue item 12
diff --git a/openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md b/openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md
new file mode 100644
index 00000000..f1a7307f
--- /dev/null
+++ b/openspec/changes/honest-tool-list/specs/tools/tool-deprecation/spec.md
@@ -0,0 +1,42 @@
+## Purpose
+
+A tool replaced by another keeps working for one minor release, and says
+what replaced it, so a client can move without breaking.
+
+## ADDED Requirements
+
+### Requirement: A deprecated tool keeps working and names its replacement
+A tool at the `deprecated` level SHALL behave as before. Its description
+SHALL open with "Deprecated: use ``." (or "Deprecated: no
+replacement." when there is none), and a successful result SHALL carry that
+sentence as `warning`.
+
+#### Scenario: Calling a deprecated tool
+- **WHEN** an agent calls `load_part` with a valid part path
+- **THEN** the part opens as before, and the result's `warning` is
+ "Deprecated: use `open_model`."
+
+#### Scenario: Reading its description
+- **WHEN** a client lists the tools
+- **THEN** `load_part`'s description starts "Deprecated: use `open_model`."
+ and its tags include `level:deprecated`
+
+### Requirement: A replacement covers what it replaces
+A tool SHALL be deprecated only when its replacement accepts every input
+the deprecated tool accepted, or the description names the other tool
+that does the rest.
+
+#### Scenario: save_assembly's reference copy
+- **WHEN** `save_assembly` is deprecated in favour of `save_file`
+- **THEN** its description says to use `pack_and_go_assembly` for a copy
+ with the referenced parts
+
+### Requirement: Deprecated tools are removed at the next major release
+The support-level check SHALL fail when the package's major version is
+higher than the one a tool was deprecated in and the tool is still
+registered.
+
+#### Scenario: Releasing 3.0.0
+- **WHEN** the version is 3.0.0 and `load_part` (deprecated in 2.1.0) is
+ still registered
+- **THEN** the check fails and names `load_part`
diff --git a/openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md b/openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md
new file mode 100644
index 00000000..bf490f23
--- /dev/null
+++ b/openspec/changes/honest-tool-list/specs/tools/tool-naming/spec.md
@@ -0,0 +1,34 @@
+## Purpose
+
+Tool names use one verb per meaning, so an agent can guess a tool's name
+and tell two tools apart from their names alone.
+
+## ADDED Requirements
+
+### Requirement: One verb per meaning
+A tool's name SHALL start with a verb from the list in
+`docs/agents/tool-description-standard.md`:
+
+| Verb | Meaning |
+| --- | --- |
+| `create_` | makes a new document, or a new feature built from a sketch or acting on the whole body (extrusion, rib, hole, shell) |
+| `add_` | adds an entity to an open sketch or a drawing, or treats edges or faces of an existing body (fillet, chamfer, draft, thread) |
+| `pattern_`, `mirror_` | repeats existing features |
+| `sketch_` | an operation on the open sketch's entities (offset, mirror, pattern, convert) |
+| `get_` | reads one thing |
+| `list_` | reads a collection |
+| `set_` | changes one value |
+| `open_`, `save_`, `close_`, `export_` | file operations |
+| `check_`, `verify_`, `measure_`, `compare_` | read-only checks |
+
+Names already registered that break the list SHALL be listed as
+exceptions in the same file, and the check SHALL fail on any other name
+that breaks it.
+
+#### Scenario: A new tool with an unlisted verb
+- **WHEN** a tool named `make_hole` is registered
+- **THEN** the naming check fails and names the tool and the verb list
+
+#### Scenario: An existing exception
+- **WHEN** `insert_component` is registered
+- **THEN** the check passes because it is a listed exception
diff --git a/openspec/changes/honest-tool-list/tasks.md b/openspec/changes/honest-tool-list/tasks.md
new file mode 100644
index 00000000..24836a84
--- /dev/null
+++ b/openspec/changes/honest-tool-list/tasks.md
@@ -0,0 +1,48 @@
+## 1. The deprecated level
+
+- [ ] 1.1 `SupportLevel.DEPRECATED` and `Support.since`; `warning()` gives "Deprecated: use ``." or "Deprecated: no replacement."; tests
+- [ ] 1.2 `ToolRegistrar`: the description opening and success `warning` for deprecated tools (same path as beta); tests
+- [ ] 1.3 Support-level test: a deprecated entry names a registered replacement or "no replacement"; fails when the major version is above `since`'s; every planned reason names a queue item; tests for each rule
+- [ ] 1.4 Progress generator: deprecated tools counted on their own, left out of the coverage bars; tests
+
+## 2. Remove the 33 planned tools
+
+- [ ] 2.0 Check `manage_design_table` before removing it: does `IModelDoc2.InsertFamilyTableNew` work on the user's machine (it needs Excel), and is there a read path (`IDesignTable`) without Excel? Record the finding in design.md. If design tables work, keep the tool `planned` for queue item 13 (`configuration-tools`) and add it there; otherwise remove it with the rest. Its live probe joins this change's live bundle (7.1), not a separate run
+- [ ] 2.1 Analysis, automation, drawing (`add_annotation`) and export: remove the tools, input models, hints, levels and tests
+- [ ] 2.2 Drawing analysis (six), file management (three), macros (six), sketching (`tutorial_simple_hole`), templates (five): the same
+- [ ] 2.3 Remove every "use ``" sentence from other descriptions; a test that no description names an unregistered tool
+- [ ] 2.4 The seven planned drawing tools' reason: "planned in queue item 12 (the drawing pack)."
+
+## 3. Replacements gain what they replace
+
+- [ ] 3.1 `save_file`: `overwrite` input, `_prepare_save_target` on a new path with the extension from the active document's type; tests for a missing folder, the wrong extension, an existing file, and in place
+- [ ] 3.2 `get_model_info`: `size_bytes`, `created`, `modified` from one `os.stat` helper shared with `get_file_properties`; tests for saved and unsaved
+- [ ] 3.3 Mock adapter: the model info it returns carries a path that the tests can stat, and an unsaved document has none; tests
+
+## 4. Deprecate the eight stable duplicates
+
+- [ ] 4.1 Levels: `load_part`, `load_assembly` → `open_model`; `save_part`, `save_assembly` → `save_file`; `calculate_mass_properties` → `get_mass_properties`; `get_file_properties` → `get_model_info`; `add_drawing_view` → `create_drawing_view`; `sketch_tutorial_simple_hole` → no replacement; all `since` 2.1.0
+- [ ] 4.2 `save_assembly`'s description names `pack_and_go_assembly` for `include_references`
+- [ ] 4.3 Replacements' descriptions drop "for X, use ``" pointers; tests
+
+## 5. Verb list
+
+- [ ] 5.1 The verb table and its exceptions in `docs/agents/tool-description-standard.md`; CONTRIBUTING.md links it
+- [ ] 5.2 The naming check in the description-standard test; a test that an unlisted verb fails
+
+## 6. Docs
+
+- [ ] 6.1 Tool catalog pages: removed rows gone, deprecated rows marked
+- [ ] 6.2 The agent skill's tool lists and `errors-and-limits.md`
+- [ ] 6.3 README counts and progress bars regenerated (`python -m solidworks_mcp.progress.generate`)
+- [ ] 6.4 CHANGELOG (2.1.0): Removed (the 33 names), Deprecated (the eight), Changed (`save_file` refuses an existing file without `overwrite`; `get_model_info` adds file details)
+
+## 7. Live bundle (one set, run together, then fixes one by one)
+
+- [ ] 7.1 Live tests: `save_file` to a new path, a missing folder and an existing file; `get_model_info` on a saved and a new part; one deprecated tool's `warning`; the design-table probe (task 2.0): insert one on a scratch part and read it back
+- [ ] 7.2 Hand the user the bundle; fix each failure afterwards, one at a time
+
+## 8. Finish
+
+- [ ] 8.1 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`
+- [ ] 8.2 Sign-off, PR (no attribution) closing #174, archive, the queue updated
diff --git a/openspec/changes/part-feature-depth/.openspec.yaml b/openspec/changes/part-feature-depth/.openspec.yaml
new file mode 100644
index 00000000..55ab199b
--- /dev/null
+++ b/openspec/changes/part-feature-depth/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-12
diff --git a/openspec/changes/part-feature-depth/design.md b/openspec/changes/part-feature-depth/design.md
new file mode 100644
index 00000000..4084b8ab
--- /dev/null
+++ b/openspec/changes/part-feature-depth/design.md
@@ -0,0 +1,108 @@
+## Context
+
+The feature tools live in `tools/modeling.py` and call adapter methods
+implemented in `adapters/solidworks/features.py` (real) and
+`mock_adapter.py`. Faces and edges are already picked by points:
+`create_reference_plane`'s `face_point`, `select_face_edges`, and
+`face_selection.py`'s helpers, which rebuild first and pass a `VT_DISPATCH`
+null callout (runbook #11, #13). `pattern_circular` and `mirror_feature`
+already check the volume change, and the extrude tools report
+`measured_change`.
+
+The COM calls, from the type library index (`lookup_api_method`):
+
+| Tool | COM call |
+| --- | --- |
+| `create_hole` | `IFeatureManager.HoleWizard5` (27 arguments) |
+| `add_cosmetic_thread` | `IFeatureManager.InsertCosmeticThread3(Standard, StandardType, Size, Diameter, EndType, Depth, Note)` |
+| `pattern_linear` | `IFeatureManager.FeatureLinearPattern5` (22 arguments) |
+| `create_shell` | `IModelDoc2.InsertFeatureShell(Thickness, Outward)` |
+| `add_draft` | `IFeatureManager.InsertMultiFaceDraft(Angle, FlipDir, EdgeDraft, PropType, IsStepDraft, IsBodyDraft)` |
+| `create_rib` | `IFeatureManager.InsertRib(Is2Sided, ReverseThicknessDir, Thickness, ReferenceEdgeIndex, ReverseMaterialDir, IsDrafted, DraftOutward, DraftAngle, IsNormToSketch, IsDraftedFromWall)` |
+| `sketch_convert_entities` | `ISketchManager.SketchUseEdge3(Chain, InnerLoops)` |
+
+## Goals / Non-Goals
+
+**Goals:**
+- The six features and convert-entities, each in one call, with points
+ for every pick.
+- Each solid tool proves itself by the volume change, as the existing ones
+ do.
+
+**Non-Goals:**
+- Several holes in one call: one hole per call, then `pattern_linear` or
+ `pattern_circular`. Editing a Hole Wizard position sketch is a second
+ feature's worth of work.
+- Every Hole Wizard standard and fastener type: ISO and ANSI inch, four
+ hole types, a fixed size list each.
+- Variable-pitch patterns, step draft, drafted ribs, multi-thickness
+ shells.
+- Sheet metal (queue item 15).
+
+## Decisions
+
+### 1. Points for every pick, through `face_selection.py`
+
+Every face or edge input is a point in millimetres, as the existing tools
+take, resolved by the shared helpers (rebuild once, `SelectByID2` with
+`FACE` or `EDGE` and the null callout, read the selected object's type).
+Marks: the shell's faces to remove and the draft's faces are mark 1 (the
+draft's neutral face is mark 2), set through the helpers' `append`/`mark`
+arguments. No tool takes face or edge names; agents don't know them.
+
+### 2. `HoleWizard5` is mapped by a live diagnostic first
+
+`HoleWizard5` takes integer standard, fastener-type and end-condition
+codes, a size string, and twelve type-dependent values. The first task is
+a live diagnostic (run in the bundle, not before) that makes one hole of
+each of the four types for ISO and ANSI at one size, with the codes from
+the `swWzdHoleStandards_e` and `swWzdHoleStandardFastenerTypes_e` enums,
+and records which arguments SolidWorks honours. The tool's table of
+`(hole_type, standard) → (StandardIndex, FastenerTypeIndex)` and its size
+lists come from that run. Until it passes, `create_hole` is `beta`.
+
+The hole sits where the face was picked: `HoleWizard5` places the hole at
+the selection point of the selected face.
+
+### 3. `pattern_linear` mirrors `pattern_circular`
+
+Same input style (`features`, plus per-direction direction, count and
+spacing), same adapter flow: select the features (mark 4), the direction
+edge or axis (mark 1, and mark 2 for direction 2), call
+`FeatureLinearPattern5` with `GeometryPattern` off and the
+`CtrlByNum`/offset arguments at their defaults, then check the volume.
+
+### 4. One success rule
+
+A solid tool succeeds when its feature exists and the volume moved. When
+SolidWorks returns a feature but the volume didn't change, the tool deletes
+the feature it made (the same path `delete_feature` uses) and fails, so a
+failure never leaves a no-op feature in the tree. `add_cosmetic_thread` is
+the exception: its check is the thread feature in the tree and an
+unchanged volume.
+
+### 5. `sketch_convert_entities` returns registry ids
+
+The sketch adapter keeps a registry of entities it created so other tools
+can name them. `SketchUseEdge3` returns only a Boolean, so the adapter
+reads the sketch's segments before and after, registers the new ones, and
+sets them to construction when asked (`ISketchSegment.ConstructionGeometry`).
+
+### 6. Names follow the verb list
+
+`create_` for features built from a sketch or acting on the body (hole,
+shell, rib), `add_` for treating existing faces and edges (draft, thread),
+`pattern_` and `sketch_` as listed in the honest-tool-list change's verb
+table. This change depends on that change being merged first.
+
+## Risks / Trade-offs
+
+- [`HoleWizard5`'s codes differ by SolidWorks version] → the diagnostic
+ runs on the user's SolidWorks 2026; the tool stays `beta` with that as
+ its reason until checked on another version.
+- [A point on an edge also lies on two faces] → face picks use `FACE`, edge
+ picks `EDGE`; the helpers already handle this for chamfers.
+- [Seven new tools grow the tool list] → item 10 removes 33 first, and
+ item 14's toolsets can turn families off.
+- [Shell or draft fails on a body with fillets] → SolidWorks' own error is
+ passed on through the error classifier; no retry.
diff --git a/openspec/changes/part-feature-depth/proposal.md b/openspec/changes/part-feature-depth/proposal.md
new file mode 100644
index 00000000..a57fc38e
--- /dev/null
+++ b/openspec/changes/part-feature-depth/proposal.md
@@ -0,0 +1,78 @@
+## Why
+
+An agent can extrude, cut, revolve, sweep, loft, fillet, chamfer and
+pattern around an axis, but it can't make the features most real parts
+need next: a standard tapped or counterbored hole, a thread, a row of
+features, a hollowed body, drafted walls for moulding, or a rib. The
+closest comparable server leads with holes and threads, so this is where an
+agent comparing the two finds us short. An agent working without these
+draws a circle at a guessed size and cuts it, which gives no thread data,
+no standard callout in a drawing, and a part that doesn't match the
+fastener. Issue #105 (convert entities) was hit live: an agent couldn't
+sketch on an existing edge and cut in the wrong place.
+
+## What Changes
+
+- **`create_hole`**: a Hole Wizard hole (simple, counterbored,
+ countersunk or tapped) of a standard size (`M6`, `#10`, ...) on a flat
+ face, at a point on that face, blind to a depth or through all.
+- **`add_cosmetic_thread`**: a cosmetic thread on a cylindrical edge picked
+ by a point, to a standard size and depth (or through), so a drawing shows
+ the thread callout.
+- **`pattern_linear`**: repeats features along one or two directions given
+ by edges or axes, with count and spacing, like `pattern_circular`.
+- **`create_shell`**: hollows the active body to a wall thickness, with the
+ faces to remove picked by points, inward or outward.
+- **`add_draft`**: drafts faces picked by points by an angle against a
+ neutral plane or face.
+- **`create_rib`**: a rib from an open sketch, of a thickness, on one or
+ both sides of the sketch.
+- **`sketch_convert_entities`**: projects edges (picked by points) or a
+ face's outline into the open sketch, as normal or construction
+ geometry, and returns the new entities' ids (#105).
+- Each solid-changing tool replies with `measured_change`, as the extrude
+ tools do, and fails when the volume does not change.
+
+## Capabilities
+
+### New Capabilities
+
+- `tools/hole-wizard`: `create_hole` makes a standard hole at a point on a
+ flat face.
+- `tools/cosmetic-thread`: `add_cosmetic_thread` adds a thread to a
+ cylindrical edge.
+- `tools/shell-draft-rib`: `create_shell`, `add_draft` and `create_rib`
+ shape an existing body.
+- `tools/sketch-convert-entities`: `sketch_convert_entities` copies model
+ edges into the open sketch.
+
+### Modified Capabilities
+
+- `tools/feature-patterns`: `pattern_linear` joins `pattern_circular` and
+ `mirror_feature` under the volume-change rule.
+- `tools/measured-feature-change`: the new solid tools report
+ `measured_change`.
+
+## Impact
+
+- **COM and adapter code, all on the connect thread inside
+ `_handle_com_operation`:**
+ - `adapters/solidworks/features.py`: `IFeatureManager.HoleWizard5`,
+ `InsertCosmeticThread3`, `FeatureLinearPattern5`,
+ `InsertMultiFaceDraft`, `InsertRib`, and `IModelDoc2.InsertFeatureShell`;
+ - `adapters/solidworks/sketch.py`: `ISketchManager.SketchUseEdge3`;
+ - face and edge picks through `face_selection.py` (`ForceRebuild3`
+ first, `SelectByID2` with a `VT_DISPATCH` null callout: runbook #11,
+ #13).
+ - Seven new adapter methods through `base.py`, `circuit_breaker.py`,
+ `connection_pool.py` and `mock_adapter.py`.
+- **Tools:** `modeling.py` (six tools), `sketching.py`
+ (`sketch_convert_entities`), `tool_hints.py`, `support_levels.py`.
+- **Docs:** tool catalog pages, the agent skill's workflow notes (hole
+ before thread, convert then cut), `docs/planning/solidworks-api-coverage.md`
+ section 3.7, CHANGELOG, regenerated progress bars.
+- **Live tests:** one bundle at the end; `HoleWizard5`'s 27 arguments are
+ checked live before the tool's inputs are fixed (design decision 2).
+- Closes #105. Sheet metal (#57) is queue item 15, not this change.
+- **Depends on the honest-tool-list change (queue item 10)**, merged
+ first: the tool names follow its verb list.
diff --git a/openspec/changes/part-feature-depth/specs/tools/cosmetic-thread/spec.md b/openspec/changes/part-feature-depth/specs/tools/cosmetic-thread/spec.md
new file mode 100644
index 00000000..c990c4e3
--- /dev/null
+++ b/openspec/changes/part-feature-depth/specs/tools/cosmetic-thread/spec.md
@@ -0,0 +1,28 @@
+## Purpose
+
+`add_cosmetic_thread` marks a cylindrical edge as threaded, so the thread
+shows in drawings without modelling its helix.
+
+## ADDED Requirements
+
+### Requirement: A thread on a circular edge
+`add_cosmetic_thread` SHALL take `edge_point`, `[x, y, z]` in millimetres
+on a circular edge of the active part, `standard` (`iso` or `ansi_inch`),
+`size`, and either `depth` in millimetres or `through: true`. It SHALL add
+one cosmetic thread feature on that edge and reply with its name. The
+part's volume SHALL be unchanged.
+
+#### Scenario: A thread on a shaft end
+- **WHEN** a Ø10 mm shaft is active and `add_cosmetic_thread` is called
+ with a point on its end edge, `iso`, `M10` and `depth` 15
+- **THEN** a cosmetic thread feature appears under the shaft's feature,
+ and the volume is unchanged
+
+### Requirement: The edge must be circular
+When `edge_point` is not on a circular edge, `add_cosmetic_thread` SHALL
+fail with `invalid_input`, name the point, and add nothing.
+
+#### Scenario: A straight edge
+- **WHEN** `edge_point` is on a straight edge of a block
+- **THEN** the call fails with `invalid_input` saying the edge is not
+ circular
diff --git a/openspec/changes/part-feature-depth/specs/tools/feature-patterns/spec.md b/openspec/changes/part-feature-depth/specs/tools/feature-patterns/spec.md
new file mode 100644
index 00000000..a7853899
--- /dev/null
+++ b/openspec/changes/part-feature-depth/specs/tools/feature-patterns/spec.md
@@ -0,0 +1,35 @@
+## MODIFIED Requirements
+
+### Requirement: A pattern or mirror succeeds when the volume changes
+
+`pattern_circular`, `pattern_linear` and `mirror_feature` SHALL succeed when the part's volume
+changes, up or down, and SHALL fail when it doesn't change. The reply SHALL
+include the volume before and after.
+
+#### Scenario: A ring of holes
+- **WHEN** an agent patterns a Ø6 mm through-hole in a 10 mm plate 6 times around an axis, with every instance on the plate
+- **THEN** the call succeeds and the volume falls by 5 × π·3²·10 = 1,413.7 mm³ within 0.1 %
+
+#### Scenario: A row of holes
+- **WHEN** an agent patterns a Ø6 mm through-hole in a 10 mm plate 4 times at 15 mm along a straight edge of the plate
+- **THEN** the call succeeds and the volume falls by 3 × π·3²·10 = 848.2 mm³ within 0.1 %
+
+#### Scenario: A mirrored cut
+- **WHEN** an agent mirrors a cut about a plane, and the mirrored cut lands on the body
+- **THEN** the call succeeds and the volume falls by the cut's volume
+
+#### Scenario: Nothing patterned
+- **WHEN** a pattern's instances all land off the body, so the volume is unchanged
+- **THEN** the call fails and says the pattern produced no geometry
+
+## ADDED Requirements
+
+### Requirement: A linear pattern along one or two directions
+`pattern_linear` SHALL take `features` (at least one name), `direction_1`
+(an edge picked by a point, or an axis name), `count_1` (at least 2) and
+`spacing_1` in millimetres, and optionally `direction_2`, `count_2` and
+`spacing_2` for a grid, plus `reverse_1` and `reverse_2`.
+
+#### Scenario: A 3 × 2 grid
+- **WHEN** a hole is patterned 3 times at 15 mm along one edge and 2 times at 20 mm along the other
+- **THEN** six holes exist in all and the volume falls by five holes' volume
diff --git a/openspec/changes/part-feature-depth/specs/tools/hole-wizard/spec.md b/openspec/changes/part-feature-depth/specs/tools/hole-wizard/spec.md
new file mode 100644
index 00000000..a34f793f
--- /dev/null
+++ b/openspec/changes/part-feature-depth/specs/tools/hole-wizard/spec.md
@@ -0,0 +1,45 @@
+## Purpose
+
+`create_hole` makes a standard Hole Wizard hole at a point on a flat face,
+so the hole matches its fastener and a drawing can call it out.
+
+## ADDED Requirements
+
+### Requirement: A standard hole at a point on a face
+`create_hole` SHALL take `hole_type` (`simple`, `counterbore`,
+`countersink` or `tapped`), `standard` (`iso` or `ansi_inch`), `size` (for
+example `M6`, `#10`), `end_condition` (`blind` or `through_all`), `depth`
+in millimetres for `blind`, and `position`, `[x, y, z]` in millimetres on a
+flat face of the active part. It SHALL make one Hole Wizard feature at that
+point, normal to the face, and reply with the feature's name and
+`measured_change`.
+
+#### Scenario: A through M6 counterbore
+- **WHEN** a 10 mm plate is active and `create_hole` is called with
+ `counterbore`, `iso`, `M6`, `through_all` and a point on the top face
+- **THEN** one Hole Wizard feature appears in the tree, the volume falls,
+ and the reply names the feature
+
+#### Scenario: A blind tapped hole
+- **WHEN** `create_hole` is called with `tapped`, `iso`, `M5`, `blind` and
+ `depth` 8
+- **THEN** the hole is 8 mm deep (measured from the volume change within
+ 1 %), and its feature carries the M5 thread data
+
+### Requirement: Bad hole inputs fail before SolidWorks
+`create_hole` SHALL fail with `invalid_input` when `size` is not a size of
+the given `standard` and `hole_type`, when `blind` has no `depth`, or when
+`position` is not three numbers; nothing SHALL be added.
+
+#### Scenario: A size from the wrong standard
+- **WHEN** `standard` is `iso` and `size` is `#10`
+- **THEN** the call fails with `invalid_input` listing the ISO sizes
+
+### Requirement: The point must be on a flat face
+When `position` is not on a flat face of the active part, `create_hole`
+SHALL fail with `invalid_input`, name the point, and add nothing.
+
+#### Scenario: A point in the air
+- **WHEN** `position` is 50 mm above the plate
+- **THEN** the call fails with `invalid_input` and the feature tree is
+ unchanged
diff --git a/openspec/changes/part-feature-depth/specs/tools/measured-feature-change/spec.md b/openspec/changes/part-feature-depth/specs/tools/measured-feature-change/spec.md
new file mode 100644
index 00000000..47d63dd1
--- /dev/null
+++ b/openspec/changes/part-feature-depth/specs/tools/measured-feature-change/spec.md
@@ -0,0 +1,13 @@
+## ADDED Requirements
+
+### Requirement: The new solid feature tools report the measured change
+On success, `create_hole`, `create_shell`, `add_draft`, `create_rib` and
+`pattern_linear` SHALL include the same `measured_change` block as
+`create_extrusion`, under the same best-effort rule. `create_hole`,
+`create_shell` and `create_rib` SHALL fail, removing nothing, when the
+volume is unchanged.
+
+#### Scenario: A hole off the body
+- **WHEN** SolidWorks accepts a hole that removes no material
+- **THEN** the call fails, says the hole changed no volume, and the hole
+ feature is deleted so the tree is as before
diff --git a/openspec/changes/part-feature-depth/specs/tools/shell-draft-rib/spec.md b/openspec/changes/part-feature-depth/specs/tools/shell-draft-rib/spec.md
new file mode 100644
index 00000000..c5bc04b0
--- /dev/null
+++ b/openspec/changes/part-feature-depth/specs/tools/shell-draft-rib/spec.md
@@ -0,0 +1,54 @@
+## Purpose
+
+`create_shell`, `add_draft` and `create_rib` shape an existing body: hollow
+it, taper its walls, or stiffen it, each picked by points the agent already
+knows.
+
+## ADDED Requirements
+
+### Requirement: Shell to a wall thickness
+`create_shell` SHALL take `thickness` in millimetres, `remove_face_points`
+(a list of `[x, y, z]` points, each on a face to remove; may be empty for a
+closed hollow body) and `outward` (default off). It SHALL make one shell
+feature and reply with its name and `measured_change`.
+
+#### Scenario: An open box
+- **WHEN** a 40 × 40 × 20 mm block is active and `create_shell` is called
+ with `thickness` 2 and a point on the top face
+- **THEN** the volume falls to 40·40·20 − 36·36·18 = 8,672 mm³ within 0.5 %
+
+#### Scenario: Too thick
+- **WHEN** `thickness` is more than half the block's smallest size
+- **THEN** the call fails, says SolidWorks could not build the shell, and
+ the tree is unchanged
+
+### Requirement: Draft faces against a neutral plane
+`add_draft` SHALL take `angle` in degrees (above 0 and below 90),
+`neutral_point` (a point on the neutral face) or `neutral_plane` (a plane
+name), exactly one of them, and `face_points` (points on the faces to
+draft, at least one). It SHALL make one draft feature and reply with its
+name and `measured_change`.
+
+#### Scenario: Drafting a block's sides
+- **WHEN** a block's four side faces are drafted 5° from its bottom face
+- **THEN** one draft feature appears and the volume changes
+
+#### Scenario: Both neutral inputs
+- **WHEN** `neutral_point` and `neutral_plane` are both given
+- **THEN** the call fails with `invalid_input`
+
+### Requirement: A rib from an open sketch
+`create_rib` SHALL take `sketch` (the name of an open-profile sketch),
+`thickness` in millimetres, `both_sides` (default on) and `flip_material`
+(default off). It SHALL make one rib feature and reply with its name and
+`measured_change`.
+
+#### Scenario: A rib between two walls
+- **WHEN** a sketch line runs between two walls of a shelled box and
+ `create_rib` is called with `thickness` 3
+- **THEN** one rib feature appears and the volume rises
+
+#### Scenario: A rib that reaches nothing
+- **WHEN** the rib's sketch does not reach the body in its material
+ direction
+- **THEN** the call fails and says the rib added no material
diff --git a/openspec/changes/part-feature-depth/specs/tools/sketch-convert-entities/spec.md b/openspec/changes/part-feature-depth/specs/tools/sketch-convert-entities/spec.md
new file mode 100644
index 00000000..7cf8f705
--- /dev/null
+++ b/openspec/changes/part-feature-depth/specs/tools/sketch-convert-entities/spec.md
@@ -0,0 +1,35 @@
+## Purpose
+
+`sketch_convert_entities` copies model edges into the open sketch, so a new
+feature can be drawn on the real geometry instead of a guessed copy of it.
+
+## ADDED Requirements
+
+### Requirement: Edges or a face outline into the open sketch
+`sketch_convert_entities` SHALL take exactly one of `edge_points` (points
+on edges of the active part) and `face_point` (a point on a face, whose
+outer loop is converted), plus `construction` (default off). With a sketch
+open, it SHALL add one sketch entity per converted edge and reply with the
+new entities' ids, usable by `add_sketch_constraint` and
+`add_sketch_dimension`.
+
+#### Scenario: A face outline
+- **WHEN** a sketch is open on a plate's top face and
+ `sketch_convert_entities` is called with a point on that face
+- **THEN** four lines are added, one per edge of the face, and their ids
+ are returned
+
+#### Scenario: Construction geometry
+- **WHEN** `construction` is on
+- **THEN** the converted entities are construction geometry, and a cut
+ from the sketch uses only the other entities
+
+### Requirement: No sketch or no edge fails
+`sketch_convert_entities` SHALL fail with `invalid_input` when no sketch is
+open, or when a point is not on an edge (or face) of the active part,
+naming the point; nothing SHALL be added.
+
+#### Scenario: No sketch open
+- **WHEN** no sketch is open
+- **THEN** the call fails with `invalid_input` saying to open a sketch with
+ `create_sketch` first
diff --git a/openspec/changes/part-feature-depth/tasks.md b/openspec/changes/part-feature-depth/tasks.md
new file mode 100644
index 00000000..1bdaab60
--- /dev/null
+++ b/openspec/changes/part-feature-depth/tasks.md
@@ -0,0 +1,46 @@
+## 1. Shared pieces
+
+- [ ] 1.1 `face_selection.py`: pick a face or edge by point with a mark and append, and report whether it is flat, circular or neither; tests
+- [ ] 1.2 Feature tools' shared success rule: the feature exists and the volume moved, else delete the feature and fail; tests
+
+## 2. Linear pattern
+
+- [ ] 2.1 `PatternLinearInput`, `pattern_linear` tool, hints, level; tests
+- [ ] 2.2 Adapter interface `pattern_linear` in `base.py`, `circuit_breaker.py`, `connection_pool.py`; tests
+- [ ] 2.3 Real adapter: select features and directions, `FeatureLinearPattern5`, volume check; tests
+- [ ] 2.4 Mock adapter: a pattern's volume change from count and the seed's volume; tests
+
+## 3. Shell, draft, rib
+
+- [ ] 3.1 Inputs and tools `create_shell`, `add_draft`, `create_rib`; the one-of rule for the neutral face; tests
+- [ ] 3.2 Adapter interface for the three, through every layer; tests
+- [ ] 3.3 Real adapter: `InsertFeatureShell`, `InsertMultiFaceDraft`, `InsertRib`, with the picks and marks; tests
+- [ ] 3.4 Mock adapter: the open-box shell volume, a draft's volume change, a rib's volume; tests
+
+## 4. Holes and threads
+
+- [ ] 4.1 `CreateHoleInput` with the hole type, standard, size table and end condition; `invalid_input` for a size outside the table and a blind hole with no depth; tests
+- [ ] 4.2 `AddCosmeticThreadInput` and tool; tests
+- [ ] 4.3 Adapter interface for both, through every layer; tests
+- [ ] 4.4 Real adapter: `HoleWizard5` from the code table (to be confirmed by 6.1), `InsertCosmeticThread3` on a circular edge; tests
+- [ ] 4.5 Mock adapter: a hole's volume from its size and depth; a thread leaves the volume; tests
+
+## 5. Convert entities
+
+- [ ] 5.1 `SketchConvertEntitiesInput` (one of `edge_points`, `face_point`; `construction`) and tool; tests
+- [ ] 5.2 Adapter interface through every layer; tests
+- [ ] 5.3 Real adapter: picks, `SketchUseEdge3`, new segments registered, construction set; tests
+- [ ] 5.4 Mock adapter: a face's four edges become four registered lines; tests
+
+## 6. Live bundle (one set, run together, then fixes one by one)
+
+- [ ] 6.1 Hole Wizard diagnostic: one hole of each type for ISO and ANSI, recording which codes SolidWorks honoured
+- [ ] 6.2 Live tests for each tool's spec scenarios: the 3 × 2 grid, the open box, drafted sides, a rib in the box, an M6 counterbore and M5 tapped hole, an M10 thread, a converted face outline cut through; each failure case
+- [ ] 6.3 Hand the user the bundle; fix each failure afterwards, one at a time; move `create_hole` to stable when the diagnostic and its tests pass
+
+## 7. Docs and finish
+
+- [ ] 7.1 Tool catalog pages, the agent skill's notes (one hole per call then pattern; thread after hole; convert then cut), `docs/planning/solidworks-api-coverage.md` section 3.7
+- [ ] 7.2 CHANGELOG (Added), progress bars regenerated
+- [ ] 7.3 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`
+- [ ] 7.4 Sign-off, PR (no attribution) closing #105, archive, the queue updated
diff --git a/openspec/changes/tool-discovery-mode/.openspec.yaml b/openspec/changes/tool-discovery-mode/.openspec.yaml
new file mode 100644
index 00000000..55ab199b
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-11-12
diff --git a/openspec/changes/tool-discovery-mode/design.md b/openspec/changes/tool-discovery-mode/design.md
new file mode 100644
index 00000000..370f31c6
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/design.md
@@ -0,0 +1,101 @@
+## Context
+
+`ToolRegistrar` tags every tool with its family (the defining module's
+name, `tool_family()` in `tools/tool_boundary.py`) and its level. The
+families are: `analysis`, `automation`, `docs_discovery`, `drawing`,
+`drawing_analysis`, `drawing_automation`, `engineering_data`, `export`,
+`file_management`, `macro_recording`, `modeling`, `server_admin`,
+`sketching`, `template_management`, `vba_generation`.
+
+FastMCP 3.4.9, the pinned version, provides both pieces:
+
+- `enable(tags=..., only=True)` on the server: an allowlist by tag, applied
+ as a visibility transform;
+- `fastmcp.server.transforms.search.BM25SearchTransform(max_results,
+ always_visible, search_tool_name, call_tool_name)`: replaces the listed
+ tools with `search_tools` and `call_tool`.
+
+Settings are read from `SOLIDWORKS_MCP_*` variables in `config.py`.
+
+## Goals / Non-Goals
+
+**Goals:**
+- A smaller tool list for users who want one, with no change for users
+ who don't.
+- Numbers that show what each choice saves.
+
+**Non-Goals:**
+- Changing the default list. A default of `core` would hide tools from
+ current users without warning; the measured numbers can make the case
+ for that later.
+- Tools that turn toolsets on and off during a session (FastMCP's
+ per-session visibility): clients cache the list, and few handle
+ `list_changed`.
+- Our own search ranking.
+
+## Decisions
+
+### 1. Toolsets map families, in one table
+
+A `TOOLSETS: dict[str, frozenset[str]]` table beside the hints table:
+
+| Toolset | Families |
+| --- | --- |
+| `core` | modeling, sketching, file_management, analysis, engineering_data, export, server_admin |
+| `drawing` | drawing, drawing_automation, drawing_analysis |
+| `automation` | macro_recording, automation, template_management |
+| `vba` | vba_generation |
+| `docs` | docs_discovery |
+
+A test checks every family is in exactly one toolset. After registration,
+`server.py` calls `mcp.enable(tags={}, only=True)`
+unless the choice is `all`. Tools stay registered, so the support-level
+and description checks still see all of them.
+
+### 2. Search mode is FastMCP's BM25 transform
+
+With `search`, `server.py` adds `BM25SearchTransform(max_results=5,
+always_visible=["get_model_info", "reset_circuit_breaker"])` after the
+toolset filter, so the search covers only visible tools. BM25 needs no
+model or network, and ranks on names and descriptions, which item 1's
+description standard already made consistent. `call_tool` runs a tool
+through the same registered function, so the error boundary, levels and
+warnings apply unchanged.
+
+*Alternative:* the regex transform. Rejected: agents search in plain
+words, not patterns.
+
+### 3. Settings fail fast
+
+Both settings are validated in `config.py` at start. An unknown toolset or
+mode raises a configuration error listing the valid values, and the server
+doesn't start; a silently empty tool list would be worse.
+
+### 4. Instructions are built from the mode
+
+The server instructions are a constant today (`SERVER_INSTRUCTIONS`,
+passed to FastMCP in `server.py`). They become a function of the two
+settings, called at start. They gain one line naming the toolsets, the drawing paragraph only when `drawing` is on,
+and, in search mode, a paragraph on `search_tools` and `call_tool`. The
+skill gets a short "If you see `search_tools`" note.
+
+### 5. Measuring with the real list
+
+`python -m solidworks_mcp.progress.tool_list_size` starts the server
+in-process with the mock adapter, reads `tools/list` per mode and toolset,
+and writes bytes and an estimate of tokens (bytes ÷ 4, stated as an
+estimate) to a docs table. It runs with the progress generator, so the
+numbers can't go stale.
+
+## Risks / Trade-offs
+
+- [An agent in search mode can't find a tool] → BM25 on consistent
+ descriptions; the live check runs the U-joint-style prompts' first
+ steps in search mode; list mode stays the default.
+- [`enable(only=True)` hides a tool another tool's description names] →
+ descriptions name tools across families (for example "use
+ `create_drawing_view`"); in a reduced set those pointers can name hidden
+ tools. A test lists them for `core`; the description says "(drawing
+ toolset)" where it points across toolsets.
+- [FastMCP's transform API changes] → it is pinned at 3.4.9; the tests
+ exercise both transforms through the real server object.
diff --git a/openspec/changes/tool-discovery-mode/proposal.md b/openspec/changes/tool-discovery-mode/proposal.md
new file mode 100644
index 00000000..3cd18d88
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/proposal.md
@@ -0,0 +1,70 @@
+## Why
+
+Every tool's schema is sent to the model on every turn. After the
+honest-tool-list change the list is still about 125 tools, and the next
+three items add about 20 more. Glama's review called the list "bloated
+rather than scoped" (issue #176), and the internal assessment found that
+the size of the list, not missing tools, is now the main cost of using
+the server. Users who only model parts pay for VBA generators, API-help
+lookup and drawing tools on every turn, and a client with a tool limit
+can't load the server at all.
+
+## What Changes
+
+- **The tool list is measured.** A script reports the size of
+ `tools/list`, in bytes and estimated tokens, overall and per family. The
+ numbers go in the docs and are regenerated with the progress files.
+- **Toolsets.** `SOLIDWORKS_MCP_TOOLSETS` picks which groups of families
+ are registered as visible:
+ - `core`: modelling, sketching, file management, analysis, engineering
+ data, export, server admin;
+ - `drawing`: drawing, drawing automation, drawing analysis;
+ - `automation`: macros, automation, templates;
+ - `vba`: the VBA generators;
+ - `docs`: the API-help lookup tools;
+ - `all` (the default): everything, as today.
+ Several can be given, comma-separated (`core,drawing`).
+- **Search mode.** `SOLIDWORKS_MCP_TOOL_MODE=search` replaces the list
+ with FastMCP's search transform: `search_tools` (finds tools by a
+ plain-language query and returns their schemas) and `call_tool`, plus a
+ few always-visible tools (`get_model_info`, `reset_circuit_breaker`).
+ `list` (the default) keeps today's full list. The two settings combine:
+ search covers only the chosen toolsets.
+- **The server's instructions and the agent skill** say which mode is on,
+ and in search mode tell the agent to search before calling.
+- **`--selftest`** reports the mode, the toolsets and the visible tool
+ count.
+- No breaking change: with neither setting, the server behaves as now.
+
+## Capabilities
+
+### New Capabilities
+
+- `setup/toolsets`: choosing which tool families a client sees.
+- `setup/tool-search-mode`: an opt-in search-and-call surface in place of
+ the full list.
+
+### Modified Capabilities
+
+- `agents/server-instructions`: the instructions name the active mode and,
+ in search mode, how to find tools.
+- `setup/selftest`: the self-test reports the mode and the visible tool
+ count.
+
+## Impact
+
+- **No COM or adapter code changes.** Visibility is applied after
+ registration, with FastMCP 3.4.9's `enable(tags=..., only=True)` on the
+ family tags `ToolRegistrar` already adds, and its `BM25SearchTransform`.
+ Every tool is still registered, so the support-level and description
+ checks see all of them.
+- **Code:** `config.py` (two settings), `server.py` (apply them after
+ registration), a toolset table beside `tool_hints.py`, the server
+ instructions, `selftest`, a measuring script under
+ `solidworks_mcp/progress/`.
+- **Docs:** a "Choosing tools" section in the client setup page, the
+ numbers, the skill's note, CHANGELOG.
+- **Tests:** each mode and toolset reaches the same tool bodies; `all`
+ equals today's list.
+- Depends on the honest-tool-list change (queue item 10), which settles the
+ families. Closes #176.
diff --git a/openspec/changes/tool-discovery-mode/specs/agents/server-instructions/spec.md b/openspec/changes/tool-discovery-mode/specs/agents/server-instructions/spec.md
new file mode 100644
index 00000000..bc164bf5
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/specs/agents/server-instructions/spec.md
@@ -0,0 +1,16 @@
+## ADDED Requirements
+
+### Requirement: The instructions follow the tool mode
+The server's instructions SHALL name the active toolsets. In search mode
+they SHALL tell the agent to find tools with `search_tools` and run them
+with `call_tool`, and SHALL name no tool the agent can't see.
+
+#### Scenario: Search mode
+- **WHEN** a client connects to a server in search mode
+- **THEN** the instructions say to search before calling, and every tool
+ they name directly is `search_tools`, `call_tool` or an always-visible
+ tool
+
+#### Scenario: Core only
+- **WHEN** the toolsets are `core`
+- **THEN** the instructions don't mention the drawing workflow
diff --git a/openspec/changes/tool-discovery-mode/specs/setup/selftest/spec.md b/openspec/changes/tool-discovery-mode/specs/setup/selftest/spec.md
new file mode 100644
index 00000000..650e41e1
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/specs/setup/selftest/spec.md
@@ -0,0 +1,10 @@
+## ADDED Requirements
+
+### Requirement: The tool mode is reported
+The self-test's environment section SHALL report the tool mode, the
+active toolsets and the number of visible tools.
+
+#### Scenario: A core-only setup
+- **WHEN** `--selftest` runs with `SOLIDWORKS_MCP_TOOLSETS=core`
+- **THEN** the report shows mode `list`, toolsets `core`, and the visible
+ tool count
diff --git a/openspec/changes/tool-discovery-mode/specs/setup/tool-search-mode/spec.md b/openspec/changes/tool-discovery-mode/specs/setup/tool-search-mode/spec.md
new file mode 100644
index 00000000..20f13657
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/specs/setup/tool-search-mode/spec.md
@@ -0,0 +1,44 @@
+## Purpose
+
+An opt-in mode in which the client sees a small search-and-call surface
+instead of every tool's schema.
+
+## ADDED Requirements
+
+### Requirement: Search mode replaces the list
+With `SOLIDWORKS_MCP_TOOL_MODE=search`, `tools/list` SHALL hold
+`search_tools`, `call_tool` and the always-visible tools
+(`get_model_info`, `reset_circuit_breaker`) only. `search_tools` SHALL
+take a plain-language query and return up to five matching tools with
+their full input schemas. `call_tool` SHALL run any tool the active
+toolsets allow, by name, with the same result as calling it directly.
+
+#### Scenario: Finding and calling a tool
+- **WHEN** the agent searches "fillet edges" and calls the returned
+ `add_fillet` through `call_tool`
+- **THEN** the search's results include `add_fillet` with its schema, and
+ the fillet result is the same as a direct call's
+
+#### Scenario: A tool outside the toolsets
+- **WHEN** toolsets are `core` and the agent calls `generate_vba_extrusion`
+ through `call_tool`
+- **THEN** the call fails and says the tool is not in the active toolsets
+
+### Requirement: List mode is the default
+With `SOLIDWORKS_MCP_TOOL_MODE` unset or `list`, the server SHALL list the
+toolsets' tools directly, with no `search_tools` or `call_tool`. Any other
+value SHALL stop the server at start with an error naming `list` and
+`search`.
+
+#### Scenario: Unset
+- **WHEN** the mode is unset
+- **THEN** `tools/list` holds no `search_tools`
+
+### Requirement: The list's size is measured
+A script SHALL report `tools/list`'s size in bytes and estimated tokens,
+overall and per family, for list mode and for search mode, and the docs
+SHALL show the latest numbers.
+
+#### Scenario: Regenerating
+- **WHEN** the progress files are regenerated
+- **THEN** the docs' size table matches the registered tools
diff --git a/openspec/changes/tool-discovery-mode/specs/setup/toolsets/spec.md b/openspec/changes/tool-discovery-mode/specs/setup/toolsets/spec.md
new file mode 100644
index 00000000..28566116
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/specs/setup/toolsets/spec.md
@@ -0,0 +1,43 @@
+## Purpose
+
+A user chooses which tool families their client sees, so a client pays
+only for the tools its work needs.
+
+## ADDED Requirements
+
+### Requirement: Toolsets choose the visible families
+The server SHALL read `SOLIDWORKS_MCP_TOOLSETS`, a comma-separated list of
+`core`, `drawing`, `automation`, `vba`, `docs` and `all`. Only tools whose
+family belongs to a listed toolset SHALL appear in `tools/list` and be
+callable. Unset or `all` SHALL show every tool.
+
+#### Scenario: Core only
+- **WHEN** the server starts with `SOLIDWORKS_MCP_TOOLSETS=core`
+- **THEN** `tools/list` holds `create_extrusion` and `open_model`, and no
+ `generate_vba_*`, drawing or API-help tool
+
+#### Scenario: Core and drawing
+- **WHEN** the setting is `core,drawing`
+- **THEN** `create_drawing_view` is listed too, and the VBA generators are
+ not
+
+#### Scenario: Default
+- **WHEN** the setting is unset
+- **THEN** `tools/list` is the same as before this change
+
+### Requirement: A bad toolset name stops the server with a clear error
+The server SHALL refuse to start when `SOLIDWORKS_MCP_TOOLSETS` names an
+unknown toolset, and the error SHALL list the valid names.
+
+#### Scenario: A typo
+- **WHEN** the setting is `core,drawings`
+- **THEN** the server exits at start with an error naming `drawings` and
+ the valid toolsets
+
+### Requirement: Every family is in exactly one toolset
+Each tool family SHALL belong to exactly one toolset, and a check SHALL
+fail on a family that belongs to none or more than one.
+
+#### Scenario: A new family
+- **WHEN** a new tool module adds a family no toolset lists
+- **THEN** the check fails and names the family
diff --git a/openspec/changes/tool-discovery-mode/tasks.md b/openspec/changes/tool-discovery-mode/tasks.md
new file mode 100644
index 00000000..e01868d1
--- /dev/null
+++ b/openspec/changes/tool-discovery-mode/tasks.md
@@ -0,0 +1,38 @@
+## 1. Measure first
+
+- [ ] 1.1 `progress/tool_list_size.py`: `tools/list` bytes and estimated tokens, overall and per family, through the in-process server with the mock adapter; tests
+- [ ] 1.2 Record today's numbers in the change's notes before anything else changes
+
+## 2. Toolsets
+
+- [ ] 2.1 The `TOOLSETS` table; a test that every family is in exactly one toolset
+- [ ] 2.2 `config.py`: `tool_toolsets` from `SOLIDWORKS_MCP_TOOLSETS`, validated, default `all`; tests for a list, `all`, unset and a typo
+- [ ] 2.3 `server.py`: `enable(tags=..., only=True)` after registration unless `all`; tests that `core` and `core,drawing` list the right tools and that unset equals today's list
+- [ ] 2.4 Cross-toolset pointers in descriptions: list those that name a tool outside `core`, and add "(drawing toolset)" or similar; test
+
+## 3. Search mode
+
+- [ ] 3.1 `config.py`: `tool_mode` from `SOLIDWORKS_MCP_TOOL_MODE`, `list` or `search`, validated; tests
+- [ ] 3.2 `server.py`: `BM25SearchTransform` with the always-visible tools, after the toolset filter; tests that search finds `add_fillet` for "fillet edges", `call_tool` gives a direct call's result, and a tool outside the toolsets is refused
+
+## 4. Instructions, skill and self-test
+
+- [ ] 4.1 Server instructions name the toolsets, leave out the drawing paragraph without `drawing`, and explain search mode; tests
+- [ ] 4.2 The agent skill's note for search mode
+- [ ] 4.3 `--selftest` reports mode, toolsets and visible count; tests
+
+## 5. Docs
+
+- [ ] 5.1 "Choosing tools" in the client setup page: the two settings, examples per client, and the size table
+- [ ] 5.2 The size table generated with the progress files
+- [ ] 5.3 CHANGELOG (Added)
+
+## 6. Live bundle (one set, run together, then fixes one by one)
+
+- [ ] 6.1 Live tests: in search mode with `core`, an agent-style sequence (search, open a part, extrude, fillet) through `call_tool`; `--selftest` with `core`
+- [ ] 6.2 Hand the user the bundle; fix each failure afterwards, one at a time
+
+## 7. Finish
+
+- [ ] 7.1 Full mock suite at 100% coverage, ruff, `mkdocs build --strict`
+- [ ] 7.2 Sign-off, PR (no attribution) closing #176, archive, the queue updated
diff --git a/openspec/queue.md b/openspec/queue.md
index 3b08306c..ca9c2281 100644
--- a/openspec/queue.md
+++ b/openspec/queue.md
@@ -6,7 +6,7 @@ reviewed, then implemented, signed off live where it touches SolidWorks,
and archived after its PR merges. Update this file when an item is done
or the order changes.
-Last updated 2026-11-12.
+Last updated 2026-11-14.
| # | Item | Issue | OpenSpec change | State |
| --- | --- | --- | --- | --- |
@@ -19,20 +19,26 @@ Last updated 2026-11-12.
| 6 | `--selftest` command and a compatibility-report issue template | #179 | `selftest-and-compatibility-report` (archived) | Done 2026-11-09 (#217), signed off live |
| 7 | Beta tools to stable: fix each beta tool's known fault (the small faults listed below), prove it live, and move it up a level | not filed yet | `beta-tool-faults` (archived) | Done 2026-11-09 (#219, 2.0.0): 23 tools promoted, signed off live |
| 8 | Experimental tools to stable: a live test for each of the 10, then promote it or record its fault | not filed yet | `experimental-tools-to-stable` (archived) | Done 2026-11-12 (2.0.0, tagged `v2.0.0`): all 10 promoted, signed off live. Pack and Go now copies the files `GetDependencies2` lists (SolidWorks 2026's own Pack and Go copied only the assembly); `comtypes` dropped |
-| 9 | Monitor stand demo follow-ups | #206 | not yet written | |
-| 10 | The 40 planned tools: implement each one or take it out of the tool list (listed below). A registered tool that can't run is a promise the server doesn't keep | not filed yet | not yet written | Check against #174 first, which may retire some as duplicates |
-| 11 | Clear out duplicate and overlapping tools: compare each cluster, keep one, settle a verb list, deprecate old names for one release | #174 | not yet written | |
-| 12 | Optional toolsets or a discovery mode, to cut the tool list's size | #176 | not yet written | After #174, which decides which families are core |
-| 13 | README: licence-tier tags | #79 (other half) | not yet written | |
-| 14 | Remove the stale `validate_coverage.py`; decide whether mypy gates CI | #157 | not yet written | |
-| 15 | Skills that improve the agent's results, measured on the U-joint prompt | #207 | not yet written | Tabled 2026-11-09: needs research first (what "better" means, a harness to run and score sessions). See `openspec/research/agent-skill-evaluation.md` |
-
-## Tools that can't run yet (item 10)
+| 9 | Monitor stand demo follow-ups: feature order, `verify_model`'s planes, dimension listing, STL export, `create_sketch` on a face, the demo's camera | #206 | `monitor-stand-follow-ups` (archived) | Done 2026-11-14: all five live tests pass, GIF re-recorded; PR open |
+| 10 | An honest tool list: remove the 33 planned tools no item will build, deprecate the stable duplicates for one release, settle a verb list. Replaces the old items "the 40 planned tools" and "duplicate tools" | #174 | `honest-tool-list` | Planned 2026-11-12. Items 11-14 depend on it. It probes `manage_design_table` live before removing it (kept for item 13 if design tables work) |
+| 11 | Part features the peers lead with: Hole Wizard holes, cosmetic threads, a linear feature pattern, shell, draft, rib, and sketch convert-entities | #105 | `part-feature-depth` | Planned 2026-11-12 |
+| 12 | The drawing pack, where no peer goes: section and detail views, the title block and sheet format, drawing dimensions, and one drawing check | #102, #158 | `drawing-pack` | Planned 2026-11-12. Builds the 7 planned drawing tools item 10 leaves |
+| 13 | Configurations: create, activate and delete one, and suppress a feature or set a dimension in one configuration only | none | `configuration-tools` | Planned 2026-11-12 |
+| 14 | Optional toolsets and a discovery mode, to cut the tool list's size | #176 | `tool-discovery-mode` | Planned 2026-11-12. After item 10, which decides the families |
+| 15 | Sheet metal: base flange, edge flange, sketched bend, flat pattern | #57 | not yet written | After item 11 |
+| 16 | README: licence-tier tags | #79 (other half) | not yet written | |
+| 17 | Remove the stale `validate_coverage.py`; decide whether mypy gates CI | #157 | not yet written | |
+| 18 | Skills that improve the agent's results, measured on the U-joint prompt | #207 | not yet written | Tabled 2026-11-09: needs research first (what "better" means, a harness to run and score sessions). See `openspec/research/agent-skill-evaluation.md` |
+## Tools that can't run yet (items 10 and 12)
Each one's description says "Not available yet ... planned for a future
release" (the wording is in `docs/agents/tool-description-standard.md`).
Found while rewriting the descriptions (39), plus `tutorial_simple_hole`
-(40 in all). Their support level is `planned`.
+(40 in all). Their support level is `planned`. Item 10 removes 33 of them;
+item 12 builds the seven drawing tools that are left (`add_dimension`,
+`auto_dimension_view`, `create_section_view`, `create_detail_view`,
+`update_title_block`, `update_sheet_format`, and `check_drawing_standards`
+renamed `check_drawing`).
- **Drawing analysis (7):** `analyze_drawing_comprehensive`,
`analyze_drawing_dimensions`, `analyze_drawing_annotations`,
@@ -70,17 +76,15 @@ their reason), then run `python -m solidworks_mcp.progress.generate`.
`position` says, even off the sheet, and report success (seen in the beta
live tests, 2026-11-09). They could read the sheet size (`_sheet_bounds`
in `adapters/solidworks/documentation.py`) and refuse or warn.
-- `export_stl` logs `Extension.SaveAs2 failed: Type mismatch` on its first
- attempt, then writes the file through its fallback (seen on SolidWorks
- 2026, 2026-11-09). The export works; the first attempt's arguments need
- checking.
## Notes
+- Items 11 and 12 come from the internal assessment: match the closest
+ peer on part depth, and lead on drawings, which it leaves out.
- Until #174 lands, item 1's descriptions say which of two overlapping
tools to use ("For ..., use `other_tool`."), so agents can pick
correctly before any tool is removed.
-- Item 1's family tags are what item 12's toolsets filter on.
+- Item 1's family tags are what item 14's toolsets filter on.
- Parked: the intermittent SolidWorks error sound during
`create_cut_extrude` in the chamfer live tests (#199, #201). Revisit if it
causes failures; run `live_demo.ps1 -Trace` and read the "The hole cut"
diff --git a/openspec/specs/tools/dimension-listing/spec.md b/openspec/specs/tools/dimension-listing/spec.md
new file mode 100644
index 00000000..91d696df
--- /dev/null
+++ b/openspec/specs/tools/dimension-listing/spec.md
@@ -0,0 +1,34 @@
+# tools/dimension-listing Specification
+
+## Purpose
+`list_model_dimensions` lists every dimension in the active part or assembly
+once, under the feature that owns it, so an agent can find a dimension by
+name before reading or changing it.
+## Requirements
+### Requirement: Every dimension is listed with no feature name
+`list_model_dimensions` with no `feature_name` SHALL return every dimension
+of every feature in the active part or assembly: sketch dimensions, feature
+dimensions such as an extrude's depth, and reference-plane offsets. It SHALL
+return the same dimensions the per-feature calls return, together.
+
+#### Scenario: The monitor stand
+- **WHEN** a part holds an extrude, two cuts, a fillet, `Plane1` and a cut
+ sketched on `Plane1`, and `list_model_dimensions` is called with no
+ `feature_name`
+- **THEN** the result holds each dimension that a call naming each feature
+ in turn returns, and no fewer
+
+### Requirement: Each dimension is listed once, under its own feature
+Each dimension SHALL appear once in the result, and its `feature` SHALL be
+the feature its `full_name` names after the `@`.
+
+#### Scenario: A plane's offset seen from the cut on it
+- **WHEN** a cut is sketched on `Plane1`, and SolidWorks also reports
+ `D1@Plane1` among the cut's dimensions
+- **THEN** `D1@Plane1` appears once, with `feature` `Plane1`
+
+#### Scenario: Asking for one feature
+- **WHEN** `list_model_dimensions` is called with `feature_name` `Cut-Extrude3`
+- **THEN** only dimensions whose `full_name` ends in `@Cut-Extrude3` (or its
+ sketch's own name, for a sketch) are returned, not `D1@Plane1`
+
diff --git a/openspec/specs/tools/list-features/spec.md b/openspec/specs/tools/list-features/spec.md
index 829034f0..01fe3bdc 100644
--- a/openspec/specs/tools/list-features/spec.md
+++ b/openspec/specs/tools/list-features/spec.md
@@ -14,7 +14,10 @@ Part documents. The response SHALL NOT be restructured into a nested
object (for example, separate `components`/`assembly_features`
collections) for any document type, because existing callers (feature-tree
diffing, feature-family classification, and the MCP tool's `count` field)
-depend on the result being a flat list.
+depend on the result being a flat list. Within each document, the
+descriptors SHALL be in feature-tree order (oldest first), each feature
+SHALL appear once, and its `position` SHALL be its place in that order,
+however SolidWorks was walked to find it.
#### Scenario: Listing features on a Part
- **WHEN** `list_features` is called with the active document being a
@@ -22,6 +25,12 @@ depend on the result being a flat list.
- **THEN** the result is a flat list of that Part's own feature
descriptors, in the same shape as before this change
+#### Scenario: The forward walk stops early
+- **WHEN** SolidWorks stops the feature walk at the system folders, so the
+ remaining features are found newest first
+- **THEN** the result is still in tree order: the default planes come
+ before `Plane1`, and `Plane1` before the cut sketched on it
+
### Requirement: Feature descriptors identify their originating component
Each feature descriptor SHALL carry a `component` field and a
`component_path` field. For a feature that belongs to the document's own
diff --git a/openspec/specs/tools/model-verification/spec.md b/openspec/specs/tools/model-verification/spec.md
index fccb93b0..aed144a9 100644
--- a/openspec/specs/tools/model-verification/spec.md
+++ b/openspec/specs/tools/model-verification/spec.md
@@ -82,16 +82,24 @@ excludes:
- sketches;
- the origin;
- folder entries;
-- the three default reference planes;
+- the three default reference planes, which are the first three reference
+ planes in tree order, whatever their names;
- the mate group.
-The agent can then predict the number from the features it created.
+A reference plane the agent made SHALL be counted. The agent can then
+predict the number from the features it created.
#### Scenario: Part with two extrudes and a fillet
- **WHEN** a part's tree holds the default entries, two sketches, two
extrudes and one fillet
- **THEN** the measured feature count is 3
+#### Scenario: A part with a plane the agent made
+- **WHEN** a part holds an extrude, `Plane1` offset from Top Plane, and a
+ cut sketched on `Plane1`
+- **THEN** the measured feature count is 3, and the counted features are
+ the extrude, `Plane1` and the cut, never `Front Plane`
+
### Requirement: Invalid requests fail clearly
The tool SHALL return the standard error payload (`status: "error"`,
`error_type`, `hint`):
diff --git a/openspec/specs/tools/sketch-on-face/spec.md b/openspec/specs/tools/sketch-on-face/spec.md
new file mode 100644
index 00000000..6000716a
--- /dev/null
+++ b/openspec/specs/tools/sketch-on-face/spec.md
@@ -0,0 +1,46 @@
+# tools/sketch-on-face Specification
+
+## Purpose
+`create_sketch` opens a sketch on a flat face of the body, given a point on
+that face, so a feature can follow the face when the model's dimensions
+change.
+## Requirements
+### Requirement: A sketch opens on the flat face at a point
+`create_sketch` SHALL accept `face_point`, `[x, y, z]` in millimetres in
+model coordinates, in place of `plane`. It SHALL open the sketch on the flat
+face of the active part at that point, and reply with the sketch's name
+as it does for a plane.
+
+#### Scenario: Sketching on the top face
+- **WHEN** a part has a 20 mm tall block whose top face is at y = 20 mm, and
+ `create_sketch` is called with `face_point` `[0, 20, 0]`
+- **THEN** a sketch opens on that face, and a cut drawn there and extruded
+ 3 mm leaves the block 3 mm lower at the cut
+
+#### Scenario: The sketch follows the face
+- **WHEN** the block's height is changed afterwards and the model rebuilt
+- **THEN** the sketch, and the cut made from it, move with the top face
+
+### Requirement: Exactly one of plane and face_point
+`create_sketch` SHALL fail with `invalid_input` when both `plane` and
+`face_point` are given, or neither, or `face_point` does not have three
+numbers.
+
+#### Scenario: Both given
+- **WHEN** `create_sketch` is called with `plane` `Top` and a `face_point`
+- **THEN** the call fails with `invalid_input`, and nothing is opened
+
+### Requirement: A point that is not on a flat face fails
+When `face_point` is not on a face of the active part, or is on a curved
+face, `create_sketch` SHALL fail with `invalid_input`, name the point, and
+open no sketch.
+
+#### Scenario: A point in the air
+- **WHEN** `face_point` is 50 mm above the part
+- **THEN** the call fails with `invalid_input` naming the point, and no
+ sketch is open afterwards
+
+#### Scenario: A point on a fillet
+- **WHEN** `face_point` lies on a filleted (curved) face
+- **THEN** the call fails with `invalid_input` saying the face is not flat
+
diff --git a/openspec/specs/tools/stl-export/spec.md b/openspec/specs/tools/stl-export/spec.md
new file mode 100644
index 00000000..8bca9111
--- /dev/null
+++ b/openspec/specs/tools/stl-export/spec.md
@@ -0,0 +1,23 @@
+# tools/stl-export Specification
+
+## Purpose
+`export_stl` writes the active part or assembly as an STL file through
+SolidWorks' export call with its STL options, so a multibody part or an
+assembly comes out as one merged file.
+## Requirements
+### Requirement: STL export uses its export options without a type mismatch
+`export_stl` SHALL write the file with SolidWorks' STL export options (bodies
+merged into one file), and SHALL NOT log a type-mismatch warning on the way.
+A fallback without the options SHALL be used only when the first call
+writes nothing, and the reply SHALL say when it was used.
+
+#### Scenario: A single-body part
+- **WHEN** `export_stl` writes a part with one body
+- **THEN** the file exists, is non-empty, and no type-mismatch warning is
+ logged
+
+#### Scenario: The export call writes nothing
+- **WHEN** the export with options returns without writing the file
+- **THEN** the fallback writes it, and the reply's `warning` says the STL
+ options were not applied
+
diff --git a/scripts/demo_monitor_stand.py b/scripts/demo_monitor_stand.py
index 804d9b3d..54e6dccc 100644
--- a/scripts/demo_monitor_stand.py
+++ b/scripts/demo_monitor_stand.py
@@ -9,11 +9,9 @@
leaves a 14.54 mm floor under the monitor. The session built it 55 mm tall
with a 3 mm pocket (``--height 55 --top 15 --pocket-depth 3``).
-The one difference from the hand-finished part: there, the pocket's plane
-sits on the top face, so it follows the height if the height is edited in
-SolidWorks. The tools can only offset a plane from a named plane, so here
-it is Top Plane offset by the height. The solid is the same; to change the
-height, rerun the script rather than editing the extrusion by hand.
+The pocket is sketched on the top face itself (``create_sketch`` with
+``face_point``), as in the hand-finished part, so it follows the height when
+the extrusion's depth is edited later in SolidWorks.
The stand is a top plate on four square legs. The openings at the front,
left and right are arched (large fillets where the legs meet the top); the
@@ -31,9 +29,9 @@
underside, picked by each edge's midpoint (metres): two for the front
arch, four for the side arches. The back legs' edges facing the back
opening are left sharp.
-6. The pocket: ``create_reference_plane`` on the top face (Top Plane
- offset by the height), a rectangle the base's size plus the clearance
- on each side, and a blind cut down into the top.
+6. The pocket: ``create_sketch`` on the top face (``face_point`` at its
+ centre), a rectangle the base's size plus the clearance on each side,
+ and a blind cut down into the top.
7. ``rebuild_model``, then ``verify_model`` against a hand calculation.
8. ``save_part`` and, with ``--stl``, ``export_stl``.
@@ -49,8 +47,10 @@
.\.venv\Scripts\python.exe scripts\demo_monitor_stand.py --out "C:\path\to\MonitorStand.SLDPRT" --height 70 --fillet 30 --pocket-depth 8 --replace --stl
``--replace`` closes the part if it is open in SolidWorks (unsaved changes
-to it are lost) and overwrites the file. ``--mock`` runs every call against
-the mock adapter instead, without SolidWorks.
+to it are lost) and overwrites the file. ``--look`` turns the camera to the
+isometric view after the extrusion, each cut and the fillet, for a
+recording. ``--mock`` runs every call against the mock adapter instead,
+without SolidWorks.
"""
from __future__ import annotations
@@ -60,6 +60,7 @@
import json
import math
import sys
+from collections.abc import Callable
from dataclasses import dataclass
from pathlib import Path
from typing import Any
@@ -67,6 +68,9 @@
REPO_ROOT = Path(__file__).resolve().parents[1]
sys.path.insert(0, str(REPO_ROOT / "src"))
+#: swStandardViews_e (swconst.tlb, SW 2026): the isometric view.
+ISO_VIEW = 7
+
@dataclass(frozen=True)
class Stand:
@@ -219,14 +223,31 @@ async def _close_if_open(call: Session, out: Path) -> None:
await call("close_model", {"save": False})
+def look_isometric(adapter: Any) -> None:
+ """Turn the camera to the isometric view, zoomed to fit.
+
+ Staging for a recording, not a tool call: an agent does not need it, so
+ it reaches the adapter directly.
+ """
+ model = adapter.currentModel
+ adapter._attempt(lambda: model.ShowNamedView2("", ISO_VIEW), default=None)
+ adapter._zoom_to_fit(model)
+
+
def _mm(value: float) -> float:
"""Round a length to 0.0001 mm so the calls read cleanly."""
return round(value, 4)
-async def _centred_rectangle(call: Session, plane: str, width: float, length: float) -> None:
- """Sketch a rectangle centred on the origin of ``plane`` and exit the sketch."""
- await call("create_sketch", {"plane": plane})
+async def _centred_rectangle(
+ call: Session, where: dict[str, Any], width: float, length: float
+) -> None:
+ """Sketch a rectangle centred on the origin and exit the sketch.
+
+ ``where`` is ``create_sketch``'s place: ``{"plane": ...}`` or
+ ``{"face_point": [...]}``.
+ """
+ await call("create_sketch", where)
await call(
"add_rectangle",
{"x1": -_mm(width / 2), "y1": -_mm(length / 2), "x2": _mm(width / 2), "y2": _mm(length / 2)},
@@ -234,8 +255,24 @@ async def _centred_rectangle(call: Session, plane: str, width: float, length: fl
await call("exit_sketch")
-async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session) -> None:
- """Run the build's tool calls in order."""
+async def build(
+ stand: Stand,
+ out: Path,
+ replace: bool,
+ stl: bool,
+ call: Session,
+ look: Callable[[], None] | None = None,
+) -> None:
+ """Run the build's tool calls in order.
+
+ ``look``, when given, runs after the extrusion, each cut and the fillet,
+ so a recording shows each feature as it is made.
+ """
+
+ def _show() -> None:
+ if look is not None:
+ look()
+
if replace:
await _close_if_open(call, out)
@@ -243,8 +280,9 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session
await call("set_units", {"unit_system": "mm"})
# Block: the full footprint, extruded to the full height.
- await _centred_rectangle(call, "Top", stand.width, stand.depth)
+ await _centred_rectangle(call, {"plane": "Top"}, stand.width, stand.depth)
await call("create_extrusion", {"sketch_name": "Sketch1", "depth": stand.height})
+ _show()
# Front/back opening, between the legs along X.
inner_x = _mm(stand.width / 2 - stand.leg)
@@ -259,6 +297,7 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session
"create_cut_extrude",
{"sketch_name": "Sketch2", "depth": cut_depth, "end_condition": "ThroughAllBoth"},
)
+ _show()
# Left/right opening, between the legs along Z.
inner_z = _mm(stand.depth / 2 - stand.leg)
@@ -272,18 +311,25 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session
"create_cut_extrude",
{"sketch_name": "Sketch3", "depth": cut_depth, "end_condition": "ThroughAllBoth"},
)
+ _show()
# Arches: front, left and right. The back stays square.
await call("add_fillet", {"radius": stand.fillet, "edge_names": stand.arch_edges_m()})
-
- # Pocket: a plane on the top face, the base's outline plus clearance,
- # cut down into the top. The cut finds the material itself.
- plane = await call("create_reference_plane", {"reference": "Top Plane", "offset": stand.height})
- await _centred_rectangle(call, plane["plane"]["name"], stand.pocket_width, stand.pocket_length)
+ _show()
+
+ # Pocket: sketched on the top face itself, so it follows the height, the
+ # base's outline plus clearance, cut down into the top.
+ await _centred_rectangle(
+ call,
+ {"face_point": [0, _mm(stand.height), 0]},
+ stand.pocket_width,
+ stand.pocket_length,
+ )
await call(
"create_cut_extrude",
{"sketch_name": "Sketch4", "depth": stand.pocket_depth, "end_condition": "Blind"},
)
+ _show()
await call("rebuild_model")
verdict = await call(
@@ -292,7 +338,7 @@ async def build(stand: Stand, out: Path, replace: bool, stl: bool, call: Session
"bounding_box_mm": [_mm(stand.width), _mm(stand.height), _mm(stand.depth)],
"volume_mm3": round(stand.expected_volume_mm3(), 1),
"solid_body_count": 1,
- "feature_count": 6, # extrude, two cuts, fillet, plane, pocket
+ "feature_count": 5, # extrude, two cuts, fillet, pocket
"relative_tolerance": 0.01,
},
)
@@ -327,6 +373,10 @@ def _parse(argv: list[str] | None) -> argparse.Namespace:
p.add_argument("--replace", action="store_true", help="close the open part and overwrite the file")
p.add_argument("--stl", action="store_true", help="also export an STL beside the part")
p.add_argument("--calls-json", type=Path, help="write the tool calls made to this file")
+ p.add_argument(
+ "--look", action="store_true",
+ help="turn the camera to isometric after each feature, for a recording",
+ )
p.add_argument("--mock", action="store_true", help="use the mock adapter, not SolidWorks")
return p.parse_args(argv)
@@ -343,7 +393,8 @@ async def _run(args: argparse.Namespace, stand: Stand) -> list[dict[str, Any]]:
await adapter.connect()
try:
call = Session(await _tools(adapter))
- await build(stand, args.out, args.replace, args.stl, call)
+ look = (lambda: look_isometric(adapter)) if args.look else None
+ await build(stand, args.out, args.replace, args.stl, call, look)
return call.calls
finally:
await adapter.disconnect()
diff --git a/src/solidworks_mcp/adapters/base.py b/src/solidworks_mcp/adapters/base.py
index 594d5b1f..b8249c7e 100644
--- a/src/solidworks_mcp/adapters/base.py
+++ b/src/solidworks_mcp/adapters/base.py
@@ -594,11 +594,17 @@ async def create_loft(
# Sketch Operations
@abstractmethod
- async def create_sketch(self, plane: str) -> AdapterResult[str]:
- """Create a new sketch on the specified plane.
+ async def create_sketch(
+ self,
+ plane: str | None,
+ face_point: tuple[float, float, float] | None = None,
+ ) -> AdapterResult[str]:
+ """Create a new sketch on a plane, or on the flat face at a point.
Args:
- plane (str): The plane value.
+ plane (str | None): The plane's name; None when ``face_point`` is given.
+ face_point (tuple[float, float, float] | None): ``(x, y, z)`` in mm on
+ a flat face of the active part, in place of ``plane``.
Returns:
AdapterResult[str]: The result produced by the operation.
diff --git a/src/solidworks_mcp/adapters/circuit_breaker.py b/src/solidworks_mcp/adapters/circuit_breaker.py
index 0a6d3de8..aec2ecf6 100644
--- a/src/solidworks_mcp/adapters/circuit_breaker.py
+++ b/src/solidworks_mcp/adapters/circuit_breaker.py
@@ -914,19 +914,25 @@ async def create_loft(
# Sketch operations
- async def create_sketch(self, plane: str) -> AdapterResult[str]:
+ async def create_sketch(
+ self,
+ plane: str | None,
+ face_point: tuple[float, float, float] | None = None,
+ ) -> AdapterResult[str]:
"""Create sketch through circuit breaker.
Args:
- plane (str): The plane value.
+ plane (str | None): The plane's name; None with ``face_point``.
+ face_point (tuple[float, float, float] | None): A point in mm on a
+ flat face, in place of ``plane``.
Returns:
AdapterResult[str]: The result produced by the operation.
"""
return await self._execute_with_circuit_breaker(
"create_sketch",
- lambda: self.adapter.create_sketch(plane),
- input_dict={"plane": plane},
+ lambda: self.adapter.create_sketch(plane, face_point),
+ input_dict={"plane": plane, "face_point": face_point},
)
async def add_line(
diff --git a/src/solidworks_mcp/adapters/connection_pool.py b/src/solidworks_mcp/adapters/connection_pool.py
index 4d8b9793..db59df61 100644
--- a/src/solidworks_mcp/adapters/connection_pool.py
+++ b/src/solidworks_mcp/adapters/connection_pool.py
@@ -826,17 +826,23 @@ async def create_loft(
# Sketch operations
- async def create_sketch(self, plane: str) -> AdapterResult[str]:
+ async def create_sketch(
+ self,
+ plane: str | None,
+ face_point: tuple[float, float, float] | None = None,
+ ) -> AdapterResult[str]:
"""Create sketch using pool.
Args:
- plane (str): The plane value.
+ plane (str | None): The plane's name; None with ``face_point``.
+ face_point (tuple[float, float, float] | None): A point in mm on a
+ flat face, in place of ``plane``.
Returns:
AdapterResult[str]: The result produced by the operation.
"""
return await self._execute_with_pool(
- "create_sketch", lambda adapter: adapter.create_sketch(plane)
+ "create_sketch", lambda adapter: adapter.create_sketch(plane, face_point)
)
async def add_line(
diff --git a/src/solidworks_mcp/adapters/mock_adapter.py b/src/solidworks_mcp/adapters/mock_adapter.py
index bea80829..6867003d 100644
--- a/src/solidworks_mcp/adapters/mock_adapter.py
+++ b/src/solidworks_mcp/adapters/mock_adapter.py
@@ -551,6 +551,9 @@ async def list_features(
"component_parent": None,
},
]
+ # Every row carries its tree place, as the real adapter's do.
+ for position, row in enumerate(seeded):
+ row["position"] = position
if is_assembly:
components = self._assembly_components or _DEFAULT_ASSEMBLY_COMPONENTS
seeded.extend(
@@ -1420,11 +1423,21 @@ async def create_loft(
execution_time=self._delays["feature_operation"],
)
- async def create_sketch(self, plane: str) -> AdapterResult[dict[str, Any]]: # type: ignore[override]
- """Mock creating a sketch.
+ async def create_sketch( # type: ignore[override]
+ self,
+ plane: str | None,
+ face_point: tuple[float, float, float] | None = None,
+ ) -> AdapterResult[dict[str, Any]]:
+ """Mock creating a sketch on a plane, or on a face of the canned block.
+
+ With ``face_point``, the point must lie on a face of the 10 mm block
+ ``select_face_edges`` models (every face of it is flat); any other
+ point is refused with the real adapter's message.
Args:
- plane (str): The plane value.
+ plane (str | None): The plane value; None with ``face_point``.
+ face_point (tuple[float, float, float] | None): A point in mm on a
+ face of the block.
Returns:
AdapterResult[dict[str, Any]]: The result produced by the operation.
@@ -1433,11 +1446,23 @@ async def create_sketch(self, plane: str) -> AdapterResult[dict[str, Any]]: # t
# Legacy tests start sketching immediately after connect.
await self.create_part()
+ if face_point is not None and self._mock_face_at(list(face_point)) is None:
+ return AdapterResult(
+ status=AdapterResultStatus.ERROR,
+ error=(
+ f"face_point {[float(c) for c in face_point]} mm is not on a "
+ "flat face of the active part (No face found at point "
+ f"{list(face_point)} mm.)"
+ ),
+ )
+
await asyncio.sleep(self._delays["sketch_operation"])
self._operation_count += 1
sketch_id = f"Sketch{len(self._sketches) + 1}"
- self._sketches[sketch_id] = plane
+ self._sketches[sketch_id] = (
+ plane if face_point is None else f"face at {list(face_point)} mm"
+ )
self._current_sketch = sketch_id
return AdapterResult(
diff --git a/src/solidworks_mcp/adapters/pywin32_adapter.py b/src/solidworks_mcp/adapters/pywin32_adapter.py
index 058efd7d..a2aa0ddd 100644
--- a/src/solidworks_mcp/adapters/pywin32_adapter.py
+++ b/src/solidworks_mcp/adapters/pywin32_adapter.py
@@ -32,6 +32,7 @@
SolidWorksSketchMixin,
bitmap,
)
+from .solidworks.feature_walk import walk_feature_tree
from .solidworks.features import _null_callout, _select_feature_by_name
from .solidworks.io import _byref_int
@@ -91,6 +92,12 @@ def _byref_long(initial: int = 0) -> Any:
)
+#: The note an STL export carries when SaveAs3 had to write it.
+STL_OPTIONS_NOT_APPLIED = (
+ "The STL was written by SaveAs3 because SaveAs2 wrote nothing, so its STL "
+ "options (bodies merged into one file) were not applied."
+)
+
# OLE2 / Compound File Binary Format magic. A real (SW-authored) ``.swp`` is a
# compound file; a hand-written text macro is not.
_OLE2_MAGIC = b"\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1"
@@ -1059,15 +1066,6 @@ def resolve_export_target_doc(self) -> Any:
return self._adapter.currentModel
-#: Members the ``list_features`` tree walk actually reads on each feature
-#: dispatch. Flagging just these instead of the whole ``IFeature`` interface
-#: (~100 names, ~27 ms per object) is what keeps the walk cheap: the flag
-#: cache in ``sw_type_info`` is keyed by ``id(obj)``, and every feature here
-#: is a freshly returned dispatch, so a full-interface flag never hits that
-#: cache and pays its full cost on every single feature.
-_WALK_MEMBERS = ("GetNextFeature", "GetTypeName2", "IsSuppressed", "IsSuppressed2")
-
-
class _FeatureSelectionService:
"""Encapsulate feature-selection strategies and name-candidate expansion.
@@ -1539,74 +1537,23 @@ def _list_document_features(
list[dict[str, Any]]: Ordered feature descriptors.
"""
features: list[dict[str, Any]] = []
- seen: set[tuple[str, str]] = set()
-
- feature = self._adapter._attempt(lambda: document.FirstFeature())
- # Flag only the members this walk reads (see ``_WALK_MEMBERS``) so
- # methods like GetNextFeature work, without paying the cost of
- # flagging the entire IFeature interface on every fresh dispatch.
- if feature is not None:
- self._adapter._attempt(
- lambda f=feature: sw_type_info.flag_members(f, *_WALK_MEMBERS), # type: ignore[misc]
- default=0,
- )
- pos = 0
- guard = 0
- while feature and guard < 10000:
- self._append_feature_to(
- features,
- seen,
- feature,
- pos,
- include_suppressed,
- component=component,
- component_path=component_path,
- component_parent=component_parent,
- )
- pos += 1
- guard += 1
- next_feature = self._adapter._attempt(
- lambda current_feature=feature: current_feature.GetNextFeature() # type: ignore[misc]
- )
- if next_feature is None:
- break
- feature = next_feature
- # Flag each new feature dispatch
- if feature is not None:
- self._adapter._attempt(
- lambda f=feature: sw_type_info.flag_members(f, *_WALK_MEMBERS), # type: ignore[misc]
- default=0,
- )
-
- # Always augment the forward traversal with FeatureByPositionReverse.
- # Some SolidWorks COM/type-library combinations stop GetNextFeature at
- # the system folders even though later sketches and body features
- # exist. The dedupe set keeps this fallback safe when both traversals
- # return the same entries.
- feature_manager = getattr(document, "FeatureManager", None)
- count = self._adapter._attempt(
- lambda: int(feature_manager.GetFeatureCount(True) or 0), # type: ignore[union-attr]
- default=0,
- )
- # FeatureByPositionReverse is zero-based. Starting at one silently
- # skipped the newest feature (typically the just-created extrusion).
- for reverse_pos in range(0, count or 0):
- feature = self._adapter._attempt(
- lambda pos=reverse_pos: document.FeatureByPositionReverse(pos)
- )
- if feature is None:
+ # One walk, shared with list_model_dimensions: both passes, each
+ # feature once, in tree order (see ``feature_walk``).
+ for item in walk_feature_tree(self._adapter, document):
+ suppressed = self._is_feature_suppressed(item.feature)
+ if suppressed and not include_suppressed:
continue
- self._append_feature_to(
- features,
- seen,
- feature,
- (count or 0) - reverse_pos - 1,
- include_suppressed,
- component=component,
- component_path=component_path,
- component_parent=component_parent,
+ features.append(
+ {
+ "name": item.name,
+ "type": item.type_name,
+ "suppressed": suppressed,
+ "position": item.position,
+ "component": component,
+ "component_path": component_path,
+ "component_parent": component_parent,
+ }
)
-
return features
def _list_assembly_component_features(
@@ -1737,61 +1684,6 @@ def _list_assembly_component_features(
return results
- def _append_feature_to(
- self,
- features: list[dict[str, Any]],
- seen: set[tuple[str, str]],
- feature: Any,
- position: int,
- include_suppressed: bool,
- component: str | None = None,
- component_path: str | None = None,
- component_parent: str | None = None,
- ) -> None:
- """Append one feature descriptor when dedupe and suppression rules allow.
-
- Args:
- features: Output list being populated.
- seen: Dedupe set of ``(name, type)`` keys.
- feature: Feature COM object.
- position: Display position index.
- include_suppressed: Include suppressed entries when ``True``.
- component: Owning component name, or ``None`` for a document's
- own (non-component) feature.
- component_path: Owning component's resolved document path, or
- ``None`` to match ``component``.
- component_parent: Immediate parent component's name, or
- ``None`` for a top-level component or a document's own
- feature.
- """
- name = str(getattr(feature, "Name", ""))
- feature_type = str(
- self._adapter._attempt(
- lambda: self._adapter._get_attr_or_call(feature, "GetTypeName2"),
- default="Unknown",
- )
- )
- dedupe_key = (name, feature_type)
- if dedupe_key in seen:
- return
- seen.add(dedupe_key)
-
- suppressed = self._is_feature_suppressed(feature)
- if not include_suppressed and suppressed:
- return
-
- features.append(
- {
- "name": name,
- "type": feature_type,
- "suppressed": suppressed,
- "position": position,
- "component": component,
- "component_path": component_path,
- "component_parent": component_parent,
- }
- )
-
def _is_feature_suppressed(self, feature: Any) -> bool:
"""Determine feature suppression state across COM API variants.
@@ -2560,37 +2452,37 @@ def _prepare_stl_export_data(self) -> Any | None:
def _save_stl_with_extension(
self, ext: Any, stl_data: Any | None, resolved_path: str
) -> bool:
- """Attempt STL export using Extension.SaveAs2 with optional ISTLExportData.
+ """Export STL with ``IModelDocExtension.SaveAs2`` and the STL options.
- Tries SaveAs2 with stl_data first (enables body merging); falls back to
- SaveAs2(None) if type mismatch occurs (late-bound IDispatch can't marshal
- ISTLExportData* through IDispatch::Invoke).
+ ``SaveAs2`` takes eight arguments: ``Name``, ``Version``, ``Options``,
+ ``ExportData``, ``ReferencePrefixOrSuffixText`` (String),
+ ``AddTextAsPrefix`` (Boolean), ``Errors`` and ``Warnings`` (both
+ by-reference Longs). Leaving ``Warnings`` out fails with
+ "Parameter not optional".
+ ``ExportData`` is the ``ISTLExportData`` that merges the bodies, or a
+ ``VT_DISPATCH`` null when SolidWorks gave none (runbook #11: a bare
+ ``None`` marshals as ``VT_NULL`` and is rejected).
Args:
- ext: Extension object from target document
- stl_data: Optional ISTLExportData configuration
- resolved_path: Full path where to save STL file
+ ext: The document's ``IModelDocExtension``.
+ stl_data: The ``ISTLExportData``, or None.
+ resolved_path: Full path of the STL file to write.
Returns:
- True if file was created, False otherwise.
+ bool: True when the file exists afterwards.
"""
+ export_data = stl_data if stl_data is not None else _null_callout()
+ errors = _byref_long(0)
+ warnings = _byref_long(0)
try:
- # Try with stl_data first
- try:
- # swSaveAsVersion_e.swSaveAsCurrentVersion = 0
- # swSaveAsOptions_e.swSaveAsOptions_Silent = 2
- ext.SaveAs2(resolved_path, 0, 2, stl_data, None, "")
- except Exception:
- # Fallback: try without stl_data (type mismatch on IDispatch)
- ext.SaveAs2(resolved_path, 0, 2, None, None, "")
-
- return os.path.exists(resolved_path)
+ # swSaveAsCurrentVersion = 0, swSaveAsOptions_Silent = 2
+ ext.SaveAs2(resolved_path, 0, 2, export_data, "", False, errors, warnings)
except Exception as exc:
logger.warning(
- "[pywin32.export_file] Extension.SaveAs2 failed: {}",
- str(exc),
+ "[pywin32.export_file] Extension.SaveAs2 failed: {}", str(exc)
)
return False
+ return os.path.exists(resolved_path)
def _save_stl_with_fallback(self, target_doc: Any, resolved_path: str) -> None:
"""Fallback STL export using SaveAs3 if SaveAs2 didn't create file.
@@ -2624,9 +2516,7 @@ def _save_stl_with_fallback(self, target_doc: Any, resolved_path: str) -> None:
"(tried Extension.SaveAs2 and SaveAs3)"
)
- async def export_file(
- self, file_path: str, format_type: str
- ) -> AdapterResult[None]:
+ async def export_file(self, file_path: str, format_type: str) -> AdapterResult[Any]:
"""Export the current model to a file.
Args:
@@ -2634,7 +2524,8 @@ async def export_file(
format_type (str): The format type value.
Returns:
- AdapterResult[None]: The result produced by the operation.
+ AdapterResult[Any]: No data, except an STL written by the SaveAs3
+ fallback, whose data is ``{"warning": ...}``.
Raises:
Exception: If the operation cannot be completed.
@@ -2645,11 +2536,11 @@ async def export_file(
status=AdapterResultStatus.ERROR, error="No active model"
)
- def _export_operation() -> None:
+ def _export_operation() -> dict[str, str] | None:
"""Build internal export operation.
Returns:
- None: None.
+ dict[str, str] | None: The fallback warning for an STL, else None.
Raises:
Exception: If the operation cannot be completed.
@@ -2698,11 +2589,12 @@ def _export_operation() -> None:
raise RuntimeError("No Extension object available for STL export")
stl_data = self._prepare_stl_export_data()
- if not self._save_stl_with_extension(ext, stl_data, resolved_path):
- # SaveAs2 didn't produce file — try SaveAs3 fallback
- self._save_stl_with_fallback(target_doc, resolved_path)
-
- return None
+ if self._save_stl_with_extension(ext, stl_data, resolved_path):
+ return None
+ # SaveAs2 wrote nothing: SaveAs3 writes the file without the
+ # STL options, so the reply says they weren't applied.
+ self._save_stl_with_fallback(target_doc, resolved_path)
+ return {"warning": STL_OPTIONS_NOT_APPLIED}
# ----------------------------------------------------------------
# All other formats — classic SaveAs3 path.
diff --git a/src/solidworks_mcp/adapters/solidworks/com_utils.py b/src/solidworks_mcp/adapters/solidworks/com_utils.py
index 319317fc..2f76ef81 100644
--- a/src/solidworks_mcp/adapters/solidworks/com_utils.py
+++ b/src/solidworks_mcp/adapters/solidworks/com_utils.py
@@ -20,7 +20,7 @@ def flag(adapter: Any, obj: Any, *names: str) -> None:
"""Flag just ``names`` as methods on ``obj`` (no-op for ``None``/fakes).
Flagging a whole interface costs ~27 ms per fresh dispatch (see
- ``_WALK_MEMBERS`` in pywin32_adapter); SolidWorks hands back a fresh
+ ``WALK_MEMBERS`` in feature_walk); SolidWorks hands back a fresh
dispatch on most calls, so flag only what is about to be read.
"""
attempt(adapter, lambda: _sw_type_info.flag_members(obj, *names), 0)
diff --git a/src/solidworks_mcp/adapters/solidworks/documentation.py b/src/solidworks_mcp/adapters/solidworks/documentation.py
index dbbe42d6..3cb5a08d 100644
--- a/src/solidworks_mcp/adapters/solidworks/documentation.py
+++ b/src/solidworks_mcp/adapters/solidworks/documentation.py
@@ -19,6 +19,7 @@
from ..base import AdapterResult, AdapterResultStatus
from . import dimension_layout as _layout
+from .feature_walk import walk_feature_tree
from .features import _null_callout, _parse_edge_spec, _select_edge_by_coord
from .io import (
_as_com,
@@ -311,6 +312,34 @@ def _strip_document_suffix(full_name: Any) -> str | None:
return full_name
+def _owning_feature(full_name: str | None) -> str | None:
+ """The feature a dimension's full name says owns it.
+
+ Args:
+ full_name: A short full name such as ``"D1@Plane1"``.
+
+ Returns:
+ str | None: The part after the first ``@`` (``"Plane1"``); ``None``
+ when there is no name or no ``@``.
+ """
+ if not full_name or "@" not in full_name:
+ return None
+ return full_name.split("@", 1)[1]
+
+
+def _is_folder(type_name: str) -> bool:
+ """Whether a feature-tree row is a folder, which owns no dimensions.
+
+ Args:
+ type_name: The row's ``GetTypeName2`` type.
+
+ Returns:
+ bool: True for folder types (``CommentsFolder``, ``MaterialFolder``,
+ ...) and the annotations folder (``DetailCabinet``).
+ """
+ return type_name.endswith("Folder") or type_name == "DetailCabinet"
+
+
def _sequence(raw: Any) -> list[Any]:
"""Normalise a COM array return (``None``, scalar or tuple) into a list.
@@ -383,20 +412,24 @@ def _require_doc_type(
async def list_model_dimensions(
self, feature_name: str | None = None
) -> AdapterResult[list[dict[str, Any]]]:
- """List every dimension in the active part or assembly.
+ """List every dimension in the active part or assembly, once each.
- Walks ``IModelDoc2::FirstFeature`` / ``IFeature::GetNextFeature`` and
- each feature's ``GetFirstDisplayDimension`` chain. ``full_name`` (e.g.
- ``"D1@Sketch1"``) is the name ``set_dimension`` accepts, so the pair
- gives edit-by-name access to every driving parameter in the model.
+ Reads the features with the same two-pass walk as ``list_features``
+ (:func:`~.feature_walk.walk_feature_tree`), skips folder rows, and
+ reads each feature's ``GetFirstDisplayDimension`` chain. SolidWorks
+ can show one dimension under several features (a plane's offset under
+ the cut sketched on it), so each ``full_name`` (e.g. ``"D1@Sketch1"``,
+ the name ``set_dimension`` accepts) is kept once, with ``feature`` set
+ from the part after the ``@``.
Args:
- feature_name: Only list dimensions of this feature (case-insensitive).
+ feature_name: Only list dimensions owned by this feature
+ (case-insensitive), by the ``@`` suffix of their full name.
Returns:
AdapterResult[list[dict[str, Any]]]: ``full_name``, ``feature``,
``value`` (document units), ``system_value`` (metres / radians)
- and ``read_only`` per dimension.
+ and ``read_only`` per dimension, in tree order.
"""
guard = self._require_doc_type({1, 2}, "list_model_dimensions")
if guard is not None:
@@ -404,56 +437,25 @@ async def list_model_dimensions(
target = (feature_name or "").strip().lower()
def _list() -> list[dict[str, Any]]:
- model = self.currentModel
dims: list[dict[str, Any]] = []
- feature = self._attempt(lambda: model.FirstFeature(), default=None)
- guard_count = 0
- while feature is not None and guard_count < 20000:
- guard_count += 1
- feat = _sw_type_info.flagged(feature, "IFeature")
- name = str(self._attempt(lambda f=feat: f.Name, default="") or "")
- if not target or name.lower() == target:
- display = self._attempt(
- lambda f=feat: f.GetFirstDisplayDimension(), default=None
+ seen: set[str] = set()
+ for item in walk_feature_tree(self, self.currentModel):
+ if _is_folder(item.type_name):
+ continue
+ for row in self._read_display_dimensions(item.feature, item.name):
+ full_name = row["full_name"]
+ if full_name is not None:
+ if full_name in seen:
+ continue
+ seen.add(full_name)
+ dims.append(row)
+ if target:
+ dims = [d for d in dims if d["feature"].lower() == target]
+ if not dims:
+ raise LookupError(
+ f"No dimensions found on feature {feature_name!r}; list "
+ "the feature tree with list_features for exact names"
)
- while display is not None:
- disp = _sw_type_info.flagged(display, "IDisplayDimension")
- dim = self._attempt(
- lambda d=disp: d.GetDimension2(0), default=None
- )
- if dim is not None:
- dim = _sw_type_info.flagged(dim, "IDimension")
- dims.append(
- {
- "full_name": _strip_document_suffix(
- self._attempt(
- lambda d=dim: d.FullName, default=None
- )
- ),
- "feature": name,
- "value": self._attempt(
- lambda d=dim: d.Value, default=None
- ),
- "system_value": self._attempt(
- lambda d=dim: d.SystemValue, default=None
- ),
- "read_only": bool(
- self._attempt(
- lambda d=dim: d.ReadOnly, default=False
- )
- ),
- }
- )
- display = self._attempt(
- lambda f=feat, d=display: f.GetNextDisplayDimension(d),
- default=None,
- )
- feature = self._attempt(lambda f=feat: f.GetNextFeature(), default=None)
- if target and not dims:
- raise LookupError(
- f"No dimensions found on feature {feature_name!r}; list "
- "the feature tree with list_features for exact names"
- )
return dims
return cast(
@@ -461,6 +463,50 @@ def _list() -> list[dict[str, Any]]:
self._handle_com_operation("list_model_dimensions", _list),
)
+ def _read_display_dimensions(
+ self, feature: Any, feature_name: str
+ ) -> list[dict[str, Any]]:
+ """Read one feature's display dimensions.
+
+ Args:
+ feature: The ``IFeature`` dispatch.
+ feature_name: Its name, used as ``feature`` when a dimension's
+ full name can't be read.
+
+ Returns:
+ list[dict[str, Any]]: One row per dimension SolidWorks lists under
+ the feature, with ``feature`` taken from the full name's ``@``
+ suffix.
+ """
+ feat = _sw_type_info.flagged(feature, "IFeature")
+ rows: list[dict[str, Any]] = []
+ display = self._attempt(lambda: feat.GetFirstDisplayDimension(), default=None)
+ while display is not None:
+ disp = _sw_type_info.flagged(display, "IDisplayDimension")
+ dim = self._attempt(lambda d=disp: d.GetDimension2(0), default=None)
+ if dim is not None:
+ dim = _sw_type_info.flagged(dim, "IDimension")
+ full_name = _strip_document_suffix(
+ self._attempt(lambda d=dim: d.FullName, default=None)
+ )
+ rows.append(
+ {
+ "full_name": full_name,
+ "feature": _owning_feature(full_name) or feature_name,
+ "value": self._attempt(lambda d=dim: d.Value, default=None),
+ "system_value": self._attempt(
+ lambda d=dim: d.SystemValue, default=None
+ ),
+ "read_only": bool(
+ self._attempt(lambda d=dim: d.ReadOnly, default=False)
+ ),
+ }
+ )
+ display = self._attempt(
+ lambda d=display: feat.GetNextDisplayDimension(d), default=None
+ )
+ return rows
+
async def measure_entities(
self, entities: list[str]
) -> AdapterResult[dict[str, Any]]:
diff --git a/src/solidworks_mcp/adapters/solidworks/face_selection.py b/src/solidworks_mcp/adapters/solidworks/face_selection.py
index 3085f31f..138164b8 100644
--- a/src/solidworks_mcp/adapters/solidworks/face_selection.py
+++ b/src/solidworks_mcp/adapters/solidworks/face_selection.py
@@ -208,7 +208,7 @@ def edge_matches(kind: str, edge_type: str) -> bool:
#: Exactly the members read below. Flagging a whole interface costs ~27 ms
-#: per fresh dispatch (see ``_WALK_MEMBERS`` in pywin32_adapter); a face can
+#: per fresh dispatch (see ``WALK_MEMBERS`` in feature_walk); a face can
#: hand back dozens of edges/curves/vertices, so flag just what is used.
_EDGE_MEMBERS = ("GetCurve", "GetStartVertex", "GetEndVertex", "Select4")
_FACE_MEMBERS = ("GetBox", "GetArea", "GetEdges", "GetClosestPointOn")
diff --git a/src/solidworks_mcp/adapters/solidworks/feature_walk.py b/src/solidworks_mcp/adapters/solidworks/feature_walk.py
new file mode 100644
index 00000000..2688c0fd
--- /dev/null
+++ b/src/solidworks_mcp/adapters/solidworks/feature_walk.py
@@ -0,0 +1,115 @@
+"""The one walk of a document's top-level feature tree.
+
+``list_features`` and ``list_model_dimensions`` both read the tree through
+:func:`walk_feature_tree`, so they always see the same features in the same
+order.
+
+SolidWorks can stop ``IFeature.GetNextFeature`` at the system folders even
+though later sketches and features exist, so the walk always makes a second
+pass with ``IModelDoc2.FeatureByPositionReverse``. Both passes number a
+feature by its place in the tree (the forward pass counts from 0, the
+reverse pass uses ``count - reverse_position - 1``), so a feature found by
+both gets one number, and sorting by it gives tree order, oldest first.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .com_utils import attempt, flag
+
+#: The ``IFeature`` members the walk and its callers read. Flagging only these
+#: keeps each fresh dispatch cheap (a whole interface costs ~27 ms).
+WALK_MEMBERS = ("GetNextFeature", "GetTypeName2", "IsSuppressed", "IsSuppressed2")
+
+#: Upper bound on the forward walk, against a feature chain that loops.
+_MAX_FORWARD_STEPS = 10000
+
+
+@dataclass(frozen=True)
+class TreeFeature:
+ """One top-level feature found by the walk.
+
+ Attributes:
+ position: Its place in the tree, 0 for the first.
+ name: The feature's name.
+ type_name: Its ``GetTypeName2`` type, ``"Unknown"`` when unreadable.
+ feature: The ``IFeature`` dispatch, for reading more from it.
+ """
+
+ position: int
+ name: str
+ type_name: str
+ feature: Any
+
+
+def _describe(adapter: Any, feature: Any, position: int) -> TreeFeature:
+ """Read one feature's name and type into a :class:`TreeFeature`.
+
+ Args:
+ adapter: The adapter, for ``_attempt`` and ``_get_attr_or_call``.
+ feature: The ``IFeature`` dispatch.
+ position: Its place in the tree.
+
+ Returns:
+ TreeFeature: The feature with its name and type.
+ """
+ type_name = attempt(
+ adapter,
+ lambda: adapter._get_attr_or_call(feature, "GetTypeName2"),
+ "Unknown",
+ )
+ return TreeFeature(
+ position=position,
+ name=str(getattr(feature, "Name", "")),
+ type_name=str(type_name),
+ feature=feature,
+ )
+
+
+def walk_feature_tree(adapter: Any, document: Any) -> list[TreeFeature]:
+ """Every top-level feature of ``document``, once each, in tree order.
+
+ Args:
+ adapter: The adapter, for ``_attempt`` and ``_get_attr_or_call``.
+ document: The ``IModelDoc2`` dispatch to walk.
+
+ Returns:
+ list[TreeFeature]: The features, sorted by tree position. A feature
+ found by both passes (same name and type) is kept once.
+ """
+ found: list[TreeFeature] = []
+ seen: set[tuple[str, str]] = set()
+
+ def _keep(feature: Any, position: int) -> None:
+ item = _describe(adapter, feature, position)
+ key = (item.name, item.type_name)
+ if key not in seen:
+ seen.add(key)
+ found.append(item)
+
+ feature = attempt(adapter, lambda: document.FirstFeature())
+ position = 0
+ while feature is not None and position < _MAX_FORWARD_STEPS:
+ flag(adapter, feature, *WALK_MEMBERS)
+ _keep(feature, position)
+ position += 1
+ feature = attempt(adapter, lambda f=feature: f.GetNextFeature())
+
+ feature_manager = getattr(document, "FeatureManager", None)
+ count = attempt(
+ adapter,
+ lambda: int(feature_manager.GetFeatureCount(True) or 0), # type: ignore[union-attr]
+ 0,
+ )
+ # FeatureByPositionReverse is zero-based: 0 is the newest feature.
+ for reverse_position in range(count):
+ feature = attempt(
+ adapter, lambda p=reverse_position: document.FeatureByPositionReverse(p)
+ )
+ if feature is not None:
+ _keep(feature, count - reverse_position - 1)
+
+ found.sort(key=lambda item: item.position)
+ return found
diff --git a/src/solidworks_mcp/adapters/solidworks/features.py b/src/solidworks_mcp/adapters/solidworks/features.py
index 278b43ab..5ff82db0 100644
--- a/src/solidworks_mcp/adapters/solidworks/features.py
+++ b/src/solidworks_mcp/adapters/solidworks/features.py
@@ -2977,7 +2977,7 @@ def _select_face_at_point(adapter: Any, point_mm: list[float], mark: int) -> boo
face = selector.face_at_point(selector.faces(), point_mm)
if not face.is_planar:
raise LookupError(
- f"The face at {list(point_mm)} mm is not flat; a plane needs a flat face."
+ f"The face at {list(point_mm)} mm is not flat; a plane or a sketch needs a flat face."
)
sel_mgr = adapter.currentModel.SelectionManager
_flag(adapter, sel_mgr, "CreateSelectData")
diff --git a/src/solidworks_mcp/adapters/solidworks/sketch.py b/src/solidworks_mcp/adapters/solidworks/sketch.py
index 6b76c9d2..f139ba51 100644
--- a/src/solidworks_mcp/adapters/solidworks/sketch.py
+++ b/src/solidworks_mcp/adapters/solidworks/sketch.py
@@ -100,8 +100,12 @@ def _angular_dimension_placement(
adapter._sketch_geometry.angular_dimension_placement(entity1, entity2),
)
- async def create_sketch(self, plane: str) -> AdapterResult[str]:
- return _create_sketch_impl(self, plane)
+ async def create_sketch(
+ self,
+ plane: str | None,
+ face_point: tuple[float, float, float] | None = None,
+ ) -> AdapterResult[str]:
+ return _create_sketch_impl(self, plane, face_point)
async def add_line(
self, x1: float, y1: float, x2: float, y2: float
@@ -202,8 +206,146 @@ async def check_sketch_fully_defined(
return _check_sketch_fully_defined_impl(self, sketch_name)
-def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]:
- """Open a new sketch on a named reference plane.
+def _select_sketch_plane(adapter: Any, plane: str) -> None:
+ """Select the reference plane a new sketch opens on.
+
+ Tries the plane's locale aliases by name (``FeatureByName`` then
+ ``Select2``), then ``Extension.SelectByID2`` with type ``"PLANE"``.
+
+ Args:
+ adapter: A connected adapter with a part open.
+ plane: The plane's short or full name.
+
+ Raises:
+ Exception: If no plane candidate could be selected.
+ """
+ plane_name_map = {
+ "Top": "Top Plane",
+ "Front": "Front Plane",
+ "Right": "Right Plane",
+ "XY": "Top Plane",
+ "XZ": "Front Plane",
+ "YZ": "Right Plane",
+ }
+
+ semantic_plane_aliases = {
+ "Top": ["Top Plane", "Planta", "上视基准面", "上視基準面"],
+ "Front": ["Front Plane", "Alzado", "前视基准面", "前視基準面"],
+ "Right": ["Right Plane", "Vista lateral", "右视基准面", "右視基準面"],
+ "XY": ["Top Plane", "Planta", "上视基准面"],
+ "XZ": ["Front Plane", "Alzado", "前视基准面"],
+ "YZ": ["Right Plane", "Vista lateral", "右视基准面"],
+ }
+
+ actual_plane = plane_name_map.get(plane, plane)
+ selected = False
+ selection_error = None
+
+ plane_candidates = [
+ *semantic_plane_aliases.get(plane, []),
+ actual_plane,
+ plane,
+ "Top Plane",
+ "Front Plane",
+ "Right Plane",
+ "Planta",
+ "Alzado",
+ "Vista lateral",
+ "上视基准面",
+ "前视基准面",
+ "右视基准面",
+ "上視基準面",
+ "前視基準面",
+ "右視基準面",
+ ]
+ for candidate in plane_candidates:
+ if not candidate:
+ continue
+ plane_feature, selection_error_candidate = adapter._attempt_with_error(
+ lambda c=candidate: adapter.currentModel.FeatureByName(c)
+ )
+ if selection_error_candidate:
+ selection_error = selection_error_candidate
+ continue
+ selected = bool(
+ plane_feature
+ and adapter._attempt(
+ lambda pf=plane_feature: pf.Select2(False, 0), default=False
+ )
+ )
+ if selected:
+ break
+
+ if not selected:
+ # SW 2022: callout must be None (empty string causes type mismatch)
+ selected, selection_error_candidate = adapter._attempt_with_error(
+ lambda: adapter.currentModel.Extension.SelectByID2(
+ actual_plane,
+ "PLANE",
+ 0,
+ 0,
+ 0,
+ False,
+ 0,
+ None,
+ 0,
+ )
+ )
+ if selection_error_candidate:
+ selection_error = selection_error_candidate
+ elif selected:
+ pass
+
+ if not selected:
+ if selection_error:
+ raise Exception(
+ f"Failed to select plane: {actual_plane} ({selection_error})"
+ )
+ raise Exception(f"Failed to select plane: {actual_plane}")
+
+
+def _select_sketch_face(adapter: Any, face_point: tuple[float, float, float]) -> None:
+ """Select the flat face of the active part at ``face_point`` for a sketch.
+
+ Uses the same face lookup as ``create_reference_plane``'s ``face_point``
+ (the body face whose closest point is within 0.01 mm, which must be
+ flat). On any failure the selection is cleared, so no sketch opens on a
+ stale selection.
+
+ Args:
+ adapter: A connected adapter with a part open.
+ face_point: ``(x, y, z)`` in mm on the face.
+
+ Raises:
+ LookupError: When no flat face lies at the point.
+ """
+ from .features import _select_face_at_point
+
+ point = [float(c) for c in face_point]
+ adapter._attempt(lambda: adapter.currentModel.ClearSelection2(True), default=None)
+ try:
+ selected = _select_face_at_point(adapter, point, 0)
+ reason = "SolidWorks would not select it"
+ except LookupError as exc:
+ selected, reason = False, str(exc)
+ if not selected:
+ adapter._attempt(
+ lambda: adapter.currentModel.ClearSelection2(True), default=None
+ )
+ raise LookupError(
+ f"face_point {point} mm is not on a flat face of the active part ({reason})"
+ )
+
+
+def _create_sketch_impl(
+ adapter: Any,
+ plane: str | None,
+ face_point: tuple[float, float, float] | None = None,
+) -> AdapterResult[str]:
+ """Open a new sketch on a named reference plane, or on a flat face.
+
+ With ``face_point``, the flat face of the active part at that point is
+ selected (see :func:`_select_sketch_face`) in place of a plane.
The function resolves English short-hand names (``"Top"``, ``"Front"``,
``"Right"``, ``"XY"``, ``"XZ"``, ``"YZ"``) to their full SolidWorks plane
@@ -224,7 +366,8 @@ def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]:
plane: Reference-plane identifier. Accepts short English names
(``"Top"``, ``"Front"``, ``"Right"``, ``"XY"``, ``"XZ"``,
``"YZ"``) or the exact SolidWorks plane name as it appears in
- the FeatureManager tree.
+ the FeatureManager tree. Ignored when ``face_point`` is given.
+ face_point: ``(x, y, z)`` in mm on a flat face of the active part.
Returns:
AdapterResult[str]: On success, ``data`` is the sketch name string
@@ -232,7 +375,8 @@ def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]:
Raises:
Exception: Propagated through ``_handle_com_operation`` when no plane
- candidate can be selected.
+ candidate can be selected, or (as ``LookupError``) when
+ ``face_point`` is not on a flat face.
Example::
@@ -245,100 +389,19 @@ def _create_sketch_impl(adapter: Any, plane: str) -> AdapterResult[str]:
return AdapterResult(status=AdapterResultStatus.ERROR, error="No active model")
def _sketch_operation() -> str:
- """Inner COM closure that selects the plane and opens the sketch.
-
- Iterates through all locale aliases and ``SelectByID2`` fallbacks.
- Updates adapter sketch state on success.
+ """Inner COM closure that selects the plane or face and opens the sketch.
Returns:
str: The resolved SolidWorks sketch name.
Raises:
Exception: If no plane candidate could be selected.
+ LookupError: If ``face_point`` is not on a flat face.
"""
- plane_name_map = {
- "Top": "Top Plane",
- "Front": "Front Plane",
- "Right": "Right Plane",
- "XY": "Top Plane",
- "XZ": "Front Plane",
- "YZ": "Right Plane",
- }
-
- semantic_plane_aliases = {
- "Top": ["Top Plane", "Planta", "上视基准面", "上視基準面"],
- "Front": ["Front Plane", "Alzado", "前视基准面", "前視基準面"],
- "Right": ["Right Plane", "Vista lateral", "右视基准面", "右視基準面"],
- "XY": ["Top Plane", "Planta", "上视基准面"],
- "XZ": ["Front Plane", "Alzado", "前视基准面"],
- "YZ": ["Right Plane", "Vista lateral", "右视基准面"],
- }
-
- actual_plane = plane_name_map.get(plane, plane)
- selected = False
- selection_error = None
-
- plane_candidates = [
- *semantic_plane_aliases.get(plane, []),
- actual_plane,
- plane,
- "Top Plane",
- "Front Plane",
- "Right Plane",
- "Planta",
- "Alzado",
- "Vista lateral",
- "上视基准面",
- "前视基准面",
- "右视基准面",
- "上視基準面",
- "前視基準面",
- "右視基準面",
- ]
- for candidate in plane_candidates:
- if not candidate:
- continue
- plane_feature, selection_error_candidate = adapter._attempt_with_error(
- lambda c=candidate: adapter.currentModel.FeatureByName(c)
- )
- if selection_error_candidate:
- selection_error = selection_error_candidate
- continue
- selected = bool(
- plane_feature
- and adapter._attempt(
- lambda pf=plane_feature: pf.Select2(False, 0), default=False
- )
- )
- if selected:
- break
-
- if not selected:
- # SW 2022: callout must be None (empty string causes type mismatch)
- selected, selection_error_candidate = adapter._attempt_with_error(
- lambda: adapter.currentModel.Extension.SelectByID2(
- actual_plane,
- "PLANE",
- 0,
- 0,
- 0,
- False,
- 0,
- None,
- 0,
- )
- )
- if selection_error_candidate:
- selection_error = selection_error_candidate
- elif selected:
- pass
-
- if not selected:
- if selection_error:
- raise Exception(
- f"Failed to select plane: {actual_plane} ({selection_error})"
- )
- raise Exception(f"Failed to select plane: {actual_plane}")
+ if face_point is not None:
+ _select_sketch_face(adapter, face_point)
+ else:
+ _select_sketch_plane(adapter, str(plane or ""))
adapter.currentSketchManager = adapter.currentModel.SketchManager
adapter._attempt(
diff --git a/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md b/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md
index 85e9e069..b40385f8 100644
--- a/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md
+++ b/src/solidworks_mcp/skills/solidworks-mcp/references/workflows.md
@@ -28,8 +28,14 @@ step. Values are examples; sizes are millimetres.
## Sketching somewhere other than the three planes
-`create_reference_plane` with `reference: "Top Plane"` and `offset: 10` makes
-a plane 10 mm up; its name (e.g. "Plane1") goes into `create_sketch`.
+On a flat face of the body: `create_sketch` with `face_point`, a point on the
+face in mm (e.g. `[0, 20, 0]` on the top of a 20 mm tall block). The sketch
+sits on the face, so a cut made from it follows the face when a dimension
+changes later. Prefer this to a plane at the same height.
+
+Away from the body: `create_reference_plane` with `reference: "Top Plane"`
+and `offset: 10` makes a plane 10 mm up; its name (e.g. "Plane1") goes into
+`create_sketch`.
- At an angle: `create_axis` first (its reply names the axis, e.g. "Axis1"),
then `reference`, `angle` (degrees) and `axis`.
diff --git a/src/solidworks_mcp/tools/analysis.py b/src/solidworks_mcp/tools/analysis.py
index 8fa739a0..f91db70c 100644
--- a/src/solidworks_mcp/tools/analysis.py
+++ b/src/solidworks_mcp/tools/analysis.py
@@ -155,7 +155,10 @@ def _count_modelling_features(descriptors: list[dict[str, Any]]) -> list[str]:
Skips component features, sketches, the origin, folders, the mate group
and the first three reference planes (the default ones, matched by
- position so it works in any SolidWorks language).
+ position so it works in any SolidWorks language). The rows are put in
+ tree order by their ``position`` first, so the default planes are found
+ whatever order an adapter returned them in; a row without a position
+ keeps its place.
Args:
descriptors: ``list_features`` rows.
@@ -163,9 +166,13 @@ def _count_modelling_features(descriptors: list[dict[str, Any]]) -> list[str]:
Returns:
list[str]: Counted feature names, in tree order.
"""
+ ordered = sorted(
+ enumerate(descriptors),
+ key=lambda item: (item[1].get("position", item[0]), item[0]),
+ )
names: list[str] = []
planes_seen = 0
- for row in descriptors:
+ for _, row in ordered:
if row.get("component") is not None:
continue
kind = str(row.get("type") or "")
diff --git a/src/solidworks_mcp/tools/engineering_data.py b/src/solidworks_mcp/tools/engineering_data.py
index 0e1819fd..7cd1e1e0 100644
--- a/src/solidworks_mcp/tools/engineering_data.py
+++ b/src/solidworks_mcp/tools/engineering_data.py
@@ -216,13 +216,15 @@ async def list_model_dimensions(
Use it to find a dimension in an existing model before changing it: each
`full_name` (e.g. "D1@Sketch1") is the name `get_dimension` and `set_dimension`
- take. Needs: an open part or assembly. Read-only. Returns: `data`, one entry per
- dimension with `full_name`, `feature`, `value` (document units), `system_value`
- (metres or radians) and `read_only`.
+ take. Each dimension is listed once, under the feature its full name names
+ after the `@` (`D1@Plane1` under `Plane1`, never also under a cut sketched on
+ that plane). Needs: an open part or assembly. Read-only. Returns: `data`, one
+ entry per dimension with `full_name`, `feature`, `value` (document units),
+ `system_value` (metres or radians) and `read_only`.
Args:
- input_data: Nothing is required: give `feature_name` to list one
- feature's dimensions, or omit it for every dimension.
+ input_data: Nothing is required: give `feature_name` to list the
+ dimensions that feature owns, or omit it for every dimension.
Returns:
dict[str, Any]: The dimensions.
diff --git a/src/solidworks_mcp/tools/error_classifier.py b/src/solidworks_mcp/tools/error_classifier.py
index bf2ce1ad..d18457bd 100644
--- a/src/solidworks_mcp/tools/error_classifier.py
+++ b/src/solidworks_mcp/tools/error_classifier.py
@@ -163,6 +163,15 @@ def matches(self, message: str, hresult: int | None) -> bool:
),
patterns=(r"built no feature",),
),
+ ErrorRule(
+ error_type=INVALID_INPUT,
+ hint=(
+ "face_point must lie on a flat face of the active part's body, in "
+ "mm. Read the faces' centres with select_face_edges, or sketch on "
+ "a plane instead."
+ ),
+ patterns=(r"face_point \[[^\]]*\] mm is not on a flat face",),
+ ),
ErrorRule(
error_type="not_found",
hint=(
diff --git a/src/solidworks_mcp/tools/export.py b/src/solidworks_mcp/tools/export.py
index 9da6a74b..40e1cd6f 100644
--- a/src/solidworks_mcp/tools/export.py
+++ b/src/solidworks_mcp/tools/export.py
@@ -285,7 +285,8 @@ async def export_stl(input_data: ExportFileInput) -> dict[str, Any]:
extension, so end `file_path` in .stl. Needs: an open, active part or assembly.
Changes: writes the file, creating its folder and replacing a file already
there; the open document is unchanged. Returns: `export` with `file_path` and
- `format`.
+ `format`, plus `warning` when SolidWorks wrote the file without its STL options
+ (bodies not merged into one file).
Args:
input_data: The export. `file_path` (ending in .stl) is required;
@@ -309,7 +310,7 @@ async def export_stl(input_data: ExportFileInput) -> dict[str, Any]:
"data": result.data,
"execution_time": result.execution_time,
}
- return {
+ reply: dict[str, Any] = {
"status": "success",
"message": f"Exported to STL format: {input_data.file_path}",
"export": {
@@ -320,6 +321,11 @@ async def export_stl(input_data: ExportFileInput) -> dict[str, Any]:
},
"execution_time": result.execution_time,
}
+ # The adapter's data is a dict only when its fallback wrote the file
+ # without the STL options.
+ if isinstance(result.data, dict) and result.data.get("warning"):
+ reply["warning"] = result.data["warning"]
+ return reply
@mcp.tool()
async def export_pdf(input_data: ExportFileInput) -> dict[str, Any]:
diff --git a/src/solidworks_mcp/tools/sketching.py b/src/solidworks_mcp/tools/sketching.py
index 7b8a8e0e..2d2f3b6b 100644
--- a/src/solidworks_mcp/tools/sketching.py
+++ b/src/solidworks_mcp/tools/sketching.py
@@ -27,12 +27,25 @@ class CreateSketchInput(CompatInput):
"""Input schema for creating a sketch.
Attributes:
- plane (str): The plane value.
+ plane (str | None): The plane to sketch on.
+ face_point (list[float] | None): A point on a flat face to sketch on
+ instead.
sketch_name (str | None): The sketch name value.
"""
- plane: str = Field(
- description="Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ')"
+ plane: str | None = Field(
+ default=None,
+ description=(
+ "Sketch plane name (e.g., 'Top', 'Front', 'Right', 'XY', 'XZ', 'YZ', "
+ "or a plane made by create_reference_plane). Give this or face_point"
+ ),
+ )
+ face_point: list[float] | None = Field(
+ default=None,
+ description=(
+ "[x, y, z] in mm on a flat face of the part's body; the sketch opens "
+ "on that face and follows it when the model changes. Give this or plane"
+ ),
)
sketch_name: str | None = Field(
default=None,
@@ -44,19 +57,20 @@ class CreateSketchInput(CompatInput):
)
def model_post_init(self, __context: Any) -> None:
- """Provide model post init support for the create sketch input.
+ """Require exactly one of ``plane`` and ``face_point``.
Args:
__context (Any): The context value.
- Returns:
- None: None.
-
Raises:
- ValueError: Plane is required.
+ ValueError: When both or neither are given, or ``face_point`` is not
+ three numbers.
"""
- if not self.plane.strip():
- raise ValueError("plane is required")
+ has_plane = bool((self.plane or "").strip())
+ if has_plane == (self.face_point is not None):
+ raise ValueError("give exactly one of plane and face_point")
+ if self.face_point is not None and len(self.face_point) != 3:
+ raise ValueError("face_point must be [x, y, z] in millimetres")
class AddLineInput(CompatInput):
@@ -351,25 +365,43 @@ async def register_sketching_tools(
@mcp.tool()
async def create_sketch(input_data: CreateSketchInput) -> dict[str, Any]:
- """Open a new sketch on a plane of the active part, ready for lines, circles and other sketch entities.
+ """Open a new sketch on a plane or a flat face of the active part, ready for lines, circles and other sketch entities.
Use it first in every feature: sketch, draw, `exit_sketch`, then
`create_extrusion` or `create_cut_extrude`. Planes: Front, Top, Right (or XY,
- XZ, YZ), or a plane made by `create_reference_plane`. Coordinates in the sketch
- are mm from the origin. Needs: an open part. Changes: adds a sketch and opens it
- for editing; give `sketch_name` and `exit_sketch` names it that when it closes
- it (SolidWorks won't rename an open sketch). Returns: `sketch` with `name` (the
- name in the feature tree now) and `plane`, plus `name_on_exit` when you gave
- `sketch_name`.
+ XZ, YZ), or a plane made by `create_reference_plane`. Or give `face_point`, a
+ point in mm on a flat face of the body: the sketch opens on that face and moves
+ with it when the model changes. Coordinates in the sketch are mm from the
+ origin. Needs: an open part. Changes: adds a sketch and opens it for editing;
+ give `sketch_name` and `exit_sketch` names it that when it closes it (SolidWorks
+ won't rename an open sketch). Returns: `sketch` with `name` (the name in the
+ feature tree now) and `plane` (or `face_point`), plus `name_on_exit` when you
+ gave `sketch_name`. A `face_point` not on a flat face fails with
+ `invalid_input`.
Args:
- input_data: The sketch. `plane` is required; `sketch_name` names it.
+ input_data: The sketch. Exactly one of `plane` and `face_point`;
+ `sketch_name` names it.
Returns:
dict[str, Any]: The new sketch.
"""
input_data = normalize_input(input_data, CreateSketchInput)
- result = await adapter.create_sketch(input_data.plane)
+ face_point = (
+ (
+ float(input_data.face_point[0]),
+ float(input_data.face_point[1]),
+ float(input_data.face_point[2]),
+ )
+ if input_data.face_point is not None
+ else None
+ )
+ if face_point is None:
+ result = await adapter.create_sketch(input_data.plane)
+ where = f"{input_data.plane} plane"
+ else:
+ result = await adapter.create_sketch(None, face_point)
+ where = f"the face at {list(face_point)} mm"
require_success(result, context="Failed to create sketch")
sketch_name = (
@@ -377,13 +409,13 @@ async def create_sketch(input_data: CreateSketchInput) -> dict[str, Any]:
if isinstance(result.data, dict)
else result.data
)
+ sketch: dict[str, Any] = {"name": sketch_name, "plane": input_data.plane}
+ if face_point is not None:
+ sketch["face_point"] = list(face_point)
reply: dict[str, Any] = {
"status": "success",
- "message": f"Created sketch '{sketch_name}' on {input_data.plane} plane",
- "sketch": {
- "name": sketch_name,
- "plane": input_data.plane,
- },
+ "message": f"Created sketch '{sketch_name}' on {where}",
+ "sketch": sketch,
"execution_time": result.execution_time,
}
names_on_exit.clear() # a sketch left open is abandoned with its name
diff --git a/tests/live/test_live_sw_monitor_stand_demo.py b/tests/live/test_live_sw_monitor_stand_demo.py
index 1cc0763f..a587b0a6 100644
--- a/tests/live/test_live_sw_monitor_stand_demo.py
+++ b/tests/live/test_live_sw_monitor_stand_demo.py
@@ -7,13 +7,17 @@
each call a captioned frame. The stand is built at the script's defaults,
the part as the user finished it: 66 mm tall, a 26 mm top, R25 arches and an
11.46 mm pocket. ``build()`` checks it with ``verify_model`` against a hand
-calculation before saving and exporting an STL. The last frame is the part
-in an isometric view.
+calculation before saving and exporting an STL. The camera turns to the
+isometric view after the extrusion, each cut and the fillet, and the last
+frame is the finished part.
+
+A second test (not recorded) builds the stand again, raises its height in
+the extrusion's dimension, and checks the pocket followed the top face.
Record it with::
powershell -ExecutionPolicy Bypass -File tests\\scripts\\live_demo.ps1 `
- -Test tests/live/test_live_sw_monitor_stand_demo.py `
+ -Test tests/live/test_live_sw_monitor_stand_demo.py::test_monitor_stand_from_prompt_to_part `
-CaptureDir docs/assets/demos/monitor-stand -Record -PromptSeconds 12
Collected only with ``SOLIDWORKS_MCP_RUN_REAL_INTEGRATION=1`` on Windows (see
@@ -65,11 +69,12 @@
_PROMPT_MAX_LINES = 26
_PROMPT_WRAP_CHARS = 70
-#: swStandardViews_e (swconst.tlb, SW 2026): the isometric view.
-_ISO_VIEW = 7
-#: Calls after which the camera turns to the isometric view: from the first
-#: solid on, the cuts, arches and pocket are seen in 3D.
-_LOOK_AFTER = {"create_extrusion"}
+#: The stand's volume at the script's defaults, measured on SolidWorks 2026
+#: in the session that built it (issue #206). The script's hand calculation
+#: leaves out a small blend and reads about 0.3 % low.
+_MEASURED_VOLUME_MM3 = 901_769.0
+#: How much the height is raised in the follow-the-height test, in mm.
+_RAISE_MM = 4.0
def _load_script() -> Any:
@@ -90,16 +95,6 @@ def _prompt_lines() -> list[str]:
return lines
-def _look(adapter: Any, view: int) -> None:
- """Point the camera for the demo: a standard view, zoomed to fit.
-
- Staging for the recording, not a tool call: an agent does not need it.
- """
- model = adapter.currentModel
- adapter._attempt(lambda: model.ShowNamedView2("", view), default=None)
- adapter._zoom_to_fit(model)
-
-
def _brief(result: dict[str, Any]) -> dict[str, Any]:
"""The part of a reply worth a caption: its message and what it measured."""
shown: dict[str, Any] = {"message": result.get("message")}
@@ -145,8 +140,6 @@ async def __call__(
self.calls.append({"tool": name, "args": args or {}})
self.results[name] = result
assert result.get("status") == "success", f"{name}: {result.get('message')}"
- if name in _LOOK_AFTER:
- _look(self.adapter, _ISO_VIEW)
brief = _brief(result)
brief["message"] = str(brief["message"]).replace(self.prefix, "")
evidence(label, brief, call=shown)
@@ -166,14 +159,25 @@ async def test_monitor_stand_from_prompt_to_part(scratch: Any, tmp_path: Path) -
evidence("the prompt", _prompt_lines(), max_lines=_PROMPT_MAX_LINES)
- await script.build(stand, out, replace=False, stl=True, call=call)
+ await script.build(
+ stand,
+ out,
+ replace=False,
+ stl=True,
+ call=call,
+ look=lambda: script.look_isometric(adapter),
+ )
assert out.is_file(), out
assert out.with_suffix(".stl").is_file()
check = call.results["verify_model"]
assert check["verdict"] == "pass", check
+ assert check["measured"]["volume_mm3"] == pytest.approx(
+ _MEASURED_VOLUME_MM3, rel=1e-3
+ )
+ assert "create_reference_plane" not in [c["tool"] for c in call.calls]
- _look(adapter, _ISO_VIEW)
+ script.look_isometric(adapter)
evidence(
f"the finished stand, isometric: {len(call.calls)} tool calls, all successful",
{
@@ -182,3 +186,54 @@ async def test_monitor_stand_from_prompt_to_part(scratch: Any, tmp_path: Path) -
"saved": [out.name, out.with_suffix(".stl").name],
},
)
+
+
+@pytest.mark.asyncio
+@pytest.mark.timeout(900)
+async def test_the_pocket_follows_a_raised_height(scratch: Any, tmp_path: Path) -> None:
+ """Raise the stand by editing its extrusion; the pocket moves with the top.
+
+ The pocket is sketched on the top face, so after the block's depth goes
+ from 66 to 70 mm the part grows by exactly the plate's footprint times
+ 4 mm, and the pocket is still 11.46 mm deep from the new top. A pocket on
+ a plane fixed at 66 mm would leave the volume short by the pocket's
+ footprint times 4 mm.
+ """
+ script = _load_script()
+ stand = script.Stand()
+ adapter = scratch.adapter
+ call = script.Session(await script._tools(adapter))
+ out = tmp_path / "MonitorStandRaised.SLDPRT"
+ scratch.written_files.append(str(out))
+
+ # build() ends with verify_model, so the stand is right before the edit.
+ await script.build(stand, out, replace=False, stl=False, call=call)
+
+ raised = stand.height + _RAISE_MM
+ await call("set_dimension", {"name": "D1@Boss-Extrude1", "value": raised})
+ await call("rebuild_model")
+ check = await call(
+ "verify_model",
+ {
+ "bounding_box_mm": [
+ round(stand.width, 4),
+ round(raised, 4),
+ round(stand.depth, 4),
+ ],
+ "volume_mm3": round(
+ _MEASURED_VOLUME_MM3 + stand.width * stand.depth * _RAISE_MM, 1
+ ),
+ "solid_body_count": 1,
+ "relative_tolerance": 0.002,
+ },
+ )
+
+ evidence(
+ "the pocket followed the top face",
+ {
+ "height_mm": raised,
+ "volume_after_mm3": round(check["measured"]["volume_mm3"], 1),
+ "verdict": check["verdict"],
+ },
+ )
+ assert check["verdict"] == "pass", check
diff --git a/tests/live/test_live_sw_monitor_stand_follow_ups.py b/tests/live/test_live_sw_monitor_stand_follow_ups.py
new file mode 100644
index 00000000..31f55c91
--- /dev/null
+++ b/tests/live/test_live_sw_monitor_stand_follow_ups.py
@@ -0,0 +1,251 @@
+"""The monitor-stand follow-ups (issue #206), checked on real SolidWorks.
+
+One bundle, run together after the work is done, then failures are fixed one
+at a time:
+
+1. ``list_features`` comes back in tree order, and ``verify_model`` counts
+ ``Plane1`` and not ``Front Plane``;
+2. a diagnostic of the dimension listing on the monitor stand: how many
+ features the old forward-only walk and the shared walk find, and whether
+ the full listing holds every dimension the per-feature calls find;
+3. ``export_stl`` writes through ``SaveAs2`` with its options (no warning);
+4. ``create_sketch`` on a face: the top face works, a point in the air and
+ a point on a fillet are refused with ``invalid_input``.
+
+The follow-the-height rebuild is in ``test_live_sw_monitor_stand_demo.py``
+(``test_the_pocket_follows_a_raised_height``).
+
+Run one with::
+
+ powershell -ExecutionPolicy Bypass -File tests\\scripts\\live_demo.ps1 `
+ -Test tests/live/test_live_sw_monitor_stand_follow_ups.py::test_feature_order_and_verify_model_with_a_plane
+
+Collected only with ``SOLIDWORKS_MCP_RUN_REAL_INTEGRATION=1`` on Windows (see
+``tests/live/conftest.py``).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from tests.live.evidence import evidence
+from tests.live.test_live_sw_beta_tools import _sketch
+from tests.live.test_live_sw_monitor_stand_demo import _load_script
+
+pytestmark = pytest.mark.asyncio
+
+#: The test block: 40 x 40 mm on the Top Plane, 20 mm tall (top face at y = 20).
+_HALF = 20.0
+_HEIGHT = 20.0
+
+
+async def _tools(adapter: Any) -> dict[str, Any]:
+ """The tool families these tests use, registered on ``adapter``; name -> fn."""
+ from fastmcp import FastMCP
+
+ from solidworks_mcp.tools.analysis import register_analysis_tools
+ from solidworks_mcp.tools.engineering_data import register_engineering_data_tools
+ from solidworks_mcp.tools.export import register_export_tools
+ from solidworks_mcp.tools.file_management import register_file_management_tools
+ from solidworks_mcp.tools.modeling import register_modeling_tools
+ from solidworks_mcp.tools.sketching import register_sketching_tools
+
+ mcp = FastMCP("monitor-stand-follow-ups-live")
+ for register in (
+ register_modeling_tools,
+ register_sketching_tools,
+ register_analysis_tools,
+ register_engineering_data_tools,
+ register_file_management_tools,
+ register_export_tools,
+ ):
+ await register(mcp, adapter, {})
+ return {t.name: t.fn for t in await mcp.list_tools()}
+
+
+async def _block(tools: dict[str, Any]) -> None:
+ """A new part holding the 40 x 40 x 20 mm test block."""
+ assert (await tools["create_part"]({"name": "follow_ups"}))["status"] == "success"
+ await _sketch(tools, "Top", {"x1": -_HALF, "y1": -_HALF, "x2": _HALF, "y2": _HALF})
+ made = await tools["create_extrusion"]({"depth": _HEIGHT})
+ assert made["status"] == "success", made
+
+
+async def _block_with_a_plane_and_a_cut(tools: dict[str, Any]) -> str:
+ """The block, ``Plane1`` on its top, and a 10 x 10 x 3 mm cut on Plane1."""
+ await _block(tools)
+ plane = await tools["create_reference_plane"](
+ {"reference": "Top Plane", "offset": _HEIGHT}
+ )
+ assert plane["status"] == "success", plane
+ plane_name = str(plane["plane"]["name"])
+ sketch = await _sketch(tools, plane_name, {"x1": -5, "y1": -5, "x2": 5, "y2": 5})
+ cut = await tools["create_cut_extrude"](
+ {"sketch_name": sketch, "depth": 3, "end_condition": "Blind"}
+ )
+ assert cut["status"] == "success", cut
+ return plane_name
+
+
+async def test_feature_order_and_verify_model_with_a_plane(scratch: Any) -> None:
+ """Rows in tree order; the agent's plane is counted, Front Plane is not."""
+ tools = await _tools(scratch.adapter)
+ plane_name = await _block_with_a_plane_and_a_cut(tools)
+
+ listed = await tools["list_features"]({})
+ rows = [r for r in listed["features"] if r.get("component") is None]
+ names = [r["name"] for r in rows]
+ positions = [r["position"] for r in rows]
+ verified = await tools["verify_model"]({"feature_count": 3})
+
+ evidence(
+ "list_features order, and verify_model's counted features",
+ {
+ "names": names,
+ "positions": positions,
+ "counted": verified["measured"].get("features"),
+ "verdict": verified["verdict"],
+ },
+ )
+ assert positions == sorted(positions)
+ assert names.index("Front Plane") < names.index(plane_name)
+ assert names.index(plane_name) < names.index("Cut-Extrude1")
+ assert verified["verdict"] == "pass", verified
+ assert plane_name in verified["measured"]["features"]
+ assert "Front Plane" not in verified["measured"]["features"]
+
+
+def _forward_walk_count(adapter: Any) -> int:
+ """How many features the old forward-only walk reaches (test-side COM)."""
+ from solidworks_mcp.adapters import sw_type_info
+
+ count = 0
+ feature = adapter._attempt(lambda: adapter.currentModel.FirstFeature())
+ while feature is not None and count < 10000:
+ count += 1
+ flagged = sw_type_info.flagged(feature, "IFeature")
+ feature = adapter._attempt(lambda f=flagged: f.GetNextFeature())
+ return count
+
+
+async def test_dimension_listing_on_the_monitor_stand(
+ scratch: Any, tmp_path: Path
+) -> None:
+ """The full listing holds every dimension the per-feature calls find."""
+ from solidworks_mcp.adapters.solidworks.feature_walk import walk_feature_tree
+
+ script = _load_script()
+ adapter = scratch.adapter
+ out = tmp_path / "StandDims.SLDPRT"
+ scratch.written_files.append(str(out))
+ await script.build(
+ script.Stand(),
+ out,
+ replace=False,
+ stl=False,
+ call=script.Session(await script._tools(adapter)),
+ )
+ tools = await _tools(adapter)
+
+ walked = walk_feature_tree(adapter, adapter.currentModel)
+ full = await tools["list_model_dimensions"]({})
+ per_feature: dict[str, list[str]] = {}
+ for item in walked:
+ one = await tools["list_model_dimensions"]({"feature_name": item.name})
+ if one["status"] == "success":
+ per_feature[item.name] = [d["full_name"] for d in one["data"]]
+
+ full_names = [d["full_name"] for d in full["data"]]
+ found_by_features = {n for names in per_feature.values() for n in names}
+ evidence(
+ "dimension listing: old walk vs shared walk, full vs per feature",
+ {
+ "old_forward_walk_features": _forward_walk_count(adapter),
+ "shared_walk_features": len(walked),
+ "full_listing": full_names,
+ "per_feature": per_feature,
+ },
+ )
+ assert full["status"] == "success", full
+ assert len(full_names) == len(set(full_names)), "a dimension is listed twice"
+ assert found_by_features <= set(full_names)
+ for row in full["data"]:
+ if row["full_name"] and "@" in row["full_name"]:
+ assert row["feature"] == row["full_name"].split("@", 1)[1], row
+
+
+async def test_export_stl_uses_its_options(scratch: Any, tmp_path: Path) -> None:
+ """The STL is written by SaveAs2 with its options: no fallback warning."""
+ tools = await _tools(scratch.adapter)
+ await _block(tools)
+ out = tmp_path / "block.stl"
+ scratch.written_files.append(str(out))
+
+ exported = await tools["export_stl"]({"file_path": str(out)})
+
+ evidence(
+ "export_stl",
+ {
+ "status": exported["status"],
+ "size_bytes": out.stat().st_size if out.exists() else None,
+ "warning": exported.get("warning"),
+ },
+ call=f'export_stl({{"file_path": "{out.name}"}})',
+ )
+ assert exported["status"] == "success", exported
+ assert out.stat().st_size > 0
+ assert "warning" not in exported, exported["warning"]
+
+
+async def test_create_sketch_on_a_face(scratch: Any) -> None:
+ """The top face takes a sketch; the air and a fillet are refused."""
+ tools = await _tools(scratch.adapter)
+ await _block(tools)
+
+ on_top = await tools["create_sketch"]({"face_point": [0, _HEIGHT, 0]})
+ assert on_top["status"] == "success", on_top
+ assert (await tools["add_rectangle"]({"x1": -5, "y1": -5, "x2": 5, "y2": 5}))[
+ "status"
+ ] == "success"
+ closed = await tools["exit_sketch"]()
+ assert closed["status"] == "success", closed
+ cut = await tools["create_cut_extrude"](
+ {"sketch_name": on_top["sketch"]["name"], "depth": 3, "end_condition": "Blind"}
+ )
+ in_air = await tools["create_sketch"]({"face_point": [0, _HEIGHT + 50, 0]})
+
+ # Round one vertical corner (x = z = 20), then point at the fillet's middle.
+ fillet = await tools["add_fillet"](
+ {"radius": 5, "edge_names": [f"{_HALF / 1000},{_HEIGHT / 2000},{_HALF / 1000}"]}
+ )
+ assert fillet["status"] == "success", fillet
+ on_fillet_mm = _HALF - 5 + 5 * 0.7071068
+ on_fillet = await tools["create_sketch"](
+ {"face_point": [on_fillet_mm, _HEIGHT / 2, on_fillet_mm]}
+ )
+
+ evidence(
+ "create_sketch on a face: the top, the air, a fillet",
+ {
+ "top": on_top["message"],
+ "cut_volume_delta_mm3": (cut.get("measured_change") or {}).get(
+ "volume_delta_mm3"
+ ),
+ "air": [in_air["status"], in_air.get("error_type"), in_air["message"]],
+ "fillet": [
+ on_fillet["status"],
+ on_fillet.get("error_type"),
+ on_fillet["message"],
+ ],
+ },
+ )
+ assert cut["status"] == "success", cut
+ assert cut["measured_change"]["volume_delta_mm3"] == pytest.approx(-300, rel=1e-3)
+ assert in_air["status"] == "error"
+ assert in_air["error_type"] == "invalid_input"
+ assert on_fillet["status"] == "error"
+ assert on_fillet["error_type"] == "invalid_input"
+ assert "not flat" in on_fillet["message"]
diff --git a/tests/solidworks_mcp/adapters/solidworks/test_documentation.py b/tests/solidworks_mcp/adapters/solidworks/test_documentation.py
index 6d81c684..99d513a1 100644
--- a/tests/solidworks_mcp/adapters/solidworks/test_documentation.py
+++ b/tests/solidworks_mcp/adapters/solidworks/test_documentation.py
@@ -283,6 +283,99 @@ async def test_list_model_dimensions_unknown_feature_is_not_found() -> None:
assert "No dimensions found on feature 'Fillet9'" in result.error
+class _TreeFeature(_Feature):
+ """A feature with a type, for walks that skip folders."""
+
+ def __init__(self, name: str, kind: str, dims: list[Any]) -> None:
+ super().__init__(name, dims)
+ self._kind = kind
+
+ def GetTypeName2(self): # noqa: N802 - COM name
+ return self._kind
+
+
+def _monitor_stand() -> SimpleNamespace:
+ """A part whose forward walk stops at the folders, as on the monitor stand.
+
+ The cut sketched on ``Plane1`` also reports the plane's offset.
+ """
+ tree = [
+ _TreeFeature("Comments", "CommentsFolder", [_dim("D9@Bogus@P.Part", 1.0)]),
+ _TreeFeature("Front Plane", "RefPlane", []),
+ _TreeFeature("Boss-Extrude1", "Extrusion", [_dim("D1@Boss-Extrude1", 20.0)]),
+ _TreeFeature("Plane1", "RefPlane", [_dim("D1@Plane1@Stand.Part", 20.0)]),
+ _TreeFeature(
+ "Cut-Extrude3",
+ "Cut",
+ [_dim("D1@Cut-Extrude3", 3.0), _dim("D1@Plane1@Stand.Part", 20.0)],
+ ),
+ ]
+ count = len(tree)
+ return SimpleNamespace(
+ GetType=lambda: 1,
+ FirstFeature=lambda: tree[0], # its GetNextFeature is None: the walk stops
+ FeatureByPositionReverse=lambda pos: tree[count - pos - 1],
+ FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: count),
+ )
+
+
+@pytest.mark.asyncio
+async def test_list_model_dimensions_finds_what_the_reverse_pass_finds() -> None:
+ result = await _Harness(_monitor_stand()).list_model_dimensions()
+
+ assert result.is_success
+ assert [(d["full_name"], d["feature"]) for d in result.data] == [
+ ("D1@Boss-Extrude1", "Boss-Extrude1"),
+ ("D1@Plane1", "Plane1"),
+ ("D1@Cut-Extrude3", "Cut-Extrude3"),
+ ]
+
+
+@pytest.mark.asyncio
+async def test_list_model_dimensions_for_a_cut_leaves_out_its_plane() -> None:
+ result = await _Harness(_monitor_stand()).list_model_dimensions("Cut-Extrude3")
+
+ assert [d["full_name"] for d in result.data] == ["D1@Cut-Extrude3"]
+
+
+@pytest.mark.asyncio
+async def test_list_model_dimensions_keeps_a_dimension_with_no_full_name() -> None:
+ nameless = SimpleNamespace(
+ FullName=None, Value=5.0, SystemValue=0.005, ReadOnly=True
+ )
+ feature = _Feature("Fillet1", [nameless, nameless])
+ model = SimpleNamespace(GetType=lambda: 1, FirstFeature=lambda: feature)
+
+ result = await _Harness(model).list_model_dimensions()
+
+ assert [(d["full_name"], d["feature"]) for d in result.data] == [
+ (None, "Fillet1"),
+ (None, "Fillet1"),
+ ]
+ assert result.data[0]["read_only"] is True
+
+
+@pytest.mark.parametrize(
+ ("full_name", "owner"),
+ [("D1@Plane1", "Plane1"), ("D1@Sketch@2", "Sketch@2"), ("D1", None), (None, None)],
+)
+def test_owning_feature(full_name, owner) -> None:
+ assert doc._owning_feature(full_name) == owner
+
+
+@pytest.mark.parametrize(
+ ("type_name", "folder"),
+ [
+ ("MaterialFolder", True),
+ ("DetailCabinet", True),
+ ("RefPlane", False),
+ ("Unknown", False),
+ ],
+)
+def test_is_folder(type_name, folder) -> None:
+ assert doc._is_folder(type_name) is folder
+
+
# ---- measure_entities ---------------------------------------------------------
diff --git a/tests/solidworks_mcp/adapters/solidworks/test_feature_walk.py b/tests/solidworks_mcp/adapters/solidworks/test_feature_walk.py
new file mode 100644
index 00000000..7cf11875
--- /dev/null
+++ b/tests/solidworks_mcp/adapters/solidworks/test_feature_walk.py
@@ -0,0 +1,116 @@
+"""Tests for the shared feature-tree walk."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from typing import Any
+
+from solidworks_mcp.adapters.solidworks.feature_walk import (
+ WALK_MEMBERS,
+ TreeFeature,
+ walk_feature_tree,
+)
+
+
+class _Adapter:
+ """The two adapter members the walk uses."""
+
+ def _attempt(self, operation, default=None):
+ try:
+ return operation()
+ except Exception:
+ return default
+
+ def _get_attr_or_call(self, obj, name):
+ value = getattr(obj, name)
+ return value() if callable(value) else value
+
+
+class _Feature:
+ """A fake ``IFeature`` with a forward link."""
+
+ def __init__(self, name: str, kind: str = "Extrusion") -> None:
+ self.Name = name
+ self._kind = kind
+ self.next: Any = None
+
+ def GetTypeName2(self): # noqa: N802 - COM name
+ return self._kind
+
+ def GetNextFeature(self): # noqa: N802 - COM name
+ return self.next
+
+
+def _chain(*features: _Feature) -> None:
+ for current, following in zip(features, features[1:], strict=False):
+ current.next = following
+
+
+def _document(features: list[_Feature], first: Any) -> Any:
+ total = len(features)
+ return SimpleNamespace(
+ FirstFeature=lambda: first,
+ FeatureByPositionReverse=lambda pos: features[total - pos - 1],
+ FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: total),
+ )
+
+
+def test_a_full_forward_walk_gives_each_feature_once_in_order() -> None:
+ features = [
+ _Feature("Front Plane", "RefPlane"),
+ _Feature("Sketch1"),
+ _Feature("Boss"),
+ ]
+ _chain(*features)
+
+ walked = walk_feature_tree(_Adapter(), _document(features, features[0]))
+
+ assert [(f.position, f.name) for f in walked] == [
+ (0, "Front Plane"),
+ (1, "Sketch1"),
+ (2, "Boss"),
+ ]
+ assert walked[0].type_name == "RefPlane"
+ assert walked[2].feature is features[2]
+
+
+def test_a_walk_that_stops_early_is_completed_and_sorted() -> None:
+ features = [_Feature(name) for name in ("A", "B", "C", "D")]
+ _chain(features[0], features[1]) # the forward walk stops after B
+
+ walked = walk_feature_tree(_Adapter(), _document(features, features[0]))
+
+ assert [f.name for f in walked] == ["A", "B", "C", "D"]
+ assert [f.position for f in walked] == [0, 1, 2, 3]
+
+
+def test_no_forward_walk_and_gaps_in_the_reverse_pass() -> None:
+ # The count says three; the newest (reverse position 0) can't be read.
+ by_reverse = {1: _Feature("B"), 2: _Feature("A")}
+ document = SimpleNamespace(
+ FirstFeature=lambda: None,
+ FeatureByPositionReverse=lambda pos: by_reverse.get(pos),
+ FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: 3),
+ )
+
+ walked = walk_feature_tree(_Adapter(), document)
+
+ assert [(f.position, f.name) for f in walked] == [(0, "A"), (1, "B")]
+
+
+def test_an_unreadable_type_and_a_missing_feature_manager() -> None:
+ class _Bare:
+ Name = "Odd"
+
+ def GetNextFeature(self): # noqa: N802 - COM name
+ return None
+
+ document = SimpleNamespace(FirstFeature=lambda: _Bare())
+
+ walked = walk_feature_tree(_Adapter(), document)
+
+ assert walked == [TreeFeature(0, "Odd", "Unknown", walked[0].feature)]
+
+
+def test_walk_members_cover_what_callers_read() -> None:
+ assert {"GetNextFeature", "GetTypeName2", "IsSuppressed"} <= set(WALK_MEMBERS)
diff --git a/tests/solidworks_mcp/adapters/solidworks/test_io.py b/tests/solidworks_mcp/adapters/solidworks/test_io.py
index db9a04a7..57e0e585 100644
--- a/tests/solidworks_mcp/adapters/solidworks/test_io.py
+++ b/tests/solidworks_mcp/adapters/solidworks/test_io.py
@@ -39,7 +39,10 @@ def _handle_com_operation(self, _name, callback, *args):
import solidworks_mcp.adapters.pywin32_adapter as pywin32_mod
from solidworks_mcp.adapters.mock_adapter import MockSolidWorksAdapter
-from solidworks_mcp.adapters.pywin32_adapter import PyWin32Adapter
+from solidworks_mcp.adapters.pywin32_adapter import (
+ STL_OPTIONS_NOT_APPLIED,
+ PyWin32Adapter,
+)
from solidworks_mcp.adapters.solidworks import bitmap as _io_bitmap
from solidworks_mcp.adapters.solidworks.io import (
SolidWorksIOMixin,
@@ -2642,26 +2645,44 @@ def test_prepare_stl_export_data_paths(self, monkeypatch) -> None:
assert stl_data.Merge is True
assert stl_data.ExportBodiesAs == 0
- def test_save_stl_with_extension_fallback_to_no_export_data(
+ def test_save_stl_with_extension_passes_eight_arguments(
self, monkeypatch, tmp_path
) -> None:
- """_save_stl_with_extension should retry SaveAs2 with None export data."""
+ """SaveAs2 gets its eight arguments, the export data included, once.
+
+ The last two are the by-reference ``Errors`` and ``Warnings``; leaving
+ ``Warnings`` out failed live with "Parameter not optional".
+ """
adapter = self._build_adapter(monkeypatch)
out_file = tmp_path / "out.stl"
-
- call_counter = {"count": 0}
+ stl_data = object()
def _saveas2(path, *_args):
- call_counter["count"] += 1
- if call_counter["count"] == 1:
- raise RuntimeError("type mismatch")
out_file.write_text("solid", encoding="utf-8")
+ return True
extension = SimpleNamespace(SaveAs2=Mock(side_effect=_saveas2))
- saved = adapter._save_stl_with_extension(extension, object(), str(out_file))
+ saved = adapter._save_stl_with_extension(extension, stl_data, str(out_file))
assert saved is True
- assert extension.SaveAs2.call_count == 2
+ extension.SaveAs2.assert_called_once()
+ args = extension.SaveAs2.call_args.args
+ assert len(args) == 8
+ assert args[:6] == (str(out_file), 0, 2, stl_data, "", False)
+
+ def test_save_stl_with_extension_without_export_data_passes_a_null(
+ self, monkeypatch, tmp_path
+ ) -> None:
+ """No ISTLExportData: ExportData is the VT_DISPATCH null, never None."""
+ adapter = self._build_adapter(monkeypatch)
+ extension = SimpleNamespace(SaveAs2=Mock(return_value=True))
+
+ saved = adapter._save_stl_with_extension(
+ extension, None, str(tmp_path / "never.stl")
+ )
+
+ assert saved is False # SaveAs2 said True but wrote nothing
+ assert extension.SaveAs2.call_args.args[3] is not None
def test_save_stl_with_extension_returns_false_on_failure(
self, monkeypatch
@@ -2783,6 +2804,7 @@ async def test_export_file_stl_success_via_extension_path(
result = await adapter.export_file(str(out_file), "stl")
assert result.is_success
+ assert result.data is None
target_doc.ResolveAllLightweightComponents.assert_called_once_with(True)
adapter._save_stl_with_extension.assert_called_once()
adapter._save_stl_with_fallback.assert_not_called()
@@ -2817,6 +2839,7 @@ async def test_export_file_stl_falls_back_to_saveas3(
result = await adapter.export_file(str(out_file), "stl")
assert result.is_success
+ assert result.data == {"warning": STL_OPTIONS_NOT_APPLIED}
adapter._save_stl_with_extension.assert_called_once()
adapter._save_stl_with_fallback.assert_called_once_with(
target_doc, str(out_file)
diff --git a/tests/solidworks_mcp/adapters/solidworks/test_selection.py b/tests/solidworks_mcp/adapters/solidworks/test_selection.py
index 2eeba192..1d3e8ab9 100644
--- a/tests/solidworks_mcp/adapters/solidworks/test_selection.py
+++ b/tests/solidworks_mcp/adapters/solidworks/test_selection.py
@@ -407,7 +407,65 @@ def IsSuppressed(self):
result = await adapter.list_features(include_suppressed=False)
assert result.is_success
- assert [row["name"] for row in result.data] == ["Boss-Extrude1", "Sketch1"]
+ # The reverse pass finds them newest first; the rows come in tree order.
+ assert [row["name"] for row in result.data] == ["Sketch1", "Boss-Extrude1"]
+ assert [row["position"] for row in result.data] == [0, 1]
+
+ @pytest.mark.asyncio
+ async def test_list_features_sorts_when_the_forward_walk_stops_early(
+ self, monkeypatch
+ ):
+ """A forward walk that stops at the folders still yields tree order."""
+ adapter = self._build_adapter(monkeypatch)
+
+ class _Feature:
+ """A feature whose forward link can be cut short."""
+
+ def __init__(self, name, feature_type, next_feature=None):
+ """Store the name, type and next feature."""
+ self.Name = name
+ self._feature_type = feature_type
+ self._next = next_feature
+
+ def GetTypeName2(self):
+ """Return the feature's type."""
+ return self._feature_type
+
+ def IsSuppressed(self):
+ """Never suppressed."""
+ return False
+
+ def GetNextFeature(self):
+ """Return the next feature, or None where the walk stops."""
+ return self._next
+
+ tree = [
+ ("Front Plane", "RefPlane"),
+ ("Top Plane", "RefPlane"),
+ ("Right Plane", "RefPlane"),
+ ("Sketch1", "ProfileFeature"),
+ ("Boss-Extrude1", "Extrusion"),
+ ("Plane1", "RefPlane"),
+ ("Sketch2", "ProfileFeature"),
+ ("Cut-Extrude1", "Cut"),
+ ]
+ objects = [_Feature(name, kind) for name, kind in tree]
+ # The forward walk reaches the default planes, then stops.
+ objects[0]._next = objects[1]
+ objects[1]._next = objects[2]
+ count = len(objects)
+
+ adapter.currentModel = SimpleNamespace(
+ FirstFeature=lambda: objects[0],
+ FeatureByPositionReverse=lambda pos: objects[count - pos - 1],
+ FeatureManager=SimpleNamespace(GetFeatureCount=lambda _all: count),
+ )
+
+ result = await adapter.list_features(include_suppressed=False)
+
+ assert result.is_success
+ assert [row["name"] for row in result.data] == [name for name, _ in tree]
+ assert [row["position"] for row in result.data] == list(range(count))
@pytest.mark.asyncio
async def test_list_features_suppressed_fallback_uses_is_suppressed2(
diff --git a/tests/solidworks_mcp/adapters/solidworks/test_sketch.py b/tests/solidworks_mcp/adapters/solidworks/test_sketch.py
index 034237b4..91d186d1 100644
--- a/tests/solidworks_mcp/adapters/solidworks/test_sketch.py
+++ b/tests/solidworks_mcp/adapters/solidworks/test_sketch.py
@@ -2433,3 +2433,83 @@ def test_text_beside_line(ends, point, expected) -> None:
text = sketch._text_beside_line(adapter, object(), point)
assert text == (None if expected is None else pytest.approx(expected))
+
+
+# ---- create_sketch on a face (face_point) --------------------------------------
+
+
+def _face_model(cleared: list[bool]) -> SimpleNamespace:
+ """A model whose sketch manager opens ``FaceSketch``; records clears."""
+ return SimpleNamespace(
+ ClearSelection2=lambda _all: cleared.append(True),
+ SketchManager=SimpleNamespace(
+ InsertSketch=lambda *args: SimpleNamespace(Name="FaceSketch")
+ ),
+ )
+
+
+def test_create_sketch_on_a_flat_face(monkeypatch) -> None:
+ from solidworks_mcp.adapters.solidworks import features
+
+ picked: list[list[float]] = []
+ monkeypatch.setattr(
+ features,
+ "_select_face_at_point",
+ lambda _adapter, point, mark: picked.append(point) or True,
+ )
+ adapter = _FakeSketchAdapter()
+ adapter.currentModel = _face_model([])
+
+ result = sketch._create_sketch_impl(adapter, None, (5.0, 20.0, 5.0))
+
+ assert result.is_success
+ assert result.data == "FaceSketch"
+ assert picked == [[5.0, 20.0, 5.0]]
+
+
+def test_create_sketch_point_off_the_body_names_the_point(monkeypatch) -> None:
+ from solidworks_mcp.adapters.solidworks import features
+
+ def _no_face(_adapter, point, _mark):
+ raise LookupError(f"No face found at point {point} mm.")
+
+ monkeypatch.setattr(features, "_select_face_at_point", _no_face)
+ cleared: list[bool] = []
+ adapter = _FakeSketchAdapter()
+ adapter.currentModel = _face_model(cleared)
+
+ result = sketch._create_sketch_impl(adapter, None, (0.0, 70.0, 0.0))
+
+ assert not result.is_success
+ assert "face_point [0.0, 70.0, 0.0] mm is not on a flat face" in result.error
+ assert "No face found" in result.error
+ assert len(cleared) == 2 # before the pick, and again after the failure
+ assert adapter.currentSketch is None
+
+
+def test_create_sketch_face_that_will_not_select(monkeypatch) -> None:
+ from solidworks_mcp.adapters.solidworks import features
+
+ monkeypatch.setattr(features, "_select_face_at_point", lambda *_: False)
+ adapter = _FakeSketchAdapter()
+ adapter.currentModel = _face_model([])
+
+ result = sketch._create_sketch_impl(adapter, None, (1.0, 2.0, 3.0))
+
+ assert "SolidWorks would not select it" in result.error
+
+
+@pytest.mark.asyncio
+async def test_mixin_create_sketch_forwards_face_point(monkeypatch) -> None:
+ calls: list[tuple] = []
+ monkeypatch.setattr(
+ sketch,
+ "_create_sketch_impl",
+ lambda adapter, plane, face_point: calls.append((plane, face_point)) or "ok",
+ )
+
+ class _Mixin(SolidWorksSketchMixin):
+ pass
+
+ assert await _Mixin().create_sketch(None, (1.0, 2.0, 3.0)) == "ok"
+ assert calls == [(None, (1.0, 2.0, 3.0))]
diff --git a/tests/solidworks_mcp/adapters/test_circuit_breaker.py b/tests/solidworks_mcp/adapters/test_circuit_breaker.py
index c01fcce9..c9cc0de4 100644
--- a/tests/solidworks_mcp/adapters/test_circuit_breaker.py
+++ b/tests/solidworks_mcp/adapters/test_circuit_breaker.py
@@ -600,8 +600,9 @@ async def create_loft(self, params):
"""Test helper for create loft."""
return AdapterResult(status=AdapterResultStatus.SUCCESS, data=None)
- async def create_sketch(self, plane: str):
- """Test helper for create sketch."""
+ async def create_sketch(self, plane: str | None, face_point=None):
+ """Test helper for create sketch; echoes where it was asked to sketch."""
+ self.last_sketch_args = (plane, face_point)
return AdapterResult(status=AdapterResultStatus.SUCCESS, data="Sketch1")
async def add_line(self, x1: float, y1: float, x2: float, y2: float):
@@ -1116,3 +1117,23 @@ async def test_reset_circuit_breakers_reports_through_a_result(self) -> None:
result = await breaker.reset_circuit_breakers()
assert result.is_success and result.data == {"reset": ["a"]}
+
+
+@pytest.mark.asyncio
+async def test_circuit_breaker_create_sketch_forwards_face_point(monkeypatch):
+ """face_point reaches the wrapped adapter and the breaker's input record."""
+ inner = _DummyAdapter({})
+ cb = CircuitBreakerAdapter(adapter=inner, config={})
+ recorded: dict = {}
+
+ async def _run(name, operation, **kwargs):
+ recorded.update(kwargs.get("input_dict") or {})
+ return await operation()
+
+ monkeypatch.setattr(cb, "_execute_with_circuit_breaker", _run)
+
+ result = await cb.create_sketch(None, (1.0, 2.0, 3.0))
+
+ assert result.is_success
+ assert inner.last_sketch_args == (None, (1.0, 2.0, 3.0))
+ assert recorded == {"plane": None, "face_point": (1.0, 2.0, 3.0)}
diff --git a/tests/solidworks_mcp/adapters/test_connection_pool.py b/tests/solidworks_mcp/adapters/test_connection_pool.py
index 396b0103..490fe07b 100644
--- a/tests/solidworks_mcp/adapters/test_connection_pool.py
+++ b/tests/solidworks_mcp/adapters/test_connection_pool.py
@@ -1830,3 +1830,27 @@ async def test_reset_circuit_breakers_resets_a_shared_breaker_once() -> None:
assert result.data == {"reset": ["create_extrusion"]}
assert breaker._get_bucket("create_extrusion").state == CircuitState.CLOSED
+
+
+@pytest.mark.asyncio
+async def test_connection_pool_create_sketch_forwards_face_point(monkeypatch):
+ """The pool passes face_point through to the adapter it borrows."""
+ pool = ConnectionPoolAdapter(
+ adapter_factory=lambda: _PoolAdapterStub(), pool_size=1
+ )
+ seen: list[tuple] = []
+
+ class _Borrowed:
+ async def create_sketch(self, plane, face_point=None):
+ seen.append((plane, face_point))
+ return AdapterResult(status=AdapterResultStatus.SUCCESS, data="Sketch1")
+
+ async def _fake_execute(name, operation):
+ return await operation(_Borrowed())
+
+ monkeypatch.setattr(pool, "_execute_with_pool", _fake_execute)
+
+ result = await pool.create_sketch(None, (1.0, 2.0, 3.0))
+
+ assert result.is_success
+ assert seen == [(None, (1.0, 2.0, 3.0))]
diff --git a/tests/solidworks_mcp/adapters/test_mock_adapter.py b/tests/solidworks_mcp/adapters/test_mock_adapter.py
index 4717ad59..46d301a9 100644
--- a/tests/solidworks_mcp/adapters/test_mock_adapter.py
+++ b/tests/solidworks_mcp/adapters/test_mock_adapter.py
@@ -423,6 +423,9 @@ async def test_list_features_with_actual_features(self):
result = await adapter.list_features(include_suppressed=False)
assert result.status == AdapterResultStatus.SUCCESS
assert isinstance(result.data, list)
+ positions = [row["position"] for row in result.data]
+ assert positions == sorted(positions)
+ assert result.data[-1]["name"].startswith("Boss-Extrude")
@pytest.mark.asyncio
async def test_list_features_seeded_when_empty(self):
@@ -435,6 +438,7 @@ async def test_list_features_seeded_when_empty(self):
assert result.status == AdapterResultStatus.SUCCESS
assert len(result.data) > 0
assert any(f["name"] == "Origin" for f in result.data)
+ assert [f["position"] for f in result.data] == list(range(len(result.data)))
@pytest.mark.asyncio
async def test_list_configurations_non_default_config(self):
diff --git a/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py b/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py
index 196af870..ea8bbbcc 100644
--- a/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py
+++ b/tests/solidworks_mcp/adapters/test_mock_adapter_engineering_data.py
@@ -24,6 +24,20 @@ async def test_list_model_dimensions_filters_by_feature(part) -> None:
assert [d["full_name"] for d in result.data] == ["D1@Boss-Extrude1"]
+@pytest.mark.asyncio
+async def test_list_model_dimensions_lists_each_once_under_its_owner(part) -> None:
+ part._dimensions = {"D1@Plane1": 20.0, "D1@Cut-Extrude3": 3.0}
+
+ everything = await part.list_model_dimensions()
+ cut = await part.list_model_dimensions("Cut-Extrude3")
+
+ assert [(d["full_name"], d["feature"]) for d in everything.data] == [
+ ("D1@Plane1", "Plane1"),
+ ("D1@Cut-Extrude3", "Cut-Extrude3"),
+ ]
+ assert [d["full_name"] for d in cut.data] == ["D1@Cut-Extrude3"]
+
+
@pytest.mark.asyncio
async def test_list_model_dimensions_unknown_feature(part) -> None:
result = await part.list_model_dimensions("Fillet9")
diff --git a/tests/solidworks_mcp/tools/test_analysis_verify_model.py b/tests/solidworks_mcp/tools/test_analysis_verify_model.py
index c253ba37..eed79dea 100644
--- a/tests/solidworks_mcp/tools/test_analysis_verify_model.py
+++ b/tests/solidworks_mcp/tools/test_analysis_verify_model.py
@@ -405,6 +405,30 @@ def test_feature_filter_skips_furniture_and_default_planes() -> None:
]
+def test_feature_filter_uses_tree_order_when_rows_arrive_newest_first() -> None:
+ # The monitor stand: rows found newest first by the reverse pass.
+ in_tree_order = [
+ ("Front Plane", "RefPlane"),
+ ("Top Plane", "RefPlane"),
+ ("Right Plane", "RefPlane"),
+ ("Origin", "OriginProfileFeature"),
+ ("Sketch1", "ProfileFeature"),
+ ("Boss-Extrude1", "Extrusion"),
+ ("Plane1", "RefPlane"),
+ ("Sketch2", "ProfileFeature"),
+ ("Cut-Extrude1", "Cut"),
+ ]
+ rows = [
+ {**_feature(name, kind), "position": position}
+ for position, (name, kind) in enumerate(in_tree_order)
+ ]
+
+ counted = _count_modelling_features(list(reversed(rows)))
+
+ assert counted == ["Boss-Extrude1", "Plane1", "Cut-Extrude1"]
+ assert "Front Plane" not in counted
+
+
def test_verdict_order() -> None:
assert _verdict([]) == "report_only"
assert _verdict([{"passed": True}, {"passed": None}]) == "inconclusive"
diff --git a/tests/solidworks_mcp/tools/test_error_classifier.py b/tests/solidworks_mcp/tools/test_error_classifier.py
index 6d4b3f99..1fbdeb2b 100644
--- a/tests/solidworks_mcp/tools/test_error_classifier.py
+++ b/tests/solidworks_mcp/tools/test_error_classifier.py
@@ -74,6 +74,11 @@ def classifier() -> ErrorClassifier:
),
("The selected face has no edges", "not_found"),
("No face found at point [1000, 1000, 1000] mm.", "not_found"),
+ (
+ "Error in create_sketch: face_point [5.0, 60.0, 5.0] mm is not on a "
+ "flat face of the active part (No face found at point [5, 60, 5] mm.)",
+ "invalid_input",
+ ),
("The active part has no solid body faces.", "not_found"),
("No view named 'Side'. Views: Front, Top", "not_found"),
("No drawing views found to dimension (pictorial ...)", "not_found"),
diff --git a/tests/solidworks_mcp/tools/test_export.py b/tests/solidworks_mcp/tools/test_export.py
index 055469a2..68e0d1ca 100644
--- a/tests/solidworks_mcp/tools/test_export.py
+++ b/tests/solidworks_mcp/tools/test_export.py
@@ -750,3 +750,41 @@ async def test_a_file_export_without_format_type_uses_the_tools_own(
assert result["status"] == "success"
assert mock_adapter.export_step.call_args.args[0]["format_type"] == "step"
assert ExportFileInput(file_path="C:/out/part.step").format_type is None
+
+
+class _StlFallbackAdapter:
+ """An adapter whose STL export went through the SaveAs3 fallback."""
+
+ async def export_file(self, file_path: str, format_type: str):
+ """Report the fallback's note, as the real adapter does."""
+ return SimpleNamespace(
+ is_success=True,
+ error=None,
+ data={"warning": "the STL options were not applied"},
+ execution_time=0.01,
+ )
+
+
+@pytest.mark.asyncio
+async def test_export_stl_passes_the_fallback_warning_on(mcp_server, mock_config):
+ """A file written without the STL options says so in the reply."""
+ await register_export_tools(mcp_server, _StlFallbackAdapter(), mock_config)
+
+ reply = await (await _tool(mcp_server, "export_stl"))(
+ input_data=ExportFileInput(file_path="a.stl")
+ )
+
+ assert reply["status"] == "success"
+ assert reply["warning"] == "the STL options were not applied"
+
+
+@pytest.mark.asyncio
+async def test_export_stl_without_a_fallback_has_no_warning(mcp_server, mock_config):
+ """The usual export carries no warning."""
+ await register_export_tools(mcp_server, _ExportFallbackAdapter(), mock_config)
+
+ reply = await (await _tool(mcp_server, "export_stl"))(
+ input_data=ExportFileInput(file_path="a.stl")
+ )
+
+ assert "warning" not in reply
diff --git a/tests/solidworks_mcp/tools/test_sketching.py b/tests/solidworks_mcp/tools/test_sketching.py
index e707cd17..8c3ff16a 100644
--- a/tests/solidworks_mcp/tools/test_sketching.py
+++ b/tests/solidworks_mcp/tools/test_sketching.py
@@ -1429,3 +1429,71 @@ async def test_the_hole_tutorial_points_at_the_cut_tool(
assert cut["sketch_name"] == "Sketch1"
assert cut["end_condition"] == "ThroughAll"
assert cut["depth"] > 0
+
+
+# ---- create_sketch on a face ---------------------------------------------------
+
+
+@pytest.mark.parametrize(
+ "kwargs",
+ [
+ {"plane": "Top", "face_point": [0, 0, 0]},
+ {},
+ {"plane": " "},
+ {"face_point": [1, 2]},
+ ],
+)
+def test_create_sketch_input_needs_exactly_one_place(kwargs) -> None:
+ """Both, neither, a blank plane or a short point are refused."""
+ with pytest.raises(ValueError):
+ CreateSketchInput(**kwargs)
+
+
+def test_create_sketch_input_takes_a_face_point() -> None:
+ data = CreateSketchInput(face_point=[5, 10, 5])
+ assert data.plane is None
+ assert data.face_point == [5, 10, 5]
+
+
+async def _create_sketch_tool(mcp_server, adapter, config):
+ await register_sketching_tools(mcp_server, adapter, config)
+ for tool in await mcp_server.list_tools():
+ if tool.name == "create_sketch":
+ return tool.fn
+ raise AssertionError("create_sketch is not registered")
+
+
+@pytest.mark.asyncio
+async def test_create_sketch_on_a_face_of_the_mock_block(mcp_server, mock_config):
+ """A point on the block's top face opens a sketch there."""
+ from solidworks_mcp.adapters.mock_adapter import MockSolidWorksAdapter
+
+ adapter = MockSolidWorksAdapter({})
+ await adapter.connect()
+ await adapter.create_part()
+ tool = await _create_sketch_tool(mcp_server, adapter, mock_config)
+
+ reply = await tool({"face_point": [5, 5, 10]})
+
+ assert reply["status"] == "success"
+ assert reply["sketch"]["face_point"] == [5.0, 5.0, 10.0]
+ assert reply["sketch"]["plane"] is None
+ assert "the face at [5.0, 5.0, 10.0] mm" in reply["message"]
+
+
+@pytest.mark.asyncio
+async def test_create_sketch_point_in_the_air_is_invalid_input(mcp_server, mock_config):
+ """A point off the body fails with invalid_input naming the point."""
+ from solidworks_mcp.adapters.mock_adapter import MockSolidWorksAdapter
+
+ adapter = MockSolidWorksAdapter({})
+ await adapter.connect()
+ await adapter.create_part()
+ tool = await _create_sketch_tool(mcp_server, adapter, mock_config)
+
+ reply = await tool({"face_point": [5, 60, 5]})
+
+ assert reply["status"] == "error"
+ assert reply["error_type"] == "invalid_input"
+ assert "[5.0, 60.0, 5.0]" in reply["message"]
+ assert adapter._current_sketch is None