@snaptrude/plugin-core 0.8.0 → 0.9.1

package/api-manifest.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",
@@ -412,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",
@@ -553,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",
@@ -632,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",
@@ -640,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",
@@ -2220,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",
@@ -2490,6 +2750,19 @@
     "argsType": null,
     "resultType": "boolean | null"
   },
+  {
+    "path": "core.io.terrain.replaceMesh",
+    "namespace": "core.io.terrain",
+    "summary": "Replace the terrain surface with a caller-supplied triangle mesh. Undoable (one step), and the replacement persists with the project.",
+    "examplePrompts": [
+      "Replace the terrain with this surveyed mesh",
+      "Flatten a building pad into the site surface",
+      "Load a custom DEM surface onto the terrain",
+      "Regrade the terrain from these points\n\n# Example\n```ts\n// Projects with no terrain yet: import first, then replace.\nif (!(await snaptrude.core.io.terrain.exists())) {\nawait snaptrude.core.io.import.terrain(40.7128, -74.006, 300, 300)\n}\nconst result = await snaptrude.core.io.terrain.replaceMesh(\npositions, // [x0, y0, z0, x1, y1, z1, …] — world space\nindices,   // [a0, b0, c0, a1, b1, c1, …]\n\"meters\",\n{\ncoordinateSpace: \"world\",\nexpectedTerrain: await snaptrude.core.io.terrain.get(),\nbaseline: \"make-replacement-original\",\npreserve: { datum: true, geolocation: true, satellite: true, material: true },\nclientMutationId: \"survey-2026-08-05-r1\",\n},\n)\n// result.modelRevision — pass back as expectedModelRevision on the next call\n```"
+    ],
+    "argsType": "number[]",
+    "resultType": "PluginTerrainReplaceMeshResult"
+  },
   {
     "path": "core.io.terrain.setDatum",
     "namespace": "core.io.terrain",
@@ -2923,6 +3196,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",
@@ -3292,6 +3600,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",
@@ -3386,7 +3786,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",
@@ -3424,6 +3825,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",
@@ -3550,7 +3963,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",
@@ -3563,7 +3977,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",
@@ -3619,6 +4034,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",
@@ -3654,10 +4082,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",
@@ -3715,6 +4144,18 @@
     "argsType": "ContourHandle",
     "resultType": "ComponentHandle"
   },
+  {
+    "path": "design.create.massFromBrep",
+    "namespace": "design.create",
+    "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": [
+      "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",
@@ -3780,10 +4221,11 @@
       "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?",
-      "Create a bedroom on the second floor from this outline\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// …place one directly on the second floor (no setActive dance):\nconst upstairs = await snaptrude.design.create.space(\ncontour, 3, \"Bedroom\", undefined, undefined, undefined, undefined, 2,\n)\n```"
+      "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",
@@ -3794,10 +4236,11 @@
       "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",
-      "Create one room on the ground floor and one on the first floor\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```"
+      "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",
@@ -3853,10 +4296,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",
@@ -4485,6 +4929,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",
@@ -4844,19 +5301,45 @@
     "resultType": "PluginEntityMeasurements | null"
   },
   {
-    "path": "design.query.spaces.get",
-    "namespace": "design.query.spaces",
-    "summary": "Get selected properties of a space — the selective multi-property read.",
+    "path": "design.query.referenceLines.get",
+    "namespace": "design.query.referenceLines",
+    "summary": "Get properties of a reference line by its ID.",
     "examplePrompts": [
-      "What is the area of this room?",
-      "Get the name, storey and height of the selected space",
-      "Which department does this room belong to?",
-      "Where is this space positioned on the plan?",
-      "Read the room type and dimensions of the selected room\n\n# Example\n```ts\nconst [space] = await snaptrude.design.query.listSpaces()\nconst info = await snaptrude.design.query.spaces.get(space, [\"name\", \"area\", \"position\"])\nconsole.log(info.name, info.area, info.position)\n```"
+      "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",
+    "summary": "Get selected properties of a space — the selective multi-property read.",
+    "examplePrompts": [
+      "What is the area of this room?",
+      "Get the name, storey and height of the selected space",
+      "Which department does this room belong to?",
+      "Where is this space positioned on the plan?",
+      "Read the room type and dimensions of the selected room\n\n# Example\n```ts\nconst [space] = await snaptrude.design.query.listSpaces()\nconst info = await snaptrude.design.query.spaces.get(space, [\"name\", \"area\", \"position\"])\nconsole.log(info.name, info.area, info.position)\n```"
     ],
     "argsType": "ComponentHandle",
     "resultType": "PluginDesignQuerySpacesGetResult"
   },
+  {
+    "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",
@@ -4960,10 +5443,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",
@@ -4974,10 +5458,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",
@@ -4988,10 +5473,11 @@
       "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",
@@ -5002,10 +5488,11 @@
       "Turn this room 45 degrees clockwise",
       "Spin the furniture block 180 degrees about its centre",
       "Rotate these masses 30 degrees around the vertical axis",
-      "Rotate these walls 90 degrees about the origin\n\n# Example\n```ts\nawait snaptrude.design.transform.rotate([\"space-id\"], 90)\n// …or rotate about an explicit pivot point\nconst { vec3 } = snaptrude.core.math\nawait snaptrude.design.transform.rotate([\"space-id\"], 90, { pivot: vec3.new(0, 0, 0) })\n```"
+      "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",
@@ -5059,6 +5546,19 @@
     "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",
@@ -5170,10 +5670,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",
@@ -5184,10 +5685,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",
@@ -5399,7 +5901,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",
@@ -5413,7 +5916,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",
@@ -5427,7 +5931,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",
@@ -5440,7 +5945,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",
@@ -5453,7 +5959,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",
@@ -5466,7 +5973,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",
@@ -5480,7 +5988,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",
@@ -5493,7 +6002,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",
@@ -5503,10 +6013,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",
@@ -5520,7 +6032,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",
@@ -5533,7 +6046,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",
@@ -5546,7 +6060,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",
@@ -5560,7 +6075,8 @@
       "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",
@@ -5829,6 +6345,18 @@
     "argsType": null,
     "resultType": "PluginPresentationDiagramsGenerateResult"
   },
+  {
+    "path": "presentation.diagrams.generateSite",
+    "namespace": "presentation.diagrams",
+    "summary": "Generate the site diagrams (location, streetview, climate) for the current model, creating new layout sheets.",
+    "examplePrompts": [
+      "Generate the site diagrams for this project",
+      "Create the location, streetview and climate sheets",
+      "Add a climate diagram sheet to the presentation\n\n# Example\n```ts\nconst { sheetIds } = await snaptrude.presentation.diagrams.generateSite({\ntypes: [\"location\", \"climate\"],\n})\n```"
+    ],
+    "argsType": "{\n    types?: PluginPresentationSiteDiagramType[]\n  }",
+    "resultType": "PluginPresentationDiagramsGenerateResult"
+  },
   {
     "path": "presentation.diagrams.place",
     "namespace": "presentation.diagrams",
@@ -5894,6 +6422,316 @@
     "argsType": "{ url?: string; dataUrl?: string }",
     "resultType": "PluginPresentationImportResult"
   },
+  {
+    "path": "presentation.placedViews.deleteShapes",
+    "namespace": "presentation.placedViews",
+    "summary": "Delete Present-canvas shapes. One undoable step for the whole batch, and the batch is atomic — if any id is rejected, nothing is deleted.",
+    "examplePrompts": [
+      "Delete the old AI renders from the sheet",
+      "Remove that placed view",
+      "Clear the diagram images I placed\n\n# Example\n```ts\nconst { deleted } = await snaptrude.presentation.placedViews.deleteShapes([\nout1.shapeId,\nout2.shapeId,\n])\n```"
+    ],
+    "argsType": "string[]",
+    "resultType": "PluginCanvasShapesDeleteResult"
+  },
+  {
+    "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.getShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Get one Present-canvas shape by id — works for any top-level shape (placed view, AI output, diagram image, plugin shape, annotation), unlike `get` which requires a placed view. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Inspect the AI render I just generated",
+      "Get the bounds of that diagram image"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
+  {
+    "path": "presentation.placedViews.getStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Read a placed view's (or sheet's) per-category presentation styles.",
+    "examplePrompts": [
+      "What line weights is this placed plan using?",
+      "Read the styling of the placed view",
+      "Which categories can I restyle on this sheet?\n\n# Example\n```ts\nconst styles = await snaptrude.presentation.placedViews.getStyles(shapeId)\nconst space = styles.categories.find((c) => c.category === \"Space\")\nconsole.log(space?.settings.cutWidth, space?.settings.lineStyle)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewStylesResult"
+  },
+  {
+    "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.listLabels",
+    "namespace": "presentation.placedViews",
+    "summary": "List a placed view's labels — the text children generated from the view's content (space names, departments, areas, dimension texts). Each label is individually addressable: it can be moved and hidden. Returns `[]` when the view has no labels. Requires Present mode to be open.",
+    "examplePrompts": [
+      "List the labels on this placed plan",
+      "Where are the space labels on this view?",
+      "Show every label with its position\n\n# Example\n```ts\nconst { labels } = await snaptrude.presentation.placedViews.listLabels(shapeId)\nfor (const l of labels) console.log(l.text, l.position, l.hidden)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabelsResult"
+  },
+  {
+    "path": "presentation.placedViews.listShapes",
+    "namespace": "presentation.placedViews",
+    "summary": "List the top-level shapes on the Present canvas — not just placed views: AI-generated outputs, placed diagram images, plugin-created shapes, and annotations, each with an `origin` classification. Sheets (frames) are not listed — use `sheets.list`. Pass `sheetId` to list only shapes on that sheet. Returns `[]` when Present mode is closed.",
+    "examplePrompts": [
+      "List everything on the Present canvas",
+      "What AI outputs are on this sheet?",
+      "Show all the shapes with their positions\n\n# Example\n```ts\nconst { shapes } = await snaptrude.presentation.placedViews.listShapes()\nconst aiOutputs = shapes.filter((s) => s.origin === \"aiOutput\")\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShapesListResult"
+  },
+  {
+    "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.moveLabel",
+    "namespace": "presentation.placedViews",
+    "summary": "Move a label to a new position (coordinates relative to its placed view, the same space `listLabels` reports). The manual position survives style changes. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Move the kitchen label out of the hatched area",
+      "Nudge this label 20 units right",
+      "Reposition the area text"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabel"
+  },
+  {
+    "path": "presentation.placedViews.moveShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Move any Present-canvas shape (AI outputs, diagram images, plugin shapes, annotations — placed views too). Same coordinate semantics as `move`: sheet-local when on a sheet, page coordinates otherwise; pass `options.sheetId` to reparent onto a sheet. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Move the AI render to the top of the sheet",
+      "Put the diagram image at 100, 200"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
+  {
+    "path": "presentation.placedViews.resetStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Reset a placed view's styling to defaults — the sidebar's Reset button: clears every per-category override and view-style restyle, resets font styles, and un-hides labels hidden by styling. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Reset this view's styling",
+      "Clear all the style overrides on the placed plan",
+      "Put the sheet styles back to default"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.resizeShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Resize any Present-canvas shape by a uniform factor about its top-left corner (aspect ratio held) — the generic counterpart of `scale`, which requires a placed view. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Make the AI output half its size",
+      "Double the size of that image"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
+  {
+    "path": "presentation.placedViews.rotateShape",
+    "namespace": "presentation.placedViews",
+    "summary": "Rotate any Present-canvas shape (AI outputs, diagram images, plugin shapes, annotations — placed views too) — the generic counterpart of `setRotation`, same target rules as `moveShape`. Same semantics: **absolute** angle in radians (tldraw convention) about the shape's bounds center, canonicalized into `[0, 2π)` (pass values in that range for an exact round-trip via `getShape`), one undo step. A placed view passed here falls under the same 3D-only rule as `setRotation`: 2D and site-plan views cannot rotate and are refused with a typed `PRECONDITION_FAILED`. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Rotate the AI render 15 degrees",
+      "Turn that image sideways",
+      "Reset the diagram image's rotation"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
+  {
+    "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.setLabelHidden",
+    "namespace": "presentation.placedViews",
+    "summary": "Hide or show a single label (independent of the category-level label visibility). Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Hide the corridor label",
+      "Show that label again"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewLabel"
+  },
+  {
+    "path": "presentation.placedViews.setMask",
+    "namespace": "presentation.placedViews",
+    "summary": "Toggle \"mask context buildings\" on a placed view — mutes the inactive proposal buildings in the view (the sidebar checkbox). Views only. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Mask the context buildings in this view",
+      "Show the neighboring proposals again in the placed view"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.setOpacity",
+    "namespace": "presentation.placedViews",
+    "summary": "Set a Present-canvas shape's opacity (`0` transparent .. `1` opaque) — the sidebar's whole-shape opacity slider (distinct from the per-category fill opacity in `updateStyles`). Works for any top-level shape. Undoable. Requires Present mode to be open.",
+    "examplePrompts": [
+      "Fade the placed view to 50%",
+      "Make the AI render semi-transparent"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.setRotation",
+    "namespace": "presentation.placedViews",
+    "summary": "Set a placed view's rotation.",
+    "examplePrompts": [
+      "Rotate the placed plan 90 degrees",
+      "Set this view's rotation to 45 degrees",
+      "Straighten the placed view back to zero rotation\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.setRotation(shapeId, Math.PI / 2)\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.placedViews.updateFontStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Update a category's label typography on a placed view (or sheet) — the configure panel's Text tab.",
+    "examplePrompts": [
+      "Set the space labels to Roboto 24px bold",
+      "Hide the area values on this plan",
+      "Make the department labels italic\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.updateFontStyles(shapeId, \"Space\", {\nobjectLabels: { fontFamily: \"Roboto\", fontWeight: \"700\", fontSize: 24 },\nvisibleTypes: [\"objectLabels\", \"areas\"],\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "void"
+  },
+  {
+    "path": "presentation.placedViews.updateStyles",
+    "namespace": "presentation.placedViews",
+    "summary": "Update one style category on a placed view (or sheet) — the same writes the Present sidebar's per-category configure panel performs.",
+    "examplePrompts": [
+      "Set the Space cut line weight to 0.5 mm",
+      "Make the Department lines dashed",
+      "Color the plan by department",
+      "Hide the dimension lines on this view",
+      "Round the space corners with a 2 ft radius\n\n# Example\n```ts\nawait snaptrude.presentation.placedViews.updateStyles(shapeId, \"Space\", {\ncutWidth: 0.5,\nprojectionWidth: 0.18,\nlineStyle: \"dashed\",\ncolorMode: \"department\",\n})\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPlacedViewCategoryStyles"
+  },
+  {
+    "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",
@@ -5994,6 +6832,18 @@
     "argsType": "string",
     "resultType": "PluginPresentationSheet"
   },
+  {
+    "path": "presentation.sheets.setMargin",
+    "namespace": "presentation.sheets",
+    "summary": "Set a sheet's print margin.",
+    "examplePrompts": [
+      "Set the sheet margin to half an inch",
+      "Remove the margins on sheet_1",
+      "Give the cover sheet a 10mm margin\n\n# Example\n```ts\nconst sheet = await snaptrude.presentation.sheets.setMargin(\"sheet_1\", 0.5)\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginPresentationSheet"
+  },
   {
     "path": "presentation.sheets.setSize",
     "namespace": "presentation.sheets",
@@ -6019,6 +6869,56 @@
     "argsType": "{\n    sheetId?: string\n  }",
     "resultType": "PluginPresentationSheetsUpdatePlacedViewResult"
   },
+  {
+    "path": "presentation.slideshow.getState",
+    "namespace": "presentation.slideshow",
+    "summary": "Read the slideshow state.",
+    "examplePrompts": [
+      "Is the slideshow running?",
+      "Which slide is the presentation on?",
+      "Check the slideshow state\n\n# Example\n```ts\nconst { running, index } = await snaptrude.presentation.slideshow.getState()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginPresentationSlideshowState"
+  },
+  {
+    "path": "presentation.slideshow.start",
+    "namespace": "presentation.slideshow",
+    "summary": "Start the slideshow.",
+    "examplePrompts": [
+      "Start the slideshow",
+      "Present the sheets from the beginning",
+      "Start the slideshow on sheet 3",
+      "Play the presentation starting at the cover sheet\n\n# Example\n```ts\nconst state = await snaptrude.presentation.slideshow.start({ startIndex: 2 })\nconsole.log(state.running, state.index) // true, 2\n```"
+    ],
+    "argsType": "{\n    sheetIds?: string[]\n    startIndex?: number\n  }",
+    "resultType": "PluginPresentationSlideshowState"
+  },
+  {
+    "path": "presentation.slideshow.stop",
+    "namespace": "presentation.slideshow",
+    "summary": "Stop the slideshow.",
+    "examplePrompts": [
+      "Stop the slideshow",
+      "Exit the presentation",
+      "Close the slideshow and go back to the sheets\n\n# Example\n```ts\nawait snaptrude.presentation.slideshow.stop()\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginPresentationSlideshowState"
+  },
+  {
+    "path": "presentation.tables.place",
+    "namespace": "presentation.tables",
+    "summary": "Place a table on a sheet.",
+    "examplePrompts": [
+      "Put the area schedule as a table on Sheet 1",
+      "Add a table of the room programs to the cover sheet",
+      "Paste this data as a table on the sheet",
+      "Place a two-column table of space names and areas\n\n# Example\n```ts\nconst shape = await snaptrude.presentation.tables.place(\"sheet_1\", {\nrows: [\n[\"Room\", \"Area\"],\n[\"Kitchen\", \"12.4 m²\"],\n[\"Living\", \"28.0 m²\"],\n],\n}, { position: { x: 40, y: 40 } })\n```"
+    ],
+    "argsType": "string",
+    "resultType": "PluginCanvasShape"
+  },
   {
     "path": "presentation.views.capture",
     "namespace": "presentation.views",
@@ -6533,6 +7433,44 @@
     "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.listEdges",
+    "namespace": "program.site",
+    "summary": "List each site parcel's boundary edges with their front / side / rear classification — the same per-edge roles the buildable-envelope setback pills show on canvas, so a plugin can pick up the user's edge tagging without asking them to set it up again.",
+    "examplePrompts": [
+      "Which edge of my site is the front?",
+      "Read the front / side / rear edges of the plot",
+      "What setback applies to each site edge?",
+      "Get the site edges the way the setback pills show them\n\n# Example\n```ts\nconst { sites } = await snaptrude.program.site.listEdges()\nfor (const site of sites)\nfor (const e of site.edges)\nconsole.log(e.edgeIndex, e.role, e.roleSource, e.setbackMeters)\n```"
+    ],
+    "argsType": null,
+    "resultType": "PluginProgramSiteListEdgesResult"
+  },
   {
     "path": "program.site.listGeoPolygons",
     "namespace": "program.site",
@@ -6584,6 +7522,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",
@@ -6633,6 +7584,31 @@
     "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",
@@ -6901,5 +7877,127 @@
     ],
     "argsType": "PluginSpreadsheetTransactionOp[]",
     "resultType": "PluginProgramSpreadsheetTransactionResult"
+  },
+  {
+    "path": "workspace.closePresentMode",
+    "namespace": "workspace",
+    "summary": "Close Present mode and return to the modeling canvas.",
+    "examplePrompts": [
+      "Close present mode",
+      "Exit the presentation editor",
+      "Go back to the modeling canvas\n\n# Example\n```ts\nawait snaptrude.workspace.closePresentMode()\n```"
+    ],
+    "argsType": null,
+    "resultType": "void"
+  },
+  {
+    "path": "workspace.openPresentMode",
+    "namespace": "workspace",
+    "summary": "Open Present mode — the documentation editor the `presentation.*` namespaces operate on.",
+    "examplePrompts": [
+      "Open present mode",
+      "Switch to the presentation editor",
+      "Open the sheets so I can lay out views\n\n# Example\n```ts\nawait snaptrude.workspace.openPresentMode()\nconst { sheets } = await snaptrude.presentation.sheets.list()\n```"
+    ],
+    "argsType": null,
+    "resultType": "void"
+  },
+  {
+    "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"
   }
 ]