@snaptrude/plugin-core 0.5.0 → 0.7.0

package/api-manifest.json

@@ -1,4 +1,244 @@
 [
+  {
+    "path": "analysis.heatmaps.isActive",
+    "namespace": "analysis.heatmaps",
+    "summary": "Is a plugin heatmap currently showing?",
+    "examplePrompts": [
+      "Is my heatmap still showing?",
+      "Check whether the custom heatmap is active",
+      "Do I need to re-render the wind overlay?\n\n# Example\n```ts\nif (!(await snaptrude.analysis.heatmaps.isActive())) {\nawait snaptrude.analysis.heatmaps.renderGrid(cells, 2)\n}\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.heatmaps.renderGrid",
+    "namespace": "analysis.heatmaps",
+    "summary": "Render a grid heatmap — a coloured mesh from point samples.",
+    "examplePrompts": [
+      "Overlay my CFD wind simulation results on the site",
+      "Render a noise-level grid around the building",
+      "Show these sampled microclimate values as a colored grid\n\n# Example\n```ts\n// World coordinates are y-up: a ground-level field varies in x/z at y = 0.\nawait snaptrude.analysis.heatmaps.renderGrid(\nsamples.map((s) => ({ position: { x: s.x, y: 0, z: s.z }, value: s.windSpeed })),\n2, // 2-unit square cells\n{ title: \"Wind speed\", unit: \"m/s\", colors: [\"#0000ff\", \"#00ff00\", \"#ff0000\"] },\n)\n```"
+    ],
+    "argsType": "PluginAnalysisHeatmapGridCell[]",
+    "resultType": "PluginAnalysisHeatmapsRenderResult"
+  },
+  {
+    "path": "analysis.heatmaps.renderSpaces",
+    "namespace": "analysis.heatmaps",
+    "summary": "Render a per-space heatmap — one flat colour per space's top face.",
+    "examplePrompts": [
+      "Color each room by its occupancy count",
+      "Show my energy simulation results as a heatmap per space",
+      "Paint the rooms red to blue by temperature\n\n# Example\n```ts\nconst spaces = await snaptrude.design.query.listSpaces()\nawait snaptrude.analysis.heatmaps.renderSpaces(\nspaces.map((space) => ({ space, value: occupancy[space] ?? 0 })),\n{ title: \"Occupancy\", unit: \"people\", min: 0, max: 50 },\n)\n```"
+    ],
+    "argsType": "PluginAnalysisHeatmapSpaceEntry[]",
+    "resultType": "PluginAnalysisHeatmapsRenderResult"
+  },
+  {
+    "path": "analysis.heatmaps.reset",
+    "namespace": "analysis.heatmaps",
+    "summary": "Clear the plugin heatmap from the scene.",
+    "examplePrompts": [
+      "Clear my custom heatmap",
+      "Remove the wind overlay from the model",
+      "Reset the plugin heatmap view\n\n# Example\n```ts\nawait snaptrude.analysis.heatmaps.reset()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.illuminance.cancel",
+    "namespace": "analysis.illuminance",
+    "summary": "Cancel the in-flight illuminance run.",
+    "examplePrompts": [
+      "Cancel the illuminance analysis",
+      "Stop the running daylight computation",
+      "Abort the lux study\n\n# Example\n```ts\nawait snaptrude.analysis.illuminance.cancel()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.illuminance.compute",
+    "namespace": "analysis.illuminance",
+    "summary": "Start a daylight-illuminance run for a date range.",
+    "examplePrompts": [
+      "Run a daylight illuminance analysis for December",
+      "Compute the lux levels inside the building for winter",
+      "How much daylight do the interior floors get?\n\n# Example\n```ts\nconst { success } = await snaptrude.analysis.illuminance.compute(\n\"2026-12-01\",\n\"2026-12-31\",\n)\n// poll until the heatmap is rendered\nlet job = await snaptrude.analysis.illuminance.get()\nwhile (job?.status === \"running\") {\nawait new Promise((r) => setTimeout(r, 5000))\njob = await snaptrude.analysis.illuminance.get()\n}\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginAnalysisComputeResult"
+  },
+  {
+    "path": "analysis.illuminance.get",
+    "namespace": "analysis.illuminance",
+    "summary": "Get the state of the illuminance study.",
+    "examplePrompts": [
+      "Is the illuminance analysis done?",
+      "Check the status of the daylight lux run",
+      "What date range was the illuminance heatmap computed for?\n\n# Example\n```ts\nconst job = await snaptrude.analysis.illuminance.get()\nif (job?.status === \"active\") console.log(job.startDate, job.endDate)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAnalysisJobStateResult"
+  },
+  {
+    "path": "analysis.illuminance.reset",
+    "namespace": "analysis.illuminance",
+    "summary": "Clear the illuminance heatmap from the scene.",
+    "examplePrompts": [
+      "Clear the illuminance heatmap",
+      "Remove the daylight lux colours from the model",
+      "Reset the illuminance analysis view\n\n# Example\n```ts\nawait snaptrude.analysis.illuminance.reset()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.shadows.disable",
+    "namespace": "analysis.shadows",
+    "summary": "Turn real-time sun shadows OFF.",
+    "examplePrompts": [
+      "Turn off shadows",
+      "Hide the sun shadows",
+      "Disable shadow rendering in the scene\n\n# Example\n```ts\nawait snaptrude.analysis.shadows.disable()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.shadows.enable",
+    "namespace": "analysis.shadows",
+    "summary": "Turn real-time sun shadows ON, optionally at a specific date and time.",
+    "examplePrompts": [
+      "Turn on shadows",
+      "Show the shadows at 3pm on June 21st",
+      "Enable sun shadows for the summer solstice afternoon\n\n# Example\n```ts\nawait snaptrude.analysis.shadows.enable({ dateTime: \"2026-06-21T15:00\" })\n```"
+    ],
+    "argsType": "PluginAnalysisShadowsEnableOptions",
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.shadows.getDateTime",
+    "namespace": "analysis.shadows",
+    "summary": "Get the sun's current date and time.",
+    "examplePrompts": [
+      "What date and time are the shadows set to?",
+      "Get the current sun position date",
+      "Which time of day is the shadow study showing?\n\n# Example\n```ts\nconst dateTime = await snaptrude.analysis.shadows.getDateTime()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAnalysisShadowsDateTimeResult"
+  },
+  {
+    "path": "analysis.shadows.isEnabled",
+    "namespace": "analysis.shadows",
+    "summary": "Whether real-time sun shadows are currently enabled.",
+    "examplePrompts": [
+      "Are shadows on?",
+      "Check whether sun shadows are enabled",
+      "Is the scene showing shadows right now?\n\n# Example\n```ts\nconst on = await snaptrude.analysis.shadows.isEnabled()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.shadows.setDateTime",
+    "namespace": "analysis.shadows",
+    "summary": "Move the sun to a specific date and time.",
+    "examplePrompts": [
+      "Set the shadow time to 9:30 am on the winter solstice",
+      "Move the sun to noon on March 1st",
+      "Change the shadow study date to December 21\n\n# Example\n```ts\nconst applied = await snaptrude.analysis.shadows.setDateTime(\"2026-12-21T09:30\")\nconsole.log(applied) // \"2026-12-21T09:30\" (snapped to the half-hour grid)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginAnalysisShadowsDateTimeResult"
+  },
+  {
+    "path": "analysis.sunlightHours.cancel",
+    "namespace": "analysis.sunlightHours",
+    "summary": "Cancel the in-flight sunlight-hours run.",
+    "examplePrompts": [
+      "Cancel the sunlight analysis",
+      "Stop the running sunlight hours computation",
+      "Abort the sun study\n\n# Example\n```ts\nawait snaptrude.analysis.sunlightHours.cancel()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.sunlightHours.compute",
+    "namespace": "analysis.sunlightHours",
+    "summary": "Start a direct-sunlight-hours run for a date range.",
+    "examplePrompts": [
+      "Run a sunlight hours analysis for June",
+      "Compute direct sunlight hours between March and September",
+      "How much sun does my building get over the summer?\n\n# Example\n```ts\nconst { success } = await snaptrude.analysis.sunlightHours.compute(\n\"2026-06-01\",\n\"2026-06-30\",\n)\n// poll until the heatmap is rendered\nlet job = await snaptrude.analysis.sunlightHours.get()\nwhile (job?.status === \"running\") {\nawait new Promise((r) => setTimeout(r, 5000))\njob = await snaptrude.analysis.sunlightHours.get()\n}\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginAnalysisComputeResult"
+  },
+  {
+    "path": "analysis.sunlightHours.get",
+    "namespace": "analysis.sunlightHours",
+    "summary": "Get the state of the sunlight-hours study.",
+    "examplePrompts": [
+      "Is the sunlight analysis done?",
+      "Check the status of the sunlight hours run",
+      "What date range was the sunlight heatmap computed for?\n\n# Example\n```ts\nconst job = await snaptrude.analysis.sunlightHours.get()\nif (job?.status === \"active\") console.log(job.startDate, job.endDate)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAnalysisJobStateResult"
+  },
+  {
+    "path": "analysis.sunlightHours.reset",
+    "namespace": "analysis.sunlightHours",
+    "summary": "Clear the sunlight-hours heatmap from the scene.",
+    "examplePrompts": [
+      "Clear the sunlight heatmap",
+      "Remove the sun hours colours from the model",
+      "Reset the sunlight analysis view\n\n# Example\n```ts\nawait snaptrude.analysis.sunlightHours.reset()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.sunpath.disable",
+    "namespace": "analysis.sunpath",
+    "summary": "Turn the sun-path diagram overlay OFF.",
+    "examplePrompts": [
+      "Hide the sun path diagram",
+      "Turn off the sunpath overlay",
+      "Remove the sun trajectory arcs from the scene\n\n# Example\n```ts\nawait snaptrude.analysis.sunpath.disable()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.sunpath.enable",
+    "namespace": "analysis.sunpath",
+    "summary": "Turn the sun-path diagram overlay ON.",
+    "examplePrompts": [
+      "Show the sun path diagram",
+      "Turn on the sunpath overlay",
+      "Visualize the sun's trajectory over my building\n\n# Example\n```ts\nawait snaptrude.analysis.sunpath.enable()\nconst active = await snaptrude.analysis.sunpath.isActive() // true\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.sunpath.isActive",
+    "namespace": "analysis.sunpath",
+    "summary": "Whether the sun-path diagram overlay is currently active.",
+    "examplePrompts": [
+      "Is the sun path diagram on?",
+      "Check whether the sunpath overlay is active",
+      "Am I looking at the sun trajectory right now?\n\n# Example\n```ts\nif (!(await snaptrude.analysis.sunpath.isActive())) {\nawait snaptrude.analysis.sunpath.enable()\n}\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
   {
     "path": "core.buildings.copy",
     "namespace": "core.buildings",
@@ -110,32 +350,52 @@
   {
     "path": "core.comment.create",
     "namespace": "core.comment",
-    "summary": "Create a comment.",
-    "examplePrompts": [],
+    "summary": "Create a comment in the project — optionally pinned to a component at a 3D point — with optional",
+    "examplePrompts": [
+      "Add a comment on this wall saying the height looks wrong",
+      "Leave a note on the selected room for the design team",
+      "Comment \"verify the door swing\" and tag alex@acme.com",
+      "Pin a review note at this point on the slab\n\n# Example\n```ts\nconst c = await snaptrude.core.comment.create(\n\"Check this wall 🎉\",\nspaceId,\nundefined,\n[\"alex@acme.com\"],\n)\n```"
+    ],
     "argsType": "string",
     "resultType": "CommentHandle"
   },
   {
     "path": "core.comment.delete",
     "namespace": "core.comment",
-    "summary": "Delete a comment.",
-    "examplePrompts": [],
+    "summary": "Permanently remove a comment from the project.",
+    "examplePrompts": [
+      "Delete this comment",
+      "Remove the note about the old layout",
+      "Get rid of my last comment",
+      "Clear that resolved comment off the wall\n\n# Example\n```ts\nconst [comment] = await snaptrude.core.comment.list()\nawait snaptrude.core.comment.delete(comment)\n```"
+    ],
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
   {
     "path": "core.comment.isResolved",
     "namespace": "core.comment",
-    "summary": "Whether a comment is resolved.",
-    "examplePrompts": [],
+    "summary": "Check whether a comment has been marked resolved.",
+    "examplePrompts": [
+      "Is this comment resolved yet?",
+      "Check if the note about the roof has been closed",
+      "Has my comment been resolved?",
+      "Tell me whether that comment is still open\n\n# Example\n```ts\nconst [comment] = await snaptrude.core.comment.list()\nconst resolved = await snaptrude.core.comment.isResolved(comment)\nconsole.log(resolved ? \"resolved\" : \"still open\")\n```"
+    ],
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
   {
     "path": "core.comment.list",
     "namespace": "core.comment",
-    "summary": "List all (non-deleted) comment handles in the project.",
-    "examplePrompts": [],
+    "summary": "List every comment in the project (deleted ones are excluded), returned as comment handles you can pass to the other comment methods.",
+    "examplePrompts": [
+      "List all the comments in this project",
+      "How many comments are on this model?",
+      "Show every note in the file",
+      "Get all comments so I can check which are resolved\n\n# Example\n```ts\nconst comments = await snaptrude.core.comment.list()\nconsole.log(`${comments.length} comments in the project`)\n```"
+    ],
     "argsType": null,
     "resultType": "CommentHandle[]"
   },
@@ -143,7 +403,12 @@
     "path": "core.comment.reopen",
     "namespace": "core.comment",
     "summary": "Reopen a resolved comment. Paired with {@link PluginCommentApi.resolve}.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Reopen this resolved comment",
+      "Mark the comment as unresolved again",
+      "Bring back the closed note about the window heights",
+      "Un-resolve that comment so we can keep discussing it\n\n# Example\n```ts\nconst [comment] = await snaptrude.core.comment.list()\nawait snaptrude.core.comment.reopen(comment)\n```"
+    ],
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
@@ -151,7 +416,12 @@
     "path": "core.comment.resolve",
     "namespace": "core.comment",
     "summary": "Mark a comment resolved. Paired with {@link PluginCommentApi.reopen}.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Mark this comment as resolved",
+      "Resolve the comment about the staircase",
+      "Close out this review note",
+      "Set that comment to done\n\n# Example\n```ts\nconst c = await snaptrude.core.comment.create(\"Verify the door swing\")\nawait snaptrude.core.comment.resolve(c)\n```"
+    ],
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
@@ -159,7 +429,12 @@
     "path": "core.comment.tag",
     "namespace": "core.comment",
     "summary": "Tag (mention) a user on an existing comment, by email.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Tag alex@acme.com on this comment",
+      "Mention the structural engineer in that note",
+      "Add priya@studio.com to the comment about the lobby",
+      "Notify a teammate about an existing comment\n\n# Example\n```ts\nconst [comment] = await snaptrude.core.comment.list()\nawait snaptrude.core.comment.tag(comment, \"alex@acme.com\")\n```"
+    ],
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
@@ -167,7 +442,12 @@
     "path": "core.comment.update",
     "namespace": "core.comment",
     "summary": "Edit a comment's message (and optional",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Edit my comment to say the beam depth is 600mm",
+      "Change the text of this comment",
+      "Update the note on the wall and mention priya@studio.com",
+      "Reword the comment I just added\n\n# Example\n```ts\nconst c = await snaptrude.core.comment.create(\"Beam depth TBD\")\nawait snaptrude.core.comment.update(c, \"Beam depth is 600mm\", [\"priya@studio.com\"])\n```"
+    ],
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
@@ -175,7 +455,10 @@
     "path": "core.geom.create.arc",
     "namespace": "core.geom.create",
     "summary": "Create a circular arc from its start, end, centre, and axis point handles. Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Draw an arc between these two points around a centre",
+      "Add a curved segment from A to B"
+    ],
     "argsType": "Vec3Handle",
     "resultType": "ArcHandle"
   },
@@ -183,7 +466,10 @@
     "path": "core.geom.create.circle",
     "namespace": "core.geom.create",
     "summary": "Create a circle from a centre point, an axis (plane normal), and a radius. Host API call — returns a handle. A circle is a closed curve; read it back via `snaptrude.core.geom.query.circle.*`.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Make a circle of radius 2 at this point",
+      "Draw a circular outline 5m across"
+    ],
     "argsType": "Vec3Handle",
     "resultType": "CircleHandle"
   },
@@ -199,7 +485,10 @@
     "path": "core.geom.create.contourFromProfiles",
     "namespace": "core.geom.create",
     "summary": "Create a contour from an outer profile plus zero or more inner profiles (holes). Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Make a shape with a hole in the middle",
+      "Cut a courtyard opening out of this floor outline"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ContourHandle"
   },
@@ -207,7 +496,10 @@
     "path": "core.geom.create.line",
     "namespace": "core.geom.create",
     "summary": "Create a straight line segment between two point handles. Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Draw a line from point A to point B",
+      "Draw a straight edge between these two points"
+    ],
     "argsType": "Vec3Handle",
     "resultType": "LineHandle"
   },
@@ -215,7 +507,9 @@
     "path": "core.geom.create.profileFromCurves",
     "namespace": "core.geom.create",
     "summary": "Create a profile from an ordered list of curve handles forming a closed loop. Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Join these lines and arcs into one closed shape"
+    ],
     "argsType": "CurveHandle[]",
     "resultType": "ProfileHandle"
   },
@@ -223,7 +517,10 @@
     "path": "core.geom.create.profileFromLinePoints",
     "namespace": "core.geom.create",
     "summary": "Create a closed profile from an ordered list of point handles connected by line segments (last auto-connected to first). Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Draw a closed polygon through these corner points",
+      "Create an L-shaped outline from a list of points"
+    ],
     "argsType": "Vec3Handle[]",
     "resultType": "ProfileHandle"
   },
@@ -231,7 +528,10 @@
     "path": "core.geom.create.profileRect",
     "namespace": "core.geom.create",
     "summary": "Create an axis-aligned **rectangle** profile (XZ plane) of `width` × `depth`, centred at `center` (defaults to the origin). Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Draw a 4m by 3m rectangle",
+      "Make a rectangular outline for a room footprint"
+    ],
     "argsType": "number",
     "resultType": "ProfileHandle"
   },
@@ -263,7 +563,10 @@
     "path": "core.geom.query.arc.getCentre",
     "namespace": "core.geom.query.arc",
     "summary": "Read the centre point of an arc.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Where is the centre of this arc?",
+      "Find the center point of the curved wall\n\n# Example\n```ts\nconst start = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst end = await snaptrude.core.math.vec3.new(0, 0, 5)\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst arc = await snaptrude.core.geom.create.arc(start, end, origin, up)\nconst centre = await snaptrude.core.geom.query.arc.getCentre(arc)\nconsole.log(centre.x, centre.y, centre.z)\n```"
+    ],
     "argsType": "ArcHandle",
     "resultType": "Vec3Components"
   },
@@ -271,7 +574,10 @@
     "path": "core.geom.query.arc.getRadius",
     "namespace": "core.geom.query.arc",
     "summary": "Read the radius of an arc.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the radius of this curved wall segment?",
+      "Measure the radius of the selected arc\n\n# Example\n```ts\nconst start = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst end = await snaptrude.core.math.vec3.new(0, 0, 5)\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst arc = await snaptrude.core.geom.create.arc(start, end, origin, up)\nconst radius = await snaptrude.core.geom.query.arc.getRadius(arc)\n```"
+    ],
     "argsType": "ArcHandle",
     "resultType": "number"
   },
@@ -279,7 +585,10 @@
     "path": "core.geom.query.arc.getSweepAngle",
     "namespace": "core.geom.query.arc",
     "summary": "Read the sweep angle of an arc (the angle subtended at its centre).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What angle does this arc sweep through?",
+      "How many degrees does this curved wall turn?\n\n# Example\n```ts\nconst start = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst end = await snaptrude.core.math.vec3.new(0, 0, 5)\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst arc = await snaptrude.core.geom.create.arc(start, end, origin, up)\nconst sweep = await snaptrude.core.geom.query.arc.getSweepAngle(arc)\nconsole.log(\"degrees:\", (sweep * 180) / Math.PI)\n```"
+    ],
     "argsType": "ArcHandle",
     "resultType": "number"
   },
@@ -295,7 +604,10 @@
     "path": "core.geom.query.brep.getBoundingBox",
     "namespace": "core.geom.query.brep",
     "summary": "Get the axis-aligned bounding box of a brep.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the bounding box of this shape?",
+      "How big is this object overall — give me its min and max extents\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst { min, max } = await snaptrude.core.geom.query.brep.getBoundingBox(brep)\nconsole.log(\"size:\", max.x - min.x, max.y - min.y, max.z - min.z)\n}\n```"
+    ],
     "argsType": "BrepHandle",
     "resultType": "BBoxComponents"
   },
@@ -303,7 +615,10 @@
     "path": "core.geom.query.brep.getCentroid",
     "namespace": "core.geom.query.brep",
     "summary": "Get the centroid (mean of all vertex positions) of a brep.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Find the centre point of this shape",
+      "What is the centroid of the selected object?\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst centroid = await snaptrude.core.geom.query.brep.getCentroid(brep)\nconsole.log(centroid.x, centroid.y, centroid.z)\n}\n```"
+    ],
     "argsType": "BrepHandle",
     "resultType": "Vec3Components"
   },
@@ -367,7 +682,10 @@
     "path": "core.geom.query.brep.isEqual",
     "namespace": "core.geom.query.brep",
     "summary": "Test whether two breps are geometrically equal.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Are these two shapes geometrically identical?",
+      "Check whether these two objects have the same geometry\n\n# Example\n```ts\nconst [a, b] = await snaptrude.design.query.listMasses()\nconst brepA = await snaptrude.design.query.geometry.getBrep(a)\nconst brepB = await snaptrude.design.query.geometry.getBrep(b)\nif (brepA && brepB) {\nconst same = await snaptrude.core.geom.query.brep.isEqual(brepA, brepB)\n}\n```"
+    ],
     "argsType": "BrepHandle",
     "resultType": "boolean"
   },
@@ -407,7 +725,10 @@
     "path": "core.geom.query.brep.listVertexPositions",
     "namespace": "core.geom.query.brep",
     "summary": "List the positions of all vertices in a brep (ordered as {@linkcode PluginGeomQueryBrepApi.listVertices}).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the coordinates of every corner of this shape",
+      "Give me all the corner points of the selected mass as XYZ coordinates\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst positions = await snaptrude.core.geom.query.brep.listVertexPositions(brep)\nfor (const p of positions) console.log(p.x, p.y, p.z)\n}\n```"
+    ],
     "argsType": "BrepHandle",
     "resultType": "Vec3Components[]"
   },
@@ -431,7 +752,10 @@
     "path": "core.geom.query.circle.getCentre",
     "namespace": "core.geom.query.circle",
     "summary": "Read the centre point of a circle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Where is the centre of this circle?",
+      "Find the center point of the circular courtyard outline\n\n# Example\n```ts\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst circle = await snaptrude.core.geom.create.circle(origin, up, 5)\nconst centre = await snaptrude.core.geom.query.circle.getCentre(circle)\nconsole.log(centre.x, centre.y, centre.z)\n```"
+    ],
     "argsType": "CircleHandle",
     "resultType": "Vec3Components"
   },
@@ -439,7 +763,10 @@
     "path": "core.geom.query.circle.getLength",
     "namespace": "core.geom.query.circle",
     "summary": "Read the length (circumference, `2πr`) of a circle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the circumference of this circle?",
+      "How long is the circular path around the courtyard?\n\n# Example\n```ts\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst circle = await snaptrude.core.geom.create.circle(origin, up, 5)\nconst circumference = await snaptrude.core.geom.query.circle.getLength(circle)\n```"
+    ],
     "argsType": "CircleHandle",
     "resultType": "number"
   },
@@ -447,7 +774,9 @@
     "path": "core.geom.query.circle.getNearestPoint",
     "namespace": "core.geom.query.circle",
     "summary": "Get the point on a circle nearest to an arbitrary point.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Find the point on the circle closest to this column\n\n# Example\n```ts\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst circle = await snaptrude.core.geom.create.circle(origin, up, 5)\nconst target = await snaptrude.core.math.vec3.new(8, 0, 2)\nconst nearest = await snaptrude.core.geom.query.circle.getNearestPoint(circle, target)\nconsole.log(nearest.x, nearest.y, nearest.z)\n```"
+    ],
     "argsType": "CircleHandle",
     "resultType": "Vec3Components"
   },
@@ -463,7 +792,9 @@
     "path": "core.geom.query.circle.getPointAtDistance",
     "namespace": "core.geom.query.circle",
     "summary": "Get the point reached by travelling a signed arc-distance along the circle from a reference point that lies on it.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Mark a point 2 metres along the circle from this point\n\n# Example\n```ts\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst circle = await snaptrude.core.geom.create.circle(origin, up, 5)\nconst ref = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst ahead = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2)\nconst behind = await snaptrude.core.geom.query.circle.getPointAtDistance(circle, ref, 2, false)\n```"
+    ],
     "argsType": "CircleHandle",
     "resultType": "Vec3Components"
   },
@@ -471,7 +802,10 @@
     "path": "core.geom.query.circle.getRadius",
     "namespace": "core.geom.query.circle",
     "summary": "Read the radius of a circle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the radius of this circle?",
+      "Measure the radius of the circular column grid\n\n# Example\n```ts\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst circle = await snaptrude.core.geom.create.circle(origin, up, 5)\nconst radius = await snaptrude.core.geom.query.circle.getRadius(circle)\n```"
+    ],
     "argsType": "CircleHandle",
     "resultType": "number"
   },
@@ -487,7 +821,9 @@
     "path": "core.geom.query.circle.hasPoint",
     "namespace": "core.geom.query.circle",
     "summary": "Test whether a point lies on a circle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Check whether this point sits on the circle\n\n# Example\n```ts\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst circle = await snaptrude.core.geom.create.circle(origin, up, 5)\nconst pt = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst onCircle = await snaptrude.core.geom.query.circle.hasPoint(circle, pt)\n```"
+    ],
     "argsType": "CircleHandle",
     "resultType": "boolean"
   },
@@ -511,7 +847,10 @@
     "path": "core.geom.query.circle.listPoints",
     "namespace": "core.geom.query.circle",
     "summary": "Sample a circle into an ordered list of points.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Divide this circle into 12 equal points",
+      "Get evenly spaced points around the circle to place columns\n\n# Example\n```ts\nconst origin = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst up = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst circle = await snaptrude.core.geom.create.circle(origin, up, 5)\nconst points = await snaptrude.core.geom.query.circle.listPoints(circle, 12)\nfor (const p of points) console.log(p.x, p.y, p.z)\n```"
+    ],
     "argsType": "CircleHandle",
     "resultType": "Vec3Components[]"
   },
@@ -519,7 +858,10 @@
     "path": "core.geom.query.contour.getArea",
     "namespace": "core.geom.query.contour",
     "summary": "Get the (approximate) net enclosed area of a contour — the outer profile area minus the area of every hole.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the area of this shape?",
+      "Calculate the usable area of this outline after subtracting its holes\n\n# Example\n```ts\nconst outer = await snaptrude.core.geom.create.profileRect(6, 4)\nconst hole = await snaptrude.core.geom.create.profileRect(2, 1)\nconst contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])\nconst area = await snaptrude.core.geom.query.contour.getArea(contour) // 24 - 2 = 22\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "number"
   },
@@ -527,7 +869,9 @@
     "path": "core.geom.query.contour.getBoundingBox",
     "namespace": "core.geom.query.contour",
     "summary": "Get the axis-aligned bounding box of a contour.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What are the overall extents of this shape?\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 { min, max } = await snaptrude.core.geom.query.contour.getBoundingBox(contour)\nconsole.log(max.x - min.x, max.z - min.z) // 4 3\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "BBoxComponents"
   },
@@ -535,7 +879,10 @@
     "path": "core.geom.query.contour.getHoleCount",
     "namespace": "core.geom.query.contour",
     "summary": "Get the number of inner profiles (holes) in a contour.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How many holes does this shape have?",
+      "Count the openings in this slab outline\n\n# Example\n```ts\nconst outer = await snaptrude.core.geom.create.profileRect(6, 4)\nconst hole = await snaptrude.core.geom.create.profileRect(2, 1)\nconst contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])\nconst count = await snaptrude.core.geom.query.contour.getHoleCount(contour) // 1\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "number"
   },
@@ -543,7 +890,9 @@
     "path": "core.geom.query.contour.getNearestPoint",
     "namespace": "core.geom.query.contour",
     "summary": "Get the point on a contour nearest to an arbitrary point.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Find the point on this boundary closest to a given location\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 point = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst nearest = await snaptrude.core.geom.query.contour.getNearestPoint(contour, point)\nconsole.log(nearest.x, nearest.y, nearest.z) // 2 0 0\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "Vec3Components"
   },
@@ -567,7 +916,10 @@
     "path": "core.geom.query.contour.getPerimeter",
     "namespace": "core.geom.query.contour",
     "summary": "Get the perimeter (total length of every curve) of a contour, including holes.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the perimeter of this shape?",
+      "How long is the boundary of this outline, including its holes?\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 perimeter = await snaptrude.core.geom.query.contour.getPerimeter(contour) // 14\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "number"
   },
@@ -575,7 +927,10 @@
     "path": "core.geom.query.contour.hasPoint",
     "namespace": "core.geom.query.contour",
     "summary": "Test whether a point lies inside a contour (inside the outer profile and outside every hole).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Is this point inside the shape?",
+      "Check whether a location falls within this boundary but not in a hole\n\n# Example\n```ts\nconst outer = await snaptrude.core.geom.create.profileRect(6, 4)\nconst hole = await snaptrude.core.geom.create.profileRect(2, 1)\nconst contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])\nconst point = await snaptrude.core.math.vec3.new(2.5, 0, 1.5)\nconst inside = await snaptrude.core.geom.query.contour.hasPoint(contour, point) // true — outside the hole\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "boolean"
   },
@@ -647,7 +1002,9 @@
     "path": "core.geom.query.curve.getChordLength",
     "namespace": "core.geom.query.curve",
     "summary": "Get the straight-line chord length between a curve's endpoints.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the straight-line distance between the two ends of this arc?\n\n# Example\n```ts\nconst start = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst end = await snaptrude.core.math.vec3.new(-5, 0, 0)\nconst centre = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst axis = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst arc = await snaptrude.core.geom.create.arc(start, end, centre, axis)\nconst chord = await snaptrude.core.geom.query.curve.getChordLength(arc) // 10 (getLength gives the arc length)\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "number"
   },
@@ -655,7 +1012,9 @@
     "path": "core.geom.query.curve.getCommonPart",
     "namespace": "core.geom.query.curve",
     "summary": "Get the common (overlapping) part of two curves.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the shared segment where these two edges overlap\n\n# Example\n```ts\nconst p0 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst p5 = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst p10 = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst p15 = await snaptrude.core.math.vec3.new(15, 0, 0)\nconst lineA = await snaptrude.core.geom.create.line(p0, p10)\nconst lineB = await snaptrude.core.geom.create.line(p5, p15)\nconst common = await snaptrude.core.geom.query.curve.getCommonPart(lineA, lineB)\nif (common) {\nconst length = await snaptrude.core.geom.query.curve.getLength(common) // 5\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "CurveHandle | null"
   },
@@ -671,7 +1030,9 @@
     "path": "core.geom.query.curve.getDistanceAlong",
     "namespace": "core.geom.query.curve",
     "summary": "Get the arc-length distance along a curve between two points on it.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How far apart are these two points measured along the curved wall?\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst mid = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst d = await snaptrude.core.geom.query.curve.getDistanceAlong(line, a, mid) // 5\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "number"
   },
@@ -679,7 +1040,10 @@
     "path": "core.geom.query.curve.getDistanceBetween",
     "namespace": "core.geom.query.curve",
     "summary": "Get the perpendicular distance between two parallel lines.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How far apart are these two parallel walls?",
+      "Measure the spacing between these two gridlines\n\n# Example\n```ts\nconst a1 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst a2 = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst b1 = await snaptrude.core.math.vec3.new(0, 0, 4)\nconst b2 = await snaptrude.core.math.vec3.new(10, 0, 4)\nconst lineA = await snaptrude.core.geom.create.line(a1, a2)\nconst lineB = await snaptrude.core.geom.create.line(b1, b2)\nconst spacing = await snaptrude.core.geom.query.curve.getDistanceBetween(lineA, lineB) // 4\n```"
+    ],
     "argsType": "LineHandle",
     "resultType": "number"
   },
@@ -687,7 +1051,10 @@
     "path": "core.geom.query.curve.getDistanceToPoint",
     "namespace": "core.geom.query.curve",
     "summary": "Get the shortest distance from an arbitrary point to a curve.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How far is this column from the wall edge?",
+      "What is the shortest distance from this point to the boundary line?\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst centerline = await snaptrude.design.query.geometry.getCenterline(wall)\nconst point = await snaptrude.core.math.vec3.new(2, 0, 3)\nif (centerline) {\nconst distance = await snaptrude.core.geom.query.curve.getDistanceToPoint(centerline, point)\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "number"
   },
@@ -695,7 +1062,9 @@
     "path": "core.geom.query.curve.getEndPoint",
     "namespace": "core.geom.query.curve",
     "summary": "Get the end point of a curve.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the coordinates of the far end of this edge\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst end = await snaptrude.core.geom.query.curve.getEndPoint(line) // { x: 5, y: 0, z: 0 }\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "Vec3Components"
   },
@@ -703,7 +1072,10 @@
     "path": "core.geom.query.curve.getLength",
     "namespace": "core.geom.query.curve",
     "summary": "Get the arc-length of a curve.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How long is this wall edge?",
+      "Measure the length of this curved boundary\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst centerline = await snaptrude.design.query.geometry.getCenterline(wall)\nif (centerline) {\nconst length = await snaptrude.core.geom.query.curve.getLength(centerline)\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "number"
   },
@@ -711,7 +1083,9 @@
     "path": "core.geom.query.curve.getMergedCurve",
     "namespace": "core.geom.query.curve",
     "summary": "Merge two curves into a single curve when they are mergeable.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Merge these two line segments into a single line\n\n# Example\n```ts\nconst p0 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst p5 = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst p10 = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst lineA = await snaptrude.core.geom.create.line(p0, p5)\nconst lineB = await snaptrude.core.geom.create.line(p5, p10)\nconst merged = await snaptrude.core.geom.query.curve.getMergedCurve(lineA, lineB)\nif (merged) {\nconst length = await snaptrude.core.geom.query.curve.getLength(merged) // 10\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "CurveHandle | null"
   },
@@ -719,7 +1093,10 @@
     "path": "core.geom.query.curve.getMidPoint",
     "namespace": "core.geom.query.curve",
     "summary": "Get the mid point of a curve.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Find the midpoint of this wall edge",
+      "Where is the centre of this boundary line?\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst centerline = await snaptrude.design.query.geometry.getCenterline(wall)\nif (centerline) {\nconst mid = await snaptrude.core.geom.query.curve.getMidPoint(centerline)\nconsole.log(mid.x, mid.y, mid.z)\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "Vec3Components"
   },
@@ -727,7 +1104,9 @@
     "path": "core.geom.query.curve.getNearestPoint",
     "namespace": "core.geom.query.curve",
     "summary": "Get the point on a curve nearest to an arbitrary point.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Find the point on this edge closest to the column\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst centerline = await snaptrude.design.query.geometry.getCenterline(wall)\nconst reference = await snaptrude.core.math.vec3.new(2, 0, 3)\nif (centerline) {\nconst nearest = await snaptrude.core.geom.query.curve.getNearestPoint(centerline, reference)\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "Vec3Components"
   },
@@ -751,7 +1130,10 @@
     "path": "core.geom.query.curve.getPointAtDistance",
     "namespace": "core.geom.query.curve",
     "summary": "Get the point at a given distance along a curve from a reference point.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Find the point 2 metres along this edge from the corner",
+      "Mark a spot 900mm from the start of the wall edge\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst p = await snaptrude.core.geom.query.curve.getPointAtDistance(line, a, 2) // { x: 2, y: 0, z: 0 }\nconst q = await snaptrude.core.geom.query.curve.getPointAtDistance(line, b, 2, false) // measured backwards from the end\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "Vec3Components"
   },
@@ -767,7 +1149,10 @@
     "path": "core.geom.query.curve.getShortestGap",
     "namespace": "core.geom.query.curve",
     "summary": "Get the shortest gap between two curves, optionally including their endpoints.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the gap between these two wall edges?",
+      "How close do these two curves get to each other?\n\n# Example\n```ts\nconst a1 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst a2 = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst b1 = await snaptrude.core.math.vec3.new(0, 0, 2)\nconst b2 = await snaptrude.core.math.vec3.new(5, 0, 2)\nconst curveA = await snaptrude.core.geom.create.line(a1, a2)\nconst curveB = await snaptrude.core.geom.create.line(b1, b2)\nconst gap = await snaptrude.core.geom.query.curve.getShortestGap(curveA, curveB) // 2\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "number"
   },
@@ -775,7 +1160,9 @@
     "path": "core.geom.query.curve.getStartPoint",
     "namespace": "core.geom.query.curve",
     "summary": "Get the start point of a curve.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Where does this wall edge start?\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst centerline = await snaptrude.design.query.geometry.getCenterline(wall)\nif (centerline) {\nconst start = await snaptrude.core.geom.query.curve.getStartPoint(centerline)\nconsole.log(start.x, start.y, start.z)\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "Vec3Components"
   },
@@ -799,7 +1186,9 @@
     "path": "core.geom.query.curve.isContinuous",
     "namespace": "core.geom.query.curve",
     "summary": "Test whether two curves are continuous (share an endpoint without a gap).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Do these two edges connect end to end without a gap?\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst c = await snaptrude.core.math.vec3.new(5, 0, 5)\nconst lineA = await snaptrude.core.geom.create.line(a, b)\nconst lineB = await snaptrude.core.geom.create.line(b, c)\nconst connected = await snaptrude.core.geom.query.curve.isContinuous(lineA, lineB) // true\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "boolean"
   },
@@ -815,7 +1204,9 @@
     "path": "core.geom.query.curve.isLinear",
     "namespace": "core.geom.query.curve",
     "summary": "Test whether a curve is a straight line.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Is this edge straight or curved?\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst centerline = await snaptrude.design.query.geometry.getCenterline(wall)\nif (centerline) {\nconst straight = await snaptrude.core.geom.query.curve.isLinear(centerline)\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "boolean"
   },
@@ -823,7 +1214,9 @@
     "path": "core.geom.query.curve.isOnCurve",
     "namespace": "core.geom.query.curve",
     "summary": "Test whether a point lies on a curve within an optional threshold.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Check whether this point lies on the wall edge\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst point = await snaptrude.core.math.vec3.new(5, 0, 0.005)\nconst on = await snaptrude.core.geom.query.curve.isOnCurve(line, point, 0.01) // true within tolerance\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "boolean"
   },
@@ -831,7 +1224,9 @@
     "path": "core.geom.query.curve.isOverlapping",
     "namespace": "core.geom.query.curve",
     "summary": "Test whether two curves overlap (share a collinear/concentric span), optionally including their endpoints.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Do these two wall edges overlap?\n\n# Example\n```ts\nconst p0 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst p5 = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst p10 = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst p15 = await snaptrude.core.math.vec3.new(15, 0, 0)\nconst lineA = await snaptrude.core.geom.create.line(p0, p10)\nconst lineB = await snaptrude.core.geom.create.line(p5, p15)\nconst overlaps = await snaptrude.core.geom.query.curve.isOverlapping(lineA, lineB) // true (share the 5..10 span)\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "boolean"
   },
@@ -839,7 +1234,10 @@
     "path": "core.geom.query.curve.isParallel",
     "namespace": "core.geom.query.curve",
     "summary": "Test whether two lines are parallel within an optional tolerance.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Are these two walls parallel?",
+      "Check if these gridlines run parallel to each other\n\n# Example\n```ts\nconst a1 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst a2 = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst b1 = await snaptrude.core.math.vec3.new(0, 0, 3)\nconst b2 = await snaptrude.core.math.vec3.new(10, 0, 3)\nconst lineA = await snaptrude.core.geom.create.line(a1, a2)\nconst lineB = await snaptrude.core.geom.create.line(b1, b2)\nconst parallel = await snaptrude.core.geom.query.curve.isParallel(lineA, lineB) // true\n```"
+    ],
     "argsType": "LineHandle",
     "resultType": "boolean"
   },
@@ -847,7 +1245,10 @@
     "path": "core.geom.query.curve.listIntersections",
     "namespace": "core.geom.query.curve",
     "summary": "List the intersection points between two curves.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Where do these two lines cross?",
+      "Find the intersection points of these two gridlines\n\n# Example\n```ts\nconst a1 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst a2 = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst b1 = await snaptrude.core.math.vec3.new(5, 0, -5)\nconst b2 = await snaptrude.core.math.vec3.new(5, 0, 5)\nconst lineA = await snaptrude.core.geom.create.line(a1, a2)\nconst lineB = await snaptrude.core.geom.create.line(b1, b2)\nconst points = await snaptrude.core.geom.query.curve.listIntersections(lineA, lineB) // [{ x: 5, y: 0, z: 0 }]\nconst unbounded = await snaptrude.core.geom.query.curve.listIntersections(lineA, lineB, false, false) // treat both as infinite\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "Vec3Components[]"
   },
@@ -863,7 +1264,10 @@
     "path": "core.geom.query.curve.listSubdivisions",
     "namespace": "core.geom.query.curve",
     "summary": "List the points produced by subdividing a curve into equal segments.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Divide this edge into 5 equal segments",
+      "Split the wall line into equal parts for placing columns\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst centerline = await snaptrude.design.query.geometry.getCenterline(wall)\nif (centerline) {\nconst points = await snaptrude.core.geom.query.curve.listSubdivisions(centerline, 5)\n}\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "Vec3Components[]"
   },
@@ -951,7 +1355,9 @@
     "path": "core.geom.query.face.hasHoles",
     "namespace": "core.geom.query.face",
     "summary": "Test whether a face has any holes.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Does this face have any holes cut into it?\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst brep = await snaptrude.design.query.geometry.getBrep(wall)\nif (brep) {\nconst [face] = await snaptrude.core.geom.query.brep.listFaces(brep)\nconst pierced = await snaptrude.core.geom.query.face.hasHoles(face)\n}\n```"
+    ],
     "argsType": "FaceHandle",
     "resultType": "boolean"
   },
@@ -959,7 +1365,10 @@
     "path": "core.geom.query.face.listAdjacentFaces",
     "namespace": "core.geom.query.face",
     "summary": "List the faces adjacent to a face (sharing an edge). Boundary edges are skipped.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Which faces are next to this one?",
+      "Find the faces that share an edge with the selected face\n\n# Example\n```ts\nconst [mass] = await snaptrude.design.query.listMasses()\nconst brep = await snaptrude.design.query.geometry.getBrep(mass)\nif (brep) {\nconst [face] = await snaptrude.core.geom.query.brep.listFaces(brep)\nconst neighbours = await snaptrude.core.geom.query.face.listAdjacentFaces(face)\n}\n```"
+    ],
     "argsType": "FaceHandle",
     "resultType": "FaceHandle[]"
   },
@@ -999,7 +1408,10 @@
     "path": "core.geom.query.face.listVertexPositions",
     "namespace": "core.geom.query.face",
     "summary": "List the positions of a face's outer-loop vertices (needs the parent brep for coordinates).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What are the corner coordinates of this face?",
+      "Get the boundary points of the selected face\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst brep = await snaptrude.design.query.geometry.getBrep(wall)\nif (brep) {\nconst [face] = await snaptrude.core.geom.query.brep.listFaces(brep)\nconst corners = await snaptrude.core.geom.query.face.listVertexPositions(face, brep)\nfor (const p of corners) console.log(p.x, p.y, p.z)\n}\n```"
+    ],
     "argsType": "FaceHandle",
     "resultType": "Vec3Components[]"
   },
@@ -1007,7 +1419,9 @@
     "path": "core.geom.query.face.listVertexPositionsWithCurves",
     "namespace": "core.geom.query.face",
     "summary": "List the tessellated boundary points of a face's outer loop (arcs sampled, sense-corrected). Not cardinality-equal to {@linkcode PluginGeomQueryFaceApi.listVertexPositions}.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Trace the outline of this face including its curved edges\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst brep = await snaptrude.design.query.geometry.getBrep(wall)\nif (brep) {\nconst [face] = await snaptrude.core.geom.query.brep.listFaces(brep)\nconst outline = await snaptrude.core.geom.query.face.listVertexPositionsWithCurves(face)\n}\n```"
+    ],
     "argsType": "FaceHandle",
     "resultType": "Vec3Components[]"
   },
@@ -1087,7 +1501,10 @@
     "path": "core.geom.query.profile.getArea",
     "namespace": "core.geom.query.profile",
     "summary": "Get the (approximate) enclosed area of a profile.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the area enclosed by this outline?",
+      "Measure the area of this shape\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst area = await snaptrude.core.geom.query.profile.getArea(rect) // 12\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "number"
   },
@@ -1095,7 +1512,9 @@
     "path": "core.geom.query.profile.getBoundingBox",
     "namespace": "core.geom.query.profile",
     "summary": "Get the axis-aligned bounding box of a profile.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How wide and long is this outline overall?\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst { min, max } = await snaptrude.core.geom.query.profile.getBoundingBox(rect)\nconsole.log(max.x - min.x, max.z - min.z) // 4 3\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "BBoxComponents"
   },
@@ -1103,7 +1522,9 @@
     "path": "core.geom.query.profile.getNearestPoint",
     "namespace": "core.geom.query.profile",
     "summary": "Get the point on a profile nearest to an arbitrary point.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Find the closest point on this outline to a given point\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst point = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst nearest = await snaptrude.core.geom.query.profile.getNearestPoint(rect, point)\nconsole.log(nearest.x, nearest.y, nearest.z) // 2 0 0\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "Vec3Components"
   },
@@ -1119,7 +1540,10 @@
     "path": "core.geom.query.profile.getPerimeter",
     "namespace": "core.geom.query.profile",
     "summary": "Get the perimeter (total curve length) of a profile.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How long is the boundary of this shape in total?",
+      "Measure the perimeter of this outline\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst perimeter = await snaptrude.core.geom.query.profile.getPerimeter(rect) // 14\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "number"
   },
@@ -1127,7 +1551,10 @@
     "path": "core.geom.query.profile.hasPoint",
     "namespace": "core.geom.query.profile",
     "summary": "Test whether a point lies inside a profile.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Does this point fall inside the outline?",
+      "Check if the column location lies within this room boundary\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst point = await snaptrude.core.math.vec3.new(1, 0, 1)\nconst inside = await snaptrude.core.geom.query.profile.hasPoint(rect, point) // true\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "boolean"
   },
@@ -1143,7 +1570,10 @@
     "path": "core.geom.query.profile.isClosed",
     "namespace": "core.geom.query.profile",
     "summary": "Test whether a profile forms a closed loop.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Is my sketch outline closed or still open?",
+      "Check whether this boundary forms a complete loop\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst closed = await snaptrude.core.geom.query.profile.isClosed(rect) // true\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "boolean"
   },
@@ -1199,7 +1629,10 @@
     "path": "core.geom.query.profile.listPoints",
     "namespace": "core.geom.query.profile",
     "summary": "List the tessellated points along a profile.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Give me the corner coordinates of this shape",
+      "List the vertex points along this outline\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst points = await snaptrude.core.geom.query.profile.listPoints(rect)\nfor (const p of points) console.log(p.x, p.y, p.z)\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "Vec3Components[]"
   },
@@ -1223,7 +1656,10 @@
     "path": "core.geom.query.vertex.getPosition",
     "namespace": "core.geom.query.vertex",
     "summary": "Get the position of a vertex (needs the parent brep for coordinates).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What are the coordinates of this corner point?",
+      "Get the exact x, y, z position of the selected vertex\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst brep = await snaptrude.design.query.geometry.getBrep(wall)\nif (brep) {\nconst [vertex] = await snaptrude.core.geom.query.brep.listVertices(brep)\nconst pos = await snaptrude.core.geom.query.vertex.getPosition(brep, vertex)\nconsole.log(pos.x, pos.y, pos.z)\n}\n```"
+    ],
     "argsType": "BrepHandle",
     "resultType": "Vec3Components"
   },
@@ -1263,7 +1699,10 @@
     "path": "core.geom.update.contour.addHole",
     "namespace": "core.geom.update.contour",
     "summary": "Add a hole to a contour by appending an inner profile. Immutable — returns a NEW contour and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Cut a hole in this shape",
+      "Punch an opening through this floor outline\n\n# Example\n```ts\nconst outer = await snaptrude.core.geom.create.profileRect(10, 8)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(outer)\nconst hole = await snaptrude.core.geom.create.profileRect(2, 2)\nconst withHole = await snaptrude.core.geom.update.contour.addHole(contour, hole)\nconst count = await snaptrude.core.geom.query.contour.getHoleCount(withHole) // 1\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ContourHandle"
   },
@@ -1271,7 +1710,10 @@
     "path": "core.geom.update.contour.mirror",
     "namespace": "core.geom.update.contour",
     "summary": "Mirror a contour across a plane. Immutable — returns a NEW contour and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Mirror this shape across the gridline",
+      "Flip this outline to its mirror image\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst point = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst normal = await snaptrude.core.math.vec3.new(1, 0, 0)\nconst mirrored = await snaptrude.core.geom.update.contour.mirror(contour, { point, normal })\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ContourHandle"
   },
@@ -1279,7 +1721,10 @@
     "path": "core.geom.update.contour.move",
     "namespace": "core.geom.update.contour",
     "summary": "Translate a contour by a vector. Immutable — returns a NEW contour and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Move this shape 2 metres to the right",
+      "Shift this outline over by 5 feet\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst shift = await snaptrude.core.math.vec3.new(2, 0, 0)\nconst moved = await snaptrude.core.geom.update.contour.move(contour, shift)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ContourHandle"
   },
@@ -1287,7 +1732,10 @@
     "path": "core.geom.update.contour.offset",
     "namespace": "core.geom.update.contour",
     "summary": "Offset a contour inward/outward by a signed distance. Immutable — returns a NEW contour and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Offset this boundary 500mm inward",
+      "Shrink this floor outline by half a metre all around\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(10, 8)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst inset = await snaptrude.core.geom.update.contour.offset(contour, -0.5)\nconst area = await snaptrude.core.geom.query.contour.getArea(inset)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ContourHandle"
   },
@@ -1295,7 +1743,10 @@
     "path": "core.geom.update.contour.removeHole",
     "namespace": "core.geom.update.contour",
     "summary": "Remove a hole from a contour by inner-profile index. Immutable — returns a NEW contour and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Remove the hole from this shape",
+      "Fill in the opening in this floor outline\n\n# Example\n```ts\nconst outer = await snaptrude.core.geom.create.profileRect(10, 8)\nconst hole = await snaptrude.core.geom.create.profileRect(2, 2)\nconst contour = await snaptrude.core.geom.create.contourFromProfiles(outer, [hole])\nconst solid = await snaptrude.core.geom.update.contour.removeHole(contour, 0)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ContourHandle"
   },
@@ -1303,7 +1754,10 @@
     "path": "core.geom.update.contour.rotate",
     "namespace": "core.geom.update.contour",
     "summary": "Rotate a contour about an axis through an optional pivot. Immutable — returns a NEW contour and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Rotate this shape 45 degrees",
+      "Turn this outline 90 degrees about its corner\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst axis = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst pivot = await snaptrude.core.math.vec3.new(3, 0, 2)\nconst rotated = await snaptrude.core.geom.update.contour.rotate(contour, axis, Math.PI / 4, pivot)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ContourHandle"
   },
@@ -1311,7 +1765,10 @@
     "path": "core.geom.update.contour.scale",
     "namespace": "core.geom.update.contour",
     "summary": "Scale a contour uniformly or per-axis about an optional pivot. Immutable — returns a NEW contour and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Scale this shape up by a factor of 2",
+      "Make this outline half its current size\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst doubled = await snaptrude.core.geom.update.contour.scale(contour, 2)\nconst stretched = await snaptrude.core.geom.update.contour.scale(contour, { x: 2, y: 1, z: 1 })\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ContourHandle"
   },
@@ -1319,7 +1776,10 @@
     "path": "core.geom.update.curve.extend",
     "namespace": "core.geom.update.curve",
     "summary": "Extend a curve by a distance from one of its ends. Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Extend this line by 1 metre",
+      "Lengthen this edge from its start point\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(5, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst longer = await snaptrude.core.geom.update.curve.extend(line, 1, false)\nconst length = await snaptrude.core.geom.query.curve.getLength(longer) // 6\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "CurveHandle"
   },
@@ -1327,7 +1787,10 @@
     "path": "core.geom.update.curve.offset",
     "namespace": "core.geom.update.curve",
     "summary": "Offset a curve by a translation vector. Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Offset this line 500mm to the side",
+      "Shift this edge over to make a parallel copy\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(8, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst sideways = await snaptrude.core.math.vec3.new(0, 0, 0.5)\nconst parallel = await snaptrude.core.geom.update.curve.offset(line, sideways)\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "CurveHandle"
   },
@@ -1343,7 +1806,10 @@
     "path": "core.geom.update.curve.split",
     "namespace": "core.geom.update.curve",
     "summary": "Split a curve at a point into separate segments. Host API call — returns handles.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Split this line at its midpoint",
+      "Break this edge into two pieces where it meets the gridline\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(6, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst mid = await snaptrude.core.math.vec3.new(3, 0, 0)\nconst [left, right] = await snaptrude.core.geom.update.curve.split(line, mid)\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "CurveHandle[]"
   },
@@ -1351,7 +1817,10 @@
     "path": "core.geom.update.curve.trim",
     "namespace": "core.geom.update.curve",
     "summary": "Trim a curve to the portion between two parameter values. Host API call — returns a handle.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Trim this line back to a shorter segment",
+      "Keep only the middle portion of this curve\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst line = await snaptrude.core.geom.create.line(a, b)\nconst middle = await snaptrude.core.geom.update.curve.trim(line, 0.25, 0.75)\n```"
+    ],
     "argsType": "CurveHandle",
     "resultType": "CurveHandle"
   },
@@ -1367,7 +1836,10 @@
     "path": "core.geom.update.profile.mirror",
     "namespace": "core.geom.update.profile",
     "summary": "Mirror a profile across a plane. Immutable — returns a NEW profile and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Mirror this outline across the vertical plane",
+      "Flip this boundary to its mirror image\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst point = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst normal = await snaptrude.core.math.vec3.new(1, 0, 0)\nconst mirrored = await snaptrude.core.geom.update.profile.mirror(rect, { point, normal })\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ProfileHandle"
   },
@@ -1375,7 +1847,10 @@
     "path": "core.geom.update.profile.move",
     "namespace": "core.geom.update.profile",
     "summary": "Translate a profile by a vector. Immutable — returns a NEW profile and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Move this outline 3 metres along the x axis",
+      "Shift this boundary to a new position\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst shift = await snaptrude.core.math.vec3.new(3, 0, 0)\nconst moved = await snaptrude.core.geom.update.profile.move(rect, shift)\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ProfileHandle"
   },
@@ -1383,7 +1858,10 @@
     "path": "core.geom.update.profile.offset",
     "namespace": "core.geom.update.profile",
     "summary": "Offset a closed profile inward/outward by a signed distance. Immutable — returns a NEW profile and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Offset this outline 300mm inward",
+      "Inset this boundary by a foot all around\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(10, 8)\nconst inset = await snaptrude.core.geom.update.profile.offset(rect, -0.3)\nconst area = await snaptrude.core.geom.query.profile.getArea(inset)\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ProfileHandle"
   },
@@ -1407,7 +1885,10 @@
     "path": "core.geom.update.profile.rotate",
     "namespace": "core.geom.update.profile",
     "summary": "Rotate a profile about an axis through an optional pivot. Immutable — returns a NEW profile and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Rotate this outline 30 degrees",
+      "Turn this boundary about its centre point\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst axis = await snaptrude.core.math.vec3.new(0, 1, 0)\nconst rotated = await snaptrude.core.geom.update.profile.rotate(rect, axis, Math.PI / 6)\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ProfileHandle"
   },
@@ -1415,7 +1896,10 @@
     "path": "core.geom.update.profile.scale",
     "namespace": "core.geom.update.profile",
     "summary": "Scale a profile uniformly or per-axis about an optional pivot. Immutable — returns a NEW profile and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Scale this outline down to half size",
+      "Enlarge this boundary by 50 percent\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(6, 4)\nconst half = await snaptrude.core.geom.update.profile.scale(rect, 0.5)\nconst stretched = await snaptrude.core.geom.update.profile.scale(rect, { x: 2, y: 1, z: 1 })\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ProfileHandle"
   },
@@ -1423,7 +1907,10 @@
     "path": "core.geom.update.profile.simplify",
     "namespace": "core.geom.update.profile",
     "summary": "Simplify a profile by merging collinear/redundant segments. Immutable — returns a NEW profile and leaves the input unchanged.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Clean up this outline by merging collinear segments",
+      "Simplify this polyline and remove redundant points\n\n# Example\n```ts\nconst p0 = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst p1 = await snaptrude.core.math.vec3.new(2, 0, 0) // collinear with p0 and p2\nconst p2 = await snaptrude.core.math.vec3.new(4, 0, 0)\nconst p3 = await snaptrude.core.math.vec3.new(4, 0, 3)\nconst jagged = await snaptrude.core.geom.create.profileFromLinePoints([p0, p1, p2, p3])\nconst clean = await snaptrude.core.geom.update.profile.simplify(jagged)\nconst curves = await snaptrude.core.geom.query.profile.listCurves(clean) // p0→p2 merged\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ProfileHandle"
   },
@@ -1540,7 +2027,12 @@
     "path": "core.history.redo",
     "namespace": "core.history",
     "summary": "Step forward over previously undone entries. Symmetric with {@linkcode PluginHistoryApi.undo}.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Redo the change I just undid",
+      "Redo the last two undone actions",
+      "Bring back the edit I reverted",
+      "Step forward again in the history\n\n# Example\n```ts\nawait snaptrude.core.history.redo()\nawait snaptrude.core.history.redo(2)\n```"
+    ],
     "argsType": "number",
     "resultType": "PluginHistoryStepResult"
   },
@@ -1548,178 +2040,609 @@
     "path": "core.history.undo",
     "namespace": "core.history",
     "summary": "Step back over committed history entries.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Undo my last change",
+      "Undo the last 3 actions",
+      "Revert what I just did to the model",
+      "Step back one change",
+      "Take back that last edit\n\n# Example\n```ts\nawait snaptrude.core.history.undo()   // one step\nawait snaptrude.core.history.undo(3)  // up to three steps\n```"
+    ],
     "argsType": "number",
     "resultType": "PluginHistoryStepResult"
   },
   {
-    "path": "core.layers.get",
-    "namespace": "core.layers",
-    "summary": "Get a single drawing layer by id.",
+    "path": "core.io.import.cadJson",
+    "namespace": "core.io.import",
+    "summary": "Sketch a CAD underlay from **already-parsed CAD JSON** — synchronous, with no server round-trip. Use this when you hold parsed CAD data (e.g. produced by your own converter); use {@link PluginCoreIoImportApi.dwg} for raw `.dwg` files.",
     "examplePrompts": [
-      "Get the drawing layer with id ly_5",
-      "Is layer ly_5 hidden or locked?",
-      "Look up a single drawing layer by its id\n\n# Example\n```ts\nconst layer = await snaptrude.core.layers.get(\"ly_5\")\nif (layer) console.log(layer.name, layer.hidden, layer.locked)\n```"
+      "Sketch this parsed CAD JSON onto the active storey",
+      "Draw these CAD curves as an underlay on storey 2",
+      "Create a CAD sketch from this geometry data",
+      "Import my converted CAD JSON onto the ground floor\n\n# Example\n```ts\nconst cad = await snaptrude.core.io.import.cadJson(\n{ unit: \"mm\", geometry: [{ type: \"line\", layer: \"WALLS\", ... }] },\n1,\n)\n```"
     ],
-    "argsType": "string",
-    "resultType": "PluginCoreLayersGetResult"
+    "argsType": "CadJsonInput",
+    "resultType": "UnderlayHandle"
   },
   {
-    "path": "core.layers.getActive",
-    "namespace": "core.layers",
-    "summary": "Get the active drawing layer of a storey.",
+    "path": "core.io.import.dwg",
+    "namespace": "core.io.import",
+    "summary": "Import a **DWG** CAD drawing as a scene underlay. `.dwg` only (no DXF).",
     "examplePrompts": [
-      "Which drawing layer is active on this storey?",
-      "Get the current layer on storey st_2",
-      "What layer am I drawing on?\n\n# Example\n```ts\nconst active = await snaptrude.core.layers.getActive(\"st_2\")\nif (active) console.log(active.name)\n```"
+      "Import this DWG floor plan onto storey 1",
+      "Bring in a CAD drawing as an underlay and tell me when it's ready",
+      "Start importing this CAD file onto the ground floor\n\n# Example\n```ts\nconst job = await snaptrude.core.io.import.dwg(\"https://example.com/plan.dwg\", 1)\n// Poll until the server-side conversion finishes — always with a timeout\n// (a UI-cancelled import stays \"processing\" forever).\nconst deadline = Date.now() + 5 * 60_000\nwhile (!(await snaptrude.core.io.job.isComplete(job))) {\nif (Date.now() > deadline) throw new Error(\"DWG import timed out\")\nawait new Promise((r) => setTimeout(r, 2000))\n}\n// The DWG lands as a CAD underlay. CAD scaling isn't supported; manage it\n// (list / fade / delete) via core.io.underlay.*.\nconst cad = await snaptrude.core.io.job.getResult(job)\nif (cad) console.log(\"DWG imported as CAD underlay:\", cad)\n```"
     ],
     "argsType": "string",
-    "resultType": "PluginCoreLayersGetActiveResult"
+    "resultType": "ImportJobHandle"
   },
   {
-    "path": "core.layers.list",
-    "namespace": "core.layers",
-    "summary": "List the drawing layers of a storey.",
+    "path": "core.io.import.image",
+    "namespace": "core.io.import",
+    "summary": "Import a raster image as a scene **underlay** — a flat, textured reference plane placed on a storey that you can trace over.",
     "examplePrompts": [
-      "List the drawing layers on this storey",
-      "Show all the PDF underlays on storey st_2",
-      "What CAD layers are on the ground floor?\n\n# Example\n```ts\nconst { layers } = await snaptrude.core.layers.list(\"st_2\")\nfor (const l of layers) console.log(l.name, l.layerType, l.hidden)\n```"
+      "Import this floor plan image onto the ground floor to trace over",
+      "Drop this survey PNG in as a reference underlay at 30% opacity",
+      "Add a site plan image on storey 2",
+      "Bring in a sketch to trace, faded to half opacity\n\n# Example\n```ts\n// Place a floor plan on storey 1, then calibrate it to a real-world size.\nconst plan = await snaptrude.core.io.import.image(\n\"https://example.com/floorplan.png\",\n1,           // storey\nundefined,   // scale\n0.4,         // opacity\n\"Ground floor plan\",\n)\n// Make the plan's longest side exactly 40 project-units:\nawait snaptrude.core.io.underlay.setScale(plan, { planSize: 40 })\n```"
     ],
     "argsType": "string",
-    "resultType": "PluginCoreLayersListResult"
+    "resultType": "UnderlayHandle"
   },
   {
-    "path": "core.layers.setActive",
-    "namespace": "core.layers",
-    "summary": "Make a drawing layer the active layer of its storey.",
+    "path": "core.io.import.model",
+    "namespace": "core.io.import",
+    "summary": "Import a **3D model** file and place it in the scene as a component.",
     "examplePrompts": [
-      "Draw on layer ly_5",
-      "Make this the active layer",
-      "Switch the active layer to the CAD underlay\n\n# Example\n```ts\nawait snaptrude.core.layers.setActive(\"ly_5\")\n```"
+      "Import this SketchUp model onto storey 1",
+      "Bring in this OBJ file and place it at the origin",
+      "Add this 3D model to the ground floor\n\n# Example\n```ts\nconst model = await snaptrude.core.io.import.model(\n\"https://example.com/tree.skp\",\n1,        // storey\n\"skp\",\n)\n```"
     ],
     "argsType": "string",
-    "resultType": "PluginCoreLayersSetActiveResult"
+    "resultType": "ComponentHandle"
   },
   {
-    "path": "core.layers.update",
-    "namespace": "core.layers",
-    "summary": "Update a drawing layer's visibility.",
+    "path": "core.io.import.pdf",
+    "namespace": "core.io.import",
+    "summary": "Import one page of a PDF as a scene **underlay** (a traceable reference plane).",
     "examplePrompts": [
-      "Hide the PDF underlay layer",
-      "Show the CAD layer again",
-      "Hide layer ly_5\n\n# Example\n```ts\nconst layer = await snaptrude.core.layers.update(\"ly_5\", true)\n```"
+      "Import page 1 of this PDF floor plan onto storey 1",
+      "Bring in the second page of this PDF as an underlay at 1:50",
+      "Add this PDF plan to the ground floor to trace over",
+      "Place page 3 of the drawing set on storey 3\n\n# Example\n```ts\nconst sheet = await snaptrude.core.io.import.pdf(\n\"https://example.com/plans.pdf\",\n1,        // storey\n2,        // page\n\"1:100\",  // drawing scale\n)\n```"
     ],
     "argsType": "string",
-    "resultType": "PluginCoreLayersUpdateResult"
+    "resultType": "UnderlayHandle"
   },
   {
-    "path": "core.math.quat.components",
-    "namespace": "core.math.quat",
-    "summary": "Read the primitive `{ x, y, z, w }` components of a quaternion handle.",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "QuatComponents"
+    "path": "core.io.import.terrain",
+    "namespace": "core.io.import",
+    "summary": "Import **site terrain** for a location — Mapbox topography (elevation + satellite/streets imagery, optional neighborhood buildings and parcels).",
+    "examplePrompts": [
+      "Import the site terrain for this location, about 500m across",
+      "Load the topography at 40.7128, -74.0060 for a 300 by 300 meter site",
+      "Bring in satellite terrain for the site with the surrounding buildings",
+      "Add site elevation for a 1km by 1km area at these coordinates\n\n# Example\n```ts\n// 300m × 300m site with elevation + satellite imagery.\nconst terrain = await snaptrude.core.io.import.terrain(\n40.7128,  // lat\n-74.006,  // lng\n300,      // width  (metres)\n300,      // length (metres)\ntrue,     // elevation\ntrue,     // satellite\n)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "TerrainHandle"
   },
   {
-    "path": "core.math.quat.conjugate",
-    "namespace": "core.math.quat",
-    "summary": "Conjugate.",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "QuatHandle"
+    "path": "core.io.job.getError",
+    "namespace": "core.io.job",
+    "summary": "The failure message if the job's status is `\"failed\"`; otherwise `null`.",
+    "examplePrompts": [
+      "Why did my DWG import fail?",
+      "What went wrong with the CAD import?",
+      "Show the error from the failed import job",
+      "Did the import error out, and why?\n\n# Example\n```ts\nconst job = await snaptrude.core.io.import.dwg(url, 1)\nif ((await snaptrude.core.io.job.getStatus(job)) === \"failed\") {\nconsole.error(await snaptrude.core.io.job.getError(job))\n}\n```"
+    ],
+    "argsType": "ImportJobHandle",
+    "resultType": "string | null"
   },
   {
-    "path": "core.math.quat.dot",
-    "namespace": "core.math.quat",
-    "summary": "Dot product.",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "number"
+    "path": "core.io.job.getResult",
+    "namespace": "core.io.job",
+    "summary": "The imported result once the job is complete — the placed {@linkcode UnderlayHandle}. Returns `null` while the job is still pending/processing or if it failed (check {@link PluginCoreIoJobApi.getError}).",
+    "examplePrompts": [
+      "Get the underlay from my finished DWG import",
+      "Give me the result of the CAD import job",
+      "Fetch the imported CAD sketch once it's ready",
+      "Return the handle for the completed import\n\n# Example\n```ts\nconst job = await snaptrude.core.io.import.dwg(url, 1)\nconst deadline = Date.now() + 5 * 60_000\nwhile (!(await snaptrude.core.io.job.isComplete(job))) {\nif (Date.now() > deadline) throw new Error(\"DWG import timed out\")\nawait new Promise((r) => setTimeout(r, 2000))\n}\n// DWG results are CAD underlays (CAD scaling isn't supported); manage them\n// via core.io.underlay.* (list / setOpacity / delete).\nconst cad = await snaptrude.core.io.job.getResult(job)\nif (cad) console.log(\"import complete:\", cad)\n```"
+    ],
+    "argsType": "ImportJobHandle",
+    "resultType": "UnderlayHandle | null"
   },
   {
-    "path": "core.math.quat.equals",
-    "namespace": "core.math.quat",
-    "summary": "Exact component equality.",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "boolean"
+    "path": "core.io.job.getStatus",
+    "namespace": "core.io.job",
+    "summary": "Read a job's current status: `\"pending\"` (queued), `\"processing\"` (running), `\"complete\"` (result ready), or `\"failed\"`.",
+    "examplePrompts": [
+      "What's the status of my DWG import?",
+      "Is the CAD import still processing?",
+      "Check where the import job is up to",
+      "Did the import job fail?\n\n# Example\n```ts\nconst job = await snaptrude.core.io.import.dwg(url, 1)\nconsole.log(await snaptrude.core.io.job.getStatus(job)) // \"processing\"\n```"
+    ],
+    "argsType": "ImportJobHandle",
+    "resultType": "ImportJobStatus"
   },
   {
-    "path": "core.math.quat.equalsApprox",
-    "namespace": "core.math.quat",
-    "summary": "Approximate equality within `epsilon` (default `1e-6`).",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
+    "path": "core.io.job.isComplete",
+    "namespace": "core.io.job",
+    "summary": "Whether the job has finished successfully (status is `\"complete\"` and a result is ready). Returns `false` while pending/processing and on failure.",
+    "examplePrompts": [
+      "Is the DWG import done yet?",
+      "Has the CAD import finished?",
+      "Tell me when the import job completes",
+      "Is my import ready?\n\n# Example\n```ts\nconst job = await snaptrude.core.io.import.dwg(url, 1)\nconst deadline = Date.now() + 5 * 60_000 // cap the poll — see getStatus limitation\nwhile (!(await snaptrude.core.io.job.isComplete(job))) {\nif (Date.now() > deadline) throw new Error(\"DWG import timed out\")\nawait new Promise((r) => setTimeout(r, 2000))\n}\n```"
+    ],
+    "argsType": "ImportJobHandle",
     "resultType": "boolean"
   },
   {
-    "path": "core.math.quat.fromAxisAngle",
-    "namespace": "core.math.quat",
-    "summary": "Build from a rotation axis and angle (radians).",
-    "examplePrompts": [],
-    "argsType": "Vec3Handle",
-    "resultType": "QuatHandle"
+    "path": "core.io.query.getPdfPageCount",
+    "namespace": "core.io.query",
+    "summary": "Count the pages of a PDF without importing it. `null` if the source can't be read as a PDF.",
+    "examplePrompts": [
+      "How many pages does this PDF have?",
+      "Count the pages in the drawing set before importing",
+      "Get the PDF page count",
+      "Is this a multi-page PDF, and how many?\n\n# Example\n```ts\nconst pages = await snaptrude.core.io.query.getPdfPageCount(url)\nfor (let p = 1; p <= (pages ?? 0); p++) {\nawait snaptrude.core.io.import.pdf(url, p, p) // one page per storey\n}\n```"
+    ],
+    "argsType": "string",
+    "resultType": "number | null"
   },
   {
-    "path": "core.math.quat.fromEuler",
-    "namespace": "core.math.quat",
-    "summary": "Build from Euler angles (radians).",
-    "examplePrompts": [],
-    "argsType": "number",
-    "resultType": "QuatHandle"
+    "path": "core.io.query.listCadLayers",
+    "namespace": "core.io.query",
+    "summary": "List the distinct CAD layer names tagged on a parsed CAD JSON's entities. Read-only inspection: imports always bring in **every** layer (there is no layer filter on {@link core.io.import.dwg} / {@link core.io.import.cadJson}) — use the names to decide whether to import at all, or what to tell the user.",
+    "examplePrompts": [
+      "What CAD layers are in this drawing?",
+      "List the layers before importing the CAD",
+      "Show the DWG layer names so I can pick which to import",
+      "Enumerate the CAD JSON layers\n\n# Example\n```ts\nconst layers = await snaptrude.core.io.query.listCadLayers(cad)\nif (layers.some((l) => l.toUpperCase().includes(\"WALL\"))) {\nawait snaptrude.core.io.import.cadJson(cad, 1) // all layers import together\n}\n```"
+    ],
+    "argsType": "CadJsonInput",
+    "resultType": "string[]"
   },
   {
-    "path": "core.math.quat.identity",
-    "namespace": "core.math.quat",
-    "summary": "The identity rotation.",
-    "examplePrompts": [],
+    "path": "core.io.terrain.delete",
+    "namespace": "core.io.terrain",
+    "summary": "Delete the site terrain. Undoable.",
+    "examplePrompts": [
+      "Delete the site terrain",
+      "Remove the topography",
+      "Clear the imported site",
+      "Get rid of the terrain"
+    ],
     "argsType": null,
-    "resultType": "QuatHandle"
+    "resultType": "void"
   },
   {
-    "path": "core.math.quat.inverse",
-    "namespace": "core.math.quat",
-    "summary": "Inverse rotation.",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "QuatHandle"
+    "path": "core.io.terrain.disableElevation",
+    "namespace": "core.io.terrain",
+    "summary": "Turn terrain elevation OFF — flatten to a plane. Undoable.",
+    "examplePrompts": [
+      "Flatten the terrain",
+      "Turn off site elevation",
+      "Disable the heightmap",
+      "Make the terrain flat"
+    ],
+    "argsType": null,
+    "resultType": "void"
   },
   {
-    "path": "core.math.quat.length",
-    "namespace": "core.math.quat",
-    "summary": "Magnitude.",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "number"
+    "path": "core.io.terrain.disableSatellite",
+    "namespace": "core.io.terrain",
+    "summary": "Turn satellite imagery OFF. Undoable.",
+    "examplePrompts": [
+      "Hide the satellite imagery",
+      "Turn off the aerial texture",
+      "Disable satellite on the site",
+      "Remove the satellite drape"
+    ],
+    "argsType": null,
+    "resultType": "void"
   },
   {
-    "path": "core.math.quat.multiply",
-    "namespace": "core.math.quat",
-    "summary": "Hamilton product `a * b` (apply `b` then `a`).",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "QuatHandle"
+    "path": "core.io.terrain.enableElevation",
+    "namespace": "core.io.terrain",
+    "summary": "Turn terrain elevation (DEM height) ON — a real 3D topography surface. Undoable.",
+    "examplePrompts": [
+      "Turn on terrain elevation",
+      "Enable the site heightmap",
+      "Make the terrain 3D",
+      "Show the topography relief"
+    ],
+    "argsType": null,
+    "resultType": "void"
   },
   {
-    "path": "core.math.quat.new",
-    "namespace": "core.math.quat",
-    "summary": "Create a quaternion from primitive components.",
-    "examplePrompts": [],
-    "argsType": "number",
-    "resultType": "QuatHandle"
+    "path": "core.io.terrain.enableSatellite",
+    "namespace": "core.io.terrain",
+    "summary": "Turn satellite imagery ON. Undoable.",
+    "examplePrompts": [
+      "Show satellite imagery on the site",
+      "Enable the satellite texture",
+      "Turn on aerial imagery",
+      "Drape satellite over the terrain"
+    ],
+    "argsType": null,
+    "resultType": "void"
   },
   {
-    "path": "core.math.quat.normalize",
-    "namespace": "core.math.quat",
-    "summary": "Unit quaternion.",
-    "examplePrompts": [],
-    "argsType": "QuatHandle",
-    "resultType": "QuatHandle"
+    "path": "core.io.terrain.exists",
+    "namespace": "core.io.terrain",
+    "summary": "Whether the project has a site terrain.",
+    "examplePrompts": [
+      "Does this project have site terrain?",
+      "Is there a terrain imported?",
+      "Check if the site topography exists",
+      "Has a terrain been added yet?\n\n# Example\n```ts\nif (!(await snaptrude.core.io.terrain.exists())) {\nawait snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)\n}\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
   },
   {
-    "path": "core.math.quat.slerp",
-    "namespace": "core.math.quat",
-    "summary": "Spherical linear interpolation.",
+    "path": "core.io.terrain.get",
+    "namespace": "core.io.terrain",
+    "summary": "Resolve the project's terrain handle, or `null` if there is none. The same handle {@link core.io.import.terrain} returns — use it to obtain the handle without re-importing.",
+    "examplePrompts": [
+      "Get the terrain handle",
+      "Give me the site terrain",
+      "Fetch the current terrain",
+      "Return the topography handle if it exists"
+    ],
+    "argsType": null,
+    "resultType": "TerrainHandle | null"
+  },
+  {
+    "path": "core.io.terrain.getDatum",
+    "namespace": "core.io.terrain",
+    "summary": "Read the terrain's current vertical position (world Y, internal units). `null` if there is no terrain. Import places the terrain so its highest point sits at `y = 0`, so a never-shifted terrain reads a negative baseline, not `0`; each {@link PluginCoreIoTerrainApi.setDatum} shift moves this value.",
+    "examplePrompts": [
+      "What's the terrain's datum?",
+      "Read the current site elevation reference",
+      "Get the terrain vertical offset",
+      "How far has the datum been shifted?"
+    ],
+    "argsType": null,
+    "resultType": "number | null"
+  },
+  {
+    "path": "core.io.terrain.getOpacity",
+    "namespace": "core.io.terrain",
+    "summary": "Read the terrain opacity, `0`..`1`, or `null` if no terrain.",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "number | null"
+  },
+  {
+    "path": "core.io.terrain.getReport",
+    "namespace": "core.io.terrain",
+    "summary": "The terrain cut/fill earthwork report — cut, fill, and net volumes — or `null` if there is no terrain.",
+    "examplePrompts": [
+      "What are the cut and fill volumes for the site?",
+      "Get the terrain earthwork report",
+      "How much cut and fill does the grading need?",
+      "Show the net volume of the terrain edits\n\n# Example\n```ts\nconst r = await snaptrude.core.io.terrain.getReport()\nif (r) console.log(`cut ${r.cutVolume}, fill ${r.fillVolume}, net ${r.netVolume}`)\n```"
+    ],
+    "argsType": null,
+    "resultType": "TerrainReport | null"
+  },
+  {
+    "path": "core.io.terrain.isElevationEnabled",
+    "namespace": "core.io.terrain",
+    "summary": "Whether terrain elevation (DEM height) is on. `null` if no terrain.",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "boolean | null"
+  },
+  {
+    "path": "core.io.terrain.isSatelliteEnabled",
+    "namespace": "core.io.terrain",
+    "summary": "Whether satellite imagery is draped on the terrain. `null` if no terrain.",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "boolean | null"
+  },
+  {
+    "path": "core.io.terrain.setDatum",
+    "namespace": "core.io.terrain",
+    "summary": "Shift the terrain's **datum** — move the whole terrain vertically DOWN by `offset` (internal units) from its current position; pass a negative value to raise it. Undoable.",
+    "examplePrompts": [
+      "Shift the terrain datum down by 12",
+      "Lower the site terrain by 10",
+      "Raise the terrain a little",
+      "Nudge the terrain datum down\n\n# Example\n```ts\nawait snaptrude.core.io.terrain.setDatum(12)   // shift terrain down by 12 (relative)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "void"
+  },
+  {
+    "path": "core.io.terrain.setOpacity",
+    "namespace": "core.io.terrain",
+    "summary": "Set the terrain opacity (`0` transparent .. `1` opaque). Undoable.",
+    "examplePrompts": [
+      "Fade the terrain to 50%",
+      "Make the site semi-transparent",
+      "Set terrain opacity to 0.3",
+      "Dim the topography\n\n# Example\n```ts\nawait snaptrude.core.io.terrain.setOpacity(0.5)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "void"
+  },
+  {
+    "path": "core.io.underlay.delete",
+    "namespace": "core.io.underlay",
+    "summary": "Delete an underlay from the scene (and its backend record). Applies to image, PDF, and CAD underlays.",
+    "examplePrompts": [
+      "Delete this floor plan underlay",
+      "Remove the imported PDF from the scene",
+      "Get rid of the CAD sketch I traced over",
+      "Clear the reference image off storey 1\n\n# Example\n```ts\nconst [first] = await snaptrude.core.io.underlay.list(1)\nif (first) await snaptrude.core.io.underlay.delete(first)\n```"
+    ],
+    "argsType": "UnderlayHandle",
+    "resultType": "void"
+  },
+  {
+    "path": "core.io.underlay.getBounds",
+    "namespace": "core.io.underlay",
+    "summary": "Read an underlay's world-space bounding box (image, PDF, or CAD). `null` if the underlay no longer resolves or has no measurable mesh. Useful for fitting drawn geometry to a reference, or computing a plan size before scaling.",
+    "examplePrompts": [
+      "How big is this floor plan in the scene?",
+      "Get the bounding box of the underlay",
+      "What's the extent of the imported PDF?",
+      "Measure the CAD sketch's size\n\n# Example\n```ts\nconst bb = await snaptrude.core.io.underlay.getBounds(plan)\nif (bb) console.log(`width ${bb.max.x - bb.min.x}`)\n```"
+    ],
+    "argsType": "UnderlayHandle",
+    "resultType": "BBoxComponents | null"
+  },
+  {
+    "path": "core.io.underlay.getOpacity",
+    "namespace": "core.io.underlay",
+    "summary": "Read an underlay's opacity (`0`..`1`), or `null` if it has no material.",
+    "examplePrompts": [
+      "How transparent is this underlay?",
+      "Get the opacity of the floor plan",
+      "What's the fade level on the reference image?",
+      "Read the underlay's opacity\n\n# Example\n```ts\nconst o = await snaptrude.core.io.underlay.getOpacity(plan)\n```"
+    ],
+    "argsType": "UnderlayHandle",
+    "resultType": "number | null"
+  },
+  {
+    "path": "core.io.underlay.getScale",
+    "namespace": "core.io.underlay",
+    "summary": "Read an underlay's scale. Works for **image and PDF** underlays. Returns `null` for CAD (scaling not supported) or if the handle no longer resolves.",
+    "examplePrompts": [
+      "What scale is this floor plan set to?",
+      "Get the current and original scale of the underlay",
+      "How much has this image been scaled since import?",
+      "Read the scale factor of the reference plan\n\n# Example\n```ts\nconst s = await snaptrude.core.io.underlay.getScale(plan)\nif (s) console.log(`scale ${s.scaleFactor} (was ${s.initialScaleFactor})`)\n```"
+    ],
+    "argsType": "UnderlayHandle",
+    "resultType": "{ scaleFactor: number; initialScaleFactor: number } | null"
+  },
+  {
+    "path": "core.io.underlay.list",
+    "namespace": "core.io.underlay",
+    "summary": "List the underlays in the scene, optionally limited to one storey.",
+    "examplePrompts": [
+      "List all the reference underlays in the model",
+      "What underlays are on the ground floor?",
+      "Show every imported floor plan and PDF",
+      "How many trace-over images are on storey 2?\n\n# Example\n```ts\nconst underlays = await snaptrude.core.io.underlay.list(1)\nconsole.log(`${underlays.length} underlays on storey 1`)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "UnderlayHandle[]"
+  },
+  {
+    "path": "core.io.underlay.resetScale",
+    "namespace": "core.io.underlay",
+    "summary": "Reset an underlay's scale back to its import-time size (image or PDF; CAD scaling is not supported — throws). Equivalent to `setScale(underlay, 1)`.",
+    "examplePrompts": [
+      "Reset this floor plan's scale to how it was imported",
+      "Undo the scaling on the underlay",
+      "Put the reference image back to its original size",
+      "Restore the plan's default scale\n\n# Example\n```ts\nawait snaptrude.core.io.underlay.resetScale(plan)\n```"
+    ],
+    "argsType": "UnderlayHandle",
+    "resultType": "{ scaleFactor: number }"
+  },
+  {
+    "path": "core.io.underlay.setOpacity",
+    "namespace": "core.io.underlay",
+    "summary": "Set an underlay's opacity (`0` = transparent .. `1` = opaque). Undoable. The engine keeps underlays faintly visible: values below `0.01` clamp to `0.01`, so `setOpacity(u, 0)` reads back as `0.01`, not `0`.",
+    "examplePrompts": [
+      "Fade this floor plan to 30% so I can see through it",
+      "Make the underlay half transparent",
+      "Set the reference image opacity to 0.2",
+      "Dim the trace-over plan\n\n# Example\n```ts\nawait snaptrude.core.io.underlay.setOpacity(plan, 0.3)\n```"
+    ],
+    "argsType": "UnderlayHandle",
+    "resultType": "void"
+  },
+  {
+    "path": "core.io.underlay.setScale",
+    "namespace": "core.io.underlay",
+    "summary": "Set an underlay's scale — the **calibration** step after import. Works for **image and PDF** underlays (CAD scaling is not supported — throws).",
+    "examplePrompts": [
+      "Scale this floor plan so it's 50 meters across",
+      "Set the plan size to 30m — it's imported too small",
+      "Make the reference image twice its imported size",
+      "Calibrate the PDF: the site is 120 meters long\n\n# Example\n```ts\n// Absolute factor — set the underlay to 2× its imported size:\nawait snaptrude.core.io.underlay.setScale(plan, 2)\n\n// Fit to a real-world size — make the plan's longest side 50 project-units:\nawait snaptrude.core.io.underlay.setScale(plan, { planSize: 50 })\n```"
+    ],
+    "argsType": "UnderlayHandle",
+    "resultType": "{ scaleFactor: number }"
+  },
+  {
+    "path": "core.layers.get",
+    "namespace": "core.layers",
+    "summary": "Get a single drawing layer by id.",
+    "examplePrompts": [
+      "Get the drawing layer with id ly_5",
+      "Is layer ly_5 hidden or locked?",
+      "Look up a single drawing layer by its id\n\n# Example\n```ts\nconst layer = await snaptrude.core.layers.get(\"ly_5\")\nif (layer) console.log(layer.name, layer.hidden, layer.locked)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreLayersGetResult"
+  },
+  {
+    "path": "core.layers.getActive",
+    "namespace": "core.layers",
+    "summary": "Get the active drawing layer of a storey.",
+    "examplePrompts": [
+      "Which drawing layer is active on this storey?",
+      "Get the current layer on storey st_2",
+      "What layer am I drawing on?\n\n# Example\n```ts\nconst active = await snaptrude.core.layers.getActive(\"st_2\")\nif (active) console.log(active.name)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreLayersGetActiveResult"
+  },
+  {
+    "path": "core.layers.list",
+    "namespace": "core.layers",
+    "summary": "List the drawing layers of a storey.",
+    "examplePrompts": [
+      "List the drawing layers on this storey",
+      "Show all the PDF underlays on storey st_2",
+      "What CAD layers are on the ground floor?\n\n# Example\n```ts\nconst { layers } = await snaptrude.core.layers.list(\"st_2\")\nfor (const l of layers) console.log(l.name, l.layerType, l.hidden)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreLayersListResult"
+  },
+  {
+    "path": "core.layers.setActive",
+    "namespace": "core.layers",
+    "summary": "Make a drawing layer the active layer of its storey.",
+    "examplePrompts": [
+      "Draw on layer ly_5",
+      "Make this the active layer",
+      "Switch the active layer to the CAD underlay\n\n# Example\n```ts\nawait snaptrude.core.layers.setActive(\"ly_5\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreLayersSetActiveResult"
+  },
+  {
+    "path": "core.layers.update",
+    "namespace": "core.layers",
+    "summary": "Update a drawing layer's visibility.",
+    "examplePrompts": [
+      "Hide the PDF underlay layer",
+      "Show the CAD layer again",
+      "Hide layer ly_5\n\n# Example\n```ts\nconst layer = await snaptrude.core.layers.update(\"ly_5\", true)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreLayersUpdateResult"
+  },
+  {
+    "path": "core.math.quat.components",
+    "namespace": "core.math.quat",
+    "summary": "Read the primitive `{ x, y, z, w }` components of a quaternion handle.",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "QuatComponents"
+  },
+  {
+    "path": "core.math.quat.conjugate",
+    "namespace": "core.math.quat",
+    "summary": "Compute the conjugate of a quaternion (negated vector part).",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.dot",
+    "namespace": "core.math.quat",
+    "summary": "Compute the dot product of two quaternions.",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "number"
+  },
+  {
+    "path": "core.math.quat.equals",
+    "namespace": "core.math.quat",
+    "summary": "Test whether two quaternions have exactly equal components.",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "boolean"
+  },
+  {
+    "path": "core.math.quat.equalsApprox",
+    "namespace": "core.math.quat",
+    "summary": "Test whether two quaternions are equal within a tolerance `epsilon` (default `1e-6`).",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "boolean"
+  },
+  {
+    "path": "core.math.quat.fromAxisAngle",
+    "namespace": "core.math.quat",
+    "summary": "Build a quaternion from a rotation axis and an angle in radians.",
+    "examplePrompts": [],
+    "argsType": "Vec3Handle",
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.fromEuler",
+    "namespace": "core.math.quat",
+    "summary": "Build a quaternion from Euler angles in radians.",
+    "examplePrompts": [],
+    "argsType": "number",
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.identity",
+    "namespace": "core.math.quat",
+    "summary": "Return the identity quaternion (no rotation).",
+    "examplePrompts": [],
+    "argsType": null,
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.inverse",
+    "namespace": "core.math.quat",
+    "summary": "Compute the inverse quaternion — the rotation that undoes `q`.",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.length",
+    "namespace": "core.math.quat",
+    "summary": "Compute the magnitude (norm) of a quaternion.",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "number"
+  },
+  {
+    "path": "core.math.quat.multiply",
+    "namespace": "core.math.quat",
+    "summary": "Compose two rotations with the Hamilton product `a * b` (apply `b` then `a`).",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.new",
+    "namespace": "core.math.quat",
+    "summary": "Create a quaternion from primitive components.",
+    "examplePrompts": [],
+    "argsType": "number",
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.normalize",
+    "namespace": "core.math.quat",
+    "summary": "Normalize a quaternion to unit length.",
+    "examplePrompts": [],
+    "argsType": "QuatHandle",
+    "resultType": "QuatHandle"
+  },
+  {
+    "path": "core.math.quat.slerp",
+    "namespace": "core.math.quat",
+    "summary": "Spherically interpolate (slerp) between two rotations by factor `t`.",
     "examplePrompts": [],
     "argsType": "QuatHandle",
     "resultType": "QuatHandle"
@@ -1727,7 +2650,7 @@
   {
     "path": "core.math.quat.toAxisAngle",
     "namespace": "core.math.quat",
-    "summary": "Decompose into axis + angle.",
+    "summary": "Decompose a quaternion into its rotation axis and angle (radians).",
     "examplePrompts": [],
     "argsType": "QuatHandle",
     "resultType": "{ axis: Vec3Handle; angle: number }"
@@ -1735,7 +2658,7 @@
   {
     "path": "core.math.vec3.add",
     "namespace": "core.math.vec3",
-    "summary": "Component-wise sum `a + b`.",
+    "summary": "Add two vectors component-wise (`a + b`).",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "Vec3Handle"
@@ -1751,7 +2674,7 @@
   {
     "path": "core.math.vec3.cross",
     "namespace": "core.math.vec3",
-    "summary": "Cross product `a × b`.",
+    "summary": "Compute the cross product `a × b` — the vector perpendicular to both.",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "Vec3Handle"
@@ -1759,15 +2682,18 @@
   {
     "path": "core.math.vec3.distance",
     "namespace": "core.math.vec3",
-    "summary": "Euclidean distance between two points.",
-    "examplePrompts": [],
+    "summary": "Measure the straight-line (Euclidean) distance between two points.",
+    "examplePrompts": [
+      "What is the distance between these two points?",
+      "Measure how far apart these two points are\n\n# Example\n```ts\nconst a = await snaptrude.core.math.vec3.new(0, 0, 0)\nconst b = await snaptrude.core.math.vec3.new(3, 4, 0)\nconst dist = await snaptrude.core.math.vec3.distance(a, b) // 5\n```"
+    ],
     "argsType": "Vec3Handle",
     "resultType": "number"
   },
   {
     "path": "core.math.vec3.dot",
     "namespace": "core.math.vec3",
-    "summary": "Dot product.",
+    "summary": "Compute the dot product of two vectors.",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "number"
@@ -1775,7 +2701,7 @@
   {
     "path": "core.math.vec3.equals",
     "namespace": "core.math.vec3",
-    "summary": "Exact component equality.",
+    "summary": "Test whether two vectors have exactly equal components.",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "boolean"
@@ -1783,7 +2709,7 @@
   {
     "path": "core.math.vec3.equalsApprox",
     "namespace": "core.math.vec3",
-    "summary": "Approximate equality within `epsilon` (default `1e-6`).",
+    "summary": "Test whether two vectors are equal within a tolerance `epsilon` (default `1e-6`).",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "boolean"
@@ -1791,7 +2717,7 @@
   {
     "path": "core.math.vec3.length",
     "namespace": "core.math.vec3",
-    "summary": "Euclidean length.",
+    "summary": "Compute the Euclidean length (magnitude) of a vector.",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "number"
@@ -1799,7 +2725,7 @@
   {
     "path": "core.math.vec3.lengthSquared",
     "namespace": "core.math.vec3",
-    "summary": "Squared length (avoids the sqrt).",
+    "summary": "Compute the squared Euclidean length of a vector (avoids the sqrt).",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "number"
@@ -1807,7 +2733,7 @@
   {
     "path": "core.math.vec3.lerp",
     "namespace": "core.math.vec3",
-    "summary": "Linear interpolation `a + (b - a) * t`.",
+    "summary": "Linearly interpolate between two vectors: `a + (b - a) * t`.",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "Vec3Handle"
@@ -1815,7 +2741,7 @@
   {
     "path": "core.math.vec3.negate",
     "namespace": "core.math.vec3",
-    "summary": "Negate (reverse direction).",
+    "summary": "Negate a vector, reversing its direction.",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "Vec3Handle"
@@ -1831,7 +2757,7 @@
   {
     "path": "core.math.vec3.normalize",
     "namespace": "core.math.vec3",
-    "summary": "Unit vector in the same direction (zero vector if length 0).",
+    "summary": "Return the unit vector in the same direction (the zero vector if length is 0).",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "Vec3Handle"
@@ -1847,7 +2773,7 @@
   {
     "path": "core.math.vec3.subtract",
     "namespace": "core.math.vec3",
-    "summary": "Component-wise difference `a - b`.",
+    "summary": "Subtract vector `b` from `a` component-wise (`a - b`).",
     "examplePrompts": [],
     "argsType": "Vec3Handle",
     "resultType": "Vec3Handle"
@@ -1856,39 +2782,64 @@
     "path": "core.project.settings.getTolerance",
     "namespace": "core.project.settings",
     "summary": "Get the project tolerance as a numeric magnitude.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the tolerance setting in this project?",
+      "Check the current dimension precision of the model",
+      "How precise are the measurements in this project?",
+      "Show me the project's tolerance value\n\n# Example\n```ts\nconst tolerance = await snaptrude.core.project.settings.getTolerance()\nconsole.log(tolerance) // e.g. 0.01\n```"
+    ],
     "argsType": null,
     "resultType": "number"
   },
   {
     "path": "core.project.settings.grid.disable",
     "namespace": "core.project.settings.grid",
-    "summary": "Turn the grid off.",
-    "examplePrompts": [],
+    "summary": "Turn the grid off, hiding the visual snap-to grid in the canvas.",
+    "examplePrompts": [
+      "Turn off the grid",
+      "Hide the grid",
+      "Disable the background grid in the canvas",
+      "Remove the drawing grid from view\n\n# Example\n```ts\nawait snaptrude.core.project.settings.grid.disable()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.grid.enable",
     "namespace": "core.project.settings.grid",
-    "summary": "Turn the grid on.",
-    "examplePrompts": [],
+    "summary": "Turn the grid on, showing the visual snap-to grid in the canvas.",
+    "examplePrompts": [
+      "Turn on the grid",
+      "Show the grid in my project",
+      "Enable the drawing grid",
+      "Switch the snap grid back on\n\n# Example\n```ts\nawait snaptrude.core.project.settings.grid.enable()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.grid.getValue",
     "namespace": "core.project.settings.grid",
-    "summary": "Get the grid cell value.",
-    "examplePrompts": [],
+    "summary": "Get the current grid cell value — the size of each cell in the visual snap-to grid.",
+    "examplePrompts": [
+      "What is the grid spacing?",
+      "Check the current grid cell size",
+      "How big are the grid squares?",
+      "Show me the grid size setting\n\n# Example\n```ts\nconst cellSize = await snaptrude.core.project.settings.grid.getValue()\nconsole.log(cellSize)\n```"
+    ],
     "argsType": null,
     "resultType": "number"
   },
   {
     "path": "core.project.settings.grid.setValue",
     "namespace": "core.project.settings.grid",
-    "summary": "Set the grid cell value.",
-    "examplePrompts": [],
+    "summary": "Set the grid cell value — the size of each cell in the visual snap-to grid.",
+    "examplePrompts": [
+      "Set the grid spacing to 1 metre",
+      "Change the grid cell size to 500mm",
+      "Make the grid squares 2 feet wide",
+      "Adjust the grid size in this project\n\n# Example\n```ts\nawait snaptrude.core.project.settings.grid.setValue(1)\nawait snaptrude.core.project.settings.grid.enable()\n```"
+    ],
     "argsType": "number",
     "resultType": "boolean"
   },
@@ -1896,122 +2847,305 @@
     "path": "core.project.settings.setTolerance",
     "namespace": "core.project.settings",
     "summary": "Set the project tolerance. The value snaps to the **nearest allowed** per-unit precision option (tolerance is a discrete dropdown, not arbitrary).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Set the project tolerance to 0.01",
+      "Change the dimension precision to two decimal places",
+      "Round dimensions to the nearest quarter inch",
+      "Make the measurements in this project more precise\n\n# Example\n```ts\n// snaps to the nearest allowed precision option\nconst applied = await snaptrude.core.project.settings.setTolerance(0.01)\nif (!applied) console.log(\"no tolerance options available\")\n```"
+    ],
     "argsType": "number",
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.disableAngle",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn angle snapping off.",
-    "examplePrompts": [],
+    "summary": "Turn angle snapping off, so lines can be drawn at any angle without snapping to fixed increments.",
+    "examplePrompts": [
+      "Turn off angle snapping",
+      "Stop lines snapping to fixed angles",
+      "Disable the angle snap so I can draw at any angle",
+      "Remove angle snapping while sketching\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.disableAngle()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.disableDimension",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn dimension snapping off.",
-    "examplePrompts": [],
+    "summary": "Turn dimension snapping off, so lengths no longer snap to the configured increment while drawing.",
+    "examplePrompts": [
+      "Turn off dimension snapping",
+      "Stop snapping to fixed lengths when I draw",
+      "Disable the length snap so I can draw freely",
+      "I don't want dimensions to snap anymore\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.disableDimension()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.disableMagnetic",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn magnetic snapping off.",
-    "examplePrompts": [],
+    "summary": "Turn magnetic snapping off, so the cursor is no longer pulled to nearby geometry while drawing.",
+    "examplePrompts": [
+      "Turn off magnetic snapping",
+      "Disable the magnet snap",
+      "Stop the cursor sticking to nearby objects",
+      "The magnetic snap is annoying, switch it off\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.disableMagnetic()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.disableNormal",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn normal (perpendicular) snapping off.",
-    "examplePrompts": [],
+    "summary": "Turn normal (perpendicular) snapping off, so drawing no longer snaps at right angles to existing edges.",
+    "examplePrompts": [
+      "Turn off perpendicular snapping",
+      "Disable the normal snap",
+      "Stop snapping at right angles to edges",
+      "Remove the 90 degree snap guide\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.disableNormal()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.disableParallel",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn parallel snapping off.",
-    "examplePrompts": [],
+    "summary": "Turn parallel snapping off, so drawing no longer snaps to directions parallel to existing edges.",
+    "examplePrompts": [
+      "Turn off parallel snapping",
+      "Stop snapping to parallel edges",
+      "Disable the parallel snap guide",
+      "I don't want my lines snapping parallel anymore\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.disableParallel()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.enableAngle",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn angle snapping on.",
-    "examplePrompts": [],
+    "summary": "Turn angle snapping on, so drawn lines snap to the configured angle increment.",
+    "examplePrompts": [
+      "Turn on angle snapping",
+      "Enable snapping to angles while drawing",
+      "Make my lines snap to set angles",
+      "Switch angle snap back on\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.enableAngle()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.enableDimension",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn dimension snapping on.",
-    "examplePrompts": [],
+    "summary": "Turn dimension snapping on, so drawing and editing snap to the configured length increment.",
+    "examplePrompts": [
+      "Turn on dimension snapping",
+      "Enable snapping to set lengths while I draw",
+      "Make my walls snap to round dimensions",
+      "Switch length snapping back on\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.enableDimension()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.enableMagnetic",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn magnetic snapping on.",
-    "examplePrompts": [],
+    "summary": "Turn magnetic snapping on, so the cursor is pulled to nearby geometry while drawing.",
+    "examplePrompts": [
+      "Turn on magnetic snapping",
+      "Enable the magnet snap",
+      "Make the cursor stick to nearby geometry when drawing",
+      "Switch magnetic snap back on\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.enableMagnetic()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.enableNormal",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn normal (perpendicular) snapping on.",
-    "examplePrompts": [],
+    "summary": "Turn normal (perpendicular) snapping on, so drawing snaps when the cursor is at a right angle to existing edges.",
+    "examplePrompts": [
+      "Turn on perpendicular snapping",
+      "Enable the normal snap so lines snap at right angles",
+      "Snap to perpendicular when I draw walls",
+      "Help me draw at 90 degrees to existing edges\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.enableNormal()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.enableParallel",
     "namespace": "core.project.settings.snaps",
-    "summary": "Turn parallel snapping on.",
-    "examplePrompts": [],
+    "summary": "Turn parallel snapping on, so drawing snaps when the cursor lines up parallel to existing edges.",
+    "examplePrompts": [
+      "Turn on parallel snapping",
+      "Enable snapping to parallel lines",
+      "Help me draw walls parallel to existing ones",
+      "Snap to parallel edges when drawing\n\n# Example\n```ts\nawait snaptrude.core.project.settings.snaps.enableParallel()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.getAngle",
     "namespace": "core.project.settings.snaps",
-    "summary": "Get the angle-snap threshold (degrees).",
-    "examplePrompts": [],
+    "summary": "Get the current angle-snap threshold in degrees — the angular increment that drawing snaps to when angle snapping is on.",
+    "examplePrompts": [
+      "What angle does drawing snap to?",
+      "Check the current angle snap in degrees",
+      "Show me the angle snapping increment",
+      "How many degrees is the angle snap set to?\n\n# Example\n```ts\nconst degrees = await snaptrude.core.project.settings.snaps.getAngle()\nconsole.log(degrees)\n```"
+    ],
     "argsType": null,
     "resultType": "number"
   },
   {
     "path": "core.project.settings.snaps.getDimension",
     "namespace": "core.project.settings.snaps",
-    "summary": "Get the dimension-snap threshold.",
-    "examplePrompts": [],
+    "summary": "Get the current dimension-snap threshold — the length increment that drawing and editing snap to when dimension snapping is on.",
+    "examplePrompts": [
+      "What is the dimension snap distance?",
+      "Check the current snap increment for drawing",
+      "How far apart are the length snaps set?",
+      "Show me the snap spacing value\n\n# Example\n```ts\nconst increment = await snaptrude.core.project.settings.snaps.getDimension()\nconsole.log(increment)\n```"
+    ],
     "argsType": null,
     "resultType": "number"
   },
   {
     "path": "core.project.settings.snaps.setAngle",
     "namespace": "core.project.settings.snaps",
-    "summary": "Set the angle-snap threshold (degrees).",
-    "examplePrompts": [],
+    "summary": "Set the angle-snap threshold in degrees — the angular increment that drawing snaps to when angle snapping is on.",
+    "examplePrompts": [
+      "Set the angle snap to 15 degrees",
+      "Change angle snapping to every 45 degrees",
+      "Make drawing snap at 30 degree increments",
+      "Adjust the rotation snap angle\n\n# Example\n```ts\n// snap drawing to 15-degree increments (applies while angle snapping is on)\nawait snaptrude.core.project.settings.snaps.setAngle(15)\nawait snaptrude.core.project.settings.snaps.enableAngle()\n```"
+    ],
     "argsType": "number",
     "resultType": "boolean"
   },
   {
     "path": "core.project.settings.snaps.setDimension",
     "namespace": "core.project.settings.snaps",
-    "summary": "Set the dimension-snap threshold.",
-    "examplePrompts": [],
+    "summary": "Set the dimension-snap threshold — the length increment that drawing and editing snap to when dimension snapping is on.",
+    "examplePrompts": [
+      "Set the dimension snap to 100mm",
+      "Change the snap distance to half a metre",
+      "Make the cursor snap every 6 inches when drawing",
+      "Adjust the snapping increment for lengths\n\n# Example\n```ts\n// the threshold only applies while dimension snapping is on\nawait snaptrude.core.project.settings.snaps.setDimension(100)\nawait snaptrude.core.project.settings.snaps.enableDimension()\n```"
+    ],
     "argsType": "number",
     "resultType": "boolean"
   },
+  {
+    "path": "core.proposals.create",
+    "namespace": "core.proposals",
+    "summary": "Create a new design option (proposal).",
+    "examplePrompts": [
+      "Create a design option called Scheme B",
+      "Add a new proposal named Option 2",
+      "Make a fresh design variant to explore\n\n# Example\n```ts\nconst { id } = await snaptrude.core.proposals.create(\"Scheme B\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsCreateResult"
+  },
+  {
+    "path": "core.proposals.delete",
+    "namespace": "core.proposals",
+    "summary": "Delete a proposal.",
+    "examplePrompts": [
+      "Delete proposal prop_2 and everything in it",
+      "Remove this design option and destroy its geometry",
+      "Merge prop_2's layers into prop_1 and delete prop_2\n\n# Example\n```ts\n// destroy the proposal and its exclusive geometry\nawait snaptrude.core.proposals.delete(\"prop_2\", { deleteObjects: true })\n// …or keep the geometry by transferring its buckets to prop_1 first\nawait snaptrude.core.proposals.delete(\"prop_2\", { targetProposalId: \"prop_1\" })\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsDeleteResult"
+  },
+  {
+    "path": "core.proposals.get",
+    "namespace": "core.proposals",
+    "summary": "Get a single proposal by id.",
+    "examplePrompts": [
+      "Get the proposal with id prop_1",
+      "Look up a single design option by its id",
+      "Which buckets belong to proposal prop_2?\n\n# Example\n```ts\nconst proposal = await snaptrude.core.proposals.get(\"prop_1\")\nif (proposal) console.log(proposal.name, proposal.bucketIds)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsGetResult"
+  },
+  {
+    "path": "core.proposals.getActive",
+    "namespace": "core.proposals",
+    "summary": "Get the active proposal.",
+    "examplePrompts": [
+      "Which design option is active?",
+      "Get the current proposal",
+      "What proposal am I working in?\n\n# Example\n```ts\nconst active = await snaptrude.core.proposals.getActive()\nif (active) console.log(active.id, active.name)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCoreProposalsGetActiveResult"
+  },
+  {
+    "path": "core.proposals.isActive",
+    "namespace": "core.proposals",
+    "summary": "Test whether a proposal is the active one.",
+    "examplePrompts": [
+      "Is proposal prop_2 the active one?",
+      "Check whether this design option is currently shown",
+      "Am I working in proposal prop_1?\n\n# Example\n```ts\nif (await snaptrude.core.proposals.isActive(\"prop_1\")) {\nconsole.log(\"prop_1 is active\")\n}\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "core.proposals.list",
+    "namespace": "core.proposals",
+    "summary": "List the design options (proposals) in the active project.",
+    "examplePrompts": [
+      "List all the design options in this project",
+      "How many proposals does this project have?",
+      "Show every design variant with its name\n\n# Example\n```ts\nconst { proposals } = await snaptrude.core.proposals.list()\nfor (const p of proposals) console.log(p.id, p.name, p.isActive)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCoreProposalsListResult"
+  },
+  {
+    "path": "core.proposals.listForComponent",
+    "namespace": "core.proposals",
+    "summary": "List the proposals a component belongs to.",
+    "examplePrompts": [
+      "Which design options is this component part of?",
+      "List the proposals that contain this wall",
+      "Is this element shared across multiple design variants?\n\n# Example\n```ts\nconst { proposals } = await snaptrude.core.proposals.listForComponent(wall)\nconsole.log(`shared across ${proposals.length} proposals`)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginCoreProposalsListForComponentResult"
+  },
+  {
+    "path": "core.proposals.rename",
+    "namespace": "core.proposals",
+    "summary": "Rename a proposal.",
+    "examplePrompts": [
+      "Rename proposal prop_1 to Final Scheme",
+      "Change the name of this design option",
+      "Call proposal prop_2 \"Option A\"\n\n# Example\n```ts\nconst proposal = await snaptrude.core.proposals.rename(\"prop_1\", \"Final Scheme\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsRenameResult"
+  },
+  {
+    "path": "core.proposals.setActive",
+    "namespace": "core.proposals",
+    "summary": "Switch the active proposal.",
+    "examplePrompts": [
+      "Switch to proposal prop_2",
+      "Make Scheme B the active design option",
+      "Show me the other proposal\n\n# Example\n```ts\nawait snaptrude.core.proposals.setActive(\"prop_2\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCoreProposalsSetActiveResult"
+  },
   {
     "path": "core.tags.assign",
     "namespace": "core.tags",
@@ -2184,23 +3318,38 @@
     "path": "core.units.convert",
     "namespace": "core.units",
     "summary": "Convert a value between two unit types.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Convert 5 meters to feet and inches",
+      "How many millimetres is 12 feet?",
+      "Change this area from internal units to square metres",
+      "Turn 2500 mm into meters",
+      "Convert a volume value from babylon units to cubic feet\n\n# Example\n```ts\n// 5 meters → internal babylon units\nconst b = await snaptrude.core.units.convert(5, \"meters\", \"babylon\")\n// an internal area → square metres\nconst m2 = await snaptrude.core.units.convert(area, \"babylon\", \"meters\", 2)\n```"
+    ],
     "argsType": "number",
     "resultType": "number"
   },
   {
     "path": "core.units.getBabylonType",
     "namespace": "core.units",
-    "summary": "The internal storage unit type all geometry is stored in (`\"babylon\"`).",
-    "examplePrompts": [],
+    "summary": "Get the internal storage unit type that all geometry is kept in — always `\"babylon\"` — for use as one side of a {@linkcode PluginUnitsApi.convert} call.",
+    "examplePrompts": [
+      "What unit does Snaptrude store geometry in internally?",
+      "Get the internal babylon unit type",
+      "Which unit are raw model coordinates saved in?\n\n# Example\n```ts\nconst babylon = await snaptrude.core.units.getBabylonType() // \"babylon\"\nconst meters = await snaptrude.core.units.convert(10, babylon, \"meters\")\n```"
+    ],
     "argsType": null,
     "resultType": "PUnitType"
   },
   {
     "path": "core.units.getType",
     "namespace": "core.units",
-    "summary": "The current project's unit type. Paired with {@linkcode PluginUnitsApi.setType}.",
-    "examplePrompts": [],
+    "summary": "Get the current project's unit type — the unit lengths are displayed and entered in. Paired with {@linkcode PluginUnitsApi.setType}.",
+    "examplePrompts": [
+      "What units is this project using?",
+      "Are we working in metric or imperial?",
+      "Check the current measurement unit of the model",
+      "Is the file set to millimetres or feet and inches?\n\n# Example\n```ts\nconst type = await snaptrude.core.units.getType()\nconsole.log(type) // e.g. \"millimeters\"\n```"
+    ],
     "argsType": null,
     "resultType": "PUnitType"
   },
@@ -2208,7 +3357,12 @@
     "path": "core.units.listTypes",
     "namespace": "core.units",
     "summary": "List the selectable real-world unit types (excludes the internal `babylon` storage type, which is read via {@linkcode PluginUnitsApi.getBabylonType}).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What units can I use in this project?",
+      "List all the available measurement units",
+      "Which unit systems does Snaptrude support?",
+      "Show the unit options I could switch the model to\n\n# Example\n```ts\nconst types = await snaptrude.core.units.listTypes()\nconsole.log(types) // [\"meters\", \"feet-inches\", \"inches\", ...]\n```"
+    ],
     "argsType": null,
     "resultType": "PUnitType[]"
   },
@@ -2216,7 +3370,12 @@
     "path": "core.units.setType",
     "namespace": "core.units",
     "summary": "Set the current project's unit type. Paired with {@linkcode PluginUnitsApi.getType}.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Change the project units to millimeters",
+      "Switch this model to feet and inches",
+      "Set the working units to metric",
+      "Make the drawing use centimetres instead of meters\n\n# Example\n```ts\nawait snaptrude.core.units.setType(\"meters\")\n```"
+    ],
     "argsType": "PUnitType",
     "resultType": "boolean"
   },
@@ -2224,7 +3383,13 @@
     "path": "core.zoom.extents",
     "namespace": "core.zoom",
     "summary": "Zoom (fit) the camera to all geometry in the scene — the \"zoom extents\" action.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Zoom out so I can see the whole model",
+      "Fit everything in the view",
+      "Frame the entire building in the viewport",
+      "Do a zoom extents on the canvas",
+      "Show me the full scene\n\n# Example\n```ts\nawait snaptrude.core.zoom.extents()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
@@ -2232,31 +3397,53 @@
     "path": "core.zoom.selection",
     "namespace": "core.zoom",
     "summary": "Zoom (fit) the camera to the current selection.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Zoom in on what I have selected",
+      "Frame the selected walls in the view",
+      "Focus the camera on my current selection",
+      "Fit the view to the selected room\n\n# Example\n```ts\nawait snaptrude.core.zoom.selection()\n```"
+    ],
     "argsType": null,
     "resultType": "boolean"
   },
   {
     "path": "design.boolean.intersect",
     "namespace": "design.boolean",
-    "summary": "Keep only the overlap of the inputs (`A ∩ B`). Order-independent. HARD constraint: **EXACTLY 2** components (schema `.length(2)`; the engine also throws `MoreThan2ComponentsForIntersect` on >2).",
-    "examplePrompts": [],
+    "summary": "Keep only the overlapping volume of exactly two masses (`A ∩ B`) — a boolean (CSG) intersection that discards everything outside the shared region and commits the overlap as a single undoable step. Order-independent.",
+    "examplePrompts": [
+      "Keep only the part where these two masses overlap",
+      "Intersect the two selected volumes",
+      "Give me the common volume between the tower and the zoning envelope",
+      "Trim this mass down to just its overlap with the other one\n\n# Example\n```ts\n// Keep only the overlap of the tower and the zoning envelope (EXACTLY 2 inputs),\n// shifting the result mass 10 units in x via the optional offset\nconst [tower, envelope] = await snaptrude.design.query.listMasses()\nconst offset = await snaptrude.core.math.vec3.new(10, 0, 0)\nconst { created } = await snaptrude.design.boolean.intersect([tower, envelope], { offset })\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "BooleanOutcome"
   },
   {
     "path": "design.boolean.subtract",
     "namespace": "design.boolean",
-    "summary": "Subtract `tools` from `target` (`target − ⋃tools`). ORDER-SENSITIVE: the host seeds `[target, ...tools]`; index 0 is the arg brep, the rest are tool breps. `deleted` includes the target AND every tool; `created` is the remainder mass(es).",
-    "examplePrompts": [],
+    "summary": "Cut one or more tool masses out of a target mass (`target − ⋃tools`) — a boolean (CSG) subtraction that carves the tools' volume out of the target and commits the remainder as a single undoable step.",
+    "examplePrompts": [
+      "Cut this shape out of the bigger mass",
+      "Subtract the cylinder from the building volume",
+      "Punch an opening through this block using the small box",
+      "Carve the courtyard volume out of the main massing",
+      "Remove the overlapping part of mass B from mass A\n\n# Example\n```ts\n// Order matters: the first arg is the target, the array holds the tools\nconst [building, courtyard] = await snaptrude.design.selection.get()\nconst { created, deleted } = await snaptrude.design.boolean.subtract(building, [courtyard])\n// deleted includes the target AND every tool; created is the remainder\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "BooleanOutcome"
   },
   {
     "path": "design.boolean.union",
     "namespace": "design.boolean",
-    "summary": "Fuse ≥2 components into a single mass (`A ∪ B ∪ …`). Order-independent.",
-    "examplePrompts": [],
+    "summary": "Fuse two or more masses into a single combined mass (`A ∪ B ∪ …`) — a boolean (CSG) union that merges the adjacent or overlapping inputs into one solid, committed as a single undoable step. Order-independent.",
+    "examplePrompts": [
+      "Merge these two masses into one",
+      "Union the selected volumes into a single mass",
+      "Combine the overlapping rooms into one shape",
+      "Join the tower and podium blocks together",
+      "Fuse all the selected massing blocks into a single solid\n\n# Example\n```ts\n// Fuse the overlapping massing blocks on the ground storey into one solid\nconst masses = await snaptrude.design.query.listMasses({ storeys: [1] })\nconst { created, deleted } = await snaptrude.design.boolean.union(masses)\nconsole.log(\"created\", created.length, \"mass; consumed\", deleted.length)\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "BooleanOutcome"
   },
@@ -2264,7 +3451,12 @@
     "path": "design.create.beam",
     "namespace": "design.create",
     "summary": "Create a **beam** by extruding a cross-section contour along `direction` by `length`.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Add a beam spanning 6 metres between the columns",
+      "Create a horizontal beam along the X axis",
+      "Run a 300x600 beam across the room",
+      "Extrude this cross-section into a 5m long beam\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(0.3, 0.6)\nconst section = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst alongX = await snaptrude.core.math.vec3.new(1, 0, 0)\nconst beam = await snaptrude.design.create.beam(section, 6, alongX)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
@@ -2272,7 +3464,12 @@
     "path": "design.create.ceiling",
     "namespace": "design.create",
     "summary": "Create a **ceiling** by extruding a footprint contour by `thickness`, lifted `heightFromFloor` above the floor.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Add a false ceiling 2.7m above the floor",
+      "Create a ceiling over this room footprint",
+      "Put a dropped ceiling in the living room at 3 metres",
+      "Add a 50mm thick ceiling lifted 2800mm from floor level\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 ceiling = await snaptrude.design.create.ceiling(contour, 0.05, 2.8)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
@@ -2280,7 +3477,12 @@
     "path": "design.create.column",
     "namespace": "design.create",
     "summary": "Create a **column** by extruding a cross-section contour upward by `height` from a base `position`.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Add a 3m tall column at this point",
+      "Place a column at the grid intersection",
+      "Create a 450mm square concrete column 4 metres high",
+      "Stand a column up from this base point\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(0.45, 0.45)\nconst crossSection = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst base = await snaptrude.core.math.vec3.new(4, 0, 4)\nconst column = await snaptrude.design.create.column(base, crossSection, 3)\n```"
+    ],
     "argsType": "Vec3Handle",
     "resultType": "ComponentHandle"
   },
@@ -2288,15 +3490,40 @@
     "path": "design.create.copy",
     "namespace": "design.create",
     "summary": "**Copy** existing entities, offsetting each copy by `displacement * i` (i = 1…count), source positions preserved. Migrated from the removed `tools.copy`. In `\"instance\"` mode copies stay in the source's instance family where possible; `\"unique\"` makes independent geometry. The created copies become the active selection. Undoable.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Copy this room 3 times spaced 6m apart",
+      "Duplicate the selected furniture along the X axis",
+      "Make 5 copies of this column at 4 metre intervals",
+      "Array these walls with a 3m offset",
+      "Clone the desk as a unique copy, not an instance\n\n# Example\n```ts\nconst { vec3 } = snaptrude.core.math\nconst copies = await snaptrude.design.create.copy([\"space-id\"], vec3.new(6, 0, 0), { count: 3 })\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "ComponentHandle[]"
   },
+  {
+    "path": "design.create.door",
+    "namespace": "design.create",
+    "summary": "Place a **door** from the catalog into a host wall.",
+    "examplePrompts": [
+      "Add a door to this wall here",
+      "Place a sliding door on the selected wall",
+      "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\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```"
+    ],
+    "argsType": "string",
+    "resultType": "ComponentHandle"
+  },
   {
     "path": "design.create.floor",
     "namespace": "design.create",
     "summary": "Create a **floor** by extruding a footprint contour by `thickness` (extruded upward).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "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 = await snaptrude.design.create.floor(contour, 0.1)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
@@ -2304,7 +3531,13 @@
     "path": "design.create.furniture",
     "namespace": "design.create",
     "summary": "Place a **furniture** item from the project library at a world position.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Place a chair from the library at this spot",
+      "Add a sofa from the furniture catalog to the living room",
+      "Drop a desk into the scene at 3, 0, 5",
+      "Insert the uploaded bed model in the bedroom",
+      "Put a table from my project library here and name it Table-01\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```"
+    ],
     "argsType": "string",
     "resultType": "ComponentHandle"
   },
@@ -2312,7 +3545,12 @@
     "path": "design.create.mass",
     "namespace": "design.create",
     "summary": "Create a **mass** — a generic extruded prism (default `massType` \"Generic mass\"). Same footprint-extrude path as {@linkcode PluginDesignCreateApi.space}.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Create a generic mass 30m tall from this footprint",
+      "Block out a conceptual massing volume for the site",
+      "Extrude this shape into a building mass",
+      "Add a simple study-model volume at the origin\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(20, 15)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst tower = await snaptrude.design.create.mass(contour, 30, \"Tower A\", undefined, \"Building\")\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
@@ -2320,7 +3558,13 @@
     "path": "design.create.referenceLines",
     "namespace": "design.create",
     "summary": "Create **reference lines** from a profile — one reference line per curve in the profile's ordered chain. Returns a handle per created line.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Draw a reference line between these two points",
+      "Add dashed guide lines along this path",
+      "Create grid lines tagged A through the plan",
+      "Set up construction lines for the column grid",
+      "Mark a red reference line across the site\n\n# Example\n```ts\nconst v = snaptrude.core.math.vec3\nconst profile = await snaptrude.core.geom.create.profileFromLinePoints([\nawait v.new(0, 0, 0),\nawait v.new(10, 0, 0),\n])\nconst lines = await snaptrude.design.create.referenceLines(\nprofile,\nundefined,\nundefined,\n\"DASHED\",\n)\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ComponentHandle[]"
   },
@@ -2328,7 +3572,12 @@
     "path": "design.create.roof",
     "namespace": "design.create",
     "summary": "Create a **roof** by extruding a footprint contour by `thickness`. Created flat (extruded downward); pitch/slope is a separate post-creation edit.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Add a flat roof over the building footprint",
+      "Create a roof 200mm thick from this outline",
+      "Cover the top storey with a roof slab",
+      "Put a roof on this building\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(12, 10)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst roof = await snaptrude.design.create.roof(contour, 0.2)\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
@@ -2336,15 +3585,41 @@
     "path": "design.create.slab",
     "namespace": "design.create",
     "summary": "Create a **slab** by extruding a footprint contour by `thickness` (default direction: down).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Add a 150mm thick slab under this footprint",
+      "Create a floor slab from this outline",
+      "Pour a plinth slab over the building footprint",
+      "Make a basement slab that extrudes downward",
+      "Give this room outline a 6 inch slab\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(12, 10)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst slab = await snaptrude.design.create.slab(contour, 0.15, \"down\", \"Plinth\")\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
+  {
+    "path": "design.create.smartLayout",
+    "namespace": "design.create",
+    "summary": "Place a **smart layout** — clone an in-scene template cluster (walls, furniture, doors, windows, floors) into one or more target ROOM/DEPARTMENT spaces, adapting orientation and fit to each target.",
+    "examplePrompts": [
+      "Copy this room's layout into the selected rooms",
+      "Apply this furniture arrangement to the other offices",
+      "Replicate this template into these two spaces",
+      "Place this desk cluster into every meeting room",
+      "Use this room as a template for the rooms I selected but keep them visible\n\n# Example\n```ts\nconst [templateRoom, ...targets] = await snaptrude.design.query.listSpaces({ isSelected: true })\nconst result = await snaptrude.design.create.smartLayout({\ntemplateComponents: [templateRoom],\ntargets,\n})\nconsole.log(\"placed walls:\", result.created.walls.length, \"skipped:\", result.skippedWalls)\n\n// …or clone a saved group by its id (from core.groups.list)\nconst { groups } = await snaptrude.core.groups.list()\nawait snaptrude.design.create.smartLayout({ templateGroup: groups[0].id, targets })\n```"
+    ],
+    "argsType": "PluginSmartLayoutArgs",
+    "resultType": "PluginSmartLayoutResult"
+  },
   {
     "path": "design.create.space",
     "namespace": "design.create",
     "summary": "Create a **space** (a room / mass) by extruding a footprint contour upward.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Create a room called Living Room that's 3m tall from this outline",
+      "Add a new space on the current storey using this footprint",
+      "Make a bedroom here and assign it to the Residential department",
+      "Extrude this closed outline into a 10 foot high room",
+      "Can you create a Kitchen space from the sketch I just drew?\n\n# Example\n```ts\nconst v = snaptrude.core.math.vec3\nconst outer = await snaptrude.core.geom.create.profileFromLinePoints([\nawait v.new(0, 0, 0),\nawait v.new(10, 0, 0),\nawait v.new(10, 0, 8),\nawait v.new(0, 0, 8),\n])\nconst contour = await snaptrude.core.geom.create.contourFromProfile(outer)\nconst space = await snaptrude.design.create.space(contour, 3, \"Living\")\n```"
+    ],
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
@@ -2352,7 +3627,12 @@
     "path": "design.create.spaces",
     "namespace": "design.create",
     "summary": "Create **many spaces** in one undoable operation (bulk plural of {@linkcode space}). Migrated from the removed `entity.space.bulkCreate`. Each item extrudes a contour footprint up `height`. Validate-all-or-throw; one command. For a rectangular (box) space, build the footprint with `core.geom.create.profileRect` → `contourFromProfile`, then pass it as an item.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Create several rooms at once from these footprints",
+      "Generate all the bedrooms in one operation",
+      "Bulk create the spaces for this floor plan",
+      "Add three rooms with different heights in a single undo step\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 [a, b] = await snaptrude.design.create.spaces([\n{ contour, height: 3, label: \"R1\" },\n{ contour, height: 4, label: \"R2\", position: await vec3.new(10, 0, 0) },\n])\n```"
+    ],
     "argsType": "PluginCreateSpaceItem[]",
     "resultType": "ComponentHandle[]"
   },
@@ -2360,7 +3640,13 @@
     "path": "design.create.staircase",
     "namespace": "design.create",
     "summary": "Create a **staircase** from a parametric preset, placed at a point.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Add a dog-legged staircase at this location",
+      "Place a straight stair on level 01",
+      "Create an L-shaped staircase in the lobby",
+      "Insert a staircase near the entrance",
+      "Put amphitheatre steps at these coordinates\n\n# Example\n```ts\nconst stair = await snaptrude.design.create.staircase(\n\"dogLegged\",\nawait snaptrude.core.math.vec3.new(5, 0, 5),\n)\n```"
+    ],
     "argsType": "PluginStaircasePreset",
     "resultType": "ComponentHandle"
   },
@@ -2368,95 +3654,225 @@
     "path": "design.create.walls",
     "namespace": "design.create",
     "summary": "Create a connected run of **walls** from a profile — one wall per curve in the profile's chain, with mitred corners at shared endpoints.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Draw walls along this centerline",
+      "Create 3m high, 200mm thick walls from these points",
+      "Build a wall run around the room outline",
+      "Turn this polyline sketch into walls",
+      "Add walls with mitred corners along the path\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```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "ComponentHandle[]"
   },
+  {
+    "path": "design.create.window",
+    "namespace": "design.create",
+    "summary": "Place a **window** from the catalog into a host wall.",
+    "examplePrompts": [
+      "Add a window to this wall here",
+      "Place a casement window on the selected wall",
+      "Put a window from the catalog at this point on the wall",
+      "Insert a window into the living room wall",
+      "Add a window to the wall and name it Win-01\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"
+  },
   {
     "path": "design.delete.entities",
     "namespace": "design.delete",
     "summary": "Delete one or more entities. Generic hard delete (backed by the same batched, undoable path as `entity.space.delete`). Cascade is opinionated by the engine: children are removed and linked-list neighbours are fixed up — not caller-tunable in v1. Undoable — commits as a **single** undo entry.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Delete the selected objects",
+      "Remove these walls from the model",
+      "Get rid of this mass entirely",
+      "Delete all the furniture I picked",
+      "Remove the door and window I just created\n\n# Example\n```ts\n// Hard-delete every furniture item on storey 2 (a single undo entry)\nconst furniture = await snaptrude.design.query.listFurniture({ storeys: [2] })\nif (furniture.length > 0) {\nconst { affected } = await snaptrude.design.delete.entities(furniture)\n}\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.doors.exists",
+    "namespace": "design.doors",
+    "summary": "Test whether a door catalog item exists for the given library id.",
+    "examplePrompts": [
+      "Is this door still in the library?",
+      "Check whether a door catalog item with this id exists",
+      "Does my team library have this door?",
+      "Verify the door is available before placing it\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst stillAvailable = await snaptrude.design.doors.exists(entry.id)\nconsole.log(stillAvailable ? \"safe to place\" : \"removed from library\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.doors.getCatalogItem",
+    "namespace": "design.doors",
+    "summary": "Get a single door catalog item by its library id.",
+    "examplePrompts": [
+      "Get the details of this door from the library",
+      "Look up the catalog entry for this door id",
+      "What is the cost of this door item?",
+      "Show me the family name of this door in the catalog\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst item = await snaptrude.design.doors.getCatalogItem(entry.id)\nif (item) console.log(item.name, item.source, item.dbType)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem | null"
+  },
   {
     "path": "design.doors.getFamily",
     "namespace": "design.doors",
-    "summary": "Get a door's family name (Revit/native).",
-    "examplePrompts": [],
+    "summary": "Get the family name of a door — the Revit or native family the door instance comes from.",
+    "examplePrompts": [
+      "Which family does this door belong to?",
+      "What's the Revit family of the selected door?",
+      "Show the family name for this door",
+      "Find out which door family the imported door uses\n\n# Example\n```ts\nconst [door] = await snaptrude.design.query.listDoors()\nconst family = await snaptrude.design.doors.getFamily(door)\nif (family) console.log(\"family:\", family)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "string | null"
   },
   {
     "path": "design.doors.getHeight",
     "namespace": "design.doors",
-    "summary": "Get a door's height.",
-    "examplePrompts": [],
+    "summary": "Get the height of a door — how tall its opening is from base to head.",
+    "examplePrompts": [
+      "How tall is this door?",
+      "What's the height of the selected door?",
+      "Check the door height for this opening",
+      "Is the front door 2100mm high?\n\n# Example\n```ts\nconst [door] = await snaptrude.design.query.listDoors()\nconst height = await snaptrude.design.doors.getHeight(door)\nif (height !== null) console.log(\"door height:\", height)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "number | null"
   },
   {
     "path": "design.doors.getSupportFloor",
     "namespace": "design.doors",
-    "summary": "Get the floor a door is hosted on.",
-    "examplePrompts": [],
+    "summary": "Get the floor a door is hosted on — the storey/level component that supports the door.",
+    "examplePrompts": [
+      "Which floor is this door on?",
+      "What storey does the selected door belong to?",
+      "Find the level that hosts this door",
+      "Tell me which floor the entrance door sits on\n\n# Example\n```ts\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nconst floor = await snaptrude.design.doors.getSupportFloor(door)\nif (floor) {\nconst props = await snaptrude.design.query.getProperties(floor)\nconsole.log(\"hosted on storey:\", props.storey)\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "ComponentHandle | null"
   },
   {
     "path": "design.doors.getSwingDirection",
     "namespace": "design.doors",
-    "summary": "Get a door's swing (hinge) handedness — derived from the mesh reflection state.",
-    "examplePrompts": [],
+    "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?",
+      "Check the hinge side of this door",
+      "Does the entrance door open to the left or the right?\n\n# Example\n```ts\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nconst swing = await snaptrude.design.doors.getSwingDirection(door)\nif (swing) console.log(\"opens as a\", swing, \"hand door\")\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "\"left\" | \"right\" | null"
   },
   {
     "path": "design.doors.getType",
     "namespace": "design.doors",
-    "summary": "Get a door's type name.",
-    "examplePrompts": [],
+    "summary": "Get the type name of a door — the label that identifies which kind of door the instance is, as shown in its properties.",
+    "examplePrompts": [
+      "What type of door is this?",
+      "Tell me the door type of the selected door",
+      "Is this a single or a double door?",
+      "Check what kind of door is on this wall\n\n# Example\n```ts\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nconst type = await snaptrude.design.doors.getType(door)\nif (type) console.log(\"door type:\", type)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "string | null"
   },
   {
     "path": "design.doors.getWidth",
     "namespace": "design.doors",
-    "summary": "Get a door's width.",
-    "examplePrompts": [],
+    "summary": "Get the width of a door — how wide its opening is along the host wall.",
+    "examplePrompts": [
+      "How wide is this door?",
+      "What's the width of the selected door?",
+      "Measure the width of the entrance door",
+      "Check whether this door is 900mm wide\n\n# Example\n```ts\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nconst width = await snaptrude.design.doors.getWidth(door)\nif (width !== null) console.log(\"door width:\", width)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "number | null"
   },
+  {
+    "path": "design.doors.listCatalog",
+    "namespace": "design.doors",
+    "summary": "List the placeable door catalog (team + general libraries), optionally restricted to one group by its `dbType` token.",
+    "examplePrompts": [
+      "What doors can I place in this project?",
+      "List every door in the library",
+      "Show me the sliding doors I can add",
+      "Browse the door catalog\n\n# Example\n```ts\nconst [group] = await snaptrude.design.doors.listCatalogGroups()\nconst items = await snaptrude.design.doors.listCatalog(group?.dbType)\nfor (const item of items) console.log(item.id, item.name, item.thumbnailUrl)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem[]"
+  },
+  {
+    "path": "design.doors.listCatalogGroups",
+    "namespace": "design.doors",
+    "summary": "List the door catalog **groups** — the placement families (Swing, Sliding, Folding, Pivot, …), built-in groups merged with any team-custom types.",
+    "examplePrompts": [
+      "What kinds of doors can I place?",
+      "List the door groups in the catalog",
+      "Show me the door families available in this project",
+      "Which door types does this project support?\n\n# Example\n```ts\nconst groups = await snaptrude.design.doors.listCatalogGroups()\nfor (const g of groups) console.log(g.dbType, g.label, g.source)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginObjectCatalogGroup[]"
+  },
   {
     "path": "design.doors.mirror",
     "namespace": "design.doors",
-    "summary": "Mirror a door across an axis (reflect its swing). Undoable (one command).",
-    "examplePrompts": [],
+    "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 — 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"
   },
   {
     "path": "design.doors.setHeight",
     "namespace": "design.doors",
-    "summary": "Set the height of one or more doors (engine units; re-cuts the host wall). Undoable.",
-    "examplePrompts": [],
+    "summary": "Set the height of one or more doors, resizing each opening and re-cutting the host wall. Height is in engine units; the change is undoable.",
+    "examplePrompts": [
+      "Make this door 2100mm tall",
+      "Change the door height to 7 feet",
+      "Raise the selected doors to 2.4m high",
+      "Set all the doors on this storey to 2100 high\n\n# Example\n```ts\n// setHeight takes an array — wrap a single door\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nawait snaptrude.design.doors.setHeight([door], 2100)\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.doors.setWidth",
     "namespace": "design.doors",
-    "summary": "Set the width of one or more doors (engine units; re-cuts the host wall). Undoable.",
-    "examplePrompts": [],
+    "summary": "Set the width of one or more doors, resizing each opening and re-cutting the host wall. Width is in engine units; the change is undoable.",
+    "examplePrompts": [
+      "Make this door 900mm wide",
+      "Widen the selected doors to 1 metre",
+      "Change the door width to 3 feet",
+      "Resize all the bathroom doors to 750 wide",
+      "Narrow the entrance door a bit\n\n# Example\n```ts\n// Resize every ground-floor door to a common width (engine units)\nconst doors = await snaptrude.design.query.listDoors({ storeys: [1] })\nconst { affected } = await snaptrude.design.doors.setWidth(doors, 900)\nconsole.log(\"resized\", affected.length, \"doors\")\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.edit.offsetSplit",
     "namespace": "design.edit",
-    "summary": "Offset-and-split the top profile of one component. Positive = outward, negative = inward. Single-component only (the engine rejects batches).",
-    "examplePrompts": [],
+    "summary": "Offset the top profile of a component by a distance and split the face along the offset curve. Positive distances offset outward, negative inward. Single-component only (the engine rejects batches).",
+    "examplePrompts": [
+      "Offset the top face of this mass inward by 2 metres and split it",
+      "Create a 1m setback border on top of the selected mass",
+      "Split the roof profile with a 500mm inward offset",
+      "Offset-split the slab's top profile outward by 3 feet\n\n# Example\n```ts\n// Offset the top profile inward by 2 units and split the face along it\nconst [mass] = await snaptrude.design.query.listMasses()\nconst { createdIds, offsetValue } = await snaptrude.design.edit.offsetSplit(mass, -2)\n// offsetValue is the post-clamp distance the engine actually applied\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "OffsetSplitOutcome"
   },
@@ -2464,7 +3880,13 @@
     "path": "design.erase.edge",
     "namespace": "design.erase",
     "summary": "Commit the erase for one edge. `DirectUnion` merges the two adjacent masses; `DirectDelete` drops the single mass behind the boundary edge. Single undo entry.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Erase the edge between these two rooms so they merge",
+      "Remove the shared boundary between the kitchen and the dining space",
+      "Merge the two adjacent rooms by erasing their common edge",
+      "Knock through the partition line between these spaces",
+      "Erase this boundary edge from the plan\n\n# Example\n```ts\n// Merge two adjacent rooms by erasing an internal edge they share\nconst edges = await snaptrude.design.erase.listErasableEdges({ strategies: [\"DirectUnion\"] })\nif (edges.length > 0) {\nconst { ok } = await snaptrude.design.erase.edge(edges[0])\n}\n```"
+    ],
     "argsType": "ErasableEdgeRef",
     "resultType": "PluginDesignEraseEdgeResult"
   },
@@ -2472,7 +3894,12 @@
     "path": "design.erase.listErasableEdges",
     "namespace": "design.erase",
     "summary": "Enumerate every erasable edge in the current plan's bottom-adjacency graph (one {@linkcode ErasableEdgeRef} per edge). Pure read — no scene mutation, no command, not undoable. Erase-ineligible components (locked, hidden, off-storey) are filtered out.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Which edges in my floor plan can be erased?",
+      "List the erasable edges on this storey",
+      "Show me the shared edges I could erase to merge rooms",
+      "What edges between these two spaces can be removed?\n\n# Example\n```ts\nconst edges = await snaptrude.design.erase.listErasableEdges()\nconst union = edges.find((e) => e.strategy === \"DirectUnion\")\nif (union) await snaptrude.design.erase.edge(union)\n```"
+    ],
     "argsType": "PluginDesignListErasableEdgesArgs",
     "resultType": "ErasableEdgeRef[]"
   },
@@ -2480,7 +3907,12 @@
     "path": "design.furniture.exists",
     "namespace": "design.furniture",
     "summary": "Test whether a catalog item exists for the given library id.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Is this furniture item still in the library?",
+      "Check whether a catalog item with this id exists",
+      "Does my team library have this chair?",
+      "Verify the sofa is available in the catalog before placing it\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.furniture.listCatalog()\nconst stillAvailable = await snaptrude.design.furniture.exists(entry.id)\nconsole.log(stillAvailable ? \"safe to place\" : \"removed from library\")\n```"
+    ],
     "argsType": "string",
     "resultType": "boolean"
   },
@@ -2488,71 +3920,193 @@
     "path": "design.furniture.getCatalogItem",
     "namespace": "design.furniture",
     "summary": "Get a single catalog item by its library id.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the details of this furniture item from the library",
+      "Look up the catalog entry for this chair id",
+      "What is the cost of this furniture item?",
+      "Show me the family name of the sofa in the catalog\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.furniture.listCatalog()\nconst item = await snaptrude.design.furniture.getCatalogItem(entry.id)\nif (item) console.log(item.name, item.source, item.familyName)\n```"
+    ],
     "argsType": "string",
     "resultType": "PluginFurnitureCatalogItem | null"
   },
   {
     "path": "design.furniture.listCatalog",
     "namespace": "design.furniture",
-    "summary": "List the placeable furniture catalog (team + general libraries).",
-    "examplePrompts": [],
+    "summary": "List the placeable furniture catalog (team + general libraries), optionally filtered by library `source` and/or `category`.",
+    "examplePrompts": [
+      "What furniture can I place in this project?",
+      "Show me all the furniture available in the library",
+      "List the chairs and tables I can add to the model",
+      "Which furniture items are in my team's library?",
+      "Show me the bedroom furniture I can place\n\n# Example\n```ts\nconst bedroom = await snaptrude.design.furniture.listCatalog(\"team\", \"bedroom\")\nfor (const item of bedroom) console.log(item.id, item.name, item.thumbnailUrl)\n```"
+    ],
     "argsType": "\"team\" | \"general\"",
     "resultType": "PluginFurnitureCatalogItem[]"
   },
+  {
+    "path": "design.furniture.listCategories",
+    "namespace": "design.furniture",
+    "summary": "List the categories (Living, Bedroom, Kitchen, …) that organize the furniture catalog — the picker taxonomy, merged from built-in categories, team types, and backend user types. Pass a value to {@linkcode PluginDesignFurnitureApi.listCatalog}'s `category` filter.",
+    "examplePrompts": [
+      "What furniture categories are available?",
+      "List the furniture categories",
+      "Show me the furniture groups like living and bedroom",
+      "Which furniture categories can I filter by?\n\n# Example\n```ts\nconst categories = await snaptrude.design.furniture.listCategories()\nconst [first] = categories\nconst items = await snaptrude.design.furniture.listCatalog(undefined, first)\nconsole.log(first, \"→\", items.length, \"items\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "string[]"
+  },
+  {
+    "path": "design.isAreaLocked",
+    "namespace": "design",
+    "summary": "Test whether a space's footprint area is locked. A read — never throws; returns `false` for non-space handles and when the `area_lock` feature is off.",
+    "examplePrompts": [
+      "Is the area of this room locked?",
+      "Check whether this department's footprint is pinned",
+      "Tell me if the selected space has its area locked\n\n# Example\n```ts\nconst [room] = await snaptrude.design.selection.get()\nconst locked = await snaptrude.design.isAreaLocked(room)\nconsole.log(locked ? \"area is locked\" : \"area is free\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
   {
     "path": "design.isLocked",
     "namespace": "design",
     "summary": "Test whether an entity is locked (folds group + bucket lock unless `includeInherited: false`).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Is this wall locked?",
+      "Check whether the selected mass is locked or editable",
+      "Why can't I move this object? Check if it is locked",
+      "Tell me if this room is locked, counting locks inherited from its group\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst locked = await snaptrude.design.isLocked(wall)\n// Own flag only — ignore locks inherited from the group / bucket\nconst ownLock = await snaptrude.design.isLocked(wall, false)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "boolean"
   },
+  {
+    "path": "design.listAreaLocked",
+    "namespace": "design",
+    "summary": "List the spaces whose footprint area is locked. A read — never throws; returns `[]` when the `area_lock` feature is off.",
+    "examplePrompts": [
+      "Which spaces have their area locked?",
+      "List every room with a locked footprint",
+      "Show me all the area-locked departments\n\n# Example\n```ts\nconst locked = await snaptrude.design.listAreaLocked()\nconsole.log(locked.length, \"area-locked spaces\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "ComponentHandle[]"
+  },
   {
     "path": "design.listLocked",
     "namespace": "design",
     "summary": "List the explicitly-locked entities (excludes purely group/bucket-inherited locks).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Which objects in the model are locked?",
+      "List all the locked entities in this project",
+      "Show everything that has been locked",
+      "Are there any locked walls or masses in the scene?\n\n# Example\n```ts\nconst locked = await snaptrude.design.listLocked()\nconsole.log(locked.length, \"explicitly locked entities\")\n```"
+    ],
     "argsType": null,
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.lock",
     "namespace": "design",
-    "summary": "Lock entities (blocks editing). Undoable. Cascades to void/door/window children, stacked-wall companions, and terrain neighborhood; skips active-group members.",
-    "examplePrompts": [],
+    "summary": "Lock entities so they cannot be edited. Undoable. Cascades to void/door/window children, stacked-wall companions, and terrain neighborhood; skips active-group members.",
+    "examplePrompts": [
+      "Lock the selected walls so they can't be edited",
+      "Freeze these masses so nobody moves them by accident",
+      "Lock everything on the ground floor",
+      "Protect this room from further changes\n\n# Example\n```ts\n// Lock every wall on the ground storey\nconst walls = await snaptrude.design.query.listWalls({ storeys: [1] })\nconst { affected } = await snaptrude.design.lock(walls)\n// affected is post-cascade: hosted doors/windows are included\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
+  {
+    "path": "design.lockArea",
+    "namespace": "design",
+    "summary": "Lock the **footprint area** of one or more Room / Department mass spaces — geometry edits that would change the bottom-face area are then refused or auto-resized to preserve it. Distinct from {@linkcode PluginDesignApi.lock} (which freezes the whole object): this locks only the area. Cascades to the space's instances and its source mass. Undoable.",
+    "examplePrompts": [
+      "Lock the floor area of the selected rooms",
+      "Freeze the footprint area of this department so its size can't drift",
+      "Area-lock every room on this storey",
+      "Pin the area of this space while I edit its walls\n\n# Example\n```ts\nconst rooms = await snaptrude.design.selection.get()\nconst { affected } = await snaptrude.design.lockArea(rooms)\nconsole.log(\"area-locked\", affected.length, \"spaces\")\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.materials.apply",
     "namespace": "design.materials",
-    "summary": "Apply a material (by handle or spec) to one or more components. Undoable (`save`, default true).",
-    "examplePrompts": [],
+    "summary": "Apply a material to one or more components — an existing project material by handle, or a new one described inline as a {@linkcode PluginMaterialSpec}. Undoable when `save` is true (the default).",
+    "examplePrompts": [
+      "Paint the selected walls red",
+      "Apply the brick material to these walls",
+      "Put a wood finish on the floor",
+      "Change the colour of this room's walls to #ff8800",
+      "Add a concrete texture to the facade\n\n# Example\n```ts\nconst walls = await snaptrude.design.query.listWalls({ storeys: [1] })\n// inline spec — creates (or reuses by name) a project material, then applies it\nconst { count } = await snaptrude.design.materials.apply(walls, { name: \"Accent Red\", color: \"#b04a3a\" })\nconsole.log(\"painted\", count, \"walls\")\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginMaterialResult"
   },
+  {
+    "path": "design.materials.applyToFaces",
+    "namespace": "design.materials",
+    "summary": "Paint specific **BREP faces** of a component with a material — an existing project material by handle, or a new one described inline as a {@linkcode PluginMaterialSpec}. Faces are addressed by **durable BREP face index** (their 0-based position in the component's BREP face list). Undoable when `save` is true (the default).",
+    "examplePrompts": [
+      "Paint the top face of this slab red",
+      "Apply the brick material to faces 0 and 2 of this wall",
+      "Put a wood finish on just the front face of this column",
+      "Colour face 4 of the selected mass with #ff8800\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })\n// faces are addressed by durable 0-based BREP face index\nconst { count } = await snaptrude.design.materials.applyToFaces(wall, [0, 1], { name: \"Accent\", color: \"#b04a3a\" })\nconsole.log(\"painted\", count, \"faces\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginMaterialResult"
+  },
   {
     "path": "design.materials.create",
     "namespace": "design.materials",
-    "summary": "Create (or get, idempotent by name) a material from a spec.",
-    "examplePrompts": [],
+    "summary": "Create a new material in the project from a spec — a color, texture URL, opacity, and/or name. Idempotent by name: creating with the name of an existing material returns that material instead of duplicating it.",
+    "examplePrompts": [
+      "Create a new red material called Accent",
+      "Make a material from this texture image URL",
+      "Add a semi-transparent glass material to the project",
+      "Define a dark grey concrete finish I can reuse\n\n# Example\n```ts\nconst glass = await snaptrude.design.materials.create({ name: \"Frosted Glass\", color: \"#cfe4e8\", alpha: 0.4 })\nconst walls = await snaptrude.design.query.listWalls({ storeys: [1] })\nawait snaptrude.design.materials.apply(walls, glass)\n```"
+    ],
     "argsType": "PluginMaterialSpec",
     "resultType": "MaterialHandle"
   },
+  {
+    "path": "design.materials.getByFace",
+    "namespace": "design.materials",
+    "summary": "Read the material applied to a single BREP face.",
+    "examplePrompts": [
+      "What material is on the top face of this slab?",
+      "Get the finish applied to face 2 of this wall",
+      "Which material is painted on the front face of this column?\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst material = await snaptrude.design.materials.getByFace(wall, 0)\nif (material) console.log(await snaptrude.design.materials.getInfo(material))\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "MaterialHandle | null"
+  },
   {
     "path": "design.materials.getDefault",
     "namespace": "design.materials",
     "summary": "Get the default material for a component's type.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the default material for walls?",
+      "Get the standard material this floor type uses",
+      "Which material would this roof have out of the box?",
+      "Find the default finish for the selected column\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst defaultMaterial = await snaptrude.design.materials.getDefault(wall)\nif (defaultMaterial) console.log(await snaptrude.design.materials.getInfo(defaultMaterial))\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "MaterialHandle | null"
   },
   {
     "path": "design.materials.getInfo",
     "namespace": "design.materials",
-    "summary": "Read a material's descriptor.",
-    "examplePrompts": [],
+    "summary": "Read a material's descriptor — its name, color, opacity, and texture (when it has one).",
+    "examplePrompts": [
+      "What colour is the Brick material?",
+      "Show me the details of this material",
+      "Get the opacity of the glass finish",
+      "Which texture image does the wood material use?\n\n# Example\n```ts\nconst [material] = await snaptrude.design.materials.list()\nconst info = await snaptrude.design.materials.getInfo(material)\nif (info) console.log(info.name, info.colorHex, info.alpha)\n```"
+    ],
     "argsType": "MaterialHandle",
     "resultType": "PluginMaterialInfo | null"
   },
@@ -2560,7 +4114,12 @@
     "path": "design.materials.hasTexture",
     "namespace": "design.materials",
     "summary": "Test whether a material has a texture.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Does this material have a texture image?",
+      "Is the brick material textured or just a flat colour?",
+      "Check whether the wood finish uses an image map",
+      "Tell me if this material is image-based or a plain colour\n\n# Example\n```ts\nconst [material] = await snaptrude.design.materials.list()\nconst textured = await snaptrude.design.materials.hasTexture(material)\nconsole.log(textured ? \"image-based\" : \"flat colour\")\n```"
+    ],
     "argsType": "MaterialHandle",
     "resultType": "boolean"
   },
@@ -2568,7 +4127,12 @@
     "path": "design.materials.isDefault",
     "namespace": "design.materials",
     "summary": "Test whether a component carries its (type) default material.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Is this wall still using its default material?",
+      "Has the material on this floor been changed?",
+      "Check if the selected object still has its original finish",
+      "Tell me whether this roof has been painted or is still standard\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst untouched = await snaptrude.design.materials.isDefault(wall)\nconsole.log(untouched ? \"still default\" : \"has been painted\")\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "boolean"
   },
@@ -2576,7 +4140,12 @@
     "path": "design.materials.isUniform",
     "namespace": "design.materials",
     "summary": "Test whether a component has a single (uniform) material across all faces.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Does this wall have the same material on every face?",
+      "Is the floor finished uniformly or face by face?",
+      "Check if this column is a single material all over",
+      "Are any faces of the selected object painted differently?\n\n# Example\n```ts\nconst [selected] = await snaptrude.design.selection.get()\nconst uniform = await snaptrude.design.materials.isUniform(selected)\nconsole.log(uniform ? \"one material all over\" : \"painted per face\")\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "boolean"
   },
@@ -2584,23 +4153,63 @@
     "path": "design.materials.list",
     "namespace": "design.materials",
     "summary": "List the project materials.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "List all the materials in this project",
+      "What materials do I have available to apply?",
+      "Show me the preset materials library",
+      "Which finishes exist in this model?",
+      "Get every material in the project palette\n\n# Example\n```ts\nconst presets = await snaptrude.design.materials.list(\"preset\")\nconsole.log(presets.length, \"preset materials\")\n```"
+    ],
     "argsType": "\"project\" | \"preset\"",
     "resultType": "MaterialHandle[]"
   },
+  {
+    "path": "design.materials.listByFace",
+    "namespace": "design.materials",
+    "summary": "List the per-face materials of a component — one entry per BREP face, in face index order. A face carrying no explicit per-face material reports `null`.",
+    "examplePrompts": [
+      "List the material on every face of this wall",
+      "Show me which faces of this slab are painted and with what",
+      "Break down the per-face finishes of the selected mass\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst faces = await snaptrude.design.materials.listByFace(wall)\nfor (const f of faces) console.log(f.faceIndex, f.material ?? \"(default)\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginFaceMaterial[]"
+  },
   {
     "path": "design.materials.reset",
     "namespace": "design.materials",
-    "summary": "Reset one or more components to their default material. Undoable. Paired with `apply`.",
-    "examplePrompts": [],
+    "summary": "Reset one or more components back to the default material for their type, removing any applied finish. The inverse of `apply`; undoable when `save` is true (the default).",
+    "examplePrompts": [
+      "Remove the paint from these walls",
+      "Reset the selected objects to their default material",
+      "Clear the custom finish on the floor",
+      "Restore the original colour of this roof\n\n# Example\n```ts\nconst selected = await snaptrude.design.selection.get()\nconst { count } = await snaptrude.design.materials.reset(selected)\nconsole.log(\"reset\", count, \"components to their default material\")\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginMaterialResult"
   },
+  {
+    "path": "design.materials.resetFaces",
+    "namespace": "design.materials",
+    "summary": "Reset specific BREP faces of a component back to the component/type default, removing any per-face finish. The inverse of {@linkcode PluginDesignMaterialsApi.applyToFaces}; undoable when `save` is true (the default). BREP-only (see `applyToFaces`).",
+    "examplePrompts": [
+      "Remove the paint from the top face of this slab",
+      "Reset faces 0 and 2 of this wall to their default material",
+      "Clear the custom finish on the front face of this column\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ storeys: [1] })\nconst { count } = await snaptrude.design.materials.resetFaces(wall, [0, 1])\nconsole.log(\"reset\", count, \"faces\")\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginMaterialResult"
+  },
   {
     "path": "design.query.exists",
     "namespace": "design.query",
     "summary": "Test whether an entity id resolves to a live scene entity.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Does this element still exist in the scene?",
+      "Check whether the wall I stored earlier is still there",
+      "Is id cmp_42 still valid?",
+      "Verify the object wasn't deleted\n\n# Example\n```ts\n// Guard before acting on a handle that may have been deleted or undone\nif (await snaptrude.design.query.exists(wall)) {\nconst dx = await snaptrude.core.math.vec3.new(5, 0, 0)\nawait snaptrude.design.transform.move([wall], dx)\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "boolean"
   },
@@ -2608,23 +4217,53 @@
     "path": "design.query.geometry.getBottomContour",
     "namespace": "design.query.geometry",
     "summary": "Get the **bottom-face contour** of a component — the footprint outline (outer profile + holes) of its lowest horizontal face, as a reusable {@linkcode ContourHandle}.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the footprint of the selected mass",
+      "What is the plan outline of this building volume?",
+      "Trace the base profile of this wall",
+      "Find the ground-level outline of the slab, including any openings",
+      "Work out the footprint area of the selected component"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "ContourHandle | null"
   },
   {
     "path": "design.query.geometry.getBrep",
     "namespace": "design.query.geometry",
-    "summary": "Get the boundary-representation (BREP) mesh of a scene component.",
-    "examplePrompts": [],
+    "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",
+      "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"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "BrepHandle | null"
   },
+  {
+    "path": "design.query.geometry.getCenterline",
+    "namespace": "design.query.geometry",
+    "summary": "Get the **centerline** (core curve) of a wall — the single curve running down the middle of the wall, as a reusable {@linkcode CurveHandle} (a `Line` for a straight wall, an `Arc` for a curved wall).",
+    "examplePrompts": [
+      "Get the centerline of the selected wall",
+      "How long is this wall along its centre line?",
+      "Find the axis running down the middle of this wall",
+      "Give me the core curve of that curved wall",
+      "Where does the wall's centreline start and end?"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "CurveHandle | null"
+  },
   {
     "path": "design.query.getBoundingBox",
     "namespace": "design.query",
     "summary": "Get the **union** axis-aligned bounding box enclosing a set of entities.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the bounding box around the selected objects",
+      "What is the overall extent of these walls?",
+      "How big is the region these elements cover together?",
+      "Find the combined extents of everything on level 2\n\n# Example\n```ts\nconst walls = await snaptrude.design.query.listWalls()\nconst box = await snaptrude.design.query.getBoundingBox(walls)\n\n// Compose with the `within` filter: everything in the selection's extents\nconst selection = await snaptrude.design.selection.get()\nconst extents = await snaptrude.design.query.getBoundingBox(selection)\nif (extents) {\nconst nearby = await snaptrude.design.query.listEntities({ within: extents })\nconst width = extents.max.x - extents.min.x\n}\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "BBoxComponents | null"
   },
@@ -2632,7 +4271,12 @@
     "path": "design.query.getById",
     "namespace": "design.query",
     "summary": "Look an entity up by id — returns the same handle if it still resolves live, else `null`. A cheap validity probe (distinct from {@linkcode PluginDesignQueryApi.exists}).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Look up an object by its id",
+      "Does id cmp_42 still point to something in the model?",
+      "Fetch the element with this id",
+      "Check if this saved element id is still valid\n\n# Example\n```ts\n// Persistence round-trip: save a ref now, revalidate it in a later run\nconst [wall] = await snaptrude.design.query.listWalls()\nconst savedRef = await snaptrude.design.query.getEntityRef(wall)\n\n// ...later (savedRef restored from plugin storage)...\nconst stillThere = await snaptrude.design.query.getById(savedRef)\nif (stillThere) {\nconst props = await snaptrude.design.query.getProperties(stillThere)\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "ComponentHandle | null"
   },
@@ -2640,15 +4284,24 @@
     "path": "design.query.getEntityRef",
     "namespace": "design.query",
     "summary": "Get a serializable, persistable reference to an entity. Under the all-handle model a {@linkcode ComponentHandle} already IS the ref (raw `Component.id`), so this is the identity passthrough — provided for API completeness.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Give me a reference I can save for this element",
+      "Get a persistent id for the selected wall",
+      "Store a handle to this room so I can find it later\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst savedRef = await snaptrude.design.query.getEntityRef(wall)\n// savedRef is a plain string — persist it, then revalidate in a later run\n// with snaptrude.design.query.getById(savedRef)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "ComponentHandle"
   },
   {
     "path": "design.query.getEntityType",
     "namespace": "design.query",
-    "summary": "Get an entity's {@linkcode PluginEntityType}.",
-    "examplePrompts": [],
+    "summary": "Get the kind of BIM entity a handle refers to — wall, door, space, slab, and so on (its {@linkcode PluginEntityType}).",
+    "examplePrompts": [
+      "What kind of element is this?",
+      "Is the selected object a wall or a mass?",
+      "Tell me the type of this component",
+      "What am I looking at — a door, a window, or a panel?\n\n# Example\n```ts\n// Dispatch on what the user selected\nconst selection = await snaptrude.design.selection.get()\nfor (const component of selection) {\nconst kind = await snaptrude.design.query.getEntityType(component)\nif (kind === \"wall\") {\n// wall-specific handling\n} else if (kind === \"space\") {\n// room-specific handling\n}\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginEntityType | null"
   },
@@ -2656,7 +4309,12 @@
     "path": "design.query.getHost",
     "namespace": "design.query",
     "summary": "Get an entity's host/parent entity (e.g. the wall a door is cut into).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Which wall is this door in?",
+      "Find the parent of the selected window",
+      "What is this element attached to?",
+      "Which wall hosts this window?\n\n# Example\n```ts\n// From a door up to its host wall, then measure the wall\nconst [door] = await snaptrude.design.query.listDoors({ isSelected: true })\nconst hostWall = door ? await snaptrude.design.query.getHost(door) : null\nif (hostWall) {\nconst m = await snaptrude.design.query.measure(hostWall)\nconsole.log(\"wall length:\", m?.length)\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "ComponentHandle | null"
   },
@@ -2664,7 +4322,12 @@
     "path": "design.query.getLabel",
     "namespace": "design.query",
     "summary": "Get an entity's human label (`room_type` for spaces/masses, else the mesh label; `\"\"` when unlabelled). The write side is `design.update` (`setLabel`).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is this room called?",
+      "Get the name of the selected object",
+      "Show the label on this wall",
+      "What's the room type of this space?\n\n# Example\n```ts\n// Fuzzy label search (the `label` filter field is exact-match; for\n// case-insensitive or partial matches, read labels and compare yourself)\nconst spaces = await snaptrude.design.query.listSpaces()\nconst kitchens: typeof spaces = []\nfor (const space of spaces) {\nconst label = await snaptrude.design.query.getLabel(space)\nif (label.toLowerCase().includes(\"kitchen\")) kitchens.push(space)\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "string"
   },
@@ -2672,55 +4335,104 @@
     "path": "design.query.getProperties",
     "namespace": "design.query",
     "summary": "Read an entity's common properties as a {@linkcode PluginEntityProperties} record (only applicable fields are present). For spaces/masses this includes `adjacency` — the per-entity adjacency read (bulk form: `program.adjacency.getMatrix`).",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Show me all the details of the selected object",
+      "What storey is this wall on?",
+      "Which department does this room belong to?",
+      "Is this element locked or hidden?",
+      "Get the adjacencies of this space\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls()\nconst props = await snaptrude.design.query.getProperties(wall)\nconsole.log(props.type, props.storey, props.boundingBox)\n\n// The record is partial — type-specific fields exist only where they apply\nconst [room] = await snaptrude.design.query.listSpaces()\nconst p = await snaptrude.design.query.getProperties(room)\nif (p.spaceType === \"Room\" && p.areaClass === \"NET\") {\nfor (const adj of p.adjacency ?? []) {\n// adj.value: 2 = direct, 1 = indirect/contact, -1 = restricted\nconsole.log(adj.spaceId, adj.value)\n}\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginEntityProperties"
   },
+  {
+    "path": "design.query.getStaircaseParams",
+    "namespace": "design.query",
+    "summary": "Read a staircase's parametric properties — its preset, dimensions, step count, base offset, and height-lock state — as a {@linkcode PluginStaircaseParams} record. The paired write is `design.update.staircase`.",
+    "examplePrompts": [
+      "What's the riser height of this staircase?",
+      "How many steps does the selected stair have?",
+      "Show me the tread and width of this staircase",
+      "Read all the parameters of the stairs on level 1\n\n# Example\n```ts\nconst [stair] = await snaptrude.design.query.listStaircases({ isSelected: true })\nconst params = stair ? await snaptrude.design.query.getStaircaseParams(stair) : null\nif (params) console.log(params.steps, params.riser, params.tread)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginStaircaseParams | null"
+  },
   {
     "path": "design.query.listBeams",
     "namespace": "design.query",
-    "summary": "List all **beams**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the beams in the project, optionally filtered by storey, building, lock state, or region.",
+    "examplePrompts": [
+      "List all the beams in the project",
+      "How many beams are on the second storey?",
+      "Show the beams in this structure",
+      "Find every locked beam\n\n# Example\n```ts\nconst storey2Beams = await snaptrude.design.query.listBeams({ storeys: [2] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listByType",
     "namespace": "design.query",
-    "summary": "List entities of a single {@linkcode PluginEntityType}, plus filter.",
-    "examplePrompts": [],
+    "summary": "List all entities of one BIM object type — wall, door, slab, panel, and so on — optionally narrowed by the shared filter.",
+    "examplePrompts": [
+      "List all the curtain walls in the project",
+      "Show every curtain wall panel on this storey",
+      "Get all the elements of a single type, like columns",
+      "Find all the locked slabs in the model\n\n# Example\n```ts\nconst lockedSlabs = await snaptrude.design.query.listByType(\"slab\", { isLocked: true })\n\n// Curtain-wall panels on storeys 2-3 of one building\nconst panels = await snaptrude.design.query.listByType(\"panel\", {\nstoreys: [2, 3],\nbuildingIds: [\"bld_1\"],\n})\n```"
+    ],
     "argsType": "PluginEntityType",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listCeilings",
     "namespace": "design.query",
-    "summary": "List all **ceilings**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the ceilings in the project, optionally filtered by storey, building, visibility, or region.",
+    "examplePrompts": [
+      "List all the ceilings in the model",
+      "How many ceilings are on level 1?",
+      "Which ceilings are hidden?",
+      "Show the ceilings in building B\n\n# Example\n```ts\nconst hiddenCeilings = await snaptrude.design.query.listCeilings({ isHidden: true })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listChildren",
     "namespace": "design.query",
-    "summary": "List an entity's direct child entities.",
-    "examplePrompts": [],
+    "summary": "List an entity's direct child entities — for example the doors and windows hosted in a wall.",
+    "examplePrompts": [
+      "What's inside this wall — list its doors and windows",
+      "Show the child elements of the selected object",
+      "Which openings belong to this wall?",
+      "List everything nested under this mass\n\n# Example\n```ts\n// Count the openings hosted in a wall, split by kind\nconst children = await snaptrude.design.query.listChildren(wall)\nlet doors = 0\nlet windows = 0\nfor (const child of children) {\nconst kind = await snaptrude.design.query.getEntityType(child)\nif (kind === \"door\") doors++\nif (kind === \"window\") windows++\n}\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listColumns",
     "namespace": "design.query",
-    "summary": "List all **columns**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the columns in the project, optionally filtered by storey, building, selection state, or region.",
+    "examplePrompts": [
+      "How many columns are on the ground floor?",
+      "List all the columns in building A",
+      "Show every column on level 3",
+      "Which columns are currently selected?\n\n# Example\n```ts\nconst groundFloorColumns = await snaptrude.design.query.listColumns({ storeys: [1] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listDoors",
     "namespace": "design.query",
-    "summary": "List all **doors**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the doors in the project, optionally filtered by storey, building, selection state, or region.",
+    "examplePrompts": [
+      "How many doors are in the project?",
+      "List all the doors on the ground floor",
+      "Which doors are currently selected?",
+      "Find every door in building B\n\n# Example\n```ts\n// Ground-floor doors, then read each one's width via design.doors.*\nconst doors = await snaptrude.design.query.listDoors({ storeys: [1] })\nfor (const door of doors) {\nconst width = await snaptrude.design.doors.getWidth(door)\n}\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
@@ -2728,103 +4440,172 @@
     "path": "design.query.listEntities",
     "namespace": "design.query",
     "summary": "List **all** BIM entities in the project matching the filter.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Show me everything in the model",
+      "How many objects are on the ground floor?",
+      "List all the doors and windows on level 2",
+      "What elements are currently selected?",
+      "Find every hidden object in the project\n\n# Example\n```ts\n// Doors and windows on the ground storey (fields AND-combine)\nconst doorsAndWindows = await snaptrude.design.query.listEntities({\ntypes: [\"door\", \"window\"],\nstoreys: [1],\n})\n\n// Everything the user currently has selected\nconst selected = await snaptrude.design.query.listEntities({ isSelected: true })\n\n// Everything inside a world-space region (axis-aligned box, Snaptrude units)\nconst inRegion = await snaptrude.design.query.listEntities({\nwithin: { min: { x: 0, y: 0, z: 0 }, max: { x: 10, y: 4, z: 8 } },\n})\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listFloors",
     "namespace": "design.query",
-    "summary": "List all **floors**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the floor elements (floor plates / finishes) in the project, optionally filtered by storey, building, lock state, or region.",
+    "examplePrompts": [
+      "List all the floor elements in the model",
+      "How many floor plates are on the second storey?",
+      "Which floors are locked?",
+      "Show the floor finishes on level 0\n\n# Example\n```ts\nconst lockedFloors = await snaptrude.design.query.listFloors({ isLocked: true })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listFurniture",
     "namespace": "design.query",
-    "summary": "List all **furniture**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the furniture in the project, optionally filtered by storey, building, label, selection state, or region.",
+    "examplePrompts": [
+      "List all the furniture in the project",
+      "How many furniture items are on this floor?",
+      "Show the furniture inside the selected room",
+      "Which furniture is on storey 2?\n\n# Example\n```ts\n// Furniture whose plan footprint overlaps a room (`overlaps` is plan-only —\n// scope the storey too, or furniture stacked on other floors matches)\nconst [kitchen] = await snaptrude.design.query.listSpaces({ label: \"Kitchen\" })\nif (kitchen) {\nconst inKitchen = await snaptrude.design.query.listFurniture({\noverlaps: kitchen,\nstoreys: [1],\n})\n}\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listMasses",
     "namespace": "design.query",
-    "summary": "List all **generic masses** (non-room masses), filtered.",
-    "examplePrompts": [],
+    "summary": "List all the generic masses (non-room massing volumes) in the project, optionally filtered by storey, building, label, mass type, or region.",
+    "examplePrompts": [
+      "List all the masses in the model",
+      "How many massing blocks are on the site?",
+      "Show the generic masses on level 1",
+      "Find every mass that isn't a room\n\n# Example\n```ts\n// Only certain mass kinds — massTypes matches any of the given values\nconst massing = await snaptrude.design.query.listMasses({\nmassTypes: [\"Generic mass\", \"Plinth\"],\n})\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listMullions",
     "namespace": "design.query",
-    "summary": "List all **curtain-wall mullions**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the curtain-wall mullions in the project, optionally filtered by storey, building, selection state, or region.",
+    "examplePrompts": [
+      "List all the mullions in the curtain wall",
+      "How many mullions are on the facade?",
+      "Show every curtain wall mullion on level 5",
+      "Which mullions are currently selected?\n\n# Example\n```ts\nconst level5Mullions = await snaptrude.design.query.listMullions({ storeys: [5] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listReferenceLines",
     "namespace": "design.query",
-    "summary": "List all **reference lines**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the reference lines in the project, optionally filtered by storey, building, or region.",
+    "examplePrompts": [
+      "List all the reference lines in the model",
+      "Show the guide lines on the ground floor",
+      "How many reference lines are on this storey?",
+      "Find the setting-out lines in building A\n\n# Example\n```ts\nconst groundFloorRefLines = await snaptrude.design.query.listReferenceLines({ storeys: [1] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listRoofs",
     "namespace": "design.query",
-    "summary": "List all **roofs**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the roofs in the project, optionally filtered by storey, building, visibility, or region.",
+    "examplePrompts": [
+      "How many roofs does the model have?",
+      "List all the roof elements",
+      "Show the roofs on the top storey",
+      "Find every hidden roof\n\n# Example\n```ts\nconst hiddenRoofs = await snaptrude.design.query.listRoofs({ isHidden: true })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listSlabs",
     "namespace": "design.query",
-    "summary": "List all **slabs**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the slabs in the project, optionally filtered by storey, building, lock state, or region.",
+    "examplePrompts": [
+      "List all the slabs in the project",
+      "How many slabs are on level 2?",
+      "Which slabs are locked?",
+      "Show the slabs in the selected building\n\n# Example\n```ts\nconst storey2Slabs = await snaptrude.design.query.listSlabs({ storeys: [2] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listSpaces",
     "namespace": "design.query",
-    "summary": "List all **spaces** (room masses), filtered. See {@linkcode PluginDesignQueryApi.listWalls}.",
-    "examplePrompts": [],
+    "summary": "List all the spaces (rooms) in the project, optionally filtered by storey, department, space type, label, selection state, or region.",
+    "examplePrompts": [
+      "How many rooms are in this project?",
+      "List all the spaces on the second storey",
+      "Which rooms are in the Bedrooms department?",
+      "Find every room labelled Kitchen",
+      "Show the spaces that are currently selected\n\n# Example\n```ts\n// Balconies and decks on storey 2 (`label` is an exact match on room_type)\nconst outdoor = await snaptrude.design.query.listSpaces({\nstoreys: [2],\nspaceTypes: [\"Balcony\", \"Deck\"],\n})\n\n// Rooms in a department: resolve its id first, then filter and total the area\nconst { departments } = await snaptrude.program.departments.list()\nconst bedrooms = departments.find((d) => d.name === \"Bedrooms\")\nif (bedrooms) {\nconst rooms = await snaptrude.design.query.listSpaces({ departmentId: bedrooms.id })\nlet total = 0\nfor (const room of rooms) {\nconst m = await snaptrude.design.query.measure(room)\ntotal += m?.area ?? 0\n}\n}\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listStaircases",
     "namespace": "design.query",
-    "summary": "List all **staircases**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the staircases in the project, optionally filtered by storey, building, selection state, or region.",
+    "examplePrompts": [
+      "How many staircases are in the building?",
+      "List all the stairs in the project",
+      "Show the staircases on the ground floor",
+      "Which stairs are currently selected?\n\n# Example\n```ts\nconst groundFloorStairs = await snaptrude.design.query.listStaircases({ storeys: [1] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listWalls",
     "namespace": "design.query",
-    "summary": "List all **walls**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the walls in the project, optionally filtered by storey, building, label, selection state, or region.",
+    "examplePrompts": [
+      "How many walls are in the project?",
+      "List all the walls on the ground floor",
+      "Which walls are currently selected?",
+      "Find the walls on level 2 of building A",
+      "Show me every hidden wall\n\n# Example\n```ts\nconst groundFloorWalls = await snaptrude.design.query.listWalls({ storeys: [1] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.listWindows",
     "namespace": "design.query",
-    "summary": "List all **windows**, filtered.",
-    "examplePrompts": [],
+    "summary": "List all the windows in the project, optionally filtered by storey, building, selection state, or region.",
+    "examplePrompts": [
+      "How many windows does this building have?",
+      "List every window on level 3",
+      "Which windows are on the ground floor?",
+      "Show all the windows that are currently selected\n\n# Example\n```ts\nconst level3Windows = await snaptrude.design.query.listWindows({ storeys: [3] })\n```"
+    ],
     "argsType": "PluginEntityFilter",
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.query.measure",
     "namespace": "design.query",
-    "summary": "Measure an entity — the multi-metric bundle (area/volume/length + bbox).",
-    "examplePrompts": [],
+    "summary": "Measure an entity — read its area, volume, and/or running length (whichever its type supports) together with its world-space bounding box in one call.",
+    "examplePrompts": [
+      "What's the area of this room?",
+      "How long is the selected wall?",
+      "Get the volume of this mass",
+      "Give me the dimensions of the selected element",
+      "What's the floor area of the kitchen?\n\n# Example\n```ts\nconst [space] = await snaptrude.design.query.listSpaces()\nconst m = await snaptrude.design.query.measure(space)\nconsole.log(m?.area, m?.volume)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginEntityMeasurements | null"
   },
@@ -2832,7 +4613,13 @@
     "path": "design.query.spaces.get",
     "namespace": "design.query.spaces",
     "summary": "Get selected properties of a space — the selective multi-property read.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the area of this room?",
+      "Get the name, storey and height of the selected space",
+      "Which department does this room belong to?",
+      "Where is this space positioned on the plan?",
+      "Read the room type and dimensions of the selected room\n\n# Example\n```ts\nconst [space] = await snaptrude.design.query.listSpaces()\nconst info = await snaptrude.design.query.spaces.get(space, [\"name\", \"area\", \"position\"])\nconsole.log(info.name, info.area, info.position)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignQuerySpacesGetResult"
   },
@@ -2840,47 +4627,107 @@
     "path": "design.query.spaces.getFootprint",
     "namespace": "design.query.spaces",
     "summary": "Get the **footprint** of a space — its bottom-face contour (outer profile + holes) as a reusable {@linkcode ContourHandle}. Equivalent to {@linkcode PluginDesignQueryGeometryApi.getBottomContour} narrowed to spaces.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the footprint of this room",
+      "Trace the floor outline of the selected space",
+      "What is the plan boundary of this room, including any holes?",
+      "Give me the base profile of the selected room mass\n\n# Example\n```ts\nconst [space] = await snaptrude.design.query.listSpaces()\nconst footprint = await snaptrude.design.query.spaces.getFootprint(space)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "ContourHandle | null"
   },
   {
     "path": "design.selection.add",
     "namespace": "design.selection",
-    "summary": "Add entities to the current selection.",
-    "examplePrompts": [],
+    "summary": "Add entities to the current selection without deselecting anything — the selection grows to include the given entities alongside whatever was already selected.",
+    "examplePrompts": [
+      "Add the corridor to my current selection",
+      "Select these columns too, keeping what's already selected",
+      "Also select the roof",
+      "Extend the selection to include all the doors on this floor\n\n# Example\n```ts\n// Grow the selection to include every roof, keeping what's already selected\nconst roofs = await snaptrude.design.query.listRoofs()\nawait snaptrude.design.selection.add(roofs)\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.selection.clear",
     "namespace": "design.selection",
-    "summary": "Clear the selection (≡ `set([])`).",
-    "examplePrompts": [],
+    "summary": "Clear the selection so nothing is selected (equivalent to `set([])`).",
+    "examplePrompts": [
+      "Deselect everything",
+      "Clear my current selection",
+      "Unselect all objects in the scene",
+      "Make sure nothing is selected before we start\n\n# Example\n```ts\nconst { affected } = await snaptrude.design.selection.clear()\n// affected is the resulting selection — always [] here\n```"
+    ],
     "argsType": null,
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.selection.get",
     "namespace": "design.selection",
-    "summary": "Get the currently-selected entities.",
-    "examplePrompts": [],
+    "summary": "Read the current scene selection — the entities the user (or a previous call) has selected, returned as handles you can pass straight into other API calls.",
+    "examplePrompts": [
+      "What do I have selected right now?",
+      "List the currently selected objects",
+      "Which rooms are selected in the scene?",
+      "Get the ids of everything I've selected",
+      "Is anything selected?\n\n# Example\n```ts\n// Selection handles feed straight into other API calls\nconst selection = await snaptrude.design.selection.get()\nif (selection.length > 0) {\nconst props = await snaptrude.design.query.getProperties(selection[0])\n}\n```"
+    ],
     "argsType": null,
     "resultType": "ComponentHandle[]"
   },
   {
     "path": "design.selection.remove",
     "namespace": "design.selection",
-    "summary": "Remove entities from the current selection.",
-    "examplePrompts": [],
+    "summary": "Remove entities from the current selection — the given entities are deselected while everything else stays selected.",
+    "examplePrompts": [
+      "Deselect the stair core but keep the rest selected",
+      "Remove these walls from my selection",
+      "Take the furniture out of the current selection",
+      "Unselect the two smaller rooms\n\n# Example\n```ts\n// Deselect the furniture while keeping everything else selected\nconst furniture = await snaptrude.design.query.listFurniture({ isSelected: true })\nawait snaptrude.design.selection.remove(furniture)\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.selection.set",
     "namespace": "design.selection",
-    "summary": "Replace the selection with exactly the given entities.",
-    "examplePrompts": [],
+    "summary": "Replace the selection with exactly the given entities — anything previously selected is deselected first, so afterwards only these entities are selected.",
+    "examplePrompts": [
+      "Select these three walls",
+      "Select only the kitchen and deselect everything else",
+      "Change the selection to just these rooms",
+      "Highlight the spaces on the second storey\n\n# Example\n```ts\n// Select only the ground-storey walls (replaces the previous selection)\nconst walls = await snaptrude.design.query.listWalls({ storeys: [1] })\nconst { affected } = await snaptrude.design.selection.set(walls)\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
+  {
+    "path": "design.selection.setByFilter",
+    "namespace": "design.selection",
+    "summary": "Replace the selection with every visible entity of the active building that matches the filter — the programmatic equivalent of the editor's **Story selection** (`storeys`) and **Filter selection** (`types`) menus under the select tool, including their combination (fields AND, values within a field OR). Reaches selection-only kinds the query surface cannot (sites, terrain, CAD/PDF/image imports, dimension lines, 3D models, neighborhood buildings) and selects whole groups the way the editor does.",
+    "examplePrompts": [
+      "Select everything on storey 2",
+      "Select all the walls and doors",
+      "Story selection: select the ground floor and first floor",
+      "Filter selection: select all furniture in the model",
+      "Select only the furniture on the second storey",
+      "Select all the spaces so I can recolor them\n\n# Example\n```ts\n// \"Story selection\": everything on storeys 1 and 2\nawait snaptrude.design.selection.setByFilter({ storeys: [1, 2] })\n\n// \"Filter selection\": all walls and doors\nawait snaptrude.design.selection.setByFilter({ types: [\"wall\", \"door\"] })\n\n// Combined: only the furniture on storey 2\nconst { affected } = await snaptrude.design.selection.setByFilter({\nstoreys: [2],\ntypes: [\"furniture\"],\n})\n```"
+    ],
+    "argsType": "PluginSelectionFilter",
+    "resultType": "PluginDesignChangeResult"
+  },
+  {
+    "path": "design.transform.align",
+    "namespace": "design.transform",
+    "summary": "Align a set of components by snapping one bounding-box edge to a common value — the classic Left/Center/Right/Top/Middle/Bottom align. Purely **world-axis** (deterministic and headless — the UI's camera-relative remap is bypassed):",
+    "examplePrompts": [
+      "Align the selected rooms to the left",
+      "Line up these masses along their top edges",
+      "Center these columns horizontally",
+      "Align all the walls to the left edge of this reference wall",
+      "Snap the bottom edges of these spaces together\n\n# Example\n```ts\nconst rooms = await snaptrude.design.selection.get()\n// align every room's left (world -X) edge to a common minimum\nawait snaptrude.design.transform.align(rooms, \"left\")\n// …or align them to a fixed reference component's left edge\nconst [anchor] = await snaptrude.design.query.listWalls({ storeys: [1] })\nawait snaptrude.design.transform.align(rooms, \"left\", { reference: anchor })\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
@@ -2888,7 +4735,13 @@
     "path": "design.transform.move",
     "namespace": "design.transform",
     "summary": "Translate entities by a **relative** displacement vector (added to the first component's absolute position as the anchor). Undoable.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Move the selected room 5 metres to the right",
+      "Shift these walls 3m along the x axis",
+      "Nudge this space 500mm north",
+      "Translate the furniture block by (10, 0, 5)",
+      "Move these masses up one storey\n\n# Example\n```ts\nconst { vec3 } = snaptrude.core.math\nawait snaptrude.design.transform.move([\"space-id\"], vec3.new(10, 0, 0))\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
@@ -2896,95 +4749,252 @@
     "path": "design.transform.rotate",
     "namespace": "design.transform",
     "summary": "Rotate entities by a **signed angle in DEGREES**, anchored at the combined bounding-box centre (positive = CCW about +Y). NOTE: unlike the removed `tools.transform.rotate` (radians + caller pivot), this canonical form takes DEGREES and has NO caller pivot — the pivot is always the bbox centre. Undoable.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Rotate the selected building 90 degrees",
+      "Turn this room 45 degrees clockwise",
+      "Spin the furniture block 180 degrees about its centre",
+      "Rotate these masses 30 degrees around the vertical axis\n\n# Example\n```ts\nawait snaptrude.design.transform.rotate([\"space-id\"], 90)\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.unlock",
     "namespace": "design",
-    "summary": "Unlock entities. Undoable. Paired with {@linkcode PluginDesignApi.lock}.",
-    "examplePrompts": [],
+    "summary": "Unlock previously locked entities so they can be edited again. Undoable. Paired with {@linkcode PluginDesignApi.lock}.",
+    "examplePrompts": [
+      "Unlock the selected objects",
+      "Make this locked wall editable again",
+      "Unfreeze the masses I locked earlier",
+      "Remove the lock from these doors\n\n# Example\n```ts\n// Unlock everything that is explicitly locked\nconst locked = await snaptrude.design.listLocked()\nconst { affected } = await snaptrude.design.unlock(locked)\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
+  {
+    "path": "design.unlockArea",
+    "namespace": "design",
+    "summary": "Unlock the footprint area of previously area-locked spaces so their area can change again. Paired with {@linkcode PluginDesignApi.lockArea}; cascades to instances + source; undoable. Requires the `area_lock` feature (throws if off).",
+    "examplePrompts": [
+      "Unlock the area of the selected rooms",
+      "Remove the footprint-area lock from this department",
+      "Let me resize this space again by unlocking its area",
+      "Area-unlock everything I locked earlier\n\n# Example\n```ts\nconst locked = await snaptrude.design.listAreaLocked()\nconst { affected } = await snaptrude.design.unlockArea(locked)\n```"
+    ],
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.update.setLabel",
+    "namespace": "design.update",
+    "summary": "Set a component's **Label** — the same editable Label field the properties panel shows (doors, windows, furniture, spaces, and every other labelled component). The paired read is `design.query.getLabel`. Undoable; the canvas label text updates immediately.",
+    "examplePrompts": [
+      "Rename this door to D-101",
+      "Number all doors on storey 2 with a D-2-XX tag",
+      "Set the selected window's label to W-04",
+      "Tag every door with its fire rating\n\n# Example\n```ts\n// Door tag numbering: label every door as D-<storey>-<n>, numbered per storey\nawait snaptrude.design.selection.setByFilter({ types: [\"door\"] })\nconst doors = await snaptrude.design.selection.get()\nconst counts = {}\nfor (const door of doors) {\nconst { storey = 0 } = await snaptrude.design.query.getProperties(door)\ncounts[storey] = (counts[storey] ?? 0) + 1\nawait snaptrude.design.update.setLabel(door, `D-${storey}-${String(counts[storey]).padStart(2, \"0\")}`)\n}\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "boolean"
+  },
   {
     "path": "design.update.space",
     "namespace": "design.update",
-    "summary": "Update ONE space — sparse `properties` and/or a `geometry` re-extrude. Undoable.",
-    "examplePrompts": [],
+    "summary": "Update a single space (room) — change its properties (room label, space type, mass type, area class, department) and/or replace its geometry by re-extruding a profile to a new height. Sparse and undoable: only the fields you provide change.",
+    "examplePrompts": [
+      "Rename this room to Office",
+      "Change this space's room type to Meeting Room",
+      "Set the height of this room to 3 metres",
+      "Move this space into the Circulation department",
+      "Exclude this room from the area calculations\n\n# Example\n```ts\nawait snaptrude.design.update.space(\"space-id\", { properties: { room_type: \"Office\" } })\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginSpaceUpdateResult"
   },
   {
     "path": "design.update.spaces",
     "namespace": "design.update",
-    "summary": "Update **many spaces** in one undoable operation (bulk plural of {@linkcode space}). Migrated from `entity.space.bulkUpdate`. Validate-all-or-throw; one command.",
-    "examplePrompts": [],
+    "summary": "Update many spaces (rooms) in one undoable operation — the bulk form of {@linkcode space}. Each item pairs a space with the sparse property changes and/or geometry re-extrude to apply; every item is validated up front, then all changes are applied as a single command.",
+    "examplePrompts": [
+      "Label all the selected rooms as Bedrooms",
+      "Change the room type of these five spaces at once",
+      "Set every room on this floor to a 3m height in one go",
+      "Bulk-assign these spaces to the Service department",
+      "Mark all of these rooms as excluded from area in one update\n\n# Example\n```ts\n// Re-label every selected room and mark it NET area — one undoable bulk update\nconst rooms = await snaptrude.design.query.listSpaces({ isSelected: true })\nconst results = await snaptrude.design.update.spaces(\nrooms.map((space) => ({\nspace,\nproperties: { room_type: \"Bedroom\", areaClass: \"NET\" },\n})),\n)\n// One result per item, in input order\nconsole.log(results.map((r) => r.spaceId))\n```"
+    ],
     "argsType": "PluginUpdateSpaceItem[]",
     "resultType": "PluginSpaceUpdateResult[]"
   },
+  {
+    "path": "design.update.staircase",
+    "namespace": "design.update",
+    "summary": "Update the parameters of one or more staircases — riser, tread, width, depth, step count, total height, well size, landing depth, base offset, and the two height locks — in one undoable operation. Sparse: only the fields you provide change. The paired read is `design.query.getStaircaseParams`.",
+    "examplePrompts": [
+      "Set the riser of this staircase to 165mm",
+      "Change all the stairs to 14 steps",
+      "Make the selected staircase 1200 wide with a 280 tread",
+      "Widen every staircase on level 1 to 1 metre",
+      "Unlock the height and set this stair to 3200 tall\n\n# Example\n```ts\n// Give every ground-floor staircase a common riser + tread (engine units)\nconst stairs = await snaptrude.design.query.listStaircases({ storeys: [1] })\nconst { affected } = await snaptrude.design.update.staircase(stairs, {\nriser: 165,\ntread: 280,\n})\nconsole.log(\"updated\", affected.length, \"staircases\")\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
+  {
+    "path": "design.windows.exists",
+    "namespace": "design.windows",
+    "summary": "Test whether a window catalog item exists for the given library id.",
+    "examplePrompts": [
+      "Is this window still in the library?",
+      "Check whether a window catalog item with this id exists",
+      "Does my team library have this window?",
+      "Verify the window is available before placing it\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.windows.listCatalog()\nconst stillAvailable = await snaptrude.design.windows.exists(entry.id)\nconsole.log(stillAvailable ? \"safe to place\" : \"removed from library\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "design.windows.getCatalogItem",
+    "namespace": "design.windows",
+    "summary": "Get a single window catalog item by its library id.",
+    "examplePrompts": [
+      "Get the details of this window from the library",
+      "Look up the catalog entry for this window id",
+      "What is the cost of this window item?",
+      "Show me the family name of this window in the catalog\n\n# Example\n```ts\nconst [entry] = await snaptrude.design.windows.listCatalog()\nconst item = await snaptrude.design.windows.getCatalogItem(entry.id)\nif (item) console.log(item.name, item.source, item.dbType)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem | null"
+  },
   {
     "path": "design.windows.getDimensions",
     "namespace": "design.windows",
-    "summary": "Get a window's dimensions (local oriented space; `thickness` = through-wall depth).",
-    "examplePrompts": [],
+    "summary": "Get a window's full dimensions in one call — width along the wall, vertical height, and thickness through the wall — measured in the window's local oriented space.",
+    "examplePrompts": [
+      "What are the dimensions of this window?",
+      "How big is the selected window?",
+      "Give me the width, height and depth of this window",
+      "Measure the living room window",
+      "Get the window size including its thickness through the wall\n\n# Example\n```ts\nconst [win] = await snaptrude.design.query.listWindows({ isSelected: true })\nconst dims = await snaptrude.design.windows.getDimensions(win)\nif (dims) console.log(dims.width, dims.height, dims.thickness)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginWindowDimensions | null"
   },
   {
     "path": "design.windows.getHeight",
     "namespace": "design.windows",
-    "summary": "Get a window's height.",
-    "examplePrompts": [],
+    "summary": "Get the height of a window — how tall its opening is on the host wall.",
+    "examplePrompts": [
+      "How tall is this window?",
+      "What's the height of the selected window?",
+      "Check the window height on this wall",
+      "Is the bedroom window 1.5m high?\n\n# Example\n```ts\nconst [win] = await snaptrude.design.query.listWindows()\nconst height = await snaptrude.design.windows.getHeight(win)\nif (height !== null) console.log(\"window height:\", height)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "number | null"
   },
   {
     "path": "design.windows.getType",
     "namespace": "design.windows",
-    "summary": "Get a window's type name.",
-    "examplePrompts": [],
+    "summary": "Get the type name of a window — the label that identifies which kind of window the instance is, as shown in its properties.",
+    "examplePrompts": [
+      "What type of window is this?",
+      "Is the selected window a casement or a slider?",
+      "Tell me the window type used on this wall",
+      "Check what kind of window the living room has\n\n# Example\n```ts\nconst [win] = await snaptrude.design.query.listWindows({ isSelected: true })\nconst type = await snaptrude.design.windows.getType(win)\nif (type) console.log(\"window type:\", type)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "string | null"
   },
   {
     "path": "design.windows.getWidth",
     "namespace": "design.windows",
-    "summary": "Get a window's width.",
-    "examplePrompts": [],
+    "summary": "Get the width of a window — how wide its opening is along the host wall.",
+    "examplePrompts": [
+      "How wide is this window?",
+      "What's the width of the selected window?",
+      "Measure the width of the kitchen window",
+      "Check whether this window is 1200mm wide\n\n# Example\n```ts\nconst [win] = await snaptrude.design.query.listWindows()\nconst width = await snaptrude.design.windows.getWidth(win)\nif (width !== null) console.log(\"window width:\", width)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "number | null"
   },
+  {
+    "path": "design.windows.listCatalog",
+    "namespace": "design.windows",
+    "summary": "List the placeable window catalog (team + general libraries), optionally restricted to one group by its `dbType` token.",
+    "examplePrompts": [
+      "What windows can I place in this project?",
+      "List every window in the library",
+      "Show me the casement windows I can add",
+      "Browse the window catalog\n\n# Example\n```ts\nconst [group] = await snaptrude.design.windows.listCatalogGroups()\nconst items = await snaptrude.design.windows.listCatalog(group?.dbType)\nfor (const item of items) console.log(item.id, item.name, item.thumbnailUrl)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginObjectCatalogItem[]"
+  },
+  {
+    "path": "design.windows.listCatalogGroups",
+    "namespace": "design.windows",
+    "summary": "List the window catalog **groups** — the placement families (Fixed, Casement, Sliding, Folding, …), built-in groups merged with any team-custom types.",
+    "examplePrompts": [
+      "What kinds of windows can I place?",
+      "List the window groups in the catalog",
+      "Show me the window families available in this project",
+      "Which window types does this project support?\n\n# Example\n```ts\nconst groups = await snaptrude.design.windows.listCatalogGroups()\nfor (const g of groups) console.log(g.dbType, g.label, g.source)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginObjectCatalogGroup[]"
+  },
   {
     "path": "design.windows.setHeight",
     "namespace": "design.windows",
-    "summary": "Set a window's height (engine units; re-cuts the host wall). Undoable.",
-    "examplePrompts": [],
+    "summary": "Set the height of a window, resizing its opening and re-cutting the host wall. Height is in engine units; the change is undoable.",
+    "examplePrompts": [
+      "Make this window 1.5m tall",
+      "Change the window height to 4 feet",
+      "Shorten the selected window to 900mm high",
+      "Set the bedroom window height to 1200\n\n# Example\n```ts\nconst [win] = await snaptrude.design.query.listWindows({ isSelected: true })\nawait snaptrude.design.windows.setHeight(win, 1500)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "design.windows.setWidth",
     "namespace": "design.windows",
-    "summary": "Set a window's width (engine units; re-cuts the host wall). Undoable.",
-    "examplePrompts": [],
+    "summary": "Set the width of a window, resizing its opening and re-cutting the host wall. Width is in engine units; the change is undoable.",
+    "examplePrompts": [
+      "Make this window 1200mm wide",
+      "Widen the selected window to 4 feet",
+      "Change the window width to 1.5m",
+      "Resize the kitchen window to 900 wide\n\n# Example\n```ts\n// Takes a single window (unlike design.doors.setWidth, which takes an array)\nconst [win] = await snaptrude.design.query.listWindows({ isSelected: true })\nconst { affected } = await snaptrude.design.windows.setWidth(win, 1200)\n```"
+    ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
   },
   {
     "path": "entity.buildableEnvelope.create",
     "namespace": "entity.buildableEnvelope",
-    "summary": "Create a new parametric buildable envelope.",
-    "examplePrompts": [],
+    "summary": "Create a new parametric buildable envelope — the zoning-regulated volume a building may occupy — generated from a site polygon, tiered setbacks, a height or floor-count cap, and optional FAR and lot-coverage limits.",
+    "examplePrompts": [
+      "Create a buildable envelope for my site",
+      "Generate the zoning envelope with 10ft front setbacks",
+      "Show the maximum buildable volume with a 150ft height limit",
+      "Model the allowable massing from the setback rules",
+      "Create a zoning envelope capped at 12 floors with FAR 3\n\n# Example\n```ts\nconst { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.create(\n[\n{ x: 0, z: 0 },\n{ x: 100, z: 0 },\n{ x: 100, z: 80 },\n{ x: 0, z: 80 },\n],\n\"ft\",\n[\n{ aboveHeight: 0, front: 10, side: 5, rear: 10 },\n{ aboveHeight: 100, front: 20, side: 10, rear: 20 },\n],\n{ kind: \"max_height\", maxHeight: 150 },\n12,\n)\n```"
+    ],
     "argsType": "PluginBuildableEnvelopePolygonVertex[]",
     "resultType": "PluginBuildableEnvelopeCreateResult"
   },
   {
     "path": "entity.buildableEnvelope.update",
     "namespace": "entity.buildableEnvelope",
-    "summary": "Update an existing parametric buildable envelope.",
-    "examplePrompts": [],
+    "summary": "Update an existing parametric buildable envelope — regenerate the zoning volume from a revised site polygon, setbacks, vertical cap, or FAR and lot-coverage limits, keeping the same envelope id.",
+    "examplePrompts": [
+      "Change the envelope's height limit to 175 feet",
+      "Update the setbacks on the buildable envelope",
+      "Regenerate the zoning envelope with a new site boundary",
+      "Increase the FAR on the buildable volume",
+      "Modify the envelope to allow 15 storeys instead\n\n# Example\n```ts\nconst { buildableEnvelopeId } = await snaptrude.entity.buildableEnvelope.update(\nexistingId,\n[\n{ x: 0, z: 0 },\n{ x: 100, z: 0 },\n{ x: 100, z: 80 },\n{ x: 0, z: 80 },\n],\n\"ft\",\n[{ aboveHeight: 0, front: 10, side: 5, rear: 10 }],\n{ kind: \"max_height\", maxHeight: 175 },\n12,\n)\n```"
+    ],
     "argsType": "string",
     "resultType": "PluginBuildableEnvelopeUpdateResult"
   },
@@ -2992,7 +5002,13 @@
     "path": "entity.referenceLine.createMulti",
     "namespace": "entity.referenceLine",
     "summary": "Create multiple reference lines from a profile.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Draw grid lines across the site",
+      "Create reference lines from these curves",
+      "Add alignment guides along the building edge",
+      "Set up a structural grid using guide lines",
+      "Turn this profile into reference lines\n\n# Example\n```ts\nconst { vec3 } = snaptrude.core.math\n\nconst start = await vec3.new(0, 0, 0)\nconst mid = await vec3.new(10, 0, 0)\nconst end = await vec3.new(10, 0, 10)\nconst l1 = await snaptrude.core.geom.create.line(start, mid)\nconst l2 = await snaptrude.core.geom.create.line(mid, end)\nconst profile = await snaptrude.core.geom.create.profileFromCurves([l1, l2])\n\nconst { referenceLineIds } = await snaptrude.entity.referenceLine.createMulti(profile)\n```"
+    ],
     "argsType": "ProfileHandle",
     "resultType": "PluginReferenceLineCreateMultiResult"
   },
@@ -3000,7 +5016,12 @@
     "path": "entity.referenceLine.delete",
     "namespace": "entity.referenceLine",
     "summary": "Delete a reference line by its ID.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Delete this reference line",
+      "Remove the grid line I just drew",
+      "Get rid of the alignment guide on the left",
+      "Erase a reference line by its id\n\n# Example\n```ts\nawait snaptrude.entity.referenceLine.delete(\"some-ref-line-id\")\n```"
+    ],
     "argsType": "string",
     "resultType": "PluginReferenceLineDeleteResult"
   },
@@ -3008,7 +5029,12 @@
     "path": "entity.referenceLine.get",
     "namespace": "entity.referenceLine",
     "summary": "Get properties of a reference line by its ID.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Get the curve geometry of this reference line",
+      "Where does this grid line run?",
+      "Read the geometry of a guide line by its id",
+      "Look up the curve of the selected reference line\n\n# Example\n```ts\nconst result = await snaptrude.entity.referenceLine.get(\"some-ref-line-id\", [\"curve\"])\n// result.curve is an opaque CurveHandle; a dedicated curve read API for its\n// coordinates is exposed separately via `snaptrude.core.geom.curve`.\n```"
+    ],
     "argsType": "string",
     "resultType": "PluginReferenceLineGetResult"
   },
@@ -3016,7 +5042,12 @@
     "path": "entity.referenceLine.getAll",
     "namespace": "entity.referenceLine",
     "summary": "Get the IDs of all reference lines in the current project.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How many grid lines are in the project?",
+      "List all the reference lines in my model",
+      "Show every guide line in the file",
+      "Do I have any reference lines in this project?\n\n# Example\n```ts\nconst { referenceLineIds } = await snaptrude.entity.referenceLine.getAll()\nconsole.log(`Project has ${referenceLineIds.length} reference lines`)\n```"
+    ],
     "argsType": null,
     "resultType": "PluginReferenceLineGetAllResult"
   },
@@ -3024,15 +5055,40 @@
     "path": "entity.story.create",
     "namespace": "entity.story",
     "summary": "Create a new story (floor) in the project.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "Add a third floor to the building",
+      "Create a new storey above the second floor",
+      "Add a basement level to this project",
+      "Insert a new level with a custom floor height",
+      "Add another floor on top of the building\n\n# Example\n```ts\n// Create a new third floor with custom height\nconst { storyId } = await snaptrude.entity.story.create(3, 4.5)\n```"
+    ],
     "argsType": "number",
     "resultType": "PluginStoryCreateResult"
   },
+  {
+    "path": "entity.story.duplicate",
+    "namespace": "entity.story",
+    "summary": "Duplicate a story into the adjacent level, up or down.",
+    "examplePrompts": [
+      "Duplicate this floor to the storey above",
+      "Copy the ground floor down into a new basement",
+      "Repeat this level upwards with its own independent geometry",
+      "Duplicate just the selected walls onto the next floor up\n\n# Example\n```ts\n// Duplicate the whole active story one level up (instanced copies).\nconst { targetStories, created, skipped } =\nawait snaptrude.entity.story.duplicate(\"up\")\nconsole.log(`Copied ${created.length} elements onto story ${targetStories}`)\nif (skipped) console.log(`${skipped} elements were skipped`)\n```"
+    ],
+    "argsType": "\"up\" | \"down\"",
+    "resultType": "PluginStoryDuplicateResult"
+  },
   {
     "path": "entity.story.get",
     "namespace": "entity.story",
     "summary": "Get properties of a story by its storey number.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "What is the height of the ground floor?",
+      "How many rooms are on the second storey?",
+      "Get the total floor area of level 3",
+      "Is the first floor hidden in the viewport?",
+      "Show me the name and height of story 2\n\n# Example\n```ts\nconst info = await snaptrude.entity.story.get(1, [\"height\", \"name\", \"spacesCount\"])\nconsole.log(info.name, info.height, info.spacesCount)\n```"
+    ],
     "argsType": "number",
     "resultType": "PluginStoryGetResult"
   },
@@ -3040,15 +5096,25 @@
     "path": "entity.story.getAll",
     "namespace": "entity.story",
     "summary": "Get all stories in the current project.",
-    "examplePrompts": [],
+    "examplePrompts": [
+      "How many floors does this building have?",
+      "List all the storeys in the project",
+      "Show me every level with its name",
+      "Which stories exist in this model?\n\n# Example\n```ts\nconst { stories } = await snaptrude.entity.story.getAll()\nfor (const s of stories) {\nconsole.log(`Story ${s.value}: ${s.name} (id: ${s.id})`)\n}\n```"
+    ],
     "argsType": null,
     "resultType": "PluginStoryGetAllResult"
   },
   {
     "path": "entity.story.update",
     "namespace": "entity.story",
-    "summary": "Update a story's height.",
-    "examplePrompts": [],
+    "summary": "Update a story's floor-to-floor height, cascading the full geometry change.",
+    "examplePrompts": [
+      "Change the ground floor height to 3.5 metres",
+      "Make the second storey taller",
+      "Set the floor-to-floor height of level 1",
+      "Increase the height of the third floor\n\n# Example\n```ts\n// Set ground floor height to 5 Babylon units — walls stretch and the\n// floors above move up to match, all in a single undo step.\nconst result = await snaptrude.entity.story.update(1, 5)\n```"
+    ],
     "argsType": "number",
     "resultType": "PluginStoryUpdateResult"
   },
@@ -3090,6 +5156,19 @@
     "argsType": "{ url?: string; dataUrl?: string }",
     "resultType": "PluginPresentationImportResult"
   },
+  {
+    "path": "presentation.import.svg",
+    "namespace": "presentation.import",
+    "summary": "Import an SVG onto the current Present sheet as a vector asset.",
+    "examplePrompts": [
+      "Import this SVG diagram onto the present canvas",
+      "Add a vector logo to my presentation board",
+      "Place this SVG floor plan on the current sheet as vectors",
+      "Bring a crisp vector graphic into Present mode\n\n# Example\n```ts\nconst { shapeIds } = await snaptrude.presentation.import.svg({\nurl: \"https://example.com/diagram.svg\",\n})\n```"
+    ],
+    "argsType": "{ url?: string; dataUrl?: string }",
+    "resultType": "PluginPresentationImportResult"
+  },
   {
     "path": "presentation.sheets.create",
     "namespace": "presentation.sheets",
@@ -3190,6 +5269,19 @@
     "argsType": null,
     "resultType": "PluginPresentationViewsGetResult"
   },
+  {
+    "path": "presentation.views.getSettings",
+    "namespace": "presentation.views",
+    "summary": "Read a saved view's display settings (background, color mode, axis, edges, labels).",
+    "examplePrompts": [
+      "What color mode is the Ground Floor view using?",
+      "Get the display settings for this view",
+      "Does the site plan view show axes and labels?",
+      "Read the background color of the active view\n\n# Example\n```ts\nconst settings = await snaptrude.presentation.views.getSettings(\"view_123\")\nif (settings) console.log(settings.colorMode, settings.backgroundColor)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationViewsGetSettingsResult"
+  },
   {
     "path": "presentation.views.list",
     "namespace": "presentation.views",
@@ -3217,6 +5309,20 @@
     "argsType": "string",
     "resultType": "PluginPresentationViewsSetActiveResult"
   },
+  {
+    "path": "presentation.views.updateSettings",
+    "namespace": "presentation.views",
+    "summary": "Update a saved view's display settings (partial patch — only the fields you pass change).",
+    "examplePrompts": [
+      "Switch this view to monochrome color mode",
+      "Turn off the axis in the Ground Floor view",
+      "Set the background of the active view to white",
+      "Show area labels on this view",
+      "Enable hidden-line mode for the section view\n\n# Example\n```ts\nawait snaptrude.presentation.views.updateSettings(\"view_123\", {\ncolorMode: \"monochrome\",\nshowAxis: false,\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationViewsUpdateSettingsResult"
+  },
   {
     "path": "program.adjacency.compute",
     "namespace": "program.adjacency",
@@ -3250,6 +5356,8 @@
     "examplePrompts": [
       "What's my FAR right now?",
       "Give me the program area summary",
+      "What is my net internal area vs gross external area?",
+      "How much net and gross area do I have?",
       "How much built-up area have I used against the site area?",
       "Am I within my FAR target?\n\n# Example\n```ts\nconst s = await snaptrude.program.areas.get()\nconsole.log(s.builtUp, s.siteArea, s.achievedFar, s.targetFar, s.areaUnit)\n```"
     ],
@@ -3262,6 +5370,7 @@
     "summary": "List the program area rollup grouped by a facet.",
     "examplePrompts": [
       "Break down the area by storey",
+      "Break down net vs gross area by storey",
       "Show the area rollup per department",
       "Group the built-up area by building\n\n# Example\n```ts\nconst { groups } = await snaptrude.program.areas.list(\"storeys\")\nfor (const g of groups) console.log(g.name, g.builtUp, g.count)\n```"
     ],
@@ -3274,6 +5383,7 @@
     "summary": "List the spaces that make up one area group.",
     "examplePrompts": [
       "List the spaces on this storey with their areas",
+      "Which spaces are net and which are gross on this storey?",
       "What rooms are in the Bedrooms department bucket?",
       "Break the storey area down into individual spaces\n\n# Example\n```ts\nconst { members } = await snaptrude.program.areas.listMembers(\"storeys\", \"st_2\")\nfor (const m of members) console.log(m.label, m.carpet)\n```"
     ],
@@ -3434,6 +5544,54 @@
     "argsType": "string",
     "resultType": "PluginProgramDepartmentsUpdateResult"
   },
+  {
+    "path": "program.layout.arrange",
+    "namespace": "program.layout",
+    "summary": "Arrange the spaces inside the envelope using the computed adjacency data.",
+    "examplePrompts": [
+      "Arrange the rooms in the envelope",
+      "Lay out the departments inside the building envelope",
+      "Auto-arrange the program spaces\n\n# Example\n```ts\nconst { success, error } = await snaptrude.program.layout.arrange()\nif (!success) throw new Error(error)\n// poll until the layout is applied\nlet job = await snaptrude.program.layout.getState()\nwhile (job?.status === \"running\") {\nawait new Promise((r) => setTimeout(r, 5000))\njob = await snaptrude.program.layout.getState()\n}\n```"
+    ],
+    "argsType": "PluginProgramLayoutRunArgs",
+    "resultType": "PluginProgramLayoutRunResult"
+  },
+  {
+    "path": "program.layout.cancel",
+    "namespace": "program.layout",
+    "summary": "Cancel the in-flight layout run.",
+    "examplePrompts": [
+      "Cancel the arrange",
+      "Stop the running layout job",
+      "Abort the pack in envelope\n\n# Example\n```ts\nawait snaptrude.program.layout.cancel()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "program.layout.getState",
+    "namespace": "program.layout",
+    "summary": "Get the state of the layout run.",
+    "examplePrompts": [
+      "Is the arrange done?",
+      "Check the status of the layout run",
+      "Did the pack finish?\n\n# Example\n```ts\nconst job = await snaptrude.program.layout.getState()\nif (job?.status === \"active\") console.log(\"layout applied\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramLayoutStateResult"
+  },
+  {
+    "path": "program.layout.pack",
+    "namespace": "program.layout",
+    "summary": "Pack the spaces into the envelope (a tighter fit than arrange).",
+    "examplePrompts": [
+      "Pack the rooms into the envelope",
+      "Fit the program spaces tightly into the building",
+      "Run pack-in-envelope on this storey\n\n# Example\n```ts\nconst { success } = await snaptrude.program.layout.pack({ envelopeId: \"be_...\" })\nlet job = await snaptrude.program.layout.getState()\nwhile (job?.status === \"running\") {\nawait new Promise((r) => setTimeout(r, 5000))\njob = await snaptrude.program.layout.getState()\n}\n```"
+    ],
+    "argsType": "PluginProgramLayoutRunArgs",
+    "resultType": "PluginProgramLayoutRunResult"
+  },
   {
     "path": "program.metrics.get",
     "namespace": "program.metrics",
@@ -3488,6 +5646,30 @@
     "argsType": null,
     "resultType": "PluginProgramSiteContextResult"
   },
+  {
+    "path": "program.site.getLocation",
+    "namespace": "program.site",
+    "summary": "Get the project's geographic location.",
+    "examplePrompts": [
+      "What's the project's latitude and longitude?",
+      "Where is this site located?",
+      "Get the geographic coordinates of the project\n\n# Example\n```ts\nconst location = await snaptrude.program.site.getLocation()\nif (location) console.log(location.latitude, location.longitude)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSiteLocationResult"
+  },
+  {
+    "path": "program.site.getNorthAngle",
+    "namespace": "program.site",
+    "summary": "Get the site's true-north angle.",
+    "examplePrompts": [
+      "What's the north angle of the site?",
+      "How far is the model rotated from true north?",
+      "Get the project's true north direction\n\n# Example\n```ts\nconst northAngle = await snaptrude.program.site.getNorthAngle()\nif (northAngle !== null) console.log(`${northAngle}° from true north`)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSiteNorthAngleResult"
+  },
   {
     "path": "program.site.listGeoPolygons",
     "namespace": "program.site",