@snaptrude/plugin-core 0.9.10 → 0.9.12

package/api-manifest.json

@@ -3403,8 +3403,7 @@
     "examplePrompts": [
       "Switch to present mode",
       "Open BIM mode",
-      "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```"
+      "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```"
     ],
     "argsType": "PluginAppMode",
     "resultType": "PluginCoreModeSetResult"
@@ -4039,19 +4038,6 @@
     "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",
@@ -4313,27 +4299,10 @@
       "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",
-      "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```"
+      "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```"
     ],
     "argsType": "string",
-    "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) ```"
+    "resultType": "ComponentHandle"
   },
   {
     "path": "design.create.floor",
@@ -4346,23 +4315,7 @@
       "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",
-    "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) }, ]) ```"
+    "resultType": "ComponentHandle"
   },
   {
     "path": "design.create.furniture",
@@ -4377,23 +4330,7 @@
       "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 }, ]) ```"
+    "resultType": "ComponentHandle"
   },
   {
     "path": "design.create.mass",
@@ -4430,7 +4367,7 @@
     ],
     "argsType": "PluginDesignCreateOpeningOptions",
     "resultType": "ComponentHandle",
-    "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, }) ```"
+    "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, }) ```"
   },
   {
     "path": "design.create.referenceLines",
@@ -4532,21 +4469,6 @@
     "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",
@@ -4561,8 +4483,7 @@
       "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[]",
-    "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."
+    "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.create.window",
@@ -4577,23 +4498,7 @@
       "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",
-    "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]) ```"
+    "resultType": "ComponentHandle"
   },
   {
     "path": "design.delete.entities",
@@ -4610,82 +4515,6 @@
     "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",
@@ -4767,7 +4596,7 @@
   {
     "path": "design.doors.getSwingDirection",
     "namespace": "design.doors",
-    "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.",
+    "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.",
     "examplePrompts": [
       "Which way does this door swing?",
       "Is the selected door left-handed or right-handed?",
@@ -4832,13 +4661,13 @@
   {
     "path": "design.doors.mirror",
     "namespace": "design.doors",
-    "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.",
+    "summary": "Mirror a door across an axis, flipping its swing so it opens from the other side. 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 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```"
+      "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```"
     ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
@@ -4910,6 +4739,103 @@
     "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.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": "The prepared family's spec bundle, or `null` when nothing is prepared.",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "PluginFamilyBundle | 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```"
+    ],
+    "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 } })\n```"
+    ],
+    "argsType": "PluginDesignFamilySetParametersArgs",
+    "resultType": "PluginFamilyInstanceParameters"
+  },
   {
     "path": "design.furniture.exists",
     "namespace": "design.furniture",
@@ -7676,18 +7602,6 @@
     "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",
@@ -7714,65 +7628,6 @@
     "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",
@@ -7846,81 +7701,6 @@
     "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",
@@ -8159,19 +7939,6 @@
     "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",
@@ -8237,17 +8004,6 @@
     "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",
@@ -8314,28 +8070,6 @@
     "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",
@@ -8512,18 +8246,6 @@
     "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",
@@ -8536,17 +8258,6 @@
     "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",
@@ -8559,18 +8270,6 @@
     "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",