@snaptrude/plugin-core 0.8.0 → 0.9.0

package/api-manifest.full.json

@@ -1,4 +1,30 @@
 [
+  {
+    "path": "analysis.daylight.compute",
+    "namespace": "analysis.daylight",
+    "summary": "Compute annual daylight metrics for the model's spaces.",
+    "examplePrompts": [
+      "Run an LM-83 ASE daylight analysis on all my spaces",
+      "Which rooms fail annual sunlight exposure?",
+      "Compute ASE with a 0.6m sensor grid at desk height",
+      "Run an LM-83 sDA analysis with blinds operated",
+      "Which spaces meet sDA300/50%?",
+      "Compute sDA with 70% reflective ceilings and Tvis 0.6 glazing\n\n# Example\n```ts\nlet res = await snaptrude.analysis.daylight.compute({\nstandard: \"IES-LM-83-23\",\nmetrics: [\"sDA\", \"ASE\"],\ngrid: { spacingM: 0.6, workplaneHeightM: 0.76, boundaryOffsetM: 0.5 },\noptics: { materials: { \"Glass - Clear\": { transmittance: 0.6 } } },\n})\nconst runId = res.runId\nwhile (res.status === \"running\" && runId) {\nawait new Promise((r) => setTimeout(r, 5000))\nres = await snaptrude.analysis.daylight.poll({ runId })\n}\nconst failing = res.aggregates.filter(\n(a) => a.scope === \"space\" && (a.sdaPercent ?? 0) < 55,\n)\n```"
+    ],
+    "argsType": "PluginDaylightComputeArgs",
+    "resultType": "PluginDaylightResults"
+  },
+  {
+    "path": "analysis.daylight.poll",
+    "namespace": "analysis.daylight",
+    "summary": "Poll an asynchronous daylight run started by {@linkcode PluginAnalysisDaylightApi.compute}.",
+    "examplePrompts": [
+      "Check whether my sDA run has finished",
+      "Get the results of the daylight run"
+    ],
+    "argsType": "PluginDaylightPollArgs",
+    "resultType": "PluginDaylightResults"
+  },
   {
     "path": "analysis.heatmaps.isActive",
     "namespace": "analysis.heatmaps",
@@ -11,6 +37,79 @@
     "argsType": null,
     "resultType": "boolean"
   },
+  {
+    "path": "analysis.heatmaps.overlays.hide",
+    "namespace": "analysis.heatmaps.overlays",
+    "summary": "Hide an overlay without removing it.",
+    "examplePrompts": [
+      "Hide the wind overlay but keep it around",
+      "Temporarily hide my heatmap",
+      "Turn off the occupancy colours without deleting them\n\n# Example\n```ts\nawait snaptrude.analysis.heatmaps.overlays.hide(\"wind\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.heatmaps.overlays.list",
+    "namespace": "analysis.heatmaps.overlays",
+    "summary": "List the registered heatmap overlays.",
+    "examplePrompts": [
+      "Which heatmap overlays do I have?",
+      "List my rendered analysis overlays",
+      "Check which heatmap is currently visible\n\n# Example\n```ts\nconst { overlays } = await snaptrude.analysis.heatmaps.overlays.list()\nconst visible = overlays.find((o) => o.visible)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAnalysisHeatmapOverlaysListResult"
+  },
+  {
+    "path": "analysis.heatmaps.overlays.remove",
+    "namespace": "analysis.heatmaps.overlays",
+    "summary": "Remove an overlay — dispose its meshes and forget it.",
+    "examplePrompts": [
+      "Delete the wind overlay",
+      "Remove my occupancy heatmap for good",
+      "Free up an overlay slot\n\n# Example\n```ts\nawait snaptrude.analysis.heatmaps.overlays.remove(\"wind\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.heatmaps.overlays.removeAll",
+    "namespace": "analysis.heatmaps.overlays",
+    "summary": "Remove every registered overlay and close the legend.",
+    "examplePrompts": [
+      "Clear all my heatmap overlays",
+      "Remove every analysis overlay from the scene",
+      "Start over with a clean set of overlays\n\n# Example\n```ts\nconst removed = await snaptrude.analysis.heatmaps.overlays.removeAll()\n```"
+    ],
+    "argsType": null,
+    "resultType": "number"
+  },
+  {
+    "path": "analysis.heatmaps.overlays.show",
+    "namespace": "analysis.heatmaps.overlays",
+    "summary": "Make a registered overlay the visible one.",
+    "examplePrompts": [
+      "Switch back to my wind heatmap",
+      "Show the occupancy overlay",
+      "Flip between my two analysis overlays\n\n# Example\n```ts\nawait snaptrude.analysis.heatmaps.overlays.show(\"wind\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "analysis.heatmaps.renderField",
+    "namespace": "analysis.heatmaps",
+    "summary": "Render a heatmap from **arbitrary cell geometry** — planar polygons or pre-tessellated meshes, one scalar value each.",
+    "examplePrompts": [
+      "Overlay my FEA stress results on their solver mesh",
+      "Color these Voronoi regions by footfall",
+      "Paint each façade panel polygon by its PV yield",
+      "Render pass/fail daylight compliance per zone polygon\n\n# Example\n```ts\n// Two triangular cells at ground level, coloured pass/fail at 300 lux.\nawait snaptrude.analysis.heatmaps.renderField(\n[\n{ polygon: [{ x: 0, y: 0, z: 0 }, { x: 4, y: 0, z: 0 }, { x: 0, y: 0, z: 4 }], value: 420 },\n{ polygon: [{ x: 4, y: 0, z: 4 }, { x: 0, y: 0, z: 4 }, { x: 4, y: 0, z: 0 }], value: 180 },\n],\n{ title: \"Daylight\", unit: \"lux\", scale: { type: \"threshold\", threshold: 300 } },\n)\n```"
+    ],
+    "argsType": "PluginAnalysisHeatmapFieldCell[]",
+    "resultType": "PluginAnalysisHeatmapsRenderResult"
+  },
   {
     "path": "analysis.heatmaps.renderGrid",
     "namespace": "analysis.heatmaps",
@@ -35,10 +134,23 @@
     "argsType": "PluginAnalysisHeatmapSpaceEntry[]",
     "resultType": "PluginAnalysisHeatmapsRenderResult"
   },
+  {
+    "path": "analysis.heatmaps.renderSurfaceGrid",
+    "namespace": "analysis.heatmaps",
+    "summary": "Render a grid heatmap on an **arbitrarily oriented plane** — a façade, a section cut, any flat surface.",
+    "examplePrompts": [
+      "Paint the solar irradiance results on the south façade",
+      "Show my daylight values as a heatmap on this wall",
+      "Render panel-level PV yield on the building face",
+      "Overlay wind pressure on the tower's west elevation\n\n# Example\n```ts\n// Samples lie on a wall plane facing +X; colour each 1-unit cell by irradiance.\nawait snaptrude.analysis.heatmaps.renderSurfaceGrid(\nsamples.map((s) => ({ position: { x: wallX, y: s.y, z: s.z }, value: s.irradiance })),\n1,\n{ x: 1, y: 0, z: 0 }, // façade normal\n{ title: \"Irradiance\", unit: \"kWh/m²\", colors: [\"#0000ff\", \"#ffff00\", \"#ff0000\"] },\n)\n```"
+    ],
+    "argsType": "PluginAnalysisHeatmapGridCell[]",
+    "resultType": "PluginAnalysisHeatmapsRenderResult"
+  },
   {
     "path": "analysis.heatmaps.reset",
     "namespace": "analysis.heatmaps",
-    "summary": "Clear the plugin heatmap from the scene.",
+    "summary": "Clear every plugin heatmap overlay from the scene.",
     "examplePrompts": [
       "Clear my custom heatmap",
       "Remove the wind overlay from the model",
@@ -155,6 +267,18 @@
     "argsType": "string",
     "resultType": "PluginAnalysisShadowsDateTimeResult"
   },
+  {
+    "path": "analysis.solar.sampleGrid",
+    "namespace": "analysis.solar",
+    "summary": "Sample solar exposure at a set of points.",
+    "examplePrompts": [
+      "What's the irradiance at these facade points at noon on June 21?",
+      "How shaded are these balcony points across the summer?",
+      "Sample direct sun visibility at these roof points right now\n\n# Example\n```ts\nconst grid = await snaptrude.analysis.solar.sampleGrid({\npoints: [\n{ id: \"a\", position: [0, 3, 0] },\n{ id: \"b\", position: [5, 3, 0], normal: [0, 0, 1] },\n],\ndateTime: \"2026-06-21T12:00:00+05:30\",\n})\nfor (const r of grid.results) {\nconsole.log(r.id, r.directSunVisible, r.totalIrradiance, grid.units)\n}\n```"
+    ],
+    "argsType": "PluginSolarSampleGridArgs",
+    "resultType": "PluginSolarSampleGridResult"
+  },
   {
     "path": "analysis.sunlightHours.cancel",
     "namespace": "analysis.sunlightHours",
@@ -239,6 +363,18 @@
     "argsType": null,
     "resultType": "boolean"
   },
+  {
+    "path": "analysis.weather.getSeries",
+    "namespace": "analysis.weather",
+    "summary": "Get the hourly weather series for a date range, paged.",
+    "examplePrompts": [
+      "Get the weather series for June at my site",
+      "Pull the hourly temperature and irradiance for this location",
+      "What EPW weather file is my project using?\n\n# Example\n```ts\nlet cursor: string | undefined = undefined\nconst rows = []\ndo {\nconst page = await snaptrude.analysis.weather.getSeries({\nstartDate: \"2026-06-01\",\nendDate: \"2026-06-30\",\ncursor,\n})\nrows.push(...page.rows)\ncursor = page.nextCursor ?? undefined\n} while (cursor)\n```"
+    ],
+    "argsType": "PluginWeatherGetSeriesArgs",
+    "resultType": "PluginWeatherSeriesResult"
+  },
   {
     "path": "core.buildings.copy",
     "namespace": "core.buildings",
@@ -347,6 +483,18 @@
     "argsType": "string",
     "resultType": "PluginCoreBuildingsUpdateResult"
   },
+  {
+    "path": "core.camera.getProjection",
+    "namespace": "core.camera",
+    "summary": "Read the camera's current projection: `\"perspective\"` (the default 3D view) or `\"orthographic\"`. In 2D (plan) mode this always reports `\"orthographic\"` — a plan is an orthographic projection.",
+    "examplePrompts": [
+      "Is the camera in perspective or orthographic?",
+      "What projection is the 3D view using?",
+      "Check whether perspective is on\n\n# Example\n```ts\nconst projection = await snaptrude.core.camera.getProjection()\nconsole.log(projection) // \"perspective\" | \"orthographic\"\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCameraProjection"
+  },
   {
     "path": "core.camera.lookFrom",
     "namespace": "core.camera",
@@ -373,6 +521,19 @@
     "argsType": "PluginCameraMode",
     "resultType": "boolean"
   },
+  {
+    "path": "core.camera.setProjection",
+    "namespace": "core.camera",
+    "summary": "Switch the 3D camera between `\"perspective\"` and `\"orthographic\"` projection — the Perspective/Orthographic control in the Design tab's View Settings panel. Like {@linkcode PluginCameraApi.setMode}, this is a transient view-state change: not write-gated, not undoable.",
+    "examplePrompts": [
+      "Switch the camera to orthographic",
+      "Turn perspective off",
+      "Give me a perspective view of the model",
+      "Make the 3D view orthographic like an axonometric drawing\n\n# Example\n```ts\nawait snaptrude.core.camera.setProjection(\"orthographic\")\nconst projection = await snaptrude.core.camera.getProjection() // \"orthographic\"\n```"
+    ],
+    "argsType": "PluginCameraProjection",
+    "resultType": "boolean"
+  },
   {
     "path": "core.camera.setStandardView",
     "namespace": "core.camera",
@@ -387,6 +548,32 @@
     "argsType": "PluginStandardView",
     "resultType": "boolean"
   },
+  {
+    "path": "core.camera.zoomExtents",
+    "namespace": "core.camera",
+    "summary": "Zoom (fit) the camera to all geometry in the scene — the \"zoom extents\" action. View-state only — not undoable. Canonical home of the zoom-extents read (the deprecated `core.zoom.extents`).",
+    "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\n\n# Example\n```ts\nawait snaptrude.core.camera.zoomExtents()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
+  {
+    "path": "core.camera.zoomSelection",
+    "namespace": "core.camera",
+    "summary": "Zoom (fit) the camera to the current selection. View-state only — not undoable. Canonical home of the zoom-to-selection read (the deprecated `core.zoom.selection`).",
+    "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.camera.zoomSelection()\n```"
+    ],
+    "argsType": null,
+    "resultType": "boolean"
+  },
   {
     "path": "core.comment.create",
     "namespace": "core.comment",
@@ -413,6 +600,19 @@
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
+  {
+    "path": "core.comment.get",
+    "namespace": "core.comment",
+    "summary": "Read a comment's full detail — its text, author, pin location, resolved state, and reply thread. Comments are otherwise write-only; this is the read side. Pass a top-level comment handle or a reply handle (a reply has an empty `thread`). Returns `null` if the handle doesn't match a live comment.",
+    "examplePrompts": [
+      "Read the comment on this wall and tell me what it says",
+      "Who left this comment and where is it pinned?",
+      "Show me the full thread for this comment",
+      "Get the text and author of the selected comment\n\n# Example\n```ts\nconst [first] = await snaptrude.core.comment.list()\nconst details = await snaptrude.core.comment.get(first)\nconsole.log(details?.content, \"by\", details?.author?.name)\nconsole.log(`${details?.thread.length ?? 0} replies`)\n```"
+    ],
+    "argsType": "CommentHandle",
+    "resultType": "PluginCommentDetails | null"
+  },
   {
     "path": "core.comment.isResolved",
     "namespace": "core.comment",
@@ -452,6 +652,19 @@
     "argsType": "CommentHandle",
     "resultType": "boolean"
   },
+  {
+    "path": "core.comment.reply",
+    "namespace": "core.comment",
+    "summary": "Reply to a comment — posts a new comment threaded under `comment` (which must be a top-level comment, not itself a reply). Notifies the thread's participants, mirroring the sidebar Reply action.",
+    "examplePrompts": [
+      "Reply to this comment saying I fixed the wall height",
+      "Add a reply to the review note confirming it's done",
+      "Respond to the comment about the door with \"looks good now\"",
+      "Post a follow-up on the selected comment thread\n\n# Example\n```ts\nconst [thread] = await snaptrude.core.comment.list()\nconst reply = await snaptrude.core.comment.reply(thread, \"Fixed 👍\")\n```"
+    ],
+    "argsType": "CommentHandle",
+    "resultType": "CommentHandle"
+  },
   {
     "path": "core.comment.resolve",
     "namespace": "core.comment",
@@ -502,6 +715,90 @@
     "argsType": "Vec3Handle",
     "resultType": "ArcHandle"
   },
+  {
+    "path": "core.geom.create.brepFromExtrusion",
+    "namespace": "core.geom.create",
+    "summary": "Create a closed solid **B-rep** by extruding a contour along a direction. Host API call — returns a {@linkcode BrepHandle}. The direction is normalised by the host, so `amount` is the extrusion distance in raw Babylon units (negative extrudes the opposite way). The contour is copied — the input handle is never mutated. Holes and arc/circle profiles extrude natively (a circle profile yields a cylinder).",
+    "examplePrompts": [
+      "Extrude this profile 3 metres up",
+      "Make a solid by extruding this outline",
+      "Create a cylinder from a circle profile\n\n# Example\n```ts\nconst rect = await snaptrude.core.geom.create.profileRect(4, 3)\nconst contour = await snaptrude.core.geom.create.contourFromProfile(rect)\nconst brep = await snaptrude.core.geom.create.brepFromExtrusion(contour, { x: 0, y: 1, z: 0 }, 3)\nconst faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6\n```"
+    ],
+    "argsType": "ContourHandle",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromFaces",
+    "namespace": "core.geom.create",
+    "summary": "Create a closed solid **B-rep** from explicit face loops. Host API call — returns a {@linkcode BrepHandle}. Faces are plain arrays of `{x, y, z}` point components, NOT point handles (bulk-data precedent: `design.query.geometry.getTriangulatedMeshes`), in raw Babylon units.",
+    "examplePrompts": [
+      "Create a brep from faces",
+      "Build a custom solid from a set of faces",
+      "Make a pyramid from triangular faces\n\n# Example\n```ts\n// A pyramid: square base + 4 triangular sides\nconst apex = { x: 0, y: 4, z: 0 }\nconst a = { x: -2, y: 0, z: -2 }\nconst b = { x: 2, y: 0, z: -2 }\nconst c = { x: 2, y: 0, z: 2 }\nconst d = { x: -2, y: 0, z: 2 }\nconst brep = await snaptrude.core.geom.create.brepFromFaces([\n[a, d, c, b], // base\n[a, b, apex],\n[b, c, apex],\n[c, d, apex],\n[d, a, apex],\n])\nconst faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 5\n```"
+    ],
+    "argsType": "Vec3Components[][]",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromIntersection",
+    "namespace": "core.geom.create",
+    "summary": "Create a closed solid **B-rep** as the boolean **intersection** of two breps (`a ∩ b` — the shared volume only). Host API call — returns a new {@linkcode BrepHandle}. Inputs are read-only and may be authored or scene-derived breps (see {@linkcode PluginGeomCreateApi.brepFromUnion}); coordinates are combined as-is.",
+    "examplePrompts": [
+      "Keep only the overlap of these two solids",
+      "Intersect these two masses",
+      "Clip the tower to the zoning envelope\n\n# Example\n```ts\nconst overlap = await snaptrude.core.geom.create.brepFromIntersection(towerBrep, envelopeBrep)\n```"
+    ],
+    "argsType": "BrepHandle",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromLoft",
+    "namespace": "core.geom.create",
+    "summary": "Create a closed solid **B-rep** by lofting between a bottom and a top contour. Host API call — returns a {@linkcode BrepHandle}. Both contours must have the same number of edges (and matching hole counts); side faces connect corresponding edges by authored index. Corresponding edges must stay coplanar — a twisted loft would produce non-planar side faces and is rejected. The contours are copied — the input handles are never mutated.",
+    "examplePrompts": [
+      "Make a tapered tower from these two outlines",
+      "Loft between a large base and a smaller top",
+      "Create a frustum from two squares\n\n# Example\n```ts\n// A square frustum: 4m base lofted to a 2m top, 3m up\nconst base = await snaptrude.core.geom.create.profileRect(4, 4)\nconst top = await snaptrude.core.geom.create.profileRect(2, 2, await snaptrude.core.math.vec3.new(0, 3, 0))\nconst brep = await snaptrude.core.geom.create.brepFromLoft(\nawait snaptrude.core.geom.create.contourFromProfile(base),\nawait snaptrude.core.geom.create.contourFromProfile(top),\n)\nconst faceCount = await snaptrude.core.geom.query.brep.getFaceCount(brep) // 6\n```"
+    ],
+    "argsType": "ContourHandle",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromMesh",
+    "namespace": "core.geom.create",
+    "summary": "Create a closed solid **B-rep** from indexed mesh data: a vertex position array plus face loops of indices into it. Host API call — returns a {@linkcode BrepHandle}. The indexed form of {@linkcode PluginGeomCreateApi.brepFromFaces} — same validation (planar faces, closed manifold solid, every edge shared by exactly two faces) after the indices are expanded to point loops.",
+    "examplePrompts": [
+      "Create a brep from mesh vertices and indices",
+      "Turn this indexed mesh into a solid",
+      "Build a solid from vertex positions and face indices\n\n# Example\n```ts\n// A tetrahedron from 4 vertices and 4 triangular faces\nconst positions = [\n{ x: 0, y: 0, z: 0 },\n{ x: 4, y: 0, z: 0 },\n{ x: 2, y: 0, z: 4 },\n{ x: 2, y: 3, z: 1.5 },\n]\nconst brep = await snaptrude.core.geom.create.brepFromMesh(positions, [\n[0, 2, 1], // base\n[0, 1, 3],\n[1, 2, 3],\n[2, 0, 3],\n])\nconst vertexCount = await snaptrude.core.geom.query.brep.getVertexCount(brep) // 4\n```"
+    ],
+    "argsType": "Vec3Components[]",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromSubtraction",
+    "namespace": "core.geom.create",
+    "summary": "Create a closed solid **B-rep** as the boolean **subtraction** of two breps: **`a` minus `b`** — `b` is cut away from `a`. Host API call — returns a new {@linkcode BrepHandle}. Argument order matters: `brepFromSubtraction(a, b)` removes `b`'s volume from `a`. Inputs are read-only and may be authored or scene-derived breps (see {@linkcode PluginGeomCreateApi.brepFromUnion}); coordinates are combined as-is.",
+    "examplePrompts": [
+      "Subtract the courtyard from the building mass",
+      "Cut this solid out of that one",
+      "Punch a hole through the slab with this box\n\n# Example\n```ts\n// buildingBrep minus courtyardBrep — order matters\nconst carved = await snaptrude.core.geom.create.brepFromSubtraction(buildingBrep, courtyardBrep)\n```"
+    ],
+    "argsType": "BrepHandle",
+    "resultType": "BrepHandle"
+  },
+  {
+    "path": "core.geom.create.brepFromUnion",
+    "namespace": "core.geom.create",
+    "summary": "Create a closed solid **B-rep** as the boolean **union** of two breps (`a ∪ b`). Host API call — returns a new {@linkcode BrepHandle}. Inputs are read-only and may be authored breps (any `core.geom.create` brep constructor) or scene-derived breps from `design.query.geometry.getBrep`; coordinates are combined as-is, so both inputs must share a frame. The result must be a single solid — disjoint inputs are rejected.",
+    "examplePrompts": [
+      "Union these two solids",
+      "Merge these breps into one mass",
+      "Combine the tower and the podium into a single solid\n\n# Example\n```ts\nconst a = await snaptrude.core.geom.create.brepFromExtrusion(baseContour, { x: 0, y: 1, z: 0 }, 3)\nconst b = await snaptrude.core.geom.create.brepFromExtrusion(overlappingContour, { x: 0, y: 1, z: 0 }, 5)\nconst merged = await snaptrude.core.geom.create.brepFromUnion(a, b)\n```"
+    ],
+    "argsType": "BrepHandle",
+    "resultType": "BrepHandle"
+  },
   {
     "path": "core.geom.create.circle",
     "namespace": "core.geom.create",
@@ -581,7 +878,8 @@
     "summary": "Free a transient contour resource handle — releases its registry entry and reclaims its share of the plugin's resource quota. Handle-lifecycle only; does NOT tear down engine-side geometry, nor the contour's child profile handles.",
     "examplePrompts": [],
     "argsType": "ContourHandle",
-    "resultType": "void"
+    "resultType": "void",
+    "deprecated": "core.handles.release"
   },
   {
     "path": "core.geom.delete.profile",
@@ -589,7 +887,8 @@
     "summary": "Free a transient profile resource handle — releases its registry entry and reclaims its share of the plugin's resource quota. This is a handle-lifecycle operation only and does NOT tear down any engine-side geometry.",
     "examplePrompts": [],
     "argsType": "ProfileHandle",
-    "resultType": "void"
+    "resultType": "void",
+    "deprecated": "core.handles.release"
   },
   {
     "path": "core.geom.query.arc.getAxis",
@@ -2138,7 +2437,8 @@
       "Export the model as a GLB",
       "Give me the whole scene as an OBJ file",
       "Export just my selection to GLB",
-      "Download the model as a glTF binary\n\n# Example\n```ts\nconst file = await snaptrude.core.io.export.model(\"glb\")\n// decode base64 → bytes and save/download in the plugin UI\nconst bytes = Uint8Array.from(atob(file.dataBase64), (c) => c.charCodeAt(0))\nconst blob = new Blob([bytes], { type: file.mimeType })\n// ...offer blob for download as file.fileName\n\n// Only the current selection, as OBJ text:\nconst obj = await snaptrude.core.io.export.model(\"obj\", \"selection\")\nconst text = atob(obj.dataBase64)\n```"
+      "Download the model as an FBX file",
+      "Export the scene to 3DS for 3ds Max\n\n# Example\n```ts\nconst file = await snaptrude.core.io.export.model(\"glb\")\n// decode base64 → bytes and save/download in the plugin UI\nconst bytes = Uint8Array.from(atob(file.dataBase64), (c) => c.charCodeAt(0))\nconst blob = new Blob([bytes], { type: file.mimeType })\n// ...offer blob for download as file.fileName\n\n// Only the current selection, as OBJ text:\nconst obj = await snaptrude.core.io.export.model(\"obj\", \"selection\")\nconst text = atob(obj.dataBase64)\n```"
     ],
     "argsType": "ExportModelFormat",
     "resultType": "ExportedFile"
@@ -2168,6 +2468,18 @@
     "argsType": "string",
     "resultType": "ImportJobHandle"
   },
+  {
+    "path": "core.io.import.epw",
+    "namespace": "core.io.import",
+    "summary": "Import an **EPW weather file** into the project's weather catalog.",
+    "examplePrompts": [
+      "Import this EPW weather file for the site",
+      "Upload a custom weather file for the daylight analysis",
+      "Use this .epw as the project's weather source\n\n# Example\n```ts\nconst { weatherFileId, label } = await snaptrude.core.io.import.epw(\n\"https://example.com/Chicago-OHare.epw\",\n)\nconsole.log(`Weather set to ${label} (${weatherFileId})`)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginImportEpwResult"
+  },
   {
     "path": "core.io.import.image",
     "namespace": "core.io.import",
@@ -2871,6 +3183,41 @@
     "argsType": "Vec3Handle",
     "resultType": "Vec3Handle"
   },
+  {
+    "path": "core.mode.get",
+    "namespace": "core.mode",
+    "summary": "Get the currently active application mode.",
+    "examplePrompts": [
+      "Which mode am I in right now?",
+      "Am I in present mode?",
+      "Check whether the editor is in BIM mode\n\n# Example\n```ts\nconst mode = await snaptrude.core.mode.get()\nif (mode !== \"present\") await snaptrude.core.mode.set(\"present\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAppMode"
+  },
+  {
+    "path": "core.mode.list",
+    "namespace": "core.mode",
+    "summary": "List every application mode the editor has.",
+    "examplePrompts": [
+      "What modes does Snaptrude have?",
+      "List the editor modes I can switch to\n\n# Example\n```ts\nconst { modes } = await snaptrude.core.mode.list()\n// [\"design\", \"bim\", \"present\", \"program\"]\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCoreModeListResult"
+  },
+  {
+    "path": "core.mode.set",
+    "namespace": "core.mode",
+    "summary": "Switch the editor to another application mode — the same action as clicking that tab in the top menu bar.",
+    "examplePrompts": [
+      "Switch to present mode",
+      "Open BIM mode",
+      "Go back to design mode\n\n# Example\n```ts\nawait snaptrude.core.mode.set(\"present\")\n// ... presentation work ...\nawait snaptrude.core.mode.set(\"design\")\n```"
+    ],
+    "argsType": "PluginAppMode",
+    "resultType": "PluginCoreModeSetResult"
+  },
   {
     "path": "core.project.settings.getTolerance",
     "namespace": "core.project.settings",
@@ -3134,11 +3481,12 @@
   {
     "path": "core.proposals.create",
     "namespace": "core.proposals",
-    "summary": "Create a new design option (proposal).",
+    "summary": "Create a new design option (proposal) — blank, or configured from a base proposal (the New Proposal modal's two paths).",
     "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```"
+      "Duplicate the current proposal as Scheme C",
+      "Create a design option based on Proposal 1 that shares its site layer\n\n# Example\n```ts\n// blank design option\nconst { id } = await snaptrude.core.proposals.create(\"Scheme B\")\n\n// configured from the active proposal: duplicate every layer\nconst base = await snaptrude.core.proposals.getActive()\nif (base) {\nconst { id: dup } = await snaptrude.core.proposals.create(\"Scheme C\", {\nbaseProposalId: base.id,\n})\n// …or share one layer and leave the rest behind\nconst { id: shared } = await snaptrude.core.proposals.create(\"Scheme D\", {\nbaseProposalId: base.id,\nlayers: [{ bucketId: base.defaultBucketId, action: \"share\" }],\n})\n}\n```"
     ],
     "argsType": "string",
     "resultType": "PluginCoreProposalsCreateResult"
@@ -3239,6 +3587,98 @@
     "argsType": "string",
     "resultType": "PluginCoreProposalsSetActiveResult"
   },
+  {
+    "path": "core.storeys.copy",
+    "namespace": "core.storeys",
+    "summary": "Copy a storey into the adjacent level, up or down.",
+    "examplePrompts": [
+      "Copy this floor to the storey above",
+      "Copy the ground floor down into a new basement",
+      "Repeat this level upwards with its own independent geometry",
+      "Copy just the selected walls onto the next floor up\n\n# Example\n```ts\n// Copy the whole active storey one level up (instanced copies).\nconst { targetStories, created, skipped } =\nawait snaptrude.core.storeys.copy(\"up\")\nconsole.log(`Copied ${created.length} elements onto storey ${targetStories}`)\nif (skipped) console.log(`${skipped} elements were skipped`)\n```"
+    ],
+    "argsType": "\"up\" | \"down\"",
+    "resultType": "PluginStoryDuplicateResult"
+  },
+  {
+    "path": "core.storeys.create",
+    "namespace": "core.storeys",
+    "summary": "Create a new storey (floor) in the project.",
+    "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\n\n# Example\n```ts\n// Create a new third floor with custom height\nconst { storyId } = await snaptrude.core.storeys.create(3, 4.5)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "PluginStoryCreateResult"
+  },
+  {
+    "path": "core.storeys.delete",
+    "namespace": "core.storeys",
+    "summary": "Delete a storey and everything on it — the same as removing it from the storey panel. Every element placed on the storey (walls, floors, masses, …) is deleted with it, the remaining storeys are re-stacked, and the active storey falls back to an adjacent one. Committed as a single undo step.",
+    "examplePrompts": [
+      "Delete the top floor",
+      "Remove the basement level",
+      "Get rid of storey 3",
+      "Delete the second floor and everything on it\n\n# Example\n```ts\nconst { newActiveStory } = await snaptrude.core.storeys.delete(3)\nconsole.log(`Deleted storey 3; now on storey ${newActiveStory}`)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "PluginStoryDeleteResult"
+  },
+  {
+    "path": "core.storeys.get",
+    "namespace": "core.storeys",
+    "summary": "Get properties of a storey by its storey number.",
+    "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 storey 2\n\n# Example\n```ts\nconst info = await snaptrude.core.storeys.get(1, [\"height\", \"name\", \"spacesCount\"])\nconsole.log(info.name, info.height, info.spacesCount)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "PluginStoryGetResult"
+  },
+  {
+    "path": "core.storeys.list",
+    "namespace": "core.storeys",
+    "summary": "List all storeys in the current project.",
+    "examplePrompts": [
+      "How many floors does this building have?",
+      "List all the storeys in the project",
+      "Show me every level with its name",
+      "Which storeys exist in this model?\n\n# Example\n```ts\nconst { storeys } = await snaptrude.core.storeys.list()\nfor (const s of storeys) {\nconsole.log(`Storey ${s.value}: ${s.name} (id: ${s.id})`)\n}\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginCoreStoreysListResult"
+  },
+  {
+    "path": "core.storeys.setActive",
+    "namespace": "core.storeys",
+    "summary": "Make a storey the active storey — the same as clicking it in the storey/layer panel. Subsequent draws and creates target this storey, and in 2D the viewport switches to it. This is a view/navigation change: it is **not** undoable and commits nothing to the model.",
+    "examplePrompts": [
+      "Switch to the second floor",
+      "Make the ground storey active",
+      "Go to the basement level",
+      "Set level 3 as the current storey\n\n# Example\n```ts\n// Activate storey 2, then draw a wall — it lands on storey 2.\nawait snaptrude.core.storeys.setActive(2)\n```"
+    ],
+    "argsType": "number",
+    "resultType": "PluginStorySetActiveResult"
+  },
+  {
+    "path": "core.storeys.update",
+    "namespace": "core.storeys",
+    "summary": "Update a storey's floor-to-floor `height` and/or `name`.",
+    "examplePrompts": [
+      "Change the ground floor height to 3.5 metres",
+      "Make the second storey taller",
+      "Rename the ground floor to \"Lobby\"",
+      "Set the floor-to-floor height of level 1\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.core.storeys.update(1, 5)\n// Rename only, leaving the height untouched.\nawait snaptrude.core.storeys.update(1, undefined, { name: \"Lobby\" })\n```"
+    ],
+    "argsType": "number",
+    "resultType": "PluginStoryUpdateResult"
+  },
   {
     "path": "core.tags.assign",
     "namespace": "core.tags",
@@ -3333,7 +3773,8 @@
       "Show the labels applied to this room\n\n# Example\n```ts\nconst { tags } = await snaptrude.core.tags.getTagsForComponent(\"cmp_42\")\nfor (const t of tags) console.log(t.categoryName, t.tagName)\n```"
     ],
     "argsType": "ComponentHandle",
-    "resultType": "PluginCoreTagsGetTagsForComponentResult"
+    "resultType": "PluginCoreTagsGetTagsForComponentResult",
+    "deprecated": "core.tags.listForComponent"
   },
   {
     "path": "core.tags.list",
@@ -3371,6 +3812,18 @@
     "argsType": "{ tagId?: string; categoryId?: string; untagged?: boolean }",
     "resultType": "PluginCoreTagsListComponentsResult"
   },
+  {
+    "path": "core.tags.listForComponent",
+    "namespace": "core.tags",
+    "summary": "List the tags carried by a component.",
+    "examplePrompts": [
+      "What tags does this space have?",
+      "List the tags on component cmp_42",
+      "Show the labels applied to this room\n\n# Example\n```ts\nconst { tags } = await snaptrude.core.tags.listForComponent(\"cmp_42\")\nfor (const t of tags) console.log(t.categoryName, t.tagName)\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginCoreTagsGetTagsForComponentResult"
+  },
   {
     "path": "core.tags.unassign",
     "namespace": "core.tags",
@@ -3497,7 +3950,8 @@
       "Show me the full scene\n\n# Example\n```ts\nawait snaptrude.core.zoom.extents()\n```"
     ],
     "argsType": null,
-    "resultType": "boolean"
+    "resultType": "boolean",
+    "deprecated": "core.camera.zoomExtents"
   },
   {
     "path": "core.zoom.selection",
@@ -3510,7 +3964,8 @@
       "Fit the view to the selected room\n\n# Example\n```ts\nawait snaptrude.core.zoom.selection()\n```"
     ],
     "argsType": null,
-    "resultType": "boolean"
+    "resultType": "boolean",
+    "deprecated": "core.camera.zoomSelection"
   },
   {
     "path": "design.boolean.intersect",
@@ -3556,7 +4011,7 @@
   {
     "path": "design.create.beam",
     "namespace": "design.create",
-    "summary": "Create a **beam** by extruding a cross-section contour along `direction` by `length`.",
+    "summary": "Create a **beam** by extruding a cross-section contour along `direction` by `length`. Matches the Snaptrude beam tool's semantics: the beam body hangs BELOW the plane the section is authored on.",
     "examplePrompts": [
       "Add a beam spanning 6 metres between the columns",
       "Create a horizontal beam along the X axis",
@@ -3566,6 +4021,19 @@
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
+  {
+    "path": "design.create.buildableEnvelope",
+    "namespace": "design.create",
+    "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. The host mints the envelope id and returns it. Canonical home of the create formerly at `entity.buildableEnvelope.create` (now deprecated).",
+    "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",
+      "Create a zoning envelope capped at 12 floors with FAR 3\n\n# Example\n```ts\nconst { buildableEnvelopeId } = await snaptrude.design.create.buildableEnvelope(\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": "design.create.ceiling",
     "namespace": "design.create",
@@ -3582,7 +4050,7 @@
   {
     "path": "design.create.column",
     "namespace": "design.create",
-    "summary": "Create a **column** by extruding a cross-section contour upward by `height` from a base `position`.",
+    "summary": "Create a **column** by extruding a cross-section contour upward by `height` from a base `position`. The column is built to EXACTLY `height` — unlike the interactive draw tool, no slab-thickness deduction is applied.",
     "examplePrompts": [
       "Add a 3m tall column at this point",
       "Place a column at the grid intersection",
@@ -3601,10 +4069,11 @@
       "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```"
+      "Clone the desk as a unique copy, not an instance"
     ],
     "argsType": "ComponentHandle[]",
-    "resultType": "ComponentHandle[]"
+    "resultType": "ComponentHandle[]",
+    "performance": "To place N repeats of the same geometry, bulk-create the seed(s) once then call this ONCE with `{ count: N - 1 }` — one host round-trip for all copies. Never reproduce geometry by looping `design.create.*` N times. Copy only after the create that mints the seed ids. # Example ```ts const { vec3 } = snaptrude.core.math const copies = await snaptrude.design.create.copy([\"space-id\"], vec3.new(6, 0, 0), { count: 3 }) ```"
   },
   {
     "path": "design.create.door",
@@ -3615,7 +4084,8 @@
       "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```"
+      "Add a door to the wall and call it Entry-01",
+      "Add a door that opens into the living room\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ isSelected: true })\nconst [entry] = await snaptrude.design.doors.listCatalog()\nconst door = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Entry-01\" },\n)\n// …facing a specific side of the wall (pass a point inside that room):\nconst intoKitchen = await snaptrude.design.create.door(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\nundefined,\nawait snaptrude.core.math.vec3.new(3, 0, 9),\n)\n```"
     ],
     "argsType": "string",
     "resultType": "ComponentHandle"
@@ -3642,7 +4112,8 @@
       "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```"
+      "Put a table from my project library here and name it Table-01",
+      "Place a chair here rotated 90 degrees\n\n# Example\n```ts\nconst chair = await snaptrude.design.create.furniture(\n\"6620f1a…\",             // from design.furniture.listCatalog()\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Chair-01\" },\n)\n// …placed already turned 90° about the vertical axis:\nconst turned = await snaptrude.design.create.furniture(\n\"6620f1a…\",\nawait snaptrude.core.math.vec3.new(3, 0, 5),\nundefined,\n90,\n)\n```"
     ],
     "argsType": "string",
     "resultType": "ComponentHandle"
@@ -3661,13 +4132,25 @@
     "resultType": "ComponentHandle"
   },
   {
-    "path": "design.create.referenceLines",
+    "path": "design.create.massFromBrep",
     "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.",
+    "summary": "Create a **mass** from a custom solid built with a `core.geom.create` brep constructor (`brepFromFaces`, `brepFromExtrusion`, `brepFromLoft`, `brepFromMesh`, or a brep boolean) — the free-form counterpart of {@linkcode PluginDesignCreateApi.mass}, for solids that are not simple footprint extrusions (pyramids, wedges, faceted volumes).",
     "examplePrompts": [
-      "Draw a reference line between these two points",
-      "Add dashed guide lines along this path",
-      "Create grid lines tagged A through the plan",
+      "Create a mass from these faces",
+      "Turn this custom brep into a scene mass",
+      "Add a pyramid-shaped mass to the model\n\n# Example\n```ts\nconst apex = { x: 0, y: 4, z: 0 }\nconst a = { x: -2, y: 0, z: -2 }\nconst b = { x: 2, y: 0, z: -2 }\nconst c = { x: 2, y: 0, z: 2 }\nconst d = { x: -2, y: 0, z: 2 }\nconst brep = await snaptrude.core.geom.create.brepFromFaces([\n[a, d, c, b],\n[a, b, apex],\n[b, c, apex],\n[c, d, apex],\n[d, a, apex],\n])\nconst pyramid = await snaptrude.design.create.massFromBrep(brep, \"Pavilion\")\n```"
+    ],
+    "argsType": "BrepHandle",
+    "resultType": "ComponentHandle"
+  },
+  {
+    "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": [
+      "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```"
     ],
@@ -3724,23 +4207,27 @@
       "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```"
+      "Can you create a Kitchen space from the sketch I just drew?",
+      "Create a bedroom on the second floor from this outline"
     ],
     "argsType": "ContourHandle",
-    "resultType": "ComponentHandle"
+    "resultType": "ComponentHandle",
+    "performance": "For MORE THAN ONE space, call `design.create.spaces(items[])` — the whole batch is one host round-trip. Looping this single-space creator is N round-trips (slow, and a large loop can trip the plugin rate limit). # Example ```ts const v = snaptrude.core.math.vec3 const outer = await snaptrude.core.geom.create.profileFromLinePoints([ await v.new(0, 0, 0), await v.new(10, 0, 0), await v.new(10, 0, 8), await v.new(0, 0, 8), ]) const contour = await snaptrude.core.geom.create.contourFromProfile(outer) const space = await snaptrude.design.create.space(contour, 3, \"Living\") // …place one directly on the second floor (no setActive dance): const upstairs = await snaptrude.design.create.space( contour, 3, \"Bedroom\", undefined, undefined, undefined, undefined, 2, ) ```"
   },
   {
     "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.",
+    "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. Each item may carry its own `storey` (see {@linkcode PluginCreateSpaceItem}) so a single call can populate several floors at once.",
     "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```"
+      "Add three rooms with different heights in a single undo step",
+      "Create one room on the ground floor and one on the first floor"
     ],
     "argsType": "PluginCreateSpaceItem[]",
-    "resultType": "ComponentHandle[]"
+    "resultType": "ComponentHandle[]",
+    "performance": "Bulk creator — the whole batch is ONE host round-trip. Always prefer this over calling `design.create.space` in a loop: build the full `items[]` array first (all per-item math and geometry up front), then make one call. # Example ```ts const rect = await snaptrude.core.geom.create.profileRect(4, 3) const contour = await snaptrude.core.geom.create.contourFromProfile(rect) const [a, b] = await snaptrude.design.create.spaces([ { contour, height: 3, label: \"R1\" }, { contour, height: 4, label: \"R2\", position: await vec3.new(10, 0, 0) }, ]) ```"
   },
   {
     "path": "design.create.staircase",
@@ -3765,7 +4252,9 @@
       "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```"
+      "Add walls with mitred corners along the path",
+      "Draw brick walls with plaster along this outline",
+      "Build the perimeter in exposed concrete walls\n\n# Example\n```ts\nconst v = snaptrude.core.math.vec3\nconst centerlines = await snaptrude.core.geom.create.profileFromLinePoints([\nawait v.new(0, 0, 0),\nawait v.new(8, 0, 0),\nawait v.new(8, 0, 6),\n])\nconst walls = await snaptrude.design.create.walls(centerlines, 3, 0.2)\n// …built as a specific wall type (layers/material/thickness from the type):\nconst [brick] = await snaptrude.design.types.list(\"wall\")\nconst brickWalls = await snaptrude.design.create.walls(\ncenterlines, 3, undefined, brick.label,\n)\n```"
     ],
     "argsType": "ProfileHandle",
     "resultType": "ComponentHandle[]"
@@ -3779,7 +4268,8 @@
       "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```"
+      "Add a window to the wall and name it Win-01",
+      "Add a casement window opening toward the garden side\n\n# Example\n```ts\nconst [wall] = await snaptrude.design.query.listWalls({ isSelected: true })\nconst [entry] = await snaptrude.design.windows.listCatalog()\nconst window = await snaptrude.design.create.window(\nentry.id,\nwall,\nawait snaptrude.core.math.vec3.new(3, 0, 5),\n{ label: \"Win-01\" },\n)\n```"
     ],
     "argsType": "string",
     "resultType": "ComponentHandle"
@@ -3793,10 +4283,11 @@
       "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```"
+      "Remove the door and window I just created"
     ],
     "argsType": "ComponentHandle[]",
-    "resultType": "PluginDesignChangeResult"
+    "resultType": "PluginDesignChangeResult",
+    "performance": "Array delete — pass every target in one call (one host round-trip). There is no per-item delete; collect the whole set and never loop this per entity. # Example ```ts // Hard-delete every furniture item on storey 2 (a single undo entry) const furniture = await snaptrude.design.query.listFurniture({ storeys: [2] }) if (furniture.length > 0) { const { affected } = await snaptrude.design.delete.entities(furniture) } ```"
   },
   {
     "path": "design.doors.exists",
@@ -4217,6 +4708,20 @@
     "argsType": "PluginMaterialSpec",
     "resultType": "MaterialHandle"
   },
+  {
+    "path": "design.materials.get",
+    "namespace": "design.materials",
+    "summary": "Read the material applied to a component **as a whole** — the eyedropper. For a uniformly-painted component this is that single material; for a per-face-painted component it is the material on the component's base/first face. Use {@linkcode PluginDesignMaterialsApi.getByFace} / {@linkcode PluginDesignMaterialsApi.listByFace} for the per-face breakdown.",
+    "examplePrompts": [
+      "What material is on this wall?",
+      "Eyedrop the finish of the selected object",
+      "Which material does this slab use?",
+      "Read the material on this column so I can paint others with it",
+      "Is this component painted, and with what?\n\n# Example\n```ts\nconst [component] = await snaptrude.design.selection.get()\nconst sampled = await snaptrude.design.materials.get(component)\nif (sampled) {\nconsole.log(sampled.name, sampled.source) // e.g. \"Brick Red\" \"applied\"\nconst info = await snaptrude.design.materials.getInfo(sampled.material)\nconsole.log(info?.colorHex)\n}\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginComponentMaterial | null"
+  },
   {
     "path": "design.materials.getByFace",
     "namespace": "design.materials",
@@ -4297,15 +4802,14 @@
   {
     "path": "design.materials.list",
     "namespace": "design.materials",
-    "summary": "List the project materials.",
+    "summary": "List the materials loaded in the project — every named material in the live scene (applied finishes, plugin-created materials, and type defaults in use). For the browsable preset/library catalog (finishes not yet in the project), use {@linkcode PluginDesignMaterialsApi.listPresets}.",
     "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```"
+      "Get every material in the project palette\n\n# Example\n```ts\nconst materials = await snaptrude.design.materials.list()\nconsole.log(materials.length, \"materials in the project\")\n```"
     ],
-    "argsType": "\"project\" | \"preset\"",
+    "argsType": null,
     "resultType": "MaterialHandle[]"
   },
   {
@@ -4320,6 +4824,19 @@
     "argsType": "ComponentHandle",
     "resultType": "PluginFaceMaterial[]"
   },
+  {
+    "path": "design.materials.listPresets",
+    "namespace": "design.materials",
+    "summary": "List the preset material library — the catalog the app's material browser shows (the built-in finishes plus the workspace's uploaded materials), fetched from the material library service. Library entries are **not** scene materials and carry no {@linkcode MaterialHandle}; each is a named texture record. To use one, feed it to {@linkcode PluginDesignMaterialsApi.create} / {@linkcode PluginDesignMaterialsApi.apply} as a {@linkcode PluginMaterialSpec}: `{ name, textureUrl, materialType: category }`.",
+    "examplePrompts": [
+      "Show me the preset materials library",
+      "What wood finishes are available in the material library?",
+      "Browse the material catalog and apply a brick texture",
+      "Which preset materials can I choose from?\n\n# Example\n```ts\nconst presets = await snaptrude.design.materials.listPresets()\nconst brick = presets.find((p) => p.category.toLowerCase().includes(\"brick\"))\nif (brick) {\nconst walls = await snaptrude.design.query.listWalls()\nawait snaptrude.design.materials.apply(walls, {\nname: brick.name,\ntextureUrl: brick.textureUrl,\nmaterialType: brick.category,\n})\n}\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginPresetMaterial[]"
+  },
   {
     "path": "design.materials.reset",
     "namespace": "design.materials",
@@ -4399,6 +4916,19 @@
     "argsType": "ComponentHandle",
     "resultType": "CurveHandle | null"
   },
+  {
+    "path": "design.query.geometry.getTriangulatedMeshes",
+    "namespace": "design.query.geometry",
+    "summary": "Get the **triangulated render meshes** of scene components as plain, serializable arrays — flat world-space vertex `positions` (`[x0, y0, z0, x1, …]`) and triangle `indices` (three per triangle), one record per requested component.",
+    "examplePrompts": [
+      "Export the selected masses as a triangle mesh",
+      "Get the raw vertices and triangles of this wall in world coordinates",
+      "Give me the triangulated geometry of every space with its materials",
+      "Compute the surface area of this roof from its triangles"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignQueryGeometryGetTriangulatedMeshesResult"
+  },
   {
     "path": "design.query.getBoundingBox",
     "namespace": "design.query",
@@ -4479,10 +5009,11 @@
   {
     "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`).",
+    "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`). For walls and the slab family (slab / floor / roof / ceiling) this includes `buildingType` — the assigned building type NAME the panel's type dropdown shows, matching `design.types.list(kind)`.",
     "examplePrompts": [
       "Show me all the details of the selected object",
       "What storey is this wall on?",
+      "Which wall type is assigned to this wall?",
       "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```"
@@ -4747,13 +5278,28 @@
     "examplePrompts": [
       "What's the area of this room?",
       "How long is the selected wall?",
+      "How thick is this wall?",
+      "Get the thickness of the slab on level 2",
       "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```"
+      "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\n// wall dimensions — the panel's Thickness / Height, in engine units\nconst [wall] = await snaptrude.design.query.listWalls()\nconst wm = await snaptrude.design.query.measure(wall)\nconsole.log(wm?.thickness, wm?.height)\n```"
     ],
     "argsType": "ComponentHandle",
     "resultType": "PluginEntityMeasurements | null"
   },
+  {
+    "path": "design.query.referenceLines.get",
+    "namespace": "design.query.referenceLines",
+    "summary": "Get properties of a reference line by its ID.",
+    "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 [refLine] = await snaptrude.design.query.listReferenceLines()\nconst result = await snaptrude.design.query.referenceLines.get(refLine, [\"curve\"])\n// result.curve is an opaque CurveHandle; read its coordinates via\n// `snaptrude.core.geom.curve`.\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginReferenceLineGetResult"
+  },
   {
     "path": "design.query.spaces.get",
     "namespace": "design.query.spaces",
@@ -4768,6 +5314,19 @@
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignQuerySpacesGetResult"
   },
+  {
+    "path": "design.query.spaces.getEnclosure",
+    "namespace": "design.query.spaces",
+    "summary": "Get the **enclosure** of a space — the floor and ceiling that cap it, the bounding walls around it (with each wall's door/window openings), and the neighbouring spaces it shares a boundary with.",
+    "examplePrompts": [
+      "What walls, floor and ceiling enclose this room?",
+      "Which of this room's walls are external?",
+      "List the doors and windows around the selected space",
+      "Which spaces are adjacent to this room, and through which wall?\n\n# Example\n```ts\nconst [space] = await snaptrude.design.query.listSpaces()\nconst enclosure = await snaptrude.design.query.spaces.getEnclosure(space)\nif (enclosure) {\nconst walls = enclosure.surfaces.filter((s) => s.role === \"wall\")\nconst external = walls.filter((s) => s.isExternal)\nconsole.log(`${walls.length} walls, ${external.length} external`)\n}\n```"
+    ],
+    "argsType": "ComponentHandle",
+    "resultType": "PluginSpaceEnclosure | null"
+  },
   {
     "path": "design.query.spaces.getFootprint",
     "namespace": "design.query.spaces",
@@ -4871,10 +5430,11 @@
       "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```"
+      "Snap the bottom edges of these spaces together"
     ],
     "argsType": "ComponentHandle[]",
-    "resultType": "PluginDesignChangeResult"
+    "resultType": "PluginDesignChangeResult",
+    "performance": "Array API — one host round-trip for the whole set. Pass every target in a single call; never loop `design.transform.align` per entity. # Example ```ts const rooms = await snaptrude.design.selection.get() // align every room's left (world -X) edge to a common minimum await snaptrude.design.transform.align(rooms, \"left\") // …or align them to a fixed reference component's left edge const [anchor] = await snaptrude.design.query.listWalls({ storeys: [1] }) await snaptrude.design.transform.align(rooms, \"left\", { reference: anchor }) ```"
   },
   {
     "path": "design.transform.mirror",
@@ -4885,10 +5445,11 @@
       "Flip these rooms left to right",
       "Mirror this furniture block horizontally",
       "Flip the selected walls front to back",
-      "Create a mirror image of these masses about the z axis\n\n# Example\n```ts\nconst rooms = await snaptrude.design.selection.get()\nawait snaptrude.design.transform.mirror(rooms, \"x\")\n```"
+      "Create a mirror image of these masses about the z axis"
     ],
     "argsType": "ComponentHandle[]",
-    "resultType": "PluginDesignChangeResult"
+    "resultType": "PluginDesignChangeResult",
+    "performance": "Array API — one host round-trip for the whole set. Pass every target in a single call; never loop `design.transform.mirror` per entity. # Example ```ts const rooms = await snaptrude.design.selection.get() await snaptrude.design.transform.mirror(rooms, \"x\") ```"
   },
   {
     "path": "design.transform.move",
@@ -4899,23 +5460,26 @@
       "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```"
+      "Move these masses up one storey"
     ],
     "argsType": "ComponentHandle[]",
-    "resultType": "PluginDesignChangeResult"
+    "resultType": "PluginDesignChangeResult",
+    "performance": "Array API — one host round-trip for the whole set. Pass every target in a single call; never loop `design.transform.move` per entity. # Example ```ts const { vec3 } = snaptrude.core.math await snaptrude.design.transform.move([\"space-id\"], vec3.new(10, 0, 0)) ```"
   },
   {
     "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.",
+    "summary": "Rotate entities by a **signed angle in DEGREES** (positive = CCW about +Y). The pivot defaults to the combined bounding-box centre; pass `options.pivot` to rotate about an explicit world-space point instead. NOTE: unlike the removed `tools.transform.rotate` (radians), this canonical form takes DEGREES. Undoable.",
     "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```"
+      "Rotate these masses 30 degrees around the vertical axis",
+      "Rotate these walls 90 degrees about the origin"
     ],
     "argsType": "ComponentHandle[]",
-    "resultType": "PluginDesignChangeResult"
+    "resultType": "PluginDesignChangeResult",
+    "performance": "Array API — one host round-trip for the whole set. Pass every target in a single call; never loop `design.transform.rotate` per entity. # Example ```ts await snaptrude.design.transform.rotate([\"space-id\"], 90) // …or rotate about an explicit pivot point const { vec3 } = snaptrude.core.math await snaptrude.design.transform.rotate([\"space-id\"], 90, { pivot: vec3.new(0, 0, 0) }) ```"
   },
   {
     "path": "design.types.get",
@@ -4969,10 +5533,23 @@
     "argsType": "ComponentHandle[]",
     "resultType": "PluginDesignChangeResult"
   },
+  {
+    "path": "design.update.buildableEnvelope",
+    "namespace": "design.update",
+    "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. Canonical home of the update formerly at `entity.buildableEnvelope.update` (now deprecated).",
+    "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\n\n# Example\n```ts\nconst { buildableEnvelopeId } = await snaptrude.design.update.buildableEnvelope(\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"
+  },
   {
     "path": "design.update.ceiling",
     "namespace": "design.update",
-    "summary": "Edit a **ceiling's** thickness — the slab-family updater for ceilings (shares the slab thickness command). Undoable. Thickness is in **engine units** (the `design.doors.setWidth` convention) and must be `> 0`.",
+    "summary": "Edit a **ceiling's** thickness — the slab-family updater for ceilings (shares the slab thickness command). Undoable. Thickness is in **engine units** (the `design.doors.setWidth` convention) and must be `> 0`. Ceilings have no Overhang control, so `overhang` is rejected with `PRECONDITION_FAILED`.",
     "examplePrompts": [
       "Make this ceiling 150mm thick",
       "Set every ceiling to a 100 thickness",
@@ -4984,7 +5561,7 @@
   {
     "path": "design.update.floor",
     "namespace": "design.update",
-    "summary": "Edit a **floor's** thickness — the slab-family updater for floors (shares the slab thickness command). Undoable. Thickness is in **engine units** (the `design.doors.setWidth` convention) and must be `> 0`.",
+    "summary": "Edit a **floor's** thickness — the slab-family updater for floors (shares the slab thickness command). Undoable. Thickness is in **engine units** (the `design.doors.setWidth` convention) and must be `> 0`. Floors have no Overhang control, so `overhang` is rejected with `PRECONDITION_FAILED`.",
     "examplePrompts": [
       "Make this floor 200mm thick",
       "Set every floor to a 250 thickness",
@@ -4996,11 +5573,12 @@
   {
     "path": "design.update.roof",
     "namespace": "design.update",
-    "summary": "Edit a **roof's** thickness — the slab-family updater for roofs (shares the slab thickness command). Undoable. Thickness is in **engine units** (the `design.doors.setWidth` convention) and must be `> 0`.",
+    "summary": "Edit a **roof's** thickness and/or overhang — the same commands the roof panel's Thickness field and Overhang slider drive (shares the slab-family machinery). Sparse: only the fields you provide change. Undoable. Both values are in **engine units** (the `design.doors.setWidth` convention); thickness must be `> 0`, overhang is an absolute offset (negative insets the roof) and re-applying the current overhang is a no-op.",
     "examplePrompts": [
       "Make this roof 300mm thick",
       "Set the roof slab thickness to 250",
-      "Thicken every roof to 350\n\n# Example\n```ts\nconst [roof] = await snaptrude.design.query.listRoofs()\nawait snaptrude.design.update.roof(roof, { thickness: 300 })\n```"
+      "Give the roof a 600 overhang",
+      "Pull the roof overhang back to 0\n\n# Example\n```ts\nconst [roof] = await snaptrude.design.query.listRoofs()\nawait snaptrude.design.update.roof(roof, { overhang: 600 })\n```"
     ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
@@ -5044,14 +5622,28 @@
     "argsType": "ComponentHandle",
     "resultType": "boolean"
   },
+  {
+    "path": "design.update.setStorey",
+    "namespace": "design.update",
+    "summary": "Reassign one or more components to another **storey** — the same operation as the properties panel's Story dropdown, and it works across element kinds exactly like the panel (walls, slabs, masses, furniture, staircases, ...). Each component is moved vertically to the target storey's level (per-kind placement rules — e.g. a slab sits at the storey base, a wall on it) and its storey assignment, children, and dimension lines update together as **one undoable operation**.",
+    "examplePrompts": [
+      "Move this sofa to storey 2",
+      "Put the selected walls on the first basement level",
+      "Send everything on this storey up one level",
+      "Reassign these slabs to storey 3\n\n# Example\n```ts\n// Move the current selection up to storey 2\nconst selection = await snaptrude.design.selection.get()\nconst { affected } = await snaptrude.design.update.setStorey(selection, 2)\nconsole.log(\"moved\", affected.length, \"components\")\n```"
+    ],
+    "argsType": "ComponentHandle[]",
+    "resultType": "PluginDesignChangeResult"
+  },
   {
     "path": "design.update.slab",
     "namespace": "design.update",
-    "summary": "Edit a **slab's** thickness — the same command the properties panel's Thickness field drives. Undoable; the slab rebuilds and dimension lines refresh. The thickness is in **engine units** (the same convention as `design.doors.setWidth`) and must be `> 0`.",
+    "summary": "Edit a **slab's** thickness and/or overhang — the same commands the properties panel's Thickness field and Overhang slider drive. Sparse: only the fields you provide change. Undoable; the slab rebuilds and dimension lines refresh. Both values are in **engine units** (the same convention as `design.doors.setWidth`); thickness must be `> 0`, overhang is an absolute offset (negative insets the slab) and re-applying the current overhang is a no-op.",
     "examplePrompts": [
       "Set this slab's thickness to 250mm",
       "Make the floor slab 300 thick",
-      "Thicken every slab on level 2 to 200\n\n# Example\n```ts\nconst [slab] = await snaptrude.design.query.listSlabs()\nawait snaptrude.design.update.slab(slab, { thickness: 250 })\n```"
+      "Give this slab a 200 overhang",
+      "Remove the overhang on every slab on level 2\n\n# Example\n```ts\nconst [slab] = await snaptrude.design.query.listSlabs()\nawait snaptrude.design.update.slab(slab, { thickness: 250, overhang: 200 })\n```"
     ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
@@ -5065,10 +5657,11 @@
       "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```"
+      "Exclude this room from the area calculations"
     ],
     "argsType": "ComponentHandle",
-    "resultType": "PluginSpaceUpdateResult"
+    "resultType": "PluginSpaceUpdateResult",
+    "performance": "For MORE THAN ONE space, call `design.update.spaces(items[])` — the whole batch is one host round-trip. Looping this single-space updater is N round-trips. # Example ```ts await snaptrude.design.update.space(\"space-id\", { properties: { room_type: \"Office\" } }) ```"
   },
   {
     "path": "design.update.spaces",
@@ -5079,10 +5672,11 @@
       "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```"
+      "Mark all of these rooms as excluded from area in one update"
     ],
     "argsType": "PluginUpdateSpaceItem[]",
-    "resultType": "PluginSpaceUpdateResult[]"
+    "resultType": "PluginSpaceUpdateResult[]",
+    "performance": "Bulk update — the whole batch is ONE host round-trip. Prefer over looping `design.update.space`: build the `items[]` array first, then make one call. # Example ```ts // Re-label every selected room and mark it NET area — one undoable bulk update const rooms = await snaptrude.design.query.listSpaces({ isSelected: true }) const results = await snaptrude.design.update.spaces( rooms.map((space) => ({ space, properties: { room_type: \"Bedroom\", areaClass: \"NET\" }, })), ) // One result per item, in input order console.log(results.map((r) => r.spaceId)) ```"
   },
   {
     "path": "design.update.staircase",
@@ -5101,13 +5695,13 @@
   {
     "path": "design.update.wall",
     "namespace": "design.update",
-    "summary": "Edit a **wall's** dimensions — its thickness and/or height — the same command the properties panel's Thickness/Height fields drive. Sparse: only the fields you provide change. Undoable; the geometry rebuilds and any dimension lines refresh. Stacked-wall companions and hosted fenestration are handled exactly as the panel does.",
+    "summary": "Edit a **wall** — its thickness and/or height (the same command the properties panel's Thickness/Height fields drive) and/or its **wall type** (the panel's Wall Types dropdown: converts the wall to another type, rebuilding its layer stack and materials). Sparse: only the fields you provide change. Undoable; the geometry rebuilds and any dimension lines refresh. Stacked-wall companions and hosted fenestration are handled exactly as the panel does.",
     "examplePrompts": [
       "Make this wall 230mm thick",
       "Set the selected wall's height to 3 metres",
       "Thicken every exterior wall to 300",
-      "Raise all the walls on this floor to 3200 tall",
-      "Change this partition to 100mm thick and 2700 high\n\n# Example\n```ts\n// Standardise every wall on storey 1 to a 230mm thickness\nconst walls = await snaptrude.design.query.listWalls({ storeys: [1] })\nfor (const wall of walls) {\nawait snaptrude.design.update.wall(wall, { thickness: 230 })\n}\n```"
+      "Change this wall to a Glass Wall",
+      "Convert all the partitions on this floor to Brick Wall\n\n# Example\n```ts\n// Convert every wall on storey 1 to the first listed wall type\nconst [wallType] = await snaptrude.design.types.list(\"wall\")\nconst walls = await snaptrude.design.query.listWalls({ storeys: [1] })\nfor (const wall of walls) {\nawait snaptrude.design.update.wall(wall, { type: wallType.id })\n}\n```"
     ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignChangeResult"
@@ -5294,7 +5888,8 @@
       "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"
+    "resultType": "PluginBuildableEnvelopeCreateResult",
+    "deprecated": "design.create.buildableEnvelope"
   },
   {
     "path": "entity.buildableEnvelope.update",
@@ -5308,7 +5903,8 @@
       "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"
+    "resultType": "PluginBuildableEnvelopeUpdateResult",
+    "deprecated": "design.update.buildableEnvelope"
   },
   {
     "path": "entity.referenceLine.createMulti",
@@ -5322,7 +5918,8 @@
       "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"
+    "resultType": "PluginReferenceLineCreateMultiResult",
+    "deprecated": "design.create.referenceLines"
   },
   {
     "path": "entity.referenceLine.delete",
@@ -5335,7 +5932,8 @@
       "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"
+    "resultType": "PluginReferenceLineDeleteResult",
+    "deprecated": "design.delete.entities"
   },
   {
     "path": "entity.referenceLine.get",
@@ -5348,7 +5946,8 @@
       "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"
+    "resultType": "PluginReferenceLineGetResult",
+    "deprecated": "design.query.referenceLines.get"
   },
   {
     "path": "entity.referenceLine.getAll",
@@ -5361,7 +5960,8 @@
       "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"
+    "resultType": "PluginReferenceLineGetAllResult",
+    "deprecated": "design.query.listReferenceLines"
   },
   {
     "path": "entity.story.create",
@@ -5375,7 +5975,8 @@
       "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"
+    "resultType": "PluginStoryCreateResult",
+    "deprecated": "core.storeys.create"
   },
   {
     "path": "entity.story.delete",
@@ -5388,7 +5989,8 @@
       "Delete the second floor and everything on it\n\n# Example\n```ts\nconst { newActiveStory } = await snaptrude.entity.story.delete(3)\nconsole.log(`Deleted story 3; now on story ${newActiveStory}`)\n```"
     ],
     "argsType": "number",
-    "resultType": "PluginStoryDeleteResult"
+    "resultType": "PluginStoryDeleteResult",
+    "deprecated": "core.storeys.delete"
   },
   {
     "path": "entity.story.duplicate",
@@ -5398,10 +6000,12 @@
       "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```"
+      "Duplicate just the selected walls onto the next floor up"
     ],
     "argsType": "\"up\" | \"down\"",
-    "resultType": "PluginStoryDuplicateResult"
+    "resultType": "PluginStoryDuplicateResult",
+    "performance": "For storeys that share a layout, duplicate the storey instead of recreating its contents floor by floor — this copies every eligible element in one call, and the default instanced copies keep the floors linked. To stack many identical floors, either call this per level or capture the storey's component ids and `design.create.copy(ids, oneFloorRise, { count })` to lay them all down in a single call. # Example ```ts // Duplicate the whole active story one level up (instanced copies). const { targetStories, created, skipped } = await snaptrude.entity.story.duplicate(\"up\") console.log(`Copied ${created.length} elements onto story ${targetStories}`) if (skipped) console.log(`${skipped} elements were skipped`) ```",
+    "deprecated": "core.storeys.copy"
   },
   {
     "path": "entity.story.get",
@@ -5415,7 +6019,8 @@
       "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"
+    "resultType": "PluginStoryGetResult",
+    "deprecated": "core.storeys.get"
   },
   {
     "path": "entity.story.getAll",
@@ -5428,7 +6033,8 @@
       "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"
+    "resultType": "PluginStoryGetAllResult",
+    "deprecated": "core.storeys.list"
   },
   {
     "path": "entity.story.setActive",
@@ -5441,7 +6047,8 @@
       "Set level 3 as the current storey\n\n# Example\n```ts\n// Activate story 2, then draw a wall — it lands on story 2.\nawait snaptrude.entity.story.setActive(2)\n```"
     ],
     "argsType": "number",
-    "resultType": "PluginStorySetActiveResult"
+    "resultType": "PluginStorySetActiveResult",
+    "deprecated": "core.storeys.setActive"
   },
   {
     "path": "entity.story.update",
@@ -5455,7 +6062,41 @@
       "Rename storey 2 and make it taller in one go\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// Rename only, leaving the height untouched.\nawait snaptrude.entity.story.update(1, undefined, { name: \"Lobby\" })\n```"
     ],
     "argsType": "number",
-    "resultType": "PluginStoryUpdateResult"
+    "resultType": "PluginStoryUpdateResult",
+    "deprecated": "core.storeys.update"
+  },
+  {
+    "path": "presentation.aiInspiration.cancelJob",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Cancel a transient AI Inspiration job.",
+    "examplePrompts": [
+      "Cancel the running generation",
+      "Stop that AI job\n\n# Example\n```ts\nconst { job } = await snaptrude.presentation.aiInspiration.cancelJob({ jobId })\nconsole.log(job.status) // \"cancelled\" (or a terminal state it already reached)\n```"
+    ],
+    "argsType": "PluginAIInspirationJobArgs",
+    "resultType": "PluginAIInspirationCancelJobResult"
+  },
+  {
+    "path": "presentation.aiInspiration.deleteRecipe",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Delete a project-level AI Inspiration recipe.",
+    "examplePrompts": [
+      "Delete the facade render recipe",
+      "Remove that saved AI recipe\n\n# Example\n```ts\nconst { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()\nconst stale = recipes.find((r) => r.name === \"Old style test\")\nif (stale) {\nconst { deleted } = await snaptrude.presentation.aiInspiration.deleteRecipe({ recipeId: stale.id })\nconsole.log(deleted)\n}\n```"
+    ],
+    "argsType": "PluginAIInspirationDeleteRecipeArgs",
+    "resultType": "PluginAIInspirationDeleteRecipeResult"
+  },
+  {
+    "path": "presentation.aiInspiration.extractRecipeFromShape",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Extract a reusable recipe draft from the workflow path ending at a shape.",
+    "examplePrompts": [
+      "Turn this workflow into a reusable recipe",
+      "Save the generation steps behind this image\n\n# Example\n```ts\nconst extraction = await snaptrude.presentation.aiInspiration.extractRecipeFromShape({\nshapeId: selected.shapeId,\n})\nif (extraction.status === \"ready\") console.log(extraction.draft.summary)\n```"
+    ],
+    "argsType": "PluginAIInspirationExtractRecipeFromShapeArgs",
+    "resultType": "PluginAIInspirationExtractionResult"
   },
   {
     "path": "presentation.aiInspiration.generate",
@@ -5466,11 +6107,90 @@
       "Render the selected view as a photorealistic image",
       "Make an AI image of a modern facade from this source",
       "Generate a video from this image",
-      "Turn this massing into a rendered street view\n\n# Example\n```ts\nconst { sources } = await snaptrude.presentation.aiInspiration.listSources({})\nconst [source, ...refs] = sources\nconst { outputs } = await snaptrude.presentation.aiInspiration.generate({\nsourceShapeId: source.shapeId,\nprompt: \"Photorealistic render of a modern timber facade at dusk\",\nreferenceShapeIds: refs.slice(0, 2).map((r) => r.shapeId),\nreferenceStrength: \"medium\",\n})\nfor (const out of outputs) console.log(out.outputType, out.shapeId, out.outputUrl)\n```"
+      "Turn this massing into a rendered street view\n\n# Example\n```ts\nconst { sources } = await snaptrude.presentation.aiInspiration.listSources({})\nconst [source, ...refs] = sources\nconst { outputs } = await snaptrude.presentation.aiInspiration.generate({\nsourceShapeId: source.shapeId,\nprompt: \"Photorealistic render of a modern timber facade at dusk\",\nreferenceShapeIds: refs.slice(0, 2).map((r) => r.shapeId),\nreferenceStrength: \"medium\",\n})\nfor (const out of outputs ?? []) console.log(out.outputType, out.shapeId, out.outputUrl)\n```"
     ],
     "argsType": "PluginAIInspirationGenerateArgs",
     "resultType": "PluginAIInspirationRunResult"
   },
+  {
+    "path": "presentation.aiInspiration.getJob",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Get a transient AI Inspiration job by ID.",
+    "examplePrompts": [
+      "Is my render finished?",
+      "Check on the generation job\n\n# Example\n```ts\nconst { jobId } = await snaptrude.presentation.aiInspiration.generate({\nsourceShapeId: source.shapeId,\nprompt: \"Aerial dusk render\",\nrunMode: \"job\",\n})\nconst { job } = await snaptrude.presentation.aiInspiration.getJob({ jobId })\nconsole.log(job.status, job.progress?.message)\n```"
+    ],
+    "argsType": "PluginAIInspirationJobArgs",
+    "resultType": "PluginAIInspirationGetJobResult"
+  },
+  {
+    "path": "presentation.aiInspiration.getModelCapabilities",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Get capability flags for a model.",
+    "examplePrompts": [
+      "What can this model do?",
+      "Does the default model support reference images?",
+      "Check if the video model supports keyframes\n\n# Example\n```ts\nconst { defaultModelId } = await snaptrude.presentation.aiInspiration.listModels()\nconst { capability } = await snaptrude.presentation.aiInspiration.getModelCapabilities({\nmodelId: defaultModelId,\n})\nconsole.log(capability.supportsReferenceImages, capability.maxExtraImages)\n```"
+    ],
+    "argsType": "PluginAIInspirationGetModelCapabilitiesArgs",
+    "resultType": "PluginAIInspirationGetModelCapabilitiesResult"
+  },
+  {
+    "path": "presentation.aiInspiration.getPresetCatalog",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Get the curated AI Inspiration preset catalog.",
+    "examplePrompts": [
+      "What style presets are available?",
+      "List the curated AI generation presets",
+      "Show me the exterior render styles\n\n# Example\n```ts\nconst { categories, presets } = await snaptrude.presentation.aiInspiration.getPresetCatalog()\nconst exterior = presets.filter((p) => p.categoryLabel === \"Exterior\")\nconsole.log(categories.map((c) => c.label), exterior.map((p) => p.name))\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAIInspirationGetPresetCatalogResult"
+  },
+  {
+    "path": "presentation.aiInspiration.getSelectedBranchRerunPlan",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Build a rerun plan for the selected workflow branch ending at a shape.",
+    "examplePrompts": [
+      "Can I rerun the steps that produced this output?",
+      "Preview the rerun for this generated image\n\n# Example\n```ts\nconst plan = await snaptrude.presentation.aiInspiration.getSelectedBranchRerunPlan({\nshapeId: selected.shapeId,\n})\nif (plan.status === \"ready\") console.log(plan.edges.map((e) => e.operation.label))\nelse console.log(\"Cannot rerun:\", plan.reason)\n```"
+    ],
+    "argsType": "PluginAIInspirationGetWorkflowForShapeArgs",
+    "resultType": "PluginAIInspirationRerunPlanResult"
+  },
+  {
+    "path": "presentation.aiInspiration.getSelection",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Get selected Present canvas shapes that AI Inspiration can use.",
+    "examplePrompts": [
+      "Generate from what I have selected",
+      "Which of my selected shapes can be used as AI sources?\n\n# Example\n```ts\nconst { selectedShapeIds, sources } = await snaptrude.presentation.aiInspiration.getSelection()\nconsole.log(selectedShapeIds.length, \"selected,\", sources.length, \"usable\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAIInspirationGetSelectionResult"
+  },
+  {
+    "path": "presentation.aiInspiration.getWorkflowForShape",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Get the sanitized workflow graph containing a Present shape.",
+    "examplePrompts": [
+      "Show the generation history of this image",
+      "What workflow produced this shape?\n\n# Example\n```ts\nconst { workflow, node } = await snaptrude.presentation.aiInspiration.getWorkflowForShape({\nshapeId: selected.shapeId,\n})\nif (workflow && node) console.log(node.id, workflow.edgeIds.length, \"edges\")\n```"
+    ],
+    "argsType": "PluginAIInspirationGetWorkflowForShapeArgs",
+    "resultType": "PluginAIInspirationGetWorkflowForShapeResult"
+  },
+  {
+    "path": "presentation.aiInspiration.listJobs",
+    "namespace": "presentation.aiInspiration",
+    "summary": "List transient AI Inspiration jobs created in the current host session.",
+    "examplePrompts": [
+      "What AI jobs are running?",
+      "Show my generation queue\n\n# Example\n```ts\nconst { jobs } = await snaptrude.presentation.aiInspiration.listJobs()\nconst running = jobs.filter((j) => j.status === \"running\" || j.status === \"queued\")\nconsole.log(running.map((j) => `${j.jobId}: ${j.method}`))\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAIInspirationListJobsResult"
+  },
   {
     "path": "presentation.aiInspiration.listModels",
     "namespace": "presentation.aiInspiration",
@@ -5483,6 +6203,17 @@
     "argsType": null,
     "resultType": "PluginAIInspirationListModelsResult"
   },
+  {
+    "path": "presentation.aiInspiration.listRecipes",
+    "namespace": "presentation.aiInspiration",
+    "summary": "List project-level AI Inspiration recipes stored in Present document metadata.",
+    "examplePrompts": [
+      "What AI recipes are saved in this project?",
+      "List my generation recipes\n\n# Example\n```ts\nconst { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()\nconsole.log(recipes.map((r) => `${r.name} → ${r.outputKind}`))\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginAIInspirationListRecipesResult"
+  },
   {
     "path": "presentation.aiInspiration.listSources",
     "namespace": "presentation.aiInspiration",
@@ -5502,11 +6233,105 @@
     "examplePrompts": [
       "Upscale this AI image",
       "Refine and sharpen the selected render",
-      "Make this generated image higher resolution\n\n# Example\n```ts\nconst { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })\nconst image = sources.find((s) => s.kind === \"image\")\nif (image) {\nconst { outputs } = await snaptrude.presentation.aiInspiration.refine({\nsourceShapeId: image.shapeId,\nupscaleFactor: 2,\n})\nconsole.log(outputs[0].shapeId)\n}\n```"
+      "Make this generated image higher resolution\n\n# Example\n```ts\nconst { sources } = await snaptrude.presentation.aiInspiration.listSources({ includeGenerated: true })\nconst image = sources.find((s) => s.kind === \"image\")\nif (image) {\nconst { outputs } = await snaptrude.presentation.aiInspiration.refine({\nsourceShapeId: image.shapeId,\nupscaleFactor: 2,\n})\nconsole.log(outputs?.[0]?.shapeId)\n}\n```"
     ],
     "argsType": "PluginAIInspirationRefineArgs",
     "resultType": "PluginAIInspirationRunResult"
   },
+  {
+    "path": "presentation.aiInspiration.rerunSelectedBranch",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Rerun the selected workflow branch and supersede the previous branch.",
+    "examplePrompts": [
+      "Rerun this generation branch",
+      "Regenerate this output with the same steps\n\n# Example\n```ts\nconst { outputs } = await snaptrude.presentation.aiInspiration.rerunSelectedBranch({\nshapeId: selected.shapeId,\n})\nconsole.log(outputs?.map((o) => o.shapeId))\n```"
+    ],
+    "argsType": "PluginAIInspirationRerunSelectedBranchArgs",
+    "resultType": "PluginAIInspirationRunResult"
+  },
+  {
+    "path": "presentation.aiInspiration.runRecipe",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Run a saved or inline recipe against Present canvas slot shapes.",
+    "examplePrompts": [
+      "Apply my saved recipe to this image",
+      "Run the dusk-render recipe on the selected view\n\n# Example\n```ts\nconst { recipes } = await snaptrude.presentation.aiInspiration.listRecipes()\nconst recipe = recipes[0]\nconst { sources } = await snaptrude.presentation.aiInspiration.listSources({})\nconst { outputs } = await snaptrude.presentation.aiInspiration.runRecipe({\nrecipeId: recipe.id,\nslotShapeIds: { [recipe.slots[0].id]: sources[0].shapeId },\n})\nconsole.log(outputs?.map((o) => o.outputUrl))\n```"
+    ],
+    "argsType": "PluginAIInspirationRunRecipeArgs",
+    "resultType": "PluginAIInspirationRunResult"
+  },
+  {
+    "path": "presentation.aiInspiration.saveRecipe",
+    "namespace": "presentation.aiInspiration",
+    "summary": "Save a project-level AI Inspiration recipe.",
+    "examplePrompts": [
+      "Save this recipe as \"Dusk facade render\"",
+      "Store these generation steps for reuse\n\n# Example\n```ts\nconst extraction = await snaptrude.presentation.aiInspiration.extractRecipeFromShape({\nshapeId: selected.shapeId,\n})\nif (extraction.status === \"ready\") {\nconst saved = await snaptrude.presentation.aiInspiration.saveRecipe({\ndraft: extraction.draft,\nname: \"Dusk facade render\",\n})\nconsole.log(saved.status, saved.recipe?.id)\n}\n```"
+    ],
+    "argsType": "PluginAIInspirationSaveRecipeArgs",
+    "resultType": "PluginAIInspirationSaveRecipeResult"
+  },
+  {
+    "path": "presentation.annotate.arrow",
+    "namespace": "presentation.annotate",
+    "summary": "Draw an arrow on a sheet.",
+    "examplePrompts": [
+      "Draw an arrow pointing at the entrance on Sheet 1",
+      "Add a red arrow from the title to the plan view",
+      "Point an arrow at the top-left view on the cover sheet\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.arrow(\n\"sheet_1\",\n{ x: 100, y: 200 },\n{ x: 300, y: 250 },\n{ color: \"red\" },\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationAnnotateResult"
+  },
+  {
+    "path": "presentation.annotate.note",
+    "namespace": "presentation.annotate",
+    "summary": "Add a sticky note to a sheet.",
+    "examplePrompts": [
+      "Add a sticky note \"Review this wall\" to Sheet 1",
+      "Put a yellow note on the cover sheet",
+      "Leave a note next to the ground floor plan\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.note(\n\"sheet_1\",\n\"Review this wall\",\n{ position: { x: 60, y: 120 }, color: \"yellow\" },\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationAnnotateResult"
+  },
+  {
+    "path": "presentation.annotate.shape",
+    "namespace": "presentation.annotate",
+    "summary": "Draw a geo shape (rectangle, ellipse, cloud, …) on a sheet.",
+    "examplePrompts": [
+      "Draw a revision cloud around the kitchen on Sheet 2",
+      "Add a red rectangle highlight to the sheet",
+      "Draw an ellipse around the entrance on the cover sheet\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.shape(\n\"sheet_1\",\n\"cloud\",\n{ x: 80, y: 80, w: 240, h: 160 },\n{ color: \"red\" },\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationAnnotateResult"
+  },
+  {
+    "path": "presentation.annotate.text",
+    "namespace": "presentation.annotate",
+    "summary": "Add a text label to a sheet.",
+    "examplePrompts": [
+      "Add a title \"Ground Floor\" to Sheet 1",
+      "Label the cover sheet with the project name",
+      "Caption this view with \"Proposed layout\"",
+      "Put a red note on the sheet\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.annotate.text(\n\"sheet_1\",\n\"Ground Floor\",\n{ position: { x: 40, y: 40 }, size: \"xl\", color: \"blue\" },\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationAnnotateTextResult"
+  },
+  {
+    "path": "presentation.diagrams.generateProgram",
+    "namespace": "presentation.diagrams",
+    "summary": "Generate the program (space + department) diagrams for the current model, creating new layout sheets.",
+    "examplePrompts": [
+      "Generate the program diagrams for this project",
+      "Auto-generate the space and department diagram sheets",
+      "Create the program layout sheets from the model\n\n# Example\n```ts\nconst { sheetIds } = await snaptrude.presentation.diagrams.generateProgram()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginPresentationDiagramsGenerateResult"
+  },
   {
     "path": "presentation.diagrams.place",
     "namespace": "presentation.diagrams",
@@ -5572,18 +6397,153 @@
     "argsType": "{ url?: string; dataUrl?: string }",
     "resultType": "PluginPresentationImportResult"
   },
+  {
+    "path": "presentation.placedViews.get",
+    "namespace": "presentation.placedViews",
+    "summary": "Get a single placed view by its shape id.",
+    "examplePrompts": [
+      "Get the placed view I just dropped on the sheet",
+      "Read the position and scale of this placed view",
+      "What's the crop on shape_123?\n\n# Example\n```ts\nconst placed = await snaptrude.presentation.placedViews.get(shapeId)\nconsole.log(placed.position, placed.scale)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedView"
+  },
+  {
+    "path": "presentation.placedViews.list",
+    "namespace": "presentation.placedViews",
+    "summary": "List the placed views in the presentation.",
+    "examplePrompts": [
+      "Which views are placed on this sheet?",
+      "List all the placed views in the presentation",
+      "What's laid out on sheet 2?",
+      "Show me every view on the Present canvas\n\n# Example\n```ts\nconst { placedViews } = await snaptrude.presentation.placedViews.list(\"sheet_1\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationPlacedViewsListResult"
+  },
+  {
+    "path": "presentation.placedViews.move",
+    "namespace": "presentation.placedViews",
+    "summary": "Move a placed view.",
+    "examplePrompts": [
+      "Move the site plan view to the top-left of sheet 2",
+      "Reposition this placed view to 100, 200",
+      "Move the hero perspective onto the cover sheet\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.move(shapeId, { x: 50, y: 50 }, {\nsheetId: \"sheet_2\",\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedView"
+  },
+  {
+    "path": "presentation.placedViews.scale",
+    "namespace": "presentation.placedViews",
+    "summary": "Resize a placed view by a uniform factor.",
+    "examplePrompts": [
+      "Make this placed view twice as big",
+      "Shrink the placed 3D view to half its size",
+      "Scale the placed plan up by 50%\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.scale(shapeId, 2)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedView"
+  },
+  {
+    "path": "presentation.placedViews.setCrop",
+    "namespace": "presentation.placedViews",
+    "summary": "Crop a placed view, or clear its crop.",
+    "examplePrompts": [
+      "Crop the placed view to its left half",
+      "Crop this view to the top-right quarter",
+      "Remove the crop from the placed plan\n\n# Example\n```ts\n// keep the left half of the view\nawait snaptrude.presentation.placedViews.setCrop(shapeId, {\ntopLeft: { x: 0, y: 0 },\nbottomRight: { x: 0.5, y: 1 },\n})\nawait snaptrude.presentation.placedViews.setCrop(shapeId, null) // clear\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedView"
+  },
+  {
+    "path": "presentation.placedViews.setScale",
+    "namespace": "presentation.placedViews",
+    "summary": "Set a placed view's architectural scale.",
+    "examplePrompts": [
+      "Set the plan to 1:100",
+      "Change the placed floor plan to 1:50 scale",
+      "Make this view print at quarter-inch scale\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.setScale(shapeId, 100) // 1:100\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedView"
+  },
+  {
+    "path": "presentation.shapes.list",
+    "namespace": "presentation.shapes",
+    "summary": "List the calling plugin's shapes.",
+    "examplePrompts": [
+      "Which annotations has my plugin placed on the sheets?",
+      "List the plugin's shapes before refreshing them",
+      "Check whether the FAR label already exists\n\n# Example\n```ts\nconst { shapes } = await snaptrude.presentation.shapes.list()\nconst hasLabel = shapes.some((s) => s.key === \"far-label\")\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginPresentationShapesListResult"
+  },
+  {
+    "path": "presentation.shapes.remove",
+    "namespace": "presentation.shapes",
+    "summary": "Delete the shape for a key.",
+    "examplePrompts": [
+      "Remove the FAR label from the sheet",
+      "Delete the highlight the plugin added earlier",
+      "Clear the \"far-label\" annotation\n\n# Example\n```ts\nconst removed = await snaptrude.presentation.shapes.remove(\"far-label\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "boolean"
+  },
+  {
+    "path": "presentation.shapes.removeAll",
+    "namespace": "presentation.shapes",
+    "summary": "Delete every shape owned by the calling plugin.",
+    "examplePrompts": [
+      "Clear all annotations my plugin added",
+      "Reset the sheet output before rerunning the analysis",
+      "Remove every plugin-drawn shape\n\n# Example\n```ts\nconst deleted = await snaptrude.presentation.shapes.removeAll()\n```"
+    ],
+    "argsType": null,
+    "resultType": "number"
+  },
+  {
+    "path": "presentation.shapes.upsert",
+    "namespace": "presentation.shapes",
+    "summary": "Create or update the shape for a key.",
+    "examplePrompts": [
+      "Update the analysis label on the sheet instead of adding another one",
+      "Rerun the daylight report and refresh its annotations",
+      "Keep one \"FAR: 2.4\" text on Sheet 1 that updates on each run",
+      "Draw a highlight rectangle the plugin can move on the next run\n\n# Example\n```ts\nconst { shapeId, created } = await snaptrude.presentation.shapes.upsert(\"far-label\", {\ntype: \"text\",\ntext: \"FAR: 2.4\",\nposition: { x: 40, y: 40 },\ncolor: \"blue\",\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationShapesUpsertResult"
+  },
   {
     "path": "presentation.sheets.create",
     "namespace": "presentation.sheets",
     "summary": "Create a new layout sheet.",
     "examplePrompts": [
       "Create a new sheet called Cover",
-      "Add a layout sheet",
-      "Make a new presentation sheet named Floor Plans\n\n# Example\n```ts\nconst sheet = await snaptrude.presentation.sheets.create(\"Cover\")\n```"
+      "Add an A3 landscape layout sheet",
+      "Make a new ANSI D presentation sheet named Floor Plans",
+      "Create a portrait A4 sheet\n\n# Example\n```ts\nconst sheet = await snaptrude.presentation.sheets.create(\"Cover\", {\nsize: \"ISO_A3\",\norientation: \"landscape\",\n})\n```"
     ],
     "argsType": "string",
     "resultType": "PluginPresentationSheet"
   },
+  {
+    "path": "presentation.sheets.delete",
+    "namespace": "presentation.sheets",
+    "summary": "Delete a layout sheet.",
+    "examplePrompts": [
+      "Delete sheet_2",
+      "Remove the Cover sheet",
+      "Get rid of the last layout sheet\n\n# Example\n```ts\nconst { id } = await snaptrude.presentation.sheets.delete(\"sheet_2\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheetsDeleteResult"
+  },
   {
     "path": "presentation.sheets.get",
     "namespace": "presentation.sheets",
@@ -5617,11 +6577,73 @@
       "Place the floor plan on Sheet 1",
       "Add this 3D view to the cover sheet",
       "Drop the site plan onto the layout sheet at 100, 200",
-      "Put the Ground Floor view on sheet_1\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.sheets.place(\"sheet_1\", \"view_123\")\n```"
+      "Put the Ground Floor view on sheet_1 at 1:100 scale",
+      "Place the plan on the cover sheet at quarter-inch scale\n\n# Example\n```ts\nconst { shapeId } = await snaptrude.presentation.sheets.place(\"sheet_1\", \"view_123\", {\nscale: 100, // 1:100 (metric project)\n})\n```"
     ],
     "argsType": "string",
     "resultType": "PluginPresentationSheetsPlaceResult"
   },
+  {
+    "path": "presentation.sheets.rename",
+    "namespace": "presentation.sheets",
+    "summary": "Rename a layout sheet.",
+    "examplePrompts": [
+      "Rename sheet_1 to Cover",
+      "Call the first sheet Ground Floor",
+      "Change this sheet's name to Site Plan\n\n# Example\n```ts\nconst sheet = await snaptrude.presentation.sheets.rename(\"sheet_1\", \"Cover\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheet"
+  },
+  {
+    "path": "presentation.sheets.reorder",
+    "namespace": "presentation.sheets",
+    "summary": "Move a sheet to a new position in the sheet order.",
+    "examplePrompts": [
+      "Move sheet_3 to the front",
+      "Make the Cover sheet the first sheet",
+      "Reorder this sheet to position 2\n\n# Example\n```ts\nconst { sheets } = await snaptrude.presentation.sheets.reorder(\"sheet_3\", 0)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheetsListResult"
+  },
+  {
+    "path": "presentation.sheets.setActive",
+    "namespace": "presentation.sheets",
+    "summary": "Make a sheet the active sheet.",
+    "examplePrompts": [
+      "Go to sheet_1",
+      "Open the Cover sheet",
+      "Switch to the Site Plan sheet\n\n# Example\n```ts\nawait snaptrude.presentation.sheets.setActive(\"sheet_1\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheet"
+  },
+  {
+    "path": "presentation.sheets.setSize",
+    "namespace": "presentation.sheets",
+    "summary": "Set a sheet's paper size and/or orientation.",
+    "examplePrompts": [
+      "Resize sheet_1 to A1",
+      "Make the cover sheet ANSI B portrait",
+      "Change this sheet to Arch D landscape",
+      "Set the sheet size to A3\n\n# Example\n```ts\nconst sheet = await snaptrude.presentation.sheets.setSize(\"sheet_1\", \"ISO_A1\", \"portrait\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheet"
+  },
+  {
+    "path": "presentation.sheets.updatePlacedView",
+    "namespace": "presentation.sheets",
+    "summary": "Refresh placed views to the current model state.",
+    "examplePrompts": [
+      "Update all the placed views to the latest model",
+      "Refresh the views on sheet_1",
+      "Re-render the placed views after my edits\n\n# Example\n```ts\nconst { shapeIds } = await snaptrude.presentation.sheets.updatePlacedView()\n```"
+    ],
+    "argsType": "{\n    sheetId?: string\n  }",
+    "resultType": "PluginPresentationSheetsUpdatePlacedViewResult"
+  },
   {
     "path": "presentation.views.capture",
     "namespace": "presentation.views",
@@ -5643,11 +6665,24 @@
       "Save the current view as Lobby Perspective",
       "Create a new saved view from where I'm looking",
       "Bookmark this camera angle",
-      "Save the current 2D plan as a view\n\n# Example\n```ts\nconst view = await snaptrude.presentation.views.create(\"Lobby\")\n```"
+      "Save the current 2D plan as a view",
+      "Save a view on the second storey\n\n# Example\n```ts\nconst view = await snaptrude.presentation.views.create(\"Lobby\")\n// …or capture the view on a specific storey\nconst level2 = await snaptrude.presentation.views.create(\"Level 2\", { storey: 2 })\n```"
     ],
     "argsType": "string",
     "resultType": "PluginPresentationViewsCreateResult"
   },
+  {
+    "path": "presentation.views.delete",
+    "namespace": "presentation.views",
+    "summary": "Delete a saved view.",
+    "examplePrompts": [
+      "Delete the view named Old Draft",
+      "Remove this saved view",
+      "Get rid of the Lobby camera bookmark\n\n# Example\n```ts\nconst { id } = await snaptrude.presentation.views.delete(\"view_123\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationViewsDeleteResult"
+  },
   {
     "path": "presentation.views.get",
     "namespace": "presentation.views",
@@ -5675,7 +6710,7 @@
   {
     "path": "presentation.views.getSettings",
     "namespace": "presentation.views",
-    "summary": "Read a saved view's display settings (background, color mode, axis, edges, labels).",
+    "summary": "Read a saved view's display settings (background, color mode, view mode, axis, edges, labels).",
     "examplePrompts": [
       "What color mode is the Ground Floor view using?",
       "Get the display settings for this view",
@@ -5699,6 +6734,18 @@
     "argsType": null,
     "resultType": "PluginPresentationViewsListResult"
   },
+  {
+    "path": "presentation.views.rename",
+    "namespace": "presentation.views",
+    "summary": "Rename a saved view.",
+    "examplePrompts": [
+      "Rename the view Lobby to Entrance Lobby",
+      "Call this view Ground Floor Plan",
+      "Change the active view's name to Final\n\n# Example\n```ts\nconst view = await snaptrude.presentation.views.rename(\"view_123\", \"Entrance\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationViewsRenameResult"
+  },
   {
     "path": "presentation.views.setActive",
     "namespace": "presentation.views",
@@ -5721,7 +6768,8 @@
       "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```"
+      "Enable hidden-line mode for the section view",
+      "Make the 3D view orthographic instead of perspective\n\n# Example\n```ts\nawait snaptrude.presentation.views.updateSettings(\"view_123\", {\ncolorMode: \"monochrome\",\nshowAxis: false,\n})\n// switch a 3D view to an isometric (orthographic) projection\nawait snaptrude.presentation.views.updateSettings(\"view_123\", {\nviewMode: \"isometric\",\n})\n```"
     ],
     "argsType": "string",
     "resultType": "PluginPresentationViewsUpdateSettingsResult"
@@ -5793,6 +6841,18 @@
     "argsType": "PluginProgramAreaGroupBy",
     "resultType": "PluginProgramAreasListMembersResult"
   },
+  {
+    "path": "program.areas.refresh",
+    "namespace": "program.areas",
+    "summary": "Force the area breakdown to recompute, then return the fresh summary.",
+    "examplePrompts": [
+      "Recompute the area totals before I read them",
+      "Refresh the FAR numbers",
+      "Make sure the area breakdown is up to date\n\n# Example\n```ts\nconst s = await snaptrude.program.areas.refresh()\nconst { groups } = await snaptrude.program.areas.list(\"storeys\") // now fresh\nconsole.log(s.builtUp, groups.length)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramAreasRefreshResult"
+  },
   {
     "path": "program.areas.update",
     "namespace": "program.areas",
@@ -5802,7 +6862,7 @@
       "Override the site area to 5000",
       "Allow a 10 percent FAR deviation\n\n# Example\n```ts\nconst s = await snaptrude.program.areas.update({ targetFar: 2.5 })\nconsole.log(s.achievedFar, s.targetFar)\n```"
     ],
-    "argsType": "{ targetFar?: number; siteArea?: number; deviation?: number }",
+    "argsType": "{\n    targetFar?: number\n    siteArea?: number\n    deviation?: number\n  }",
     "resultType": "PluginProgramAreasUpdateResult"
   },
   {
@@ -5959,6 +7019,18 @@
     "argsType": "string",
     "resultType": "PluginProgramDepartmentsUpdateResult"
   },
+  {
+    "path": "program.layout.applySolution",
+    "namespace": "program.layout",
+    "summary": "Apply one of the pending arrange solutions.",
+    "examplePrompts": [
+      "Apply the second arrange solution",
+      "Pick layout solution 3 and commit it",
+      "Apply the arrange solution I chose\n\n# Example\n```ts\nawait snaptrude.program.layout.arrange({ autoCommit: false })\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}\nif (job?.status === \"pendingReview\") {\nconsole.log(`${job.totalSolutions} candidate layouts`)\nawait snaptrude.program.layout.applySolution(1) // commit the second one\n}\n```"
+    ],
+    "argsType": "number",
+    "resultType": "PluginProgramLayoutApplyResult"
+  },
   {
     "path": "program.layout.arrange",
     "namespace": "program.layout",
@@ -5966,7 +7038,8 @@
     "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```"
+      "Auto-arrange the program spaces",
+      "Arrange the rooms but let me pick the solution\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"
@@ -6007,6 +7080,18 @@
     "argsType": "PluginProgramLayoutRunArgs",
     "resultType": "PluginProgramLayoutRunResult"
   },
+  {
+    "path": "program.layout.stack",
+    "namespace": "program.layout",
+    "summary": "Stack the program across **every storey** of the building — the product's *Pack in envelope* / auto-stack.",
+    "examplePrompts": [
+      "Stack the program across all floors",
+      "Auto-stack the departments into the envelope on every storey",
+      "Pack the whole building's program into its envelope\n\n# Example\n```ts\nconst { success, skippedStoreys, error } = await snaptrude.program.layout.stack()\nif (!success) throw new Error(error)\nif (skippedStoreys.length)\nconsole.warn(`No envelope on storeys: ${skippedStoreys.join(\", \")}`)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramLayoutStackResult"
+  },
   {
     "path": "program.metrics.get",
     "namespace": "program.metrics",
@@ -6085,6 +7170,31 @@
     "argsType": null,
     "resultType": "PluginProgramSiteNorthAngleResult"
   },
+  {
+    "path": "program.site.getTimezone",
+    "namespace": "program.site",
+    "summary": "Get the IANA timezone of the project's geographic location.",
+    "examplePrompts": [
+      "What timezone is this project in?",
+      "Get the site's IANA timezone",
+      "What's the local time zone at the project location?",
+      "Which timezone should I use for the sun study schedule?\n\n# Example\n```ts\nconst timezone = await snaptrude.program.site.getTimezone()\nif (timezone) console.log(`Project timezone: ${timezone}`)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSiteTimezoneResult"
+  },
+  {
+    "path": "program.site.getWeather",
+    "namespace": "program.site",
+    "summary": "Get the weather file resolved for the project site.",
+    "examplePrompts": [
+      "Which weather file is my project using?",
+      "What EPW station was resolved for this site?",
+      "Get the weather file id for the daylight analysis\n\n# Example\n```ts\nconst weather = await snaptrude.program.site.getWeather()\nif (weather) console.log(weather.station, weather.selectionMethod)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSiteWeatherResult"
+  },
   {
     "path": "program.site.listGeoPolygons",
     "namespace": "program.site",
@@ -6101,7 +7211,7 @@
   {
     "path": "program.site.listPolygons",
     "namespace": "program.site",
-    "summary": "List the site parcels with their footprints (in scene coordinates).",
+    "summary": "List the site parcels with their footprints (world XZ plan coordinates, Snaptrude units).",
     "examplePrompts": [
       "List every site parcel",
       "Show me each plot's footprint",
@@ -6136,6 +7246,19 @@
     "argsType": "string",
     "resultType": "PluginProgramSpreadsheetAddConditionalFormattingResult"
   },
+  {
+    "path": "program.spreadsheet.addImage",
+    "namespace": "program.spreadsheet",
+    "summary": "Place a floating image on a workbook sheet from a base64 data URI.",
+    "examplePrompts": [
+      "Add my logo image to the report sheet",
+      "Place a PNG at cell B2 on the Takeoff sheet",
+      "Put an SVG diagram on a spreadsheet sheet",
+      "Insert an image into the workbook\n\n# Example\n```ts\nconst { name } = await snaptrude.program.spreadsheet.addImage(\n\"Report\",\n{ dataUri: \"data:image/png;base64,iVBORw0...\" },\n{ anchorCell: \"B2\", size: { width: 240, height: 120 }, name: \"logo\" },\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramSpreadsheetAddImageResult"
+  },
   {
     "path": "program.spreadsheet.bindings.create",
     "namespace": "program.spreadsheet.bindings",
@@ -6169,7 +7292,7 @@
       "Re-pull all my data bindings",
       "Refresh every binding on the sheets\n\n# Example\n```ts\nawait snaptrude.program.spreadsheet.bindings.refresh({ name: \"takeoff\" })\n```"
     ],
-    "argsType": "{ name?: string }",
+    "argsType": "{\n    name?: string\n  }",
     "resultType": "PluginProgramSpreadsheetBindingsRefreshResult"
   },
   {
@@ -6185,15 +7308,41 @@
     "argsType": "string",
     "resultType": "PluginProgramSpreadsheetCreateSheetResult"
   },
+  {
+    "path": "program.spreadsheet.datasets.list",
+    "namespace": "program.spreadsheet.datasets",
+    "summary": "List the stored plugin datasets.",
+    "examplePrompts": [
+      "List my plugin datasets",
+      "What datasets are stored for the sheets?",
+      "Show the data sets bindings can use\n\n# Example\n```ts\nconst { datasets } = await snaptrude.program.spreadsheet.datasets.list()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSpreadsheetDatasetsListResult"
+  },
+  {
+    "path": "program.spreadsheet.datasets.set",
+    "namespace": "program.spreadsheet.datasets",
+    "summary": "Store (upsert) a named plugin dataset.",
+    "examplePrompts": [
+      "Store my plugin's rows as a named dataset",
+      "Upload data the sheets can bind to and refresh",
+      "Save a dataset for a live sheet binding",
+      "Push my computed table so a binding keeps it fresh\n\n# Example\n```ts\nawait snaptrude.program.spreadsheet.datasets.set(\n\"costs\",\n[\n{ key: \"item\", header: \"Item\" },\n{ key: \"cost\", header: \"Cost\", align: \"right\" },\n],\n[{ item: \"Concrete\", cost: 120 }],\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginProgramSpreadsheetDatasetsSetResult"
+  },
   {
     "path": "program.spreadsheet.export",
     "namespace": "program.spreadsheet",
-    "summary": "Export the whole report workbook to a file (xlsx, pdf, or csv).",
+    "summary": "Export the report workbook to a file (xlsx, pdf, or csv).",
     "examplePrompts": [
       "Export the report as an Excel file",
       "Download the whole workbook as a PDF",
       "Export the program workbook to xlsx",
-      "Save the report as a csv file\n\n# Example\n```ts\nconst file = await snaptrude.program.spreadsheet.export(\"xlsx\")\n// file.fileName, file.mimeType, file.dataBase64\n```"
+      "Save the report as a csv file",
+      "Export the Takeoff sheet as CSV\n\n# Example\n```ts\nconst file = await snaptrude.program.spreadsheet.export(\"xlsx\")\n// file.fileName, file.mimeType, file.dataBase64\n\n// CSV of a specific sheet:\nconst csv = await snaptrude.program.spreadsheet.export(\"csv\", { sheetName: \"Takeoff\" })\n```"
     ],
     "argsType": "PluginSpreadsheetExportFormat",
     "resultType": "PluginProgramSpreadsheetExportResult"
@@ -6208,9 +7357,23 @@
       "Get the last 10 audit log entries",
       "Read the program spreadsheet audit log\n\n# Example\n```ts\nconst { entries } = await snaptrude.program.spreadsheet.getAuditLog({ limit: 10 })\n```"
     ],
-    "argsType": "{ limit?: number }",
+    "argsType": "{\n    limit?: number\n  }",
     "resultType": "PluginProgramSpreadsheetGetAuditLogResult"
   },
+  {
+    "path": "program.spreadsheet.getMaterialTakeoff",
+    "namespace": "program.spreadsheet",
+    "summary": "Read the material take-off dataset (surface area per material, per element type).",
+    "examplePrompts": [
+      "Get the material take-off",
+      "How much of each material is used?",
+      "Read the surface area by material",
+      "Give me the material quantities before I render them",
+      "What's in the material take-off right now?\n\n# Example\n```ts\nconst mto = await snaptrude.program.spreadsheet.getMaterialTakeoff()\nfor (const row of mto.rows) {\nconsole.log(row.objectType, row.family, row.material, row.quantity, row.unit)\n}\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSpreadsheetGetMaterialTakeoffResult"
+  },
   {
     "path": "program.spreadsheet.getProgram",
     "namespace": "program.spreadsheet",
@@ -6309,7 +7472,7 @@
       "Recompute all the formulas",
       "Recalculate the Summary sheet\n\n# Example\n```ts\nawait snaptrude.program.spreadsheet.recalculate()\n```"
     ],
-    "argsType": "{ sheetName?: string }",
+    "argsType": "{\n    sheetName?: string\n  }",
     "resultType": "PluginProgramSpreadsheetRecalculateResult"
   },
   {
@@ -6336,7 +7499,7 @@
       "Generate the program schedule sheet titled Program",
       "Render the program filtered to the residential departments\n\n# Example\n```ts\nawait snaptrude.program.spreadsheet.renderProgram({ sheetName: \"Program\" })\n```"
     ],
-    "argsType": "{ sheetName?: string; title?: string; filter?: string }",
+    "argsType": "{\n    sheetName?: string\n    title?: string\n    filter?: string\n  }",
     "resultType": "PluginProgramSpreadsheetRenderResult"
   },
   {
@@ -6349,7 +7512,7 @@
       "Generate the takeoff schedule sheet titled Takeoff",
       "Render the material takeoff filtered to the walls\n\n# Example\n```ts\nawait snaptrude.program.spreadsheet.renderTakeoff({ sheetName: \"Takeoff\" })\n```"
     ],
-    "argsType": "{ sheetName?: string; title?: string; filter?: string }",
+    "argsType": "{\n    sheetName?: string\n    title?: string\n    filter?: string\n  }",
     "resultType": "PluginProgramSpreadsheetRenderResult"
   },
   {
@@ -6438,5 +7601,103 @@
     ],
     "argsType": "PluginSpreadsheetTransactionOp[]",
     "resultType": "PluginProgramSpreadsheetTransactionResult"
+  },
+  {
+    "path": "workspace.projects.copy",
+    "namespace": "workspace.projects",
+    "summary": "Copy the **current** project into a new project — the dashboard's \"Save As\".",
+    "examplePrompts": [
+      "Save this project as a new copy called Tower Study v2",
+      "Duplicate the current project into the Acme team",
+      "Make a copy of this project so I can try changes\n\n# Example\n```ts\nconst { projectId } = await snaptrude.workspace.projects.copy(\"Tower Study v2\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWorkspaceProjectsCopyResult"
+  },
+  {
+    "path": "workspace.projects.create",
+    "namespace": "workspace.projects",
+    "summary": "Create a new, empty BIM project.",
+    "examplePrompts": [
+      "Create a new project called Tower Study",
+      "Start a new project in the Acme team",
+      "Make a fresh project using millimeters",
+      "Create an empty project for me to work in\n\n# Example\n```ts\nconst { projectId } = await snaptrude.workspace.projects.create(\"Tower Study\", {\nteamId: \"team_1\",\nunit: \"mm\",\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWorkspaceProjectsCreateResult"
+  },
+  {
+    "path": "workspace.projects.get",
+    "namespace": "workspace.projects",
+    "summary": "Get a single project by id.",
+    "examplePrompts": [
+      "Get the project with this id",
+      "Look up a project by its floorkey",
+      "What is the name of this project?\n\n# Example\n```ts\nconst project = await snaptrude.workspace.projects.get(\"floorkey_123\")\nif (project) console.log(project.name)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWorkspaceProjectsGetResult"
+  },
+  {
+    "path": "workspace.projects.list",
+    "namespace": "workspace.projects",
+    "summary": "List the projects the user can access.",
+    "examplePrompts": [
+      "List all my projects",
+      "Show the projects in the Acme team",
+      "How many projects do I have?",
+      "What projects can I open?\n\n# Example\n```ts\nconst { projects } = await snaptrude.workspace.projects.list({ teamId: \"team_1\" })\nfor (const p of projects) console.log(p.id, p.name)\n```"
+    ],
+    "argsType": "{ teamId?: string }",
+    "resultType": "PluginWorkspaceProjectsListResult"
+  },
+  {
+    "path": "workspace.projects.rename",
+    "namespace": "workspace.projects",
+    "summary": "Rename a project.",
+    "examplePrompts": [
+      "Rename this project to Tower Study Final",
+      "Change the name of project floorkey_123",
+      "Give this project a new name\n\n# Example\n```ts\nconst { projectId } = await snaptrude.workspace.projects.rename(\n\"floorkey_123\",\n\"Tower Study Final\",\n)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWorkspaceProjectsRenameResult"
+  },
+  {
+    "path": "workspace.teams.get",
+    "namespace": "workspace.teams",
+    "summary": "Get a single team by id.",
+    "examplePrompts": [
+      "Get the team with id team_1",
+      "Look up a team by its id",
+      "What is the name of this team?\n\n# Example\n```ts\nconst team = await snaptrude.workspace.teams.get(\"team_1\")\nif (team) console.log(team.name)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWorkspaceTeamsGetResult"
+  },
+  {
+    "path": "workspace.teams.list",
+    "namespace": "workspace.teams",
+    "summary": "List the teams the user belongs to.",
+    "examplePrompts": [
+      "List all my teams",
+      "Which teams am I a member of?",
+      "Show every team I can access\n\n# Example\n```ts\nconst { teams } = await snaptrude.workspace.teams.list()\nfor (const t of teams) console.log(t.id, t.name)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginWorkspaceTeamsListResult"
+  },
+  {
+    "path": "workspace.teams.listMembers",
+    "namespace": "workspace.teams",
+    "summary": "List the members of a team.",
+    "examplePrompts": [
+      "List the members of the Acme team",
+      "Who is on team_1?",
+      "How many people are in this team?\n\n# Example\n```ts\nconst { members } = await snaptrude.workspace.teams.listMembers(\"team_1\")\nfor (const m of members) console.log(m.name, m.email)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginWorkspaceTeamsListMembersResult"
   }
 ]