summer-engine 3.1.0 → 3.2.0

package/library/tools/raycast/resource.yaml

@@ -0,0 +1,101 @@
+id: tool/raycast
+kind: tool
+version: 1.0.0
+summary: Cast one ray from any point in an open scene — hit node, point and normal; physics first, visual AABB fallback declared. Read-only.
+use_when:
+  - finding the wall, floor or ceiling in front of a point and its normal before anything is placed there
+  - choosing where a lamp, pipe or sign mounts on a facade
+  - checking what a line of sight or a drop line hits
+do_not_use_when:
+  - you want clearance around an existing node in every direction — summer_starcast
+  - you want to mount the piece in the same call — summer_attach_to_surface casts its own ray
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/attach-to-surface
+    - tool/starcast
+    - tool/snap-to-surface
+  skills:
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_raycast
+implementation:
+  module: src/mcp/tools/placement-tools.ts
+  export: registerPlacementTools
+surfaces:
+  mcp:
+    tool_name: summer_raycast
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene, e.g. 'res://levels/street.tscn'. It must be open; physics needs it to be the active tab.
+    origin:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: Ray start [x, y, z] in scene (world) space.
+    direction:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: Ray direction [x, y, z], non-zero; normalized for you.
+    maxDistance:
+      type: number
+      exclusiveMinimum: 0
+      maximum: 10000
+      default: 100
+      description: Maximum ray length in scene units.
+    collisionMask:
+      type: integer
+      minimum: 0
+      maximum: 4294967295
+      default: 4294967295
+      description: Godot 3D physics layer mask for physics queries.
+    collideWithAreas:
+      type: boolean
+      default: false
+      description: Also hit Area3D volumes (physics only).
+    evidence:
+      type: string
+      enum: [auto, physics, visual_aabb]
+      default: auto
+      description: "auto: physics first, visual AABB fallback when physics finds nothing (declared). physics or visual_aabb: that channel only."
+    exclude:
+      type: array
+      maxItems: 16
+      items:
+        type: string
+      description: Nodes (with descendants) the ray ignores.
+  required:
+    - scenePath
+    - origin
+    - direction
+  additionalProperties: false
+authority:
+  filesystem: false
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/read-file/resource.yaml

@@ -1,10 +1,12 @@
 id: tool/read-file
 kind: tool
-version: 1.0.2
-summary: Read a text file from the engine-bound project and return its full-file sha256 receipt for guarded overwrites.
+version: 1.1.0
+summary: Read a project text file, a line or byte window of it, or the entries of a .json picked by json_path/keys, with the full-file sha256 receipt.
 use_when:
   - reading project files through the engine
   - getting the sha256 required before overwriting a file
+  - reading a file too big for one result in pages (offset/limit)
+  - '"read the wall_door_b entry of a kit manifest" — json_path / keys instead of the whole file'
 facets:
   lifecycle:
     - build
@@ -18,6 +20,11 @@ license: MIT
 status: stable
 aliases:
   - summer_read_file
+related:
+  tools:
+    - tool/grep
+    - tool/write-file
+    - tool/replace-text
 implementation:
   module: src/mcp/tools/file-tools.ts
   export: registerFileTools
@@ -36,6 +43,33 @@ input_schema:
       exclusiveMinimum: 0
       maximum: 1000000
       default: 200000
+      description: Most bytes of content to return (UTF-8). Default 200000. A window or JSON selection is cut at this size too.
+    offset:
+      type: integer
+      minimum: 0
+      description: Skip this many units (lines by default, see unit) before returning content. 0 = from the start.
+    limit:
+      type: integer
+      exclusiveMinimum: 0
+      description: Return at most this many units (lines by default). The result's window.next_offset continues the read.
+    unit:
+      type: string
+      enum:
+        - lines
+        - bytes
+      description: "What offset/limit count: 'lines' (default) or 'bytes' (cut on UTF-8 character boundaries)."
+    json_path:
+      type: string
+      description: "For a JSON file: return only this value, e.g. 'pieces.wall_a', 'pieces[\"a b\"]', 'items[3].size_m'."
+    keys:
+      type: array
+      items:
+        type: string
+      maxItems: 64
+      description: "For a JSON object (the file root or the json_path value): keep only these keys; * and ? wildcards, e.g. ['wall_*']."
+    keys_only:
+      type: boolean
+      description: "For a JSON object: return only its key names (after the keys filter), not the values — a cheap table of contents."
   required:
     - path
   additionalProperties: false

package/library/tools/read-library/resource.yaml

@@ -1,6 +1,6 @@
 id: tool/read-library
 kind: tool
-version: 1.0.0
+version: 1.1.0
 summary: Load one library entry by id — a skill's body and metadata, a tool's call recipe, a template's pin, a reference's text — ending in the feedback footer.
 use_when:
   - summer_search_library returned an id and you need the entry itself before acting
@@ -48,7 +48,7 @@ input_schema:
       type: string
       minLength: 1
       maxLength: 200
-      description: The entry id as returned by summer_search_library, <kind>/<slug>, e.g. skill/vfx-water-ripple or tool/screenshot.
+      description: The entry id as returned by summer_search_library, <kind>/<slug>, e.g. skill/vfx-water-ripple or tool/screenshot. A file an entry links loads by <entry id>/<link as written>, e.g. skill/spatial-placement/references/kit-placement-tools.md; the linked files list at the end of a body gives each id.
     part:
       type: string
       enum:

package/library/tools/repeat-along/resource.yaml

@@ -0,0 +1,129 @@
+id: tool/repeat-along
+kind: tool
+version: 1.0.0
+summary: Instance copies of one scene along a line in one call — clamps every 0.45 m, braces, fence posts, window rows — and get the created node paths back.
+use_when:
+  - placing wall clamps, gutter braces or duct braces at a fixed spacing along a run
+  - a row of fence posts, bollards, lamps or window modules
+  - filling a line with as many copies as fit at a spacing
+do_not_use_when:
+  - scattering copies over an area or a grid — summer_run_script with ctx.scatter / ctx.grid
+  - spacing nodes that already exist — summer_align_distribute_3d
+facets:
+  lifecycle:
+    - build
+  domains:
+    - scenes
+    - 3d
+    - world-building
+    - level-design
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/instantiate-scene
+    - tool/batch
+    - tool/attach-to-surface
+  skills:
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_repeat_along
+implementation:
+  module: src/mcp/tools/placement-tools.ts
+  export: registerPlacementTools
+surfaces:
+  mcp:
+    tool_name: summer_repeat_along
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Exact scene, e.g. 'res://levels/street.tscn'.
+    template:
+      type: string
+      minLength: 1
+      maxLength: 512
+      description: Scene to instance for every copy (.tscn, .scn, .glb, .gltf).
+    parent:
+      type: string
+      minLength: 1
+      maxLength: 256
+      description: Parent for the copies; start/end/direction are in this parent's local space.
+    start:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: First copy's position [x, y, z].
+    end:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: Line end. With spacing as many copies as fit; with count, count copies from start to end.
+    direction:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: Instead of end, the row direction; needs count and spacing.
+    count:
+      type: integer
+      minimum: 1
+      maximum: 64
+      description: Number of copies.
+    spacing:
+      type: number
+      exclusiveMinimum: 0
+      maximum: 1000
+      description: Distance between neighbouring copies' origins.
+    align:
+      type: string
+      enum: [start, center, end]
+      default: start
+      description: With end + spacing, where the leftover length goes.
+    rotationDegrees:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: rotation_degrees for every copy.
+    scale:
+      type: array
+      minItems: 3
+      maxItems: 3
+      items:
+        type: number
+      description: scale for every copy.
+    namePrefix:
+      type: string
+      minLength: 1
+      maxLength: 64
+      description: Copies are named <namePrefix>_<n> (default the template file name).
+  required:
+    - scenePath
+    - template
+    - parent
+    - start
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: true
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - scene-valid

package/library/tools/replace-node/resource.yaml

@@ -1,11 +1,12 @@
 id: tool/replace-node
 kind: tool
-version: 1.0.2
-summary: Replace a node with a different type or scene, preserving its tree position and children.
+version: 1.1.0
+summary: Replace a node with another scene or type, keeping its parent, index, name, transform and children, and verify the saved scene holds it.
 use_when:
   - swapping a placeholder for a prefab or changing a body type
   - '"turn this StaticBody3D into a RigidBody3D but keep its children"'
   - swapping the placeholder cube for the real prefab in place
+  - swapping one kit piece for another (a wall host for a door host) without hand-copying its transform
 do_not_use_when:
   - adding alongside instead of replacing — summer_add_node / summer_instantiate_scene
 facets:
@@ -21,6 +22,11 @@ license: MIT
 status: stable
 aliases:
   - summer_replace_node
+related:
+  tools:
+    - tool/remove-node
+    - tool/instantiate-scene
+    - tool/read-file
 implementation:
   module: src/mcp/tools/scene-tools.ts
   export: registerSceneTools
@@ -36,13 +42,13 @@ input_schema:
       description: Target scene path, e.g. 'res://main.tscn'
     path:
       type: string
-      description: Node path to replace
+      description: Node path to replace, e.g. './House3/Front/G_f2_door'
     type:
       type: string
-      description: New node type, e.g. 'RigidBody3D'
+      description: New node type, e.g. 'RigidBody3D'. Give exactly one of type or scene.
     scene:
       type: string
-      description: Scene to replace with, e.g. 'res://enemies/boss.tscn'
+      description: Scene or model to replace with, e.g. 'res://kit/wall_door_02.tscn'. Give exactly one of type or scene.
   required:
     - scenePath
     - path

package/library/tools/scene-audit/resource.yaml

@@ -0,0 +1,144 @@
+id: tool/scene-audit
+kind: tool
+version: 1.3.0
+summary: 'Read-only pass over any 3D scene, from geometry and materials: see-through holes, exposed edges, open pipe ends, floor gaps, clipping props.'
+use_when:
+  - 'after each build stage of a 3D level or kit-built street: "what is wrong with this scene and where exactly?"'
+  - 'before calling a scene done: find see-through walls (an insert narrower than its frame), floor tiles with holes, props floating, sunk or poking into walls'
+  - 'facade bands with an open end or a gap, seams between modules and modules out of line seen from the street; a duct or downpipe with a missing elbow, coupler or section'
+  - 'the same look items keep coming back: accept the ones you judged fine (accept:[{key, reason}]) so later audits count them but hide them until their evidence changes'
+  - 'finding props turned the wrong way against a wall (a bench standing perpendicular to it), stretched texture strips, duplicated pieces'
+  - 'flickering faces: coplanar overlaps anywhere (props, roofs, ledges, inserts against hosts, decals, two surfaces of one mesh), judged by the 24-bit depth precision at the view distance'
+  - 'bare ground at wall bases, an underlay plane covering drain channels, buried props: floor_gap and sunken say which surface a ray hits first'
+  - 'a lit city scene in the Compatibility renderer: meshes lit by more than the per-object light limit, hard spot rims'
+do_not_use_when:
+  - 'you already know the spot: look at it with summer_frame_nodes or summer_zoom, measure it with summer_raycast or summer_measure'
+  - 'the question is gameplay or reachability: summer_navigation_probe, summer_play'
+  - 'the scene has unsaved edits you want audited: it reads the SAVED file, so save first'
+  - 'requires ScenePreview (any current Summer Engine); an engine without it answers engine_lacks_op'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - verification
+    - scenes
+    - 3d
+    - level-design
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/frame-nodes
+    - tool/zoom
+    - tool/shot-sheet
+    - tool/raycast
+    - tool/measure
+    - tool/inspect-asset
+  skills:
+    - skill/verifying-scenes
+    - skill/spatial-placement
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_scene_audit
+implementation:
+  module: src/mcp/tools/audit-tools.ts
+  export: registerAuditTools
+surfaces:
+  mcp:
+    tool_name: summer_scene_audit
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Scene to audit, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.
+    checks:
+      type: array
+      items:
+        type: string
+        enum:
+          - through_hole
+          - floor_gap
+          - floating
+          - sunken
+          - interpenetration
+          - exposed_edge
+          - open_fixture_end
+          - orientation
+          - uv_stretch
+          - duplicate
+          - z_fight
+          - depth_step
+          - lights
+          - transform
+          - resource
+      minItems: 1
+      maxItems: 15
+      description: Only these checks (default all 15). Fewer checks run faster (duplicate, lights, transform and resource need no physics); rerun a check budget_ms left partial on its own.
+    root:
+      type: string
+      description: Report only issues under this node (subtree), e.g. "Block3". The whole scene is still loaded, so walls and floors outside it count as surroundings.
+    min_severity:
+      type: string
+      enum:
+        - error
+        - warn
+        - look
+      description: '"error" (only errors), "warn" (errors and warnings) or "look" (default: everything, including look items that only ask you to look).'
+    offset:
+      type: integer
+      minimum: 0
+      maximum: 100000
+      description: Skip this many issues of the sorted, filtered list (paging; the result names the next offset).
+    limit:
+      type: integer
+      minimum: 1
+      maximum: 50
+      description: Issues per page (default 15, max 50). The result is capped at 5 KB; a page that does not fit is cut and says so.
+    budget_ms:
+      type: integer
+      minimum: 250
+      maximum: 60000
+      description: 'Editor time for the whole audit (default 3000 ms). Each check gets a share weighted by its usual cost (unused time passes on); a check past its share stops and counts.<check>.partial gives the share it covered. Under load, rerun the partial checks with checks or a larger budget.'
+    accept:
+      type: array
+      maxItems: 50
+      items:
+        type: object
+        properties:
+          key:
+            type: string
+            minLength: 8
+            maxLength: 360
+            description: The issue's key from a previous result (issues[].key).
+          reason:
+            type: string
+            minLength: 3
+            maxLength: 200
+            description: Why it is fine, e.g. "coplanar faces hidden behind a sign".
+        required:
+          - key
+          - reason
+        additionalProperties: false
+      description: 'Accept look or warn items you judged fine (up to 50 per call): [{key, reason}] with keys from this scene''s issues. Written to res://.summer/audit-accept.json (the only file the audit writes), then counted (counts.<check>.accepted) but hidden on every later audit until their evidence changes materially (severity rises, or the measured size moves by over 25%): then they show again with accept_stale. Errors cannot be accepted.'
+    show_accepted:
+      type: boolean
+      description: 'List accepted items too (each with its accepted reason). Default false: hidden, only counted.'
+    render:
+      type: string
+      enum:
+        - sheet
+        - none
+      description: '"sheet": also return ONE inline image of the first 6 issues of this page framed up close from their open side, each tile labelled with its issue number. Default "none".'
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false

package/library/tools/screenshot/resource.yaml

@@ -1,6 +1,6 @@
 id: tool/screenshot
 kind: tool
-version: 1.1.2
+version: 1.2.0
 summary: Capture a frame from the editor viewport, an offscreen scene render (fixed or bookmarked pose, numbered labels), or the running game, as an actual image.
 use_when:
   - visually verifying layout, scale, framing, or runtime state
@@ -8,11 +8,13 @@ use_when:
   - '"did the model land where I put it?" / "does the UI overlap?"'
   - '"take a screenshot of the game" / "screenshot the running game" — target "game" grabs the live frame'
   - before/after frames from the SAME viewpoint (framing "bookmark" / "free"), or an annotated screenshot with numbered labels mapped to node paths (marks)
+  - '"what changed since the last render of this view?" — framing "bookmark" with compare_previous returns previous | now | difference map in one image'
 do_not_use_when:
   - verifying lighting, mood, or environment-dependent materials with a preset framing (iso/top/front/...) of the scene target - those replace the WorldEnvironment with a flat preview; use framing "camera" (the scene's own Camera3D + real environment), a fixed pose ("free" / "bookmark", real environment too), or the game target instead
   - capturing motion or a sequence of frames (use a RunVerification probe's save_frame)
   - 'treating a uniformly black or grey "viewport" frame as evidence about lights, cameras, or content - the editor had not redrawn its viewport texture yet; the tool recaptures once and says so in the caption, otherwise recapture yourself'
   - saving or listing the viewpoints themselves — summer_camera_bookmark
+  - fitting a camera to nodes with the real environment, many views in one image, debug views, zooms or automatic framing — summer_frame_nodes, summer_shot_sheet, summer_debug_views, summer_zoom, summer_frame_shot
 facets:
   lifecycle:
     - build
@@ -25,6 +27,9 @@ related:
   tools:
     - tool/camera-bookmark
     - tool/world-snapshot
+    - tool/frame-nodes
+    - tool/shot-sheet
+    - tool/frame-shot
   skills:
     - skill/verifying-scenes
 source: official
@@ -95,12 +100,18 @@ input_schema:
       description: framing:"free" / "bookmark" only. Vertical field of view in degrees (1..179; default 60 for "free", the bookmark's own for "bookmark").
     marks:
       type: boolean
-      description: target:"scene" only, 3D scenes. Draw a Set-of-Mark overlay - numbered tags + box outlines over the largest visible VisualInstance3D nodes (lights excluded), ranked by projected screen area. The caption lists label -> node path (scene-root-relative) so you can name what you see. Works with every framing. 2D scenes return marks_unsupported. Default false.
+      description: 'target:"scene" only, 3D scenes. Draw a Set-of-Mark overlay - numbered tags + box outlines over the largest visible VisualInstance3D nodes (lights excluded), ranked by projected screen area. The caption lists label -> node path (scene-root-relative) so you can name what you see, and an occlusion test (centre + 4 bounds points from the rendered camera) notes "(hidden behind <path>)" on labels whose node is hidden - ignore those. Works with every framing. 2D scenes return marks_unsupported. Default false.'
     max_marks:
       type: integer
       minimum: 1
       maximum: 128
       description: marks:true only. Cap on numbered labels (engine default 32, at most 128). The caption says when the cap truncated the list.
+    compare_previous:
+      type: boolean
+      description: 'framing:"bookmark" only. Return ONE image of [previous render | now | difference map] for the bookmark, with the share of changed pixels (summer_shot_sheet compare_previous with this one bookmark); this render then replaces the bookmark''s previous image in res://.summer/shots/<bookmark>.jpg. A plain bookmark render (no marks, at most 1024 px) only creates that image when it is missing and never overwrites the compare baseline.'
+    update_previous:
+      type: boolean
+      description: 'framing:"bookmark" only. Replace the bookmark''s previous image (its compare baseline) with this clean render. Default false: an existing baseline is kept.'
   additionalProperties: false
 authority:
   filesystem: true

package/library/tools/search-assets/resource.yaml

@@ -56,6 +56,24 @@ input_schema:
         - all
       default: library
       description: "Where to search: library (public 25k+), my_assets (your generated assets), all"
+    style:
+      type: string
+      enum:
+        - realistic
+        - stylized-lowpoly
+        - toon
+        - pixel
+        - hand-painted
+        - voxel
+      description: "The game's one art direction: clashing styles are left out, matches come first"
+    preview:
+      type: boolean
+      default: false
+      description: Also return one picture of the first 9 results, numbered in order, to see them before importing
+    includeCommunity:
+      type: boolean
+      default: false
+      description: Also include people's own public AI generations
   required:
     - query
   additionalProperties: false

package/library/tools/shot-sheet/resource.yaml

@@ -0,0 +1,110 @@
+id: tool/shot-sheet
+kind: tool
+version: 1.0.0
+summary: 'Render N bookmarks and/or poses into one labelled grid image with real lighting; compare each bookmark with its previous render (difference map).'
+use_when:
+  - 'seeing every hero view of an environment at once after a change, in one image'
+  - '"did this change make it better?" — compare_previous puts previous, now and a difference map side by side per bookmark; plain sheets in between never reset that baseline'
+  - 'rendering several poses in one debug view (lighting, unshaded, normals, overdraw, wireframe) for a quick sweep'
+do_not_use_when:
+  - 'one pose in all debug views — summer_debug_views'
+  - 'motion or a frame sequence — a RunVerification probe''s save_frame'
+  - 'requires ScenePreview (any current Summer Engine); bookmarks require the camera bookmark ops (0.5.66 or newer)'
+facets:
+  lifecycle:
+    - build
+  domains:
+    - verification
+    - scenes
+    - 3d
+  modalities:
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/camera-bookmark
+    - tool/frame-shot
+    - tool/debug-views
+    - tool/zoom
+    - tool/screenshot
+  skills:
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_shot_sheet
+implementation:
+  module: src/mcp/tools/seeing-tools.ts
+  export: registerSeeingTools
+surfaces:
+  mcp:
+    tool_name: summer_shot_sheet
+    remote: false
+input_schema:
+  type: object
+  properties:
+    scenePath:
+      type: string
+      description: Scene to look at, e.g. "res://levels/town.tscn" (the SAVED file). Omit for the scene open in the editor.
+    shots:
+      type: array
+      items:
+        type: object
+        properties:
+          bookmark_name:
+            type: string
+            description: Pose from a camera bookmark (summer_camera_bookmark). Use INSTEAD of camera_position/camera_look_at.
+          camera_position:
+            type: string
+            description: 'Explicit pose: camera position, "Vector3(x, y, z)". Goes with camera_look_at.'
+          camera_look_at:
+            type: string
+            description: 'Explicit pose: point the camera looks at, "Vector3(x, y, z)".'
+          fov:
+            type: number
+            description: "Vertical field of view in degrees (1..179). Default: the bookmark's own, or 60."
+          label:
+            type: string
+            description: "Tile label (1-64 printable characters, no quotes, backslashes or $). Default: the bookmark name or 'shot N'."
+        additionalProperties: false
+      minItems: 1
+      maxItems: 12
+      description: 1-12 shots, each a bookmark_name OR camera_position + camera_look_at (+ fov), with an optional label. Rendered in this order, left to right, top to bottom.
+    view:
+      type: string
+      enum:
+        - beauty
+        - lighting
+        - unshaded
+        - normals
+        - overdraw
+        - wireframe
+      description: '"beauty" (default: real environment, lights, fog, tonemap), "lighting" (light only), "unshaded" (albedo/texture only), "normals" (world normals, x red y green z blue), "overdraw", "wireframe".'
+    compare_previous:
+      type: boolean
+      description: 'For bookmark shots: one row per bookmark of [previous render | now | difference map], with the share of changed pixels in the caption. The previous render is the bookmark''s slot in res://.summer/shots/; this render replaces it (it is the next baseline).'
+    update_previous:
+      type: boolean
+      description: 'Replace each bookmark''s previous image (its compare baseline) with this render without comparing. Default false: a sheet without compare_previous only creates a missing slot and never overwrites an existing baseline.'
+    max_size:
+      type: integer
+      minimum: 64
+      maximum: 4096
+      description: Longest edge of the returned JPEG in pixels (default 1536). Bigger costs more context; up to 4096 for detail work on a PC.
+    aspect:
+      type: number
+      description: Frame width/height (default 1.7778 = 16:9). Every tile uses it.
+    save_to:
+      type: string
+      description: Also write the returned image to res://.summer/shots/saved/<name>.jpg (1-64 of A-Z a-z 0-9 _ -; needs max_size <= 1024). Nothing is written without it, except one previous-image slot per rendered bookmark (created when missing; replaced only by compare_previous or update_previous).
+  required:
+    - shots
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false