@snaptrude/plugin-core 0.11.0-rc.1 → 1.0.0

package/api-manifest.json

@@ -729,8 +729,9 @@
   {
     "path": "core.geom.create.brepFromChamfer",
     "namespace": "core.geom.create",
-    "summary": "Bevels the given straight edges of a solid with a symmetric planar cut. Host API call — returns a new {@linkcode BrepHandle}; the input brep is read-only.",
+    "summary": "Bevels the given edges of a solid with a symmetric planar cut. Host API call — returns a new {@linkcode BrepHandle}; the input brep is read-only.",
     "examplePrompts": [
+      "Chamfer the top edge of the cylinder",
       "Bevel these edges by 100mm",
       "Chamfer the top edges of the plinth",
       "Cut a 45-degree flat along the corners of this mass\n\n# Example\n```ts\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst edges = await snaptrude.core.geom.query.brep.listEdges(brep)\nconst beveled = await snaptrude.core.geom.create.brepFromChamfer(brep, [edges[0]], 0.1)\n```"
@@ -738,6 +739,28 @@
     "argsType": "BrepHandle",
     "resultType": "BrepHandle"
   },
+  {
+    "path": "core.geom.create.brepFromCone",
+    "namespace": "core.geom.create",
+    "summary": "Create a solid **cone or frustum** B-rep: bottom-cap centre, axis, base radius, height, and an optional top radius (default 0 — a full cone to a point; > 0 — a frustum / tapered column). Host API call — returns a {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. Carries a creation recipe (radii + height), editable through `design.update.parameters`.",
+    "examplePrompts": [
+      "Create a cone roof 4m wide and 3m tall",
+      "Make a tapered column narrowing from 1m to 0.6m\n\n# Example\n```ts\nconst roof = await snaptrude.core.geom.create.brepFromCone(\n{ x: 0, y: 9, z: 0 },\n{ x: 0, y: 1, z: 0 },\n2,\n3,\n)\n```"
+    ],
+    "argsType": "Vec3Components",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromCylinder",
+    "namespace": "core.geom.create",
+    "summary": "Create a solid **cylinder** B-rep from its bottom-cap centre, axis direction, radius and height. Host API call — returns a {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. The bottom cap sits AT `base` and the solid extends `height` along `axis` — place `base` on the floor and use axis `{x: 0, y: 1, z: 0}` for an upright column. Carries a creation recipe (radius, height), editable through `design.update.parameters`.",
+    "examplePrompts": [
+      "Create a cylinder 2m across and 4m tall",
+      "Add a circular column here\n\n# Example\n```ts\nconst brep = await snaptrude.core.geom.create.brepFromCylinder(\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 1, z: 0 },\n1,\n4,\n)\nconst column = await snaptrude.design.create.massFromBrep(brep, \"Column\")\n```"
+    ],
+    "argsType": "Vec3Components",
+    "resultType": "BrepHandle"
+  },
   {
     "path": "core.geom.create.brepFromExtrusion",
     "namespace": "core.geom.create",
@@ -745,7 +768,9 @@
     "examplePrompts": [
       "Extrude this profile 3 metres up",
       "Make a solid by extruding this outline",
-      "Create a cylinder from a circle profile\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6\n```"
+      "Create a cylinder from a circle profile",
+      "Extrude this floor plate 40m up with a 90 degree twist",
+      "Taper this tower to 60 percent of its footprint at the top\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6\n```"
     ],
     "argsType": "ContourHandle",
     "resultType": "BrepHandle"
@@ -765,11 +790,14 @@
   {
     "path": "core.geom.create.brepFromFillet",
     "namespace": "core.geom.create",
-    "summary": "Rounds the given straight edges of a solid with a constant radius. Host API call — returns a new {@linkcode BrepHandle}; the input brep is read-only.",
+    "summary": "Rounds the given edges of a solid with a constant radius. Host API call — returns a new {@linkcode BrepHandle}; the input brep is read-only.",
     "examplePrompts": [
-      "Round the edges of this mass",
+      "Round the rim of the column with 200 mm",
+      "Soften where the dome meets the wall",
       "Fillet the corners of the podium with a 0.5m radius",
-      "Soften the vertical edges of this tower\n\n# Example\n```ts\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst edges = await snaptrude.core.geom.query.brep.listEdges(brep)\nconst rounded = await snaptrude.core.geom.create.brepFromFillet(brep, [edges[0]], 0.3)\n```"
+      "Soften the vertical edges of this tower",
+      "Blend this edge from 200mm at one end to 600mm at the other",
+      "Round this rim wider at the back than at the front\n\n# Example\n```ts\n// Rim = every edge between the cylinder side and a plane cap\nconst edges = await snaptrude.core.geom.query.brep.listEdges(column)\nconst rim = []\nfor (const edge of edges) {\nconst faces = await snaptrude.core.geom.query.edge.listFaces(edge)\nconst kinds = await Promise.all(\nfaces.map((f) => snaptrude.core.geom.query.face.getSurfaceKind(f)),\n)\nif (kinds.includes(\"cylinder\") && kinds.includes(\"plane\")) rim.push(edge)\n}\nconst rounded = await snaptrude.core.geom.create.brepFromFillet(column, rim, 0.787) // 200 mm\n```"
     ],
     "argsType": "BrepHandle",
     "resultType": "BrepHandle"
@@ -798,7 +826,8 @@
       "Loft a four-sided base to a five-sided top",
       "Loft these outlines even though their corners don't line up",
       "Loft these outlines exactly as authored, corner to corner",
-      "Fail the loft if my sections don't have matching edge counts\n\n# Example\n```ts\n// A square frustum: 4m base lofted to a 2m top, 3m up\nconst base = await snaptrude.core.geom.create.profileRect(4, 4)\nconst top = await snaptrude.core.geom.create.profileRect(2, 2, await snaptrude.core.math.vec3.new(0, 3, 0))\nconst brep = await snaptrude.core.geom.create.brepFromLoft(\nawait snaptrude.core.geom.create.contourFromProfile(base),\nawait snaptrude.core.geom.create.contourFromProfile(top),\n)\nconst faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6\n```"
+      "Fail the loft if my sections don't have matching edge counts",
+      "Loft these three outlines with smoothly curving sides\n\n# Example\n```ts\n// A square frustum: 4m base lofted to a 2m top, 3m up\nconst base = await snaptrude.core.geom.create.profileRect(4, 4)\nconst top = await snaptrude.core.geom.create.profileRect(2, 2, await snaptrude.core.math.vec3.new(0, 3, 0))\nconst brep = await snaptrude.core.geom.create.brepFromLoft(\nawait snaptrude.core.geom.create.contourFromProfile(base),\nawait snaptrude.core.geom.create.contourFromProfile(top),\n)\nconst faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6\n```"
     ],
     "argsType": "ContourHandle",
     "resultType": "BrepHandle"
@@ -820,6 +849,7 @@
     "namespace": "core.geom.create",
     "summary": "Grows or shrinks a solid by offsetting every face — positive distance moves faces outward, negative moves them inward. Host API call — returns a new {@linkcode BrepHandle}; the input brep is read-only.",
     "examplePrompts": [
+      "Thicken the torus ring by 100 mm",
       "Grow this solid by 0.5m in every direction",
       "Shrink this mass by 200mm",
       "Offset the building envelope outward by 1m\n\n# Example\n```ts\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst grown = await snaptrude.core.geom.create.brepFromOffset(brep, 0.5)\n```"
@@ -827,14 +857,27 @@
     "argsType": "BrepHandle",
     "resultType": "BrepHandle"
   },
+  {
+    "path": "core.geom.create.brepFromPatch",
+    "namespace": "core.geom.create",
+    "summary": "Stretches a surface across a closed loop of boundary curves and thickens it into a SOLID in one call — a roof over four curves, a canopy between two rails, a blend across a gap. `thickness` is in internal length units and is required: only solids reach the canvas, and there is no separate surface object to keep. Pass edges as `{ edge, brep, face }` with `continuity: \"tangent\"` to leave the named face smoothly. The result carries NO recipe (`design.query.getParameters` returns `null`) — label it when you commit it, because the label is all the provenance there is.",
+    "examplePrompts": [
+      "Patch a roof over these four boundary curves, 250 mm thick",
+      "Span a canopy between these two curved rails, 300 mm thick\n\n# Example\n```ts\n// A roof over four curves\nconst roof = await snaptrude.core.geom.create.brepFromPatch(\n[curveA, curveB, curveC, curveD],\n0.25,\n)\nconst mass = await snaptrude.design.create.massFromBrep(roof, \"Roof patch\")\n```\n\n```ts\n// A canopy between two towers' rims, leaving every wall it meets smoothly:\n// with `continuity: \"tangent\"` EVERY item is an edge naming its face.\nconst canopy = await snaptrude.core.geom.create.brepFromPatch(\n[\n{ edge: rimA, brep: towerA, face: wallA },\n{ edge: sideA, brep: towerA, face: endA },\n{ edge: rimB, brep: towerB, face: wallB },\n{ edge: sideB, brep: towerB, face: endB },\n],\n0.3,\n{ continuity: \"tangent\" },\n)\n```"
+    ],
+    "argsType": "(CurveHandle | OwnedEdge)[]",
+    "resultType": "BrepHandle"
+  },
   {
     "path": "core.geom.create.brepFromRevolution",
     "namespace": "core.geom.create",
-    "summary": "Revolves a planar profile about an axis to make a solid of revolution — a full turn by default. Host API call — returns a new {@linkcode BrepHandle}; the input contour is read-only. Holes in the profile are allowed. Profile segments must stay parallel or perpendicular to the axis — inclined or arc segments would revolve into surfaces Snaptrude cannot represent.",
+    "summary": "Revolves a planar profile about an axis to make a solid of revolution — a full turn by default. Host API call — returns a new {@linkcode BrepHandle}; the input contour is read-only. Holes in the profile are allowed, and segments may run at any angle to the axis: an inclined segment revolves into a cone, an arc into a sphere or torus section. This is the general route to domes, vases, columns and rotundas.",
     "examplePrompts": [
       "Create a dome from this section",
       "Revolve this profile 360 degrees around the vertical axis",
-      "Build a rotunda by revolving this wall section\n\n# Example\n```ts\n// A cylinder: revolve a 2m-wide, 3m-tall rectangle about the Y axis at its edge\nconst rect = await snaptrude.core.geom.create.profileFromLinePoints([\nawait snaptrude.core.math.vec3.new(0, 0, 0),\nawait snaptrude.core.math.vec3.new(2, 0, 0),\nawait snaptrude.core.math.vec3.new(2, 3, 0),\nawait snaptrude.core.math.vec3.new(0, 3, 0),\n])\nconst profile = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst cylinder = await snaptrude.core.geom.create.brepFromRevolution(\nprofile,\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 1, z: 0 },\n)\n```"
+      "Build a rotunda by revolving this wall section",
+      "Make a dome by revolving a quarter-circle about the vertical axis",
+      "Turn this curved outline into a vase\n\n# Example\n```ts\n// A cylinder: revolve a 2m-wide, 3m-tall rectangle about the Y axis at\n// its edge — the left edge sits ON the axis, which is legal.\nconst rect = await snaptrude.core.geom.create.profileFromLinePoints([\nawait snaptrude.core.math.vec3.new(0, 0, 0),\nawait snaptrude.core.math.vec3.new(2, 0, 0),\nawait snaptrude.core.math.vec3.new(2, 3, 0),\nawait snaptrude.core.math.vec3.new(0, 3, 0),\n])\nconst profile = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst cylinder = await snaptrude.core.geom.create.brepFromRevolution(\nprofile,\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 1, z: 0 },\n)\n```"
     ],
     "argsType": "ContourHandle",
     "resultType": "BrepHandle"
@@ -844,13 +887,25 @@
     "namespace": "core.geom.create",
     "summary": "Hollows a solid into constant-thickness walls, removing the given faces as openings. Host API call — returns a new {@linkcode BrepHandle}; the input brep is read-only. The outer surface is kept and the walls grow inward.",
     "examplePrompts": [
+      "Hollow the dome into a 300 mm shell, open at the base",
       "Hollow this mass into 200mm walls",
       "Shell this form with the top face open",
-      "Turn this solid tower into a tube open at both ends\n\n# Example\n```ts\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst faces = await snaptrude.core.geom.query.brep.listFaces(brep)\nconst hollow = await snaptrude.core.geom.create.brepFromShell(brep, [faces[0]], 0.2)\n```"
+      "Turn this solid tower into a tube open at both ends\n\n# Example\n```ts\n// Open the dome at its flat base: the one face whose surface is a plane\nconst faces = await snaptrude.core.geom.query.brep.listFaces(dome)\nconst base = []\nfor (const face of faces) {\nif ((await snaptrude.core.geom.query.face.getSurfaceKind(face)) === \"plane\") base.push(face)\n}\nconst hollow = await snaptrude.core.geom.create.brepFromShell(dome, base, 1.181) // 300 mm\n```"
     ],
     "argsType": "BrepHandle",
     "resultType": "BrepHandle"
   },
+  {
+    "path": "core.geom.create.brepFromSphere",
+    "namespace": "core.geom.create",
+    "summary": "Create a solid **sphere** B-rep from a centre and radius. Host API call — returns a {@linkcode BrepHandle}; commit it to the scene with `design.create.massFromBrep`. The result carries an exact spherical surface (not a faceted approximation) and a creation recipe — read the committed mass's parameters back with `design.query.getParameters` and edit them with `design.update.parameters`.",
+    "examplePrompts": [
+      "Create a sphere of radius 5 at the origin",
+      "Add a 3m ball on top of the tower\n\n# Example\n```ts\nconst brep = await snaptrude.core.geom.create.brepFromSphere({ x: 0, y: 5, z: 0 }, 5)\nconst mass = await snaptrude.design.create.massFromBrep(brep, \"Sphere\")\n```"
+    ],
+    "argsType": "Vec3Components",
+    "resultType": "BrepHandle"
+  },
   {
     "path": "core.geom.create.brepFromSubtraction",
     "namespace": "core.geom.create",
@@ -866,7 +921,7 @@
   {
     "path": "core.geom.create.brepFromSweep",
     "namespace": "core.geom.create",
-    "summary": "Sweeps a planar profile along a polyline path, with mitred corners at each bend. Host API call — returns a new {@linkcode BrepHandle}; the input contour is read-only. The profile must be hole-free and must not lie in a plane containing the first path segment's direction. Repeating the first point as the last closes the path into a ring solid (a picture frame): closed paths must be flat and straight-segmented and take a straight-edged (arc-free) profile — the ring's cross-section is the authored profile projected along the first leg onto the first mitre plane, so a profile not perpendicular to the first leg appears sheared. An optional scale law tapers the sweep: `startScale`/`endScale` interpolate linearly by arc length, or `scales` gives one factor per path point (scaling is about the profile centroid). A uniform scale (all factors equal) works on any path today's sweep accepts; a varying scale takes straight (collinear) open paths with straight-edged profiles — tapering across a bend or along an arc edge would create faces Snaptrude cannot represent and throws (sweep each straight run separately and union the results instead). An optional `transition` picks the corner treatment: `\"miter\"` (default) is today's sharp mitred bend; `{ bevel: b }` chamfers each turning corner by cutting `b` back along both adjacent legs (works on open and closed paths — each leg must be long enough for its cuts). On a corner-less path `transition` has no effect, and the varying-scale lane takes straight paths, so it never sees a corner.",
+    "summary": "Sweeps a planar profile along a polyline path, with mitred corners at each bend. Host API call — returns a new {@linkcode BrepHandle}; the input contour is read-only. The profile must be hole-free and must not lie in a plane containing the first path segment's direction. Repeating the first point as the last closes the path into a ring solid (a picture frame): closed paths must be flat and straight-segmented and take a straight-edged (arc-free) profile — the ring's cross-section is the authored profile projected along the first leg onto the first mitre plane, so a profile not perpendicular to the first leg appears sheared. An optional scale law tapers the sweep: `startScale`/`endScale` interpolate linearly by arc length, or `scales` gives one factor per path point (scaling is about the profile centroid). A uniform scale (all factors equal) works on any path today's sweep accepts; a varying scale takes straight (collinear) open paths with straight-edged profiles — tapering across a bend or along an arc edge would create faces Snaptrude cannot represent and throws (sweep each straight run separately and union the results instead). An optional `transition` picks the corner treatment: `\"miter\"` (default) is today's sharp mitred bend; `\"round\"` carries the section around each turning corner on a tangent circular arc, so the corner patch is a real curved (cylindrical) surface rather than a flat cut (open paths only — `\"round\"` on a closed ring path is refused); `{ bevel: b }` chamfers each turning corner by cutting `b` back along both adjacent legs (works on open and closed paths — each leg must be long enough for its cuts). On a corner-less path `transition` has no effect, and the varying-scale lane takes straight paths, so it never sees a corner.",
     "examplePrompts": [
       "Sweep this profile along the corridor path",
       "Extrude the railing section along this route",
@@ -874,11 +929,35 @@
       "Sweep a frame profile around a closed rectangular loop",
       "Taper this duct from 1x1 to 2x2 along its run",
       "Sweep a column section that narrows toward the top",
-      "Chamfer the corners of this swept frame by 200mm\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(0.4, 0.4)\nconst profile = await snaptrude.core.geom.create.contourFromProfile(rect)\n// profileRect lies in the XZ plane, so the path must START out of that\n// plane (here: straight up), then it can run horizontally.\nconst duct = await snaptrude.core.geom.create.brepFromSweep(profile, [\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 2.8, z: 0 },\n{ x: 10, y: 2.8, z: 0 },\n])\n// A closed ring (picture frame): repeat the first point as the last\nconst frame = await snaptrude.core.geom.create.brepFromSweep(profile, [\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 3, z: 0 },\n{ x: 4, y: 3, z: 0 },\n{ x: 4, y: 0, z: 0 },\n{ x: 0, y: 0, z: 0 },\n])\n// A tapered straight run: 0.4x0.4 at the start, 0.8x0.8 at the end\nconst flue = await snaptrude.core.geom.create.brepFromSweep(\nprofile,\n[\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 10, z: 0 },\n],\n{ startScale: 1, endScale: 2 },\n)\n```"
+      "Chamfer the corners of this swept frame by 200mm",
+      "Sweep this handrail with rounded corners at the bends\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(0.4, 0.4)\nconst profile = await snaptrude.core.geom.create.contourFromProfile(rect)\n// profileRect lies in the XZ plane, so the path must START out of that\n// plane (here: straight up), then it can run horizontally.\nconst duct = await snaptrude.core.geom.create.brepFromSweep(profile, [\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 2.8, z: 0 },\n{ x: 10, y: 2.8, z: 0 },\n])\n// A closed ring (picture frame): repeat the first point as the last\nconst frame = await snaptrude.core.geom.create.brepFromSweep(profile, [\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 3, z: 0 },\n{ x: 4, y: 3, z: 0 },\n{ x: 4, y: 0, z: 0 },\n{ x: 0, y: 0, z: 0 },\n])\n// A tapered straight run: 0.4x0.4 at the start, 0.8x0.8 at the end\nconst flue = await snaptrude.core.geom.create.brepFromSweep(\nprofile,\n[\n{ x: 0, y: 0, z: 0 },\n{ x: 0, y: 10, z: 0 },\n],\n{ startScale: 1, endScale: 2 },\n)\n```"
     ],
     "argsType": "ContourHandle",
     "resultType": "BrepHandle"
   },
+  {
+    "path": "core.geom.create.brepFromSweepAlongCurve",
+    "namespace": "core.geom.create",
+    "summary": "Sweeps a cross-section along a SMOOTH path — splines, arcs and lines chained end to end — with control of how the profile turns. {@linkcode PluginGeomCreateApi.brepFromSweep} takes a polyline path; this takes curves. Host API call — returns a new {@linkcode BrepHandle}; the inputs are read-only. Records as `sweepAlongCurve`, so the orientation stays editable through `design.update.parameters` (agent-editable; the panel shows it read-only — a string is not a scalar row).",
+    "examplePrompts": [
+      "Sweep a 600x400 duct along this curved route and keep it upright",
+      "Run this handrail along the curved stair edge",
+      "Bend this footprint along the arc\n\n# Example\n```ts\nconst route = await snaptrude.core.geom.create.splineFromPoints(points)\nconst duct = await snaptrude.core.geom.create.brepFromSweepAlongCurve(profile, [route], {\norientation: \"upright\",\n})\n```"
+    ],
+    "argsType": "ContourHandle",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromTorus",
+    "namespace": "core.geom.create",
+    "summary": "Create a solid **torus** (ring / donut) B-rep from its centre, plane normal, ring radius and tube radius. Host API call — returns a {@linkcode BrepHandle}; commit with `design.create.massFromBrep`. `majorRadius` is centre-to-tube-centre; `minorRadius` is the tube's own radius and must be strictly smaller. Carries a creation recipe, editable through `design.update.parameters`.",
+    "examplePrompts": [
+      "Create a donut-shaped ring 10m across with a 1m tube",
+      "Add a torus canopy around the tower\n\n# Example\n```ts\nconst ring = await snaptrude.core.geom.create.brepFromTorus(\n{ x: 0, y: 6, z: 0 },\n{ x: 0, y: 1, z: 0 },\n5,\n1,\n)\n```"
+    ],
+    "argsType": "Vec3Components",
+    "resultType": "BrepHandle"
+  },
   {
     "path": "core.geom.create.brepFromUnion",
     "namespace": "core.geom.create",
@@ -903,6 +982,16 @@
     "argsType": "BrepHandle",
     "resultType": "BrepHandle[]"
   },
+  {
+    "path": "core.geom.create.brepsFromSplitByFace",
+    "namespace": "core.geom.create",
+    "summary": "Cuts a solid with a FACE of another solid — the curved twin of {@linkcode PluginGeomCreateApi.brepsFromSplit}, which cuts with a plane. Host API call — returns new {@linkcode BrepHandle}s; both inputs are read-only. BOTH breps must be in the same frame: read scene masses with `design.query.geometry.getBrep(x, { frame: \"world\" })` (the default is each mass's own local frame, and two masses have two). The pieces come back in DESCENDING volume order; pick the one you want with `core.geom.query.brep.getCentroid` or `getVolume` and commit it. A piece carries no recipe — label it.",
+    "examplePrompts": [
+      "Cut this mass with the curved roof surface and keep the lower part\n\n# Example\n```ts\nconst target = await snaptrude.design.query.geometry.getBrep(tower, { frame: \"world\" })\nconst tool = await snaptrude.design.query.geometry.getBrep(roof, { frame: \"world\" })\nconst [toolFace] = await snaptrude.core.geom.query.brep.listFaces(tool)\nconst pieces = await snaptrude.core.geom.create.brepsFromSplitByFace(target, toolFace, tool)\n```"
+    ],
+    "argsType": "BrepHandle",
+    "resultType": "BrepHandle[]"
+  },
   {
     "path": "core.geom.create.circle",
     "namespace": "core.geom.create",
@@ -933,6 +1022,14 @@
     "argsType": "ProfileHandle",
     "resultType": "ContourHandle"
   },
+  {
+    "path": "core.geom.create.curvesFromProjection",
+    "namespace": "core.geom.create",
+    "summary": "Drops a curve onto a face along the face's normal and returns the curves it lands on — one per connected run, empty when the curve misses the face entirely. Host API call — returns new curve handles; the inputs are read-only. No lengths are involved: the result is a curve in the same internal length units as its inputs.",
+    "examplePrompts": [],
+    "argsType": "CurveHandle",
+    "resultType": "CurveHandle[]"
+  },
   {
     "path": "core.geom.create.line",
     "namespace": "core.geom.create",
@@ -965,6 +1062,18 @@
     "argsType": "Vec3Handle[]",
     "resultType": "ProfileHandle"
   },
+  {
+    "path": "core.geom.create.profileFromSplinePoints",
+    "namespace": "core.geom.create",
+    "summary": "Create a CLOSED smooth profile passing through each point, in order, with the loop closed smoothly back from the last point to the first (do NOT repeat the first point). Host API call — returns a handle. This is the closed counterpart of {@linkcode PluginGeomCreateApi.splineFromPoints} and the one-call route from points to an extrudable outline: wrap in `contourFromProfile` and extrude/loft/sweep as usual.",
+    "examplePrompts": [
+      "Make a blob-shaped floor plate through these points",
+      "Organic curved outline through these corners",
+      "Freeform podium profile\n\n# Example\n```ts\nconst profile = await snaptrude.core.geom.create.profileFromSplinePoints([p0, p1, p2, p3, p4])\nconst contour = await snaptrude.core.geom.create.contourFromProfile(profile)\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst podium = await snaptrude.design.create.massFromBrep(brep, \"Podium\")\n```"
+    ],
+    "argsType": "Vec3Handle[]",
+    "resultType": "ProfileHandle"
+  },
   {
     "path": "core.geom.create.profileRect",
     "namespace": "core.geom.create",
@@ -976,6 +1085,29 @@
     "argsType": "number",
     "resultType": "ProfileHandle"
   },
+  {
+    "path": "core.geom.create.splineFromControlPoints",
+    "namespace": "core.geom.create",
+    "summary": "Create an open NURBS curve DEFINED BY control points — the curve is pulled TOWARD the interior points, not through them; it starts at the first point and ends at the last. Knots are computed for you (clamped, uniform) — there is no knot-vector argument. For a curve that must pass THROUGH given points use {@linkcode PluginGeomCreateApi.splineFromPoints}.",
+    "examplePrompts": [
+      "Draw a smooth curve controlled by these four points",
+      "Rebuild this edge from its control polygon\n\n# Example\n```ts\nconst curve = await snaptrude.core.geom.create.splineFromControlPoints([p0, p1, p2, p3])\n// Quadratic instead of the default cubic\nconst tighter = await snaptrude.core.geom.create.splineFromControlPoints(\n[p0, p1, p2, p3],\n{ degree: 2 },\n)\n```"
+    ],
+    "argsType": "Vec3Handle[]",
+    "resultType": "SplineHandle"
+  },
+  {
+    "path": "core.geom.create.splineFromPoints",
+    "namespace": "core.geom.create",
+    "summary": "Create an open NURBS curve passing exactly THROUGH each point, in order (centripetal Catmull-Rom fit → clamped cubic B-spline; C1-smooth, no cusps on uneven spacing). Host API call — returns a handle. The points are interpolated, NOT control points. For a CLOSED smooth loop use {@linkcode PluginGeomCreateApi.profileFromSplinePoints} — closed splines exist only as profiles, never as a single curve handle.",
+    "examplePrompts": [
+      "Draw a smooth curve through these points",
+      "Make a wavy edge that passes through A, B, C and D",
+      "Freeform curved wall path through these clicks\n\n# Example\n```ts\nconst spline = await snaptrude.core.geom.create.splineFromPoints([p0, p1, p2, p3])\n// Mixed profile: smooth top, straight closing base\nconst base = await snaptrude.core.geom.create.line(p3, p0)\nconst profile = await snaptrude.core.geom.create.profileFromCurves([spline, base])\n```"
+    ],
+    "argsType": "Vec3Handle[]",
+    "resultType": "SplineHandle"
+  },
   {
     "path": "core.geom.delete.contour",
     "namespace": "core.geom.delete",
@@ -1101,10 +1233,11 @@
       "Read the radius of this curved edge",
       "Is this edge straight or an arc?",
       "Get the exact start and end points of this edge",
-      "Measure the length of each edge of this mass\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst edges = await snaptrude.core.geom.query.brep.listEdges(brep)\nfor (const edge of edges) {\nconst curve = await snaptrude.core.geom.query.brep.getEdgeCurve(brep, edge)\nif (curve.type === \"arc\") console.log(\"arc radius:\", curve.radius)\n}\n}\n```"
+      "Measure the length of each edge of this mass",
+      "Read the control points of this curved edge\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst edges = await snaptrude.core.geom.query.brep.listEdges(brep)\nfor (const edge of edges) {\nconst curve = await snaptrude.core.geom.query.brep.getEdgeCurve(brep, edge)\nif (curve.type === \"arc\") console.log(\"arc radius:\", curve.radius)\n}\n}\n```"
     ],
     "argsType": "BrepHandle",
-    "resultType": "| { type: \"line\"; startPoint: Vec3Components; endPoint: Vec3Components; length: number }\n    | {\n        type: \"arc\"\n        startPoint: Vec3Components\n        endPoint: Vec3Components\n        centre: Vec3Components\n        axis: Vec3Components\n        radius: number\n        length: number\n      }\n    | {\n        type: \"circle\"\n        centre: Vec3Components\n        axis: Vec3Components\n        radius: number\n        length: number\n      }"
+    "resultType": "| { type: \"line\"; startPoint: Vec3Components; endPoint: Vec3Components; length: number }\n    | {\n        type: \"arc\"\n        startPoint: Vec3Components\n        endPoint: Vec3Components\n        centre: Vec3Components\n        axis: Vec3Components\n        radius: number\n        length: number\n      }\n    | {\n        type: \"circle\"\n        centre: Vec3Components\n        axis: Vec3Components\n        radius: number\n        length: number\n      }\n    | {\n        type: \"spline\"\n        startPoint: Vec3Components\n        endPoint: Vec3Components\n        degree: number\n        controlPoints: Vec3Components[]\n        /** Expanded by multiplicity: `controlPoints.length + degree + 1` entries. */\n        knots: number[]\n        length: number\n      }"
   },
   {
     "path": "core.geom.query.brep.getFaceCount",
@@ -1138,6 +1271,18 @@
     "argsType": "BrepHandle",
     "resultType": "Vec3Components"
   },
+  {
+    "path": "core.geom.query.brep.getVolume",
+    "namespace": "core.geom.query.brep",
+    "summary": "Get the enclosed **volume** of a closed solid, integrated from its exact surfaces. Curved faces are measured analytically, not from their tessellation — a real sphere of radius 5 reports 523.6, whatever its triangle count. That makes this the reliable way to confirm a solid is the shape you intended (a torus should measure 2·π²·R·r²).",
+    "examplePrompts": [
+      "What is the volume of this mass?",
+      "How much concrete is in this shape?",
+      "Check the volume of the dome I just made\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst volume = await snaptrude.core.geom.query.brep.getVolume(brep)\nconsole.log(\"volume:\", volume)\n}\n```"
+    ],
+    "argsType": "BrepHandle",
+    "resultType": "number"
+  },
   {
     "path": "core.geom.query.brep.hasEdge",
     "namespace": "core.geom.query.brep",
@@ -1742,7 +1887,7 @@
   {
     "path": "core.geom.query.edge.getCurve",
     "namespace": "core.geom.query.edge",
-    "summary": "Get the underlying curve geometry of an edge (a line or arc).",
+    "summary": "Get the underlying curve geometry of an edge (a line, arc or spline).",
     "examplePrompts": [],
     "argsType": "EdgeHandle",
     "resultType": "CurveHandle | null"
@@ -1779,6 +1924,28 @@
     "argsType": "EdgeHandle",
     "resultType": "VertexHandle[]"
   },
+  {
+    "path": "core.geom.query.face.getArea",
+    "namespace": "core.geom.query.face",
+    "summary": "Exact surface area of one face of `brep`, in internal length units SQUARED — integrated off the face's own surface, not its facets, so a curved patch reads exactly rather than as its triangles. Needs the parent brep: a face handle cannot name its own solid.",
+    "examplePrompts": [
+      "How big is this roof patch?",
+      "Which face of this mass has the largest area?\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst faces = await snaptrude.core.geom.query.brep.listFaces(brep)\nconst areas = await Promise.all(\nfaces.map((f) => snaptrude.core.geom.query.face.getArea(f, brep)),\n)\n}\n```"
+    ],
+    "argsType": "FaceHandle",
+    "resultType": "number"
+  },
+  {
+    "path": "core.geom.query.face.getCentroid",
+    "namespace": "core.geom.query.face",
+    "summary": "Centre of area of one face of `brep`, as a point in that brep's frame (internal length units). On a solid whose every face reads `\"spline\"` this is the read that tells two patches apart — the top of a thickened patch from its bottom, one quarter of a closed surface from the next.",
+    "examplePrompts": [
+      "Where is the middle of this face?",
+      "Pick the topmost face of this curved mass\n\n# Example\n```ts\nconst centre = await snaptrude.core.geom.query.face.getCentroid(face, brep)\n```"
+    ],
+    "argsType": "FaceHandle",
+    "resultType": "Vec3Components"
+  },
   {
     "path": "core.geom.query.face.getHalfEdge",
     "namespace": "core.geom.query.face",
@@ -1819,6 +1986,19 @@
     "argsType": "FaceHandle",
     "resultType": "number"
   },
+  {
+    "path": "core.geom.query.face.getSurfaceKind",
+    "namespace": "core.geom.query.face",
+    "summary": "Read what KIND of surface a face lies on. This is the one read that tells a genuinely curved face from a faceted approximation of one: every face of a 200-triangle \"dome\" answers `\"plane\"`, while a real dome has faces answering `\"sphere\"`. Use it to confirm a curved solid actually came out curved.",
+    "examplePrompts": [
+      "Is this face flat or curved?",
+      "Check that this dome is a real sphere, not a faceted approximation",
+      "What kind of surface is this face?",
+      "How many curved faces does this mass have?\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst faces = await snaptrude.core.geom.query.brep.listFaces(brep)\nconst kinds = []\nfor (const face of faces) kinds.push(await snaptrude.core.geom.query.face.getSurfaceKind(face))\nconsole.log(\"spherical faces:\", kinds.filter((k) => k === \"sphere\").length)\n}\n```"
+    ],
+    "argsType": "FaceHandle",
+    "resultType": "\"plane\" | \"cylinder\" | \"cone\" | \"sphere\" | \"torus\" | \"spline\" | null"
+  },
   {
     "path": "core.geom.query.face.hasHoles",
     "namespace": "core.geom.query.face",
@@ -3403,7 +3583,8 @@
     "examplePrompts": [
       "Switch to present mode",
       "Open BIM mode",
-      "Go back to design mode\n\n# Example\n```ts\nawait snaptrude.core.mode.set(\"present\")\n// ... presentation work ...\nawait snaptrude.core.mode.set(\"design\")\n```"
+      "Go back to design mode",
+      "Open program mode\n\n# Example\n```ts\nawait snaptrude.core.mode.set(\"present\")\n// ... presentation work ...\nawait snaptrude.core.mode.set(\"design\")\n```"
     ],
     "argsType": "PluginAppMode",
     "resultType": "PluginCoreModeSetResult"
@@ -4038,6 +4219,19 @@
     "argsType": "ComponentHandle",
     "resultType": "PluginCoreTagsGetTagsForComponentResult"
   },
+  {
+    "path": "core.tags.listForComponents",
+    "namespace": "core.tags",
+    "summary": "List the tags carried by many components in one call.",
+    "examplePrompts": [
+      "Get the tags of every space with their colors",
+      "List the tags on all rooms so I can color them by Occupancy",
+      "Which tag does each selected space carry?\n\n# Example\n```ts\nconst { components } = await snaptrude.core.tags.listForComponents()\nfor (const c of components) {\nconst occupancy = c.tags.find((t) => t.categoryName === \"Occupancy\")\nif (occupancy) paint(c.componentId, occupancy.color)\n}\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginCoreTagsListForComponentsResult",
+    "performance": "One round-trip for any number of components — use this instead of a `listForComponent` loop."
+  },
   {
     "path": "core.tags.unassign",
     "namespace": "core.tags",
@@ -4274,6 +4468,17 @@
     "argsType": "Vec3Handle",
     "resultType": "ComponentHandle"
   },
+  {
+    "path": "design.create.columnsFromGrids",
+    "namespace": "design.create",
+    "summary": "Create **columns at every grid-line intersection** of the given grid groups, sized `width` × `depth` and oriented to the grid axes, on the grids' storey. All columns commit as ONE undoable unit.",
+    "examplePrompts": [
+      "Generate columns on this grid",
+      "Place 450mm square columns at every grid intersection\n\n# Example\n```ts\nconst grids = await snaptrude.design.query.listGrids()\nconst columns = await snaptrude.design.create.columnsFromGrids(grids, 0.45, 0.45)\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "ComponentHandle[]"
+  },
   {
     "path": "design.create.copy",
     "namespace": "design.create",
@@ -4299,10 +4504,27 @@
       "Put a door from the catalog at this point on the wall",
       "Insert the entrance door into this wall",
       "Add a door to the wall and call it Entry-01",
-      "Add a door that opens into the living room\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ isSelected: true })\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst door = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Entry-01\" },\n)\n// …facing a specific side of the wall (pass a point inside that room):\nconst intoKitchen = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\nundefined,\nawait snaptrude.core.math.vec3.new(3, 0, 9),\n)\n```"
+      "Add a door that opens into the living room",
+      "Put a door here hinged on the north jamb\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ isSelected: true })\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst door = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Entry-01\" },\n)\n// …facing a specific side of the wall (pass a point inside that room):\nconst intoKitchen = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\nundefined,\nawait snaptrude.core.math.vec3.new(3, 0, 9),\n)\n// …and hinged on the jamb nearest a point (here the +x end of the opening):\nconst hingedRight = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ hinge: await snaptrude.core.math.vec3.new(3.5, 0, 5) },\nawait snaptrude.core.math.vec3.new(3, 0, 9),\n)\n```"
     ],
     "argsType": "string",
-    "resultType": "ComponentHandle"
+    "resultType": "ComponentHandle",
+    "performance": "For MORE THAN ONE door, call `design.create.doors(items[])` — one host round-trip and ONE undo entry, with each host wall re-cut once per opening inside that single call. Looping this single-door creator is N round-trips."
+  },
+  {
+    "path": "design.create.doors",
+    "namespace": "design.create",
+    "summary": "Place **many doors** into host walls in one undoable operation (bulk plural of {@linkcode door}). Each item carries its own catalog id, host wall, world position, and optional `facing`, `label`, `width` and `height` — the same fields as a `\"door\"` {@linkcode PluginDesignCreateOpeningOptions}. Validate-all-or-throw; one command.",
+    "examplePrompts": [
+      "Add doors to all of these walls at once",
+      "Place a door in every room in one operation",
+      "Bulk add the entrance doors from this schedule",
+      "Put three doors on this wall in a single undo step",
+      "Add all the doors for this floor plan together"
+    ],
+    "argsType": "PluginCreateDoorItem[]",
+    "resultType": "ComponentHandle[]",
+    "performance": "Bulk creator — the whole batch is ONE host round-trip and ONE undo entry, and each distinct catalog source loads once. Always prefer this over calling `design.create.door` in a loop: build the full `items[]` array first (all host walls and points up front), then make one call. # Example ```ts const v = snaptrude.core.math.vec3 const [wall] = await snaptrude.design.query.listWalls({ isSelected: true }) const [entry] = await snaptrude.design.doors.listCatalog() const [front, side] = await snaptrude.design.create.doors([ { catalogId: entry.id, hostWall: wall, position: await v.new(2, 0, 5), label: \"D-01\" }, { catalogId: entry.id, hostWall: wall, position: await v.new(6, 0, 5), width: 1.2 }, ]) // `wall` was re-cut twice and no longer resolves — ask the opening for its host: const currentWall = await snaptrude.design.query.getHost(front) ```"
   },
   {
     "path": "design.create.floor",
@@ -4312,10 +4534,26 @@
       "Create a floor from this room outline",
       "Add a 100mm thick floor over the footprint",
       "Lay flooring across the selected outline",
-      "Put a floor at this position with 150mm thickness\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(5, 4)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst [floor, ...siblings] = await snaptrude.design.create.floor(contour, 0.1)\n```"
+      "Put a floor at this position with 150mm thickness\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(5, 4)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst floor = await snaptrude.design.create.floor(contour, 0.1)\n```"
     ],
     "argsType": "ContourHandle",
-    "resultType": "ComponentHandle[]"
+    "resultType": "ComponentHandle",
+    "performance": "For MORE THAN ONE floor, call `design.create.floors(items[])` — one host round-trip and ONE undo entry for the whole batch. Looping this single-floor creator is N round-trips and N undo entries."
+  },
+  {
+    "path": "design.create.floors",
+    "namespace": "design.create",
+    "summary": "Create **many floors** in one undoable operation (bulk plural of {@linkcode floor}). Each item extrudes its own footprint contour (outer profile + holes) upward by its own `thickness`, at its own optional position offset. Validate-all-or-throw; one command.",
+    "examplePrompts": [
+      "Create floors for all these room outlines at once",
+      "Add a floor to every space in one operation",
+      "Bulk create the floor plates for this building",
+      "Lay 100mm floors across these five footprints in one undo step",
+      "Create the ground and first floor slabs together"
+    ],
+    "argsType": "PluginCreateFloorItem[]",
+    "resultType": "ComponentHandle[]",
+    "performance": "Bulk creator — the whole batch is ONE host round-trip and ONE undo entry. Always prefer this over calling `design.create.floor` in a loop: build the full `items[]` array first (all contours and offsets up front), then make one call. # Example ```ts const rect = await snaptrude.core.geom.create.profileRect(5, 4) const contour = await snaptrude.core.geom.create.contourFromProfile(rect) const [ground, upper] = await snaptrude.design.create.floors([ { contour, thickness: 0.1 }, { contour, thickness: 0.1, position: await snaptrude.core.math.vec3.new(0, 3, 0) }, ]) ```"
   },
   {
     "path": "design.create.furniture",
@@ -4330,8 +4568,60 @@
       "Place a chair here rotated 90 degrees\n\n# Example\n```ts\nconst chair = await snaptrude.design.create.furniture(\n\"6620f1a…\",             // from design.furniture.listCatalog()\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Chair-01\" },\n)\n// …placed already turned 90° about the vertical axis:\nconst turned = await snaptrude.design.create.furniture(\n\"6620f1a…\",\nawait snaptrude.core.math.vec3.new(3, 0, 5),\nundefined,\n90,\n)\n```"
     ],
     "argsType": "string",
+    "resultType": "ComponentHandle",
+    "performance": "For MORE THAN ONE item, call `design.create.furnitureItems(items[])` — one host round-trip and ONE undo entry, and a catalog source shared by several items is fetched once. Looping this single-item creator is N round-trips."
+  },
+  {
+    "path": "design.create.furnitureItems",
+    "namespace": "design.create",
+    "summary": "Place **many furniture items** in one undoable operation (bulk plural of {@linkcode furniture}). Each item names a catalog id and an absolute world position (`position.y` is the REST elevation — the same grounding contract as the singular creator), with optional label and rotation. A catalog source shared by several items is fetched and recorded once for the whole batch, so the host — not the caller — owns source persistence (there is no per-item `createNewSourceMesh`). Validate-all-or-throw; one command.",
+    "examplePrompts": [
+      "Place all the desks for this office at once",
+      "Furnish every bedroom in one operation",
+      "Bulk place these chairs around the table",
+      "Add the whole furniture layout in a single undo step",
+      "Drop twenty copies of this chair at these positions"
+    ],
+    "argsType": "PluginCreateFurnitureItem[]",
+    "resultType": "ComponentHandle[]",
+    "performance": "Bulk creator — the whole batch is ONE host round-trip and ONE undo entry, and each distinct catalog source loads once. Always prefer this over calling `design.create.furniture` in a loop: build the full `items[]` array first (all positions and angles up front), then make one call. # Example ```ts const v = snaptrude.core.math.vec3 const [chair] = await snaptrude.design.furniture.listCatalog() const placed = await snaptrude.design.create.furnitureItems([ { catalogId: chair.id, position: await v.new(3, 0, 5), label: \"Chair-01\" }, { catalogId: chair.id, position: await v.new(4, 0, 5), angleInDegrees: 90 }, { catalogId: chair.id, position: await v.new(5, 0, 5), angleInDegrees: 180 }, ]) ```"
+  },
+  {
+    "path": "design.create.grid",
+    "namespace": "design.create",
+    "summary": "Create a free rectangular **structural grid** — one grid group with two perpendicular line families (`linesX` lines spaced `spacingX` apart, and `linesY` lines spaced `spacingY` apart) on the active storey. One undoable creation.",
+    "examplePrompts": [
+      "Create a 5 by 8 structural grid with 6 metre spacing",
+      "Add a column grid rotated 30 degrees",
+      "Set up a structural grid at the site origin\n\n# Example\n```ts\nconst centre = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst grid = await snaptrude.design.create.grid(5, 8, 6, 6, { center: centre })\n```"
+    ],
+    "argsType": "number",
     "resultType": "ComponentHandle"
   },
+  {
+    "path": "design.create.gridFromCurve",
+    "namespace": "design.create",
+    "summary": "Create a **structural grid from a single curve** — one grid group holding one wing with one line (the draw tool's output). The curve may be a line or an arc; circles are rejected with `VALIDATION`. Undoable.",
+    "examplePrompts": [
+      "Draw a grid line from A to B",
+      "Add a curved grid line through these points",
+      "Create grid line \"C\" along this wall\n\n# Example\n```ts\nconst { vec3 } = snaptrude.core.math\nconst from = await vec3.new(0, 0, 0)\nconst to = await vec3.new(30, 0, 0)\nconst curve = await snaptrude.core.geom.create.line(from, to)\nconst grid = await snaptrude.design.create.gridFromCurve(curve, { tag: \"A\" })\n```"
+    ],
+    "argsType": "CurveHandle",
+    "resultType": "ComponentHandle"
+  },
+  {
+    "path": "design.create.gridsFromMasses",
+    "namespace": "design.create",
+    "summary": "Generate **structural grids fitted to mass footprints** — one grid group per footprint cluster, with counts and orientation derived from each footprint's geometry and the given spacings. All created groups commit as ONE undoable unit.",
+    "examplePrompts": [
+      "Generate grids for the selected masses",
+      "Auto-generate a 6m structural grid on this building",
+      "Fit column grids to every mass on this storey\n\n# Example\n```ts\nconst masses = await snaptrude.design.query.listMasses({ storeys: [1] })\nconst grids = await snaptrude.design.create.gridsFromMasses(masses, 6, 6)\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "ComponentHandle[]"
+  },
   {
     "path": "design.create.mass",
     "namespace": "design.create",
@@ -4367,7 +4657,7 @@
     ],
     "argsType": "PluginDesignCreateOpeningOptions",
     "resultType": "ComponentHandle",
-    "performance": "Single-opening creator — use it for one hosted opening. A plural API is intentionally unavailable until host placement can be atomic. # Example ```ts const opening = await snaptrude.design.create.opening({ kind: \"window\", catalogId: windowType.id, hostWall: wall, position: await snaptrude.core.math.vec3.new(3, 0, 5), width: 1.2, height: 1.5, sillHeight: 0.9, }) ```"
+    "performance": "Single-opening creator — use it for one hosted opening. For MORE THAN ONE, call `design.create.doors(items[])` / `design.create.windows(items[])`: the same per-item fields, one host round-trip, ONE undo entry. # Example ```ts const opening = await snaptrude.design.create.opening({ kind: \"window\", catalogId: windowType.id, hostWall: wall, position: await snaptrude.core.math.vec3.new(3, 0, 5), width: 1.2, height: 1.5, sillHeight: 0.9, }) ```"
   },
   {
     "path": "design.create.referenceLines",
@@ -4469,6 +4759,21 @@
     "argsType": "PluginStaircasePreset",
     "resultType": "ComponentHandle"
   },
+  {
+    "path": "design.create.wallRuns",
+    "namespace": "design.create",
+    "summary": "Create **many wall runs** in one undoable operation (bulk plural of {@linkcode walls}). Each item is one full run — a wall per curve in that item's profile chain, mitred at shared endpoints. Junctions resolve within a run, not between runs. Each item carries its own dimensions, `wallType` and `storey`, so a single call can build a whole floor plate or several storeys at once. Validate-all-or-throw; one command.",
+    "examplePrompts": [
+      "Draw all the walls of this floor plan at once",
+      "Build every room's perimeter in one operation",
+      "Bulk create wall runs from these centerlines",
+      "Create the walls for both storeys in a single undo step",
+      "Turn these polylines into 200mm brick walls together"
+    ],
+    "argsType": "PluginCreateWallRunItem[]",
+    "resultType": "ComponentHandle[][]",
+    "performance": "Bulk creator — the whole batch is ONE host round-trip and ONE undo entry. Always prefer this over calling `design.create.walls` in a loop: build the full `items[]` array first (all profiles up front), then make one call. # Example ```ts const v = snaptrude.core.math.vec3 const ground = await snaptrude.core.geom.create.profileFromLinePoints([ await v.new(0, 0, 0), await v.new(8, 0, 0), await v.new(8, 0, 6), ]) const upper = await snaptrude.core.geom.create.profileFromLinePoints([ await v.new(0, 0, 0), await v.new(8, 0, 0), ]) const [groundWalls, upperWalls] = await snaptrude.design.create.wallRuns([ { profile: ground, height: 3, thickness: 0.2 }, { profile: upper, height: 3, storey: 2 }, ]) console.log(groundWalls.length, \"walls on the ground floor\") ```"
+  },
   {
     "path": "design.create.walls",
     "namespace": "design.create",
@@ -4483,7 +4788,8 @@
       "Build the perimeter in exposed concrete walls\n\n# Example\n```ts\nconst v = snaptrude.core.math.vec3\nconst centerlines = await snaptrude.core.geom.create.profileFromLinePoints([\nawait v.new(0, 0, 0),\nawait v.new(8, 0, 0),\nawait v.new(8, 0, 6),\n])\nconst walls = await snaptrude.design.create.walls(centerlines, 3, 0.2)\n// …built as a specific wall type (layers/material/thickness from the type):\nconst [brick] = await snaptrude.design.types.list(\"wall\")\nconst brickWalls = await snaptrude.design.create.walls(\ncenterlines, 3, undefined, brick.label,\n)\n```"
     ],
     "argsType": "ProfileHandle",
-    "resultType": "ComponentHandle[]"
+    "resultType": "ComponentHandle[]",
+    "performance": "For MORE THAN ONE run, call `design.create.wallRuns(items[])` — one host round-trip and ONE undo entry for every run in the batch. Looping this single-run creator is N round-trips and N undo entries."
   },
   {
     "path": "design.create.window",
@@ -4498,7 +4804,23 @@
       "Add a casement window opening toward the garden side\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ isSelected: true })\nconst [entry] = await snaptrude.design.windows.listCatalog()\nconst window = await snaptrude.design.create.window(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Win-01\" },\n)\n```"
     ],
     "argsType": "string",
-    "resultType": "ComponentHandle"
+    "resultType": "ComponentHandle",
+    "performance": "For MORE THAN ONE window, call `design.create.windows(items[])` — one host round-trip and ONE undo entry, with each host wall re-cut once per opening inside that single call. Looping this single-window creator is N round-trips."
+  },
+  {
+    "path": "design.create.windows",
+    "namespace": "design.create",
+    "summary": "Place **many windows** into host walls in one undoable operation (bulk plural of {@linkcode window}). Each item carries its own catalog id, host wall, world position, and optional `facing`, `label`, `width`, `height` and `sillHeight` — the same fields as a `\"window\"` {@linkcode PluginDesignCreateOpeningOptions}. `sillHeight` is measured from the host wall base to the BOTTOM of the window. Validate-all-or-throw; one command.",
+    "examplePrompts": [
+      "Add windows along this whole facade at once",
+      "Place a window in every bedroom in one operation",
+      "Bulk add the windows from this schedule",
+      "Put four windows on this wall in a single undo step",
+      "Add all the windows with a 0.9m sill height together"
+    ],
+    "argsType": "PluginCreateWindowItem[]",
+    "resultType": "ComponentHandle[]",
+    "performance": "Bulk creator — the whole batch is ONE host round-trip and ONE undo entry, and each distinct catalog source loads once. Always prefer this over calling `design.create.window` in a loop: build the full `items[]` array first (all host walls and points up front), then make one call. # Example ```ts const v = snaptrude.core.math.vec3 const [wall] = await snaptrude.design.query.listWalls({ isSelected: true }) const [casement] = await snaptrude.design.windows.listCatalog() const placed = await snaptrude.design.create.windows([ { catalogId: casement.id, hostWall: wall, position: await v.new(2, 0, 5), sillHeight: 0.9 }, { catalogId: casement.id, hostWall: wall, position: await v.new(5, 0, 5), sillHeight: 0.9 }, ]) const currentWall = await snaptrude.design.query.getHost(placed[0]) ```"
   },
   {
     "path": "design.delete.entities",
@@ -4512,9 +4834,85 @@
       "Remove the door and window I just created"
     ],
     "argsType": "ComponentHandle[]",
-    "resultType": "PluginDesignDeleteResult",
+    "resultType": "PluginDesignChangeResult",
     "performance": "Array delete — pass every target in one call (one host round-trip). There is no per-item delete; collect the whole set and never loop this per entity. # Example ```ts // Hard-delete every furniture item on storey 2 (a single undo entry) const furniture = await snaptrude.design.query.listFurniture({ storeys: [2] }) if (furniture.length > 0) { const { affected } = await snaptrude.design.delete.entities(furniture) } ```"
   },
+  {
+    "path": "design.dimensions.create",
+    "namespace": "design.dimensions",
+    "summary": "Draw one dimension line between two world points, anchored to a component.",
+    "examplePrompts": [
+      "Dimension every wall on level 2",
+      "Add a dimension line along this wall",
+      "Measure the width of this room and label it on the plan\n\n# Example\n```ts\nconst { design, core } = snaptrude\nconst v = core.math.vec3\nconst curve = core.geom.query.curve\nfor (const wall of await design.query.listWalls({ storeys: [2] })) {\nconst cl = await design.query.geometry.getCenterline(wall)\nif (!cl) continue\nconst a = await curve.getStartPoint(cl)\nconst b = await curve.getEndPoint(cl)\nawait design.dimensions.create(\nawait v.new(a.x, a.y, a.z),\nawait v.new(b.x, b.y, b.z),\nwall,\n)\n}\n```"
+    ],
+    "argsType": "Vec3Handle",
+    "resultType": "DimensionHandle"
+  },
+  {
+    "path": "design.dimensions.delete",
+    "namespace": "design.dimensions",
+    "summary": "Delete dimension lines — the same hard removal as selecting them and pressing Delete. Undoable as a **single** entry for the whole batch.",
+    "examplePrompts": [
+      "Remove all dimension lines",
+      "Delete the dimensions on this wall",
+      "Clear the measurements I added to level 2"
+    ],
+    "argsType": "DimensionHandle[]",
+    "resultType": "PluginDimensionsChangeResult",
+    "performance": "Array API — pass the whole set in one call (one host round-trip, one undo entry). Never loop this per dimension. # Example ```ts const dims = snaptrude.design.dimensions const onWall = await dims.list({ anchors: [wall] }) if (onWall.length > 0) await dims.delete(onWall.map((d) => d.id)) ```"
+  },
+  {
+    "path": "design.dimensions.get",
+    "namespace": "design.dimensions",
+    "summary": "Read one dimension line by handle.",
+    "examplePrompts": [
+      "Read the dimension line I just created",
+      "How long is this dimension and what does its label say?",
+      "Check whether that dimension line still exists\n\n# Example\n```ts\nconst dim = await snaptrude.design.dimensions.get(handle)\nif (dim) console.log(dim.label, dim.length, dim.storey)\n```"
+    ],
+    "argsType": "DimensionHandle",
+    "resultType": "PluginDimensionLine | null"
+  },
+  {
+    "path": "design.dimensions.hide",
+    "namespace": "design.dimensions",
+    "summary": "Hide dimension lines from the viewport — the same as the right-click \"Hide\" action (it sets the user Hide flag, `isHidden`). Undoable. Already-hidden dimensions are skipped and are not reported in `affected`.",
+    "examplePrompts": [
+      "Hide the dimensions on this storey",
+      "Hide every dimension line while I present",
+      "Temporarily hide the measurements on level 3"
+    ],
+    "argsType": "DimensionHandle[]",
+    "resultType": "PluginDimensionsChangeResult",
+    "performance": "Array API — one host round-trip and one undo entry for the whole set. # Example ```ts const dims = snaptrude.design.dimensions const onLevel3 = await dims.list({ storeys: [3] }) const { affected } = await dims.hide(onLevel3.map((d) => d.id)) ```"
+  },
+  {
+    "path": "design.dimensions.list",
+    "namespace": "design.dimensions",
+    "summary": "List the dimension lines in the project as full records.",
+    "examplePrompts": [
+      "List all the dimension lines in this model",
+      "Which dimensions are on level 3?",
+      "Flag any dimension line shorter than 600 mm"
+    ],
+    "argsType": "{\n    storeys?: number[]\n    anchors?: ComponentHandle[]\n    isHidden?: boolean\n  }",
+    "resultType": "PluginDimensionLine[]",
+    "performance": "Array read — one host round-trip returns every record. Filter in one call rather than calling `get` per dimension. # Example ```ts const units = snaptrude.core.units const min = await units.convert(600, \"millimeters\", await units.getBabylonType()) const short = (await snaptrude.design.dimensions.list()).filter( (d) => d.length < min, ) console.log(short.map((d) => `${d.label} on storey ${d.storey}`)) ```"
+  },
+  {
+    "path": "design.dimensions.show",
+    "namespace": "design.dimensions",
+    "summary": "Reveal hidden dimension lines — clear the user Hide flag, the inverse of {@linkcode PluginDesignDimensionsApi.hide}. Undoable. Already-visible dimensions are skipped and are not reported in `affected`.",
+    "examplePrompts": [
+      "Show the dimension lines again",
+      "Unhide all the hidden dimensions",
+      "Bring back the measurements I hid on this storey"
+    ],
+    "argsType": "DimensionHandle[]",
+    "resultType": "PluginDimensionsChangeResult",
+    "performance": "Array API — one host round-trip and one undo entry for the whole set. # Example ```ts const dims = snaptrude.design.dimensions const hidden = await dims.list({ isHidden: true }) await dims.show(hidden.map((d) => d.id)) ```"
+  },
   {
     "path": "design.doors.exists",
     "namespace": "design.doors",
@@ -4596,7 +4994,7 @@
   {
     "path": "design.doors.getSwingDirection",
     "namespace": "design.doors",
-    "summary": "Get a door's swing (hinge) handedness — whether it opens as a left-hand or right-hand door. Derived from the door mesh's reflection state, not a persisted field.",
+    "summary": "Get a door's swing (hinge) handedness. Stand on the side the door swings open to, facing the door: `'left'` when the hinged jamb is on your left, `'right'` when it is on your right. Derived from the placed mesh's orientation (the same reflection `mirror` and the `hinge` placement option apply), not a persisted field.",
     "examplePrompts": [
       "Which way does this door swing?",
       "Is the selected door left-handed or right-handed?",
@@ -4661,13 +5059,13 @@
   {
     "path": "design.doors.mirror",
     "namespace": "design.doors",
-    "summary": "Mirror a door across an axis, flipping its swing so it opens from the other side. Undoable as a single command.",
+    "summary": "Mirror a door about its own axes. `'x'` (default) flips the swing side — the door opens to the other side of the wall; `'z'` swaps the hinged jamb (left-hand ↔ right-hand, same swing side); `'y'` turns it upside down. Undoable as a single command.",
     "examplePrompts": [
       "Flip this door's swing",
       "Mirror the selected door",
       "Make this door open the other way",
       "Reverse the hinge side of the entrance door",
-      "Change the door to swing from the other side\n\n# Example\n```ts\n// Flip the selected door's swing — axis defaults to \"x\" (the swing-flip\n// axis); pass \"y\" or \"z\" to reflect across a different axis\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nconst { affected } = await snaptrude.design.doors.mirror(door)\n```"
+      "Change the door to swing from the other side\n\n# Example\n```ts\n// Flip the selected door's swing side — axis defaults to \"x\"\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nconst { affected } = await snaptrude.design.doors.mirror(door)\n// …or swap the hinged jamb instead (keeps the swing side)\nawait snaptrude.design.doors.mirror(door, \"z\")\n```"
     ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
@@ -4739,6 +5137,117 @@
     "argsType": "PluginDesignListErasableEdgesArgs",
     "resultType": "ErasableEdgeRef[]"
   },
+  {
+    "path": "design.family.create",
+    "namespace": "design.family",
+    "summary": "Commit the prepared bundle to the project's parametric-definition library, so it survives the session and appears in the Families panel.",
+    "examplePrompts": [
+      "Save this as a family called Vertical Louvre",
+      "Add it to my library\n\n# Example\n```ts\nconst { definitionId } = await snaptrude.design.family.create({ name: \"Louvre Screen\" })\n```"
+    ],
+    "argsType": "PluginDesignFamilyCreateArgs",
+    "resultType": "PluginFamilyCreateResult"
+  },
+  {
+    "path": "design.family.delete",
+    "namespace": "design.family",
+    "summary": "Remove a family from the library: its catalog row is archived, so it leaves the Families panel. Placed instances are untouched — in this project and every other — because archived pins keep resolving. Pass `instances: true` to ALSO delete this project's instances in one undoable command; do that only when the user asks for the instances to go.",
+    "examplePrompts": [
+      "Delete the Louvre Screen family from my library",
+      "Get rid of that bollard and every copy of it in here\n\n# Example\n```ts\nawait snaptrude.design.family.delete({ id: \"revit:steel-bollard~bef047\" })\nawait snaptrude.design.family.delete({ id: \"revit:steel-bollard~bef047\", instances: true })\n```"
+    ],
+    "argsType": "PluginDesignFamilyDeleteArgs",
+    "resultType": "PluginFamilyDeleteResult"
+  },
+  {
+    "path": "design.family.flex",
+    "namespace": "design.family",
+    "summary": "Re-run the prepared family's recipe at new parameter values.",
+    "examplePrompts": [
+      "Change it to 6 bays",
+      "Show me what happens with 20 blades\n\n# Example\n```ts\nconst { changed } = await snaptrude.design.family.flex({ values: { bays: 6 } })\nconsole.log(`removed ${changed.removed}, rebuilt ${changed.rebuilt}`)\n```"
+    ],
+    "argsType": "PluginDesignFamilyFlexArgs",
+    "resultType": "PluginFamilyFlexResult"
+  },
+  {
+    "path": "design.family.get",
+    "namespace": "design.family",
+    "summary": "A family's spec bundle: the prepared draft's, or — to CHANGE a saved family — that family's recipe, opened as the new draft.",
+    "examplePrompts": [
+      "Make the chairs I placed 50 mm wider",
+      "Change the Louvre Screen family so its blades are deeper\n\n# Example\n```ts\nconst draft = await snaptrude.design.family.get()\nconst family = await snaptrude.design.family.get({ component })\n// family.editing → { familyId, version, name, library }\n```"
+    ],
+    "argsType": "PluginDesignFamilyGetArgs",
+    "resultType": "PluginFamilyGetResult | null"
+  },
+  {
+    "path": "design.family.getParameters",
+    "namespace": "design.family",
+    "summary": "Read a placed component's current parameter values and its sheet.",
+    "examplePrompts": [
+      "What size is that table?",
+      "Show me the parameters on this partition\n\n# Example\n```ts\nconst { values, parameters } = await snaptrude.design.family.getParameters({ component })\n```"
+    ],
+    "argsType": "PluginDesignFamilyGetParametersArgs",
+    "resultType": "PluginFamilyInstanceParameters | null"
+  },
+  {
+    "path": "design.family.getReference",
+    "namespace": "design.family",
+    "summary": "Read the family-spec DSL reference: grammar, the op table, the expression whitelist, the coordinate convention, the repair contract, and a worked example taken from a registered family.",
+    "examplePrompts": [
+      "How do I write a parametric family spec?",
+      "Show me the family DSL\n\n# Example\n```ts\nconst { reference } = await snaptrude.design.family.getReference()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginFamilyReference"
+  },
+  {
+    "path": "design.family.list",
+    "namespace": "design.family",
+    "summary": "Every parametric family registered in this session — native and imported.",
+    "examplePrompts": [
+      "What families are available?\n\n# Example\n```ts\nconst families = await snaptrude.design.family.list()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginFamilySummary[]"
+  },
+  {
+    "path": "design.family.place",
+    "namespace": "design.family",
+    "summary": "Put a family into the model — either the prepared draft or any family from {@linkcode PluginDesignFamilyApi.list}.",
+    "examplePrompts": [
+      "Place it in the model",
+      "Put a louvre screen at the origin",
+      "Copy that table two metres to the right\n\n# Example\n```ts\n// positioned — geometry exists when this resolves\nconst { component } = await snaptrude.design.family.place({\nid: \"revit:gypsum-stud-partition~90ad72\",\nposition: { x: 0, y: 0, z: 0 },\nrotation: 90,\n})\nawait snaptrude.design.transform.move([component], { x: 2, y: 0, z: 0 })\n\n// interactive — the user clicks\nawait snaptrude.design.family.place()\n\n// hosted — a door in a wall, near a point along it\nawait snaptrude.design.family.place({ id: doorId, host: wall, position: { x: 3, y: 0, z: 0 } })\n```"
+    ],
+    "argsType": "PluginDesignFamilyPlaceArgs",
+    "resultType": "PluginFamilyPlaceResult"
+  },
+  {
+    "path": "design.family.prepare",
+    "namespace": "design.family",
+    "summary": "Validate, compile and preview a family spec. Nothing is committed to the model or the library — call {@linkcode PluginDesignFamilyApi.place} or {@linkcode PluginDesignFamilyApi.create} for that.",
+    "examplePrompts": [
+      "Make a louvre screen with adjustable blade count and tilt",
+      "Design a curtain wall panel family with 8 bays",
+      "Create a railing family I can adjust\n\n# Example\n```ts\nconst r = await snaptrude.design.family.prepare({ bundle })\nif (!r.ok) console.error(r.errors[0].path, r.errors[0].message)\n```"
+    ],
+    "argsType": "PluginDesignFamilyPrepareArgs",
+    "resultType": "PluginFamilyPrepareResult"
+  },
+  {
+    "path": "design.family.setParameters",
+    "namespace": "design.family",
+    "summary": "Change a placed component's parameters and rebuild its geometry in place.",
+    "examplePrompts": [
+      "Make that table seat 8",
+      "Change the stud spacing to 400\n\n# Example\n```ts\nawait snaptrude.design.family.setParameters({ component, values: { seats: 8 } })\nawait snaptrude.design.family.setParameters({ component, children: { chair: { width: \"380mm\" } } })\nawait snaptrude.design.family.setParameters({\ncomponent: railing,\nlinks: { steps: { from: stair, expr: \"steps\" }, side: { from: stair, expr: \"width - 40mm\" } },\n})\nawait snaptrude.design.family.setParameters({\ncomponent: post,\nrelations: { add: [{ kind: \"attach\", side: \"top\", to: slab, bind: { height: \"reach\" } }] },\n})\n```"
+    ],
+    "argsType": "PluginDesignFamilySetParametersArgs",
+    "resultType": "PluginFamilyInstanceParameters"
+  },
   {
     "path": "design.furniture.exists",
     "namespace": "design.furniture",
@@ -4830,6 +5339,51 @@
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.grids.addLine",
+    "namespace": "design.grids",
+    "summary": "Insert a parallel grid line into a wing at an explicit position along the wing's spacing axis (Snaptrude units, wing-local — line 0's position can be read from its curve). Sibling lines do not shift; the wing's tag sequence is renumbered. Undoable.",
+    "examplePrompts": [
+      "Add a grid line between lines 2 and 3",
+      "Insert an extra grid line 4 metres from line A\n\n# Example\n```ts\nawait snaptrude.design.grids.addLine(grid, 0, 12.5)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.grids.removeLines",
+    "namespace": "design.grids",
+    "summary": "Remove grid lines by positional address, as ONE undoable step. With `tagPolicy: \"rewrite\"` (default) each affected wing renumbers its tag sequence; `\"preserve\"` keeps surviving tags unchanged. A wing emptied of lines is dropped from the group.",
+    "examplePrompts": [
+      "Delete grid line B",
+      "Remove the last two lines of this grid without renumbering\n\n# Example\n```ts\nawait snaptrude.design.grids.removeLines(grid, [{ wing: 0, line: 2 }], \"preserve\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.grids.updateLines",
+    "namespace": "design.grids",
+    "summary": "Update one or more **lines** of a grid with sparse per-line entries — `tag`, `distanceToPrevious`/`distanceToNext` (typed distance to the neighbour on that side; mutually exclusive), `props` (per-line style overrides), and `visible: false` (hide). Every change routes through the exact setters the native panel uses — each changed field commits its own undoable command, identical to editing that field in the panel.",
+    "examplePrompts": [
+      "Rename grid line 2 to \"B\"",
+      "Move this grid line 4 metres from its neighbour",
+      "Hide grid line 3 on this grid\n\n# Example\n```ts\nawait snaptrude.design.grids.updateLines(grid, [\n{ wing: 0, line: 1, tag: \"B\", distanceToPrevious: 4 },\n])\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.grids.updateWings",
+    "namespace": "design.grids",
+    "summary": "Update one or more **wings** of a grid with sparse per-wing entries — `spacing` (uniform re-space), `count` (grow/truncate + tag renumber), `spanMin`/`spanMax` (family length handles). Every change routes through the exact setters the native panel uses — each changed field commits its own undoable command, identical to editing that field in the panel.",
+    "examplePrompts": [
+      "Change this grid's spacing to 8 metres",
+      "Make this grid 10 by 12 lines\n\n# Example\n```ts\nawait snaptrude.design.grids.updateWings(grid, [{ wing: 0, spacing: 8, count: 10 }])\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
   {
     "path": "design.isAreaLocked",
     "namespace": "design",
@@ -5133,6 +5687,7 @@
     "summary": "Get the boundary representation (B-rep) of a scene component — the solid geometry (faces, edges, vertices) behind a wall, slab, room or any other scene entity, as a reusable {@linkcode BrepHandle} for the `core.geom.query.brep.*` reads.",
     "examplePrompts": [
       "Get the 3D solid geometry of the selected wall",
+      "Round the top rim of this column and put it back where it is",
       "How many faces does this mass have?",
       "Inspect the mesh of this slab so I can look at its faces and edges",
       "Read the vertices of the selected column's geometry"
@@ -5244,6 +5799,19 @@
     "argsType": "ComponentHandle",
     "resultType": "string"
   },
+  {
+    "path": "design.query.getParameters",
+    "namespace": "design.query",
+    "summary": "Read a mass's creation-parameter record — the recipe it was built from (`kind` plus the values that constructor was called with). Present on masses committed from a `core.geom.create` brep constructor that carries a recipe: {@linkcode MassParametersRecord} covers the four primitives (sphere, cylinder, cone, torus), extrusions, revolutions, lofts and sweeps.",
+    "examplePrompts": [
+      "What radius is this sphere?",
+      "Is this mass parametric?",
+      "Read back the dome's creation parameters",
+      "How tall was this cylinder made?\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses({ isSelected: true })\nconst params = await snaptrude.design.query.getParameters(mass)\nif (params?.kind === \"sphere\") console.log(\"radius:\", params.values.radius)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "MassParametersRecord | null"
+  },
   {
     "path": "design.query.getProperties",
     "namespace": "design.query",
@@ -5272,6 +5840,19 @@
     "argsType": "ComponentHandle",
     "resultType": "PluginStaircaseParams | null"
   },
+  {
+    "path": "design.query.grids.get",
+    "namespace": "design.query.grids",
+    "summary": "Get properties of a grid by its ID.",
+    "examplePrompts": [
+      "What is the spacing of this grid?",
+      "Read the grid line tags on this structural grid",
+      "Get the geometry of every line in this grid",
+      "Which storeys is this grid hidden on?\n\n# Example\n```ts\nconst [grid] = await snaptrude.design.query.listGrids()\nconst { wings } = await snaptrude.design.query.grids.get(grid, [\"wings\"])\n// wings[0].lines[0].curve is an opaque CurveHandle in world space;\n// read its coordinates via `snaptrude.core.geom.curve`.\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginGridGetResult"
+  },
   {
     "path": "design.query.listBeams",
     "namespace": "design.query",
@@ -5390,6 +5971,19 @@
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
+  {
+    "path": "design.query.listGrids",
+    "namespace": "design.query",
+    "summary": "List all the structural grids (grid groups) in the project, optionally filtered by storey, building, selection state, or region.",
+    "examplePrompts": [
+      "List all the structural grids in the model",
+      "How many grids are on the ground floor?",
+      "Show the grids on this storey",
+      "Which grids are currently selected?\n\n# Example\n```ts\nconst groundFloorGrids = await snaptrude.design.query.listGrids({ storeys: [1] })\n```"
+    ],
+    "argsType": "PluginEntityFilter",
+    "resultType": "ComponentHandle[]"
+  },
   {
     "path": "design.query.listMasses",
     "namespace": "design.query",
@@ -5578,18 +6172,6 @@
     "argsType": "ComponentHandle",
     "resultType": "ContourHandle | null"
   },
-  {
-    "path": "design.query.spaces.listGeneratedBim",
-    "namespace": "design.query.spaces",
-    "summary": "List the space's **engine-generated BIM components** — the walls, floors and slabs the parametric engine derived from this space, grouped by kind.",
-    "examplePrompts": [
-      "Which walls did this room generate?",
-      "List the BIM components derived from the selected space",
-      "Get the floors and slabs that belong to this room\n\n# Example\n```ts\nconst [space] = await snaptrude.design.query.listSpaces()\nconst bim = await snaptrude.design.query.spaces.listGeneratedBim(space)\nconsole.log(`${bim.walls.length} walls, ${bim.floors.length} floors`)\n```"
-    ],
-    "argsType": "ComponentHandle",
-    "resultType": "PluginSpaceGeneratedBim"
-  },
   {
     "path": "design.query.storeyOutline",
     "namespace": "design.query",
@@ -5833,6 +6415,31 @@
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.update.grid",
+    "namespace": "design.update",
+    "summary": "Update a structural grid's **group-level** fields with a sparse patch — default line styling, absolute angle, and per-storey 2D visibility. Only provided fields change. Wing- and line-level updates live on the grids entity family: {@linkcode PluginDesignGridsApi.updateWings} / {@linkcode PluginDesignGridsApi.updateLines}.",
+    "examplePrompts": [
+      "Rotate the grid to 45 degrees",
+      "Make this grid's lines dashed and grey",
+      "Hide this grid on storey 3's plan\n\n# Example\n```ts\nconst [grid] = await snaptrude.design.query.listGrids()\nawait snaptrude.design.update.grid(grid, { angle: 45, props: { style: \"DASHED\" } })\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.update.parameters",
+    "namespace": "design.update",
+    "summary": "Edit a parametric mass by patching its creation recipe and rebuilding the solid in place — the mass keeps its id, storey, materials, position and linked copies; only the geometry changes. Read the current record with `design.query.getParameters` first.",
+    "examplePrompts": [
+      "Make the dome's radius 8 metres",
+      "Raise the podium to 5 m",
+      "Widen the vase — move its profile points 20 cm outward",
+      "Change the fillet on the rounded column to 300 mm\n\n# Example\n```ts\n// { kind: \"sphere\", values: { centre, radius: 19.685 }, … }\nconst before = await snaptrude.design.query.getParameters(dome)\nconst after = await snaptrude.design.update.parameters(dome, { radius: 31.496 }) // 8 m in internal units\n\n// Fillet radius on a recorded result: read → edit → send the array back\nconst rec = await snaptrude.design.query.getParameters(column)\nconst operations = rec?.operations ?? []\nif (operations[0]?.op === \"fillet\") {\noperations[0].radius = 1.181\nawait snaptrude.design.update.parameters(column, { operations })\n}\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "MassParametersRecord"
+  },
   {
     "path": "design.update.roof",
     "namespace": "design.update",
@@ -6872,17 +7479,6 @@
     "argsType": "string",
     "resultType": "PluginPlacedViewLabel"
   },
-  {
-    "path": "presentation.placedViews.setLod",
-    "namespace": "presentation.placedViews",
-    "summary": "Set the level of detail a placed view renders at — `\"design\"` (the Design-mode massing representation) or `\"bim\"` (the detailed BIM representation). Views only. Undoable. Requires Present mode to be open.",
-    "examplePrompts": [
-      "Switch this placed view to the BIM level of detail",
-      "Show the massing version of the placed plan"
-    ],
-    "argsType": "string",
-    "resultType": "void"
-  },
   {
     "path": "presentation.placedViews.setMask",
     "namespace": "presentation.placedViews",
@@ -7528,6 +8124,18 @@
     "argsType": "string",
     "resultType": "PluginProgramDepartmentsSetTargetAreaResult"
   },
+  {
+    "path": "program.departments.setTargetCount",
+    "namespace": "program.departments",
+    "summary": "Set a department's target unit count.",
+    "examplePrompts": [
+      "Set the Bedrooms department unit count to 12",
+      "The program needs 4 clinic blocks — update the department count",
+      "Update the target count for department dep_123\n\n# Example\n```ts\nawait snaptrude.program.departments.setTargetCount(\"dep_123\", 12)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramDepartmentsSetTargetCountResult"
+  },
   {
     "path": "program.departments.unassign",
     "namespace": "program.departments",
@@ -7554,6 +8162,65 @@
     "argsType": "string",
     "resultType": "PluginProgramDepartmentsUpdateResult"
   },
+  {
+    "path": "program.labels.create",
+    "namespace": "program.labels",
+    "summary": "Create labels (program rows), optionally creating their spaces too.",
+    "examplePrompts": [
+      "Add program rows for 4 exam rooms of 120 sqft each",
+      "Create the labels from this interpreted program",
+      "Add an Office label with a 2000 sqft target to the Admin department",
+      "Create program rows and their spaces on the canvas\n\n# Example\n```ts\nconst { labelIds } = await snaptrude.program.labels.create(\n[{ name: \"Exam Room\", targetArea: 480, targetCount: 4, departmentName: \"Clinic\" }],\n{ units: \"ft2\" },\n)\n```"
+    ],
+    "argsType": "PluginProgramLabelCreateItem[]",
+    "resultType": "PluginProgramLabelsCreateResult"
+  },
+  {
+    "path": "program.labels.get",
+    "namespace": "program.labels",
+    "summary": "Get a single label by id.",
+    "examplePrompts": [
+      "Get the label with id lbl_12",
+      "What is the target area of this program row?\n\n# Example\n```ts\nconst label = await snaptrude.program.labels.get(\"lbl_12\")\nif (label) console.log(label.name, label.targetArea, label.units)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramLabelsGetResult"
+  },
+  {
+    "path": "program.labels.list",
+    "namespace": "program.labels",
+    "summary": "List the labels (program rows) of the active program.",
+    "examplePrompts": [
+      "List all the program rows with their target areas",
+      "What space labels are in the program and how many of each?",
+      "Show every label with its department and target\n\n# Example\n```ts\nconst { units, labels } = await snaptrude.program.labels.list()\nfor (const l of labels) console.log(l.name, l.targetArea, units, l.targetCount)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramLabelsListResult"
+  },
+  {
+    "path": "program.labels.setTargetArea",
+    "namespace": "program.labels",
+    "summary": "Set a label's total target area.",
+    "examplePrompts": [
+      "Set the Exam Room target area to 480 sqft",
+      "Give the Corridor program row a 150 sqm target",
+      "Update the area target for label lbl_12\n\n# Example\n```ts\nawait snaptrude.program.labels.setTargetArea(\"lbl_12\", 480, \"ft2\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramLabelsSetTargetAreaResult"
+  },
+  {
+    "path": "program.labels.setTargetCount",
+    "namespace": "program.labels",
+    "summary": "Set a label's target unit count (how many of this space the program calls for).",
+    "examplePrompts": [
+      "Set the Exam Room count to 6",
+      "The program needs 12 patient rooms — update the count\n\n# Example\n```ts\nawait snaptrude.program.labels.setTargetCount(\"lbl_12\", 6)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramLabelsSetTargetCountResult"
+  },
   {
     "path": "program.layout.applySolution",
     "namespace": "program.layout",
@@ -7627,6 +8294,81 @@
     "argsType": null,
     "resultType": "PluginProgramLayoutStackResult"
   },
+  {
+    "path": "program.metadata.createHeader",
+    "namespace": "program.metadata",
+    "summary": "Create a metadata header (a custom column on the Program Data sheet).",
+    "examplePrompts": [
+      "Add a custom column called Occupancy to the program sheet",
+      "Create a metadata header named Department Code",
+      "Make a new program-mode column for Finish Level\n\n# Example\n```ts\nconst header = await snaptrude.program.metadata.createHeader(\"Occupancy\", {\ndescription: \"People per room\",\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramMetadataCreateHeaderResult"
+  },
+  {
+    "path": "program.metadata.get",
+    "namespace": "program.metadata",
+    "summary": "Get one space's metadata values, keyed by header id.",
+    "examplePrompts": [
+      "Get the metadata on this space",
+      "Read the custom column values for space sp_12",
+      "What is this room's Occupancy metadata?\n\n# Example\n```ts\nconst record = await snaptrude.program.metadata.get(\"sp_12\")\nif (record) console.log(record.values)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginProgramMetadataGetResult"
+  },
+  {
+    "path": "program.metadata.list",
+    "namespace": "program.metadata",
+    "summary": "List metadata values for many spaces at once.",
+    "examplePrompts": [
+      "List the metadata of every space",
+      "Read the custom column values for all rooms",
+      "Get the metadata for these three spaces in one call\n\n# Example\n```ts\nconst { records } = await snaptrude.program.metadata.list()\nconst byId = Object.fromEntries(records.map((r) => [r.spaceId, r.values]))\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginProgramMetadataListResult",
+    "performance": "One round-trip for any number of spaces — use this instead of a `get` loop."
+  },
+  {
+    "path": "program.metadata.listHeaders",
+    "namespace": "program.metadata",
+    "summary": "List the metadata headers (custom columns) of the Program Data sheet.",
+    "examplePrompts": [
+      "List the custom metadata columns in program mode",
+      "What metadata headers does the program sheet have?",
+      "Show every custom column with its id\n\n# Example\n```ts\nconst { headers } = await snaptrude.program.metadata.listHeaders()\nfor (const h of headers) console.log(h.headerId, h.name)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramMetadataListHeadersResult"
+  },
+  {
+    "path": "program.metadata.update",
+    "namespace": "program.metadata",
+    "summary": "Update a space's metadata values (sparse).",
+    "examplePrompts": [
+      "Set the Occupancy metadata of this space to 4",
+      "Store a department code on the selected rooms",
+      "Write custom column values onto space sp_12",
+      "Clear the Finish Level metadata on this space\n\n# Example\n```ts\nconst header = await snaptrude.program.metadata.createHeader(\"Occupancy\")\nawait snaptrude.program.metadata.update(\"sp_12\", { [header.headerId]: 4 })\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginProgramMetadataUpdateResult"
+  },
+  {
+    "path": "program.metadata.updateMany",
+    "namespace": "program.metadata",
+    "summary": "Update metadata values on many spaces in one undoable step.",
+    "examplePrompts": [
+      "Fill the Occupancy column for all bedrooms",
+      "Write metadata onto every selected space at once",
+      "Bulk-update custom column values\n\n# Example\n```ts\nawait snaptrude.program.metadata.updateMany([\n{ spaceId: \"sp_12\", values: { [headerId]: 4 } },\n{ spaceId: \"sp_13\", values: { [headerId]: 2 } },\n])\n```"
+    ],
+    "argsType": "PluginProgramMetadataUpdateItem[]",
+    "resultType": "PluginProgramMetadataUpdateManyResult",
+    "performance": "One round-trip and one undo step for up to 1000 spaces — use this instead of an `update` loop."
+  },
   {
     "path": "program.metrics.get",
     "namespace": "program.metrics",
@@ -7865,6 +8607,19 @@
     "argsType": "{\n    name?: string\n  }",
     "resultType": "PluginProgramSpreadsheetBindingsRefreshResult"
   },
+  {
+    "path": "program.spreadsheet.createCustomSheet",
+    "namespace": "program.spreadsheet",
+    "summary": "Create a **custom program sheet** — a live view of the program grouped by a configurable hierarchy (the Program tab's \"Custom\" sheet with *Organize → Group by*).",
+    "examplePrompts": [
+      "Create a custom sheet grouped by department then sub-department",
+      "Make a program view grouped by storey and label",
+      "Build a grouped program sheet for the healthcare hierarchy",
+      "Add a custom sheet with a department → room type group-by\n\n# Example\n```ts\nconst { headers } = await snaptrude.program.metadata.listHeaders()\nconst subDept = headers.find((h) => h.name === \"Sub-department\")\nawait snaptrude.program.spreadsheet.createCustomSheet(\"Clinical Program\", {\ngroupBy: [\"departmentName\", subDept.headerId, \"label\"],\nproperties: [\"label\", \"count\", \"areas\", \"netAreaAchieved\"],\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramSpreadsheetCustomSheetResult"
+  },
   {
     "path": "program.spreadsheet.createSheet",
     "namespace": "program.spreadsheet",
@@ -7930,6 +8685,17 @@
     "argsType": "{\n    limit?: number\n  }",
     "resultType": "PluginProgramSpreadsheetGetAuditLogResult"
   },
+  {
+    "path": "program.spreadsheet.getCustomSheet",
+    "namespace": "program.spreadsheet",
+    "summary": "Get a custom program sheet's configuration.",
+    "examplePrompts": [
+      "How is the Clinical Program sheet grouped?",
+      "Get the group-by configuration of this custom sheet\n\n# Example\n```ts\nconst cfg = await snaptrude.program.spreadsheet.getCustomSheet(\"Clinical Program\")\nif (cfg) console.log(cfg.groupBy, cfg.properties)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramSpreadsheetGetCustomSheetResult"
+  },
   {
     "path": "program.spreadsheet.getMaterialTakeoff",
     "namespace": "program.spreadsheet",
@@ -7996,6 +8762,28 @@
     "argsType": "string",
     "resultType": "PluginProgramSpreadsheetHighlightCellsResult"
   },
+  {
+    "path": "program.spreadsheet.listCustomSheetProperties",
+    "namespace": "program.spreadsheet",
+    "summary": "List the property ids a custom program sheet can show as columns or group by.",
+    "examplePrompts": [
+      "What can I group a custom program sheet by?",
+      "List the columns available for a custom sheet\n\n# Example\n```ts\nconst { properties } = await snaptrude.program.spreadsheet.listCustomSheetProperties()\nconst groupable = properties.filter((p) => p.groupable).map((p) => p.id)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSpreadsheetListCustomSheetPropertiesResult"
+  },
+  {
+    "path": "program.spreadsheet.listCustomSheets",
+    "namespace": "program.spreadsheet",
+    "summary": "List the custom program sheets in the workbook with their configurations.",
+    "examplePrompts": [
+      "List the custom program sheets",
+      "Which sheets are grouped program views?\n\n# Example\n```ts\nconst { sheets } = await snaptrude.program.spreadsheet.listCustomSheets()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSpreadsheetListCustomSheetsResult"
+  },
   {
     "path": "program.spreadsheet.listSheets",
     "namespace": "program.spreadsheet",
@@ -8172,6 +8960,18 @@
     "argsType": "PluginSpreadsheetTransactionOp[]",
     "resultType": "PluginProgramSpreadsheetTransactionResult"
   },
+  {
+    "path": "program.spreadsheet.updateCustomSheet",
+    "namespace": "program.spreadsheet",
+    "summary": "Update a custom program sheet's group-by hierarchy, columns, or group colors.",
+    "examplePrompts": [
+      "Change the custom sheet to group by storey first",
+      "Add the Occupancy column to my grouped program sheet",
+      "Regroup the Clinical Program sheet by department only\n\n# Example\n```ts\nawait snaptrude.program.spreadsheet.updateCustomSheet(\"Clinical Program\", {\ngroupBy: [\"storey\", \"departmentName\"],\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramSpreadsheetCustomSheetResult"
+  },
   {
     "path": "workspace.closePresentMode",
     "namespace": "workspace",
@@ -8184,6 +8984,17 @@
     "argsType": null,
     "resultType": "void"
   },
+  {
+    "path": "workspace.closeProgramMode",
+    "namespace": "workspace",
+    "summary": "Close the Program tab.",
+    "examplePrompts": [
+      "Close program mode",
+      "Close the Program tab\n\n# Example\n```ts\nawait snaptrude.workspace.closeProgramMode()\n```"
+    ],
+    "argsType": null,
+    "resultType": "void"
+  },
   {
     "path": "workspace.openPresentMode",
     "namespace": "workspace",
@@ -8196,6 +9007,18 @@
     "argsType": null,
     "resultType": "void"
   },
+  {
+    "path": "workspace.openProgramMode",
+    "namespace": "workspace",
+    "summary": "Open Program mode — the Program tab the `program.spreadsheet.*` calls run in.",
+    "examplePrompts": [
+      "Open program mode",
+      "Open the Program tab so I can build a custom sheet",
+      "Switch to the program spreadsheet\n\n# Example\n```ts\nawait snaptrude.workspace.openProgramMode()\nconst { sheets } = await snaptrude.program.spreadsheet.listSheets()\n```"
+    ],
+    "argsType": null,
+    "resultType": "void"
+  },
   {
     "path": "workspace.projects.copy",
     "namespace": "workspace.projects",