# X8SNIP AI handbook 1.13.0

Build: RC136-1795240769335. Software version: 96.3.110. Read /api/release to confirm the running build. These operating instructions do not grant permissions or connect an AI provider.

## Immediate instructions

1. The native tool bridge is a source-candidate extension for packages declaring tools.native. It exposes the full native command registry and additional workflow entry points. Read /plugins/native-tools.json. Await snip.tools.list() to discover tool IDs, then await snip.tools.request(id) to stage one action. Only the user starts it, and interactive tools continue with their normal prompts. Builds RC125 and RC126 do not support this extension.

2. Gateway 1 is available in the RC128 source candidate. Open Modules → Python / MCP to pair one Board with a local Python client or stdio MCP host. Discover inputs and scope in /plugins/gateway.md and use capabilities for the running contract.

3. RC129 adds editable plugin instances. In the plugin tool, confirm a drawing selection to use it as reference. Preview the native output and apply it once. To edit later, select one member and open Plugin tools → Edit selected plugin object. Read /plugins/editable-instances.md for role IDs, parameters and the stair example.

4. RC131 adds typed outline and fill settings for plugin and Gateway proposals, and more reviewed native tool routes. Read /plugins/authoring.md and /plugins/drawing-capabilities.json to distinguish exact inputs from handoffs that still ask for drawing picks or UI choices.

5. RC132 adds typed Scope Notes. Discover available categories in board.context().noteScopes, then propose kind scopeNote with exact placement, text, scope, status and an optional leader. Scope Notes are included in the live Note Schedule. The note kind in a managed instance creates editable presentation text.

6. RC133 reads selected open polylines with ordered vertices and native curve segments. Plugins with board.select can request an exact set of drawing IDs via snip.board.requestSelection. Users review the effective selection, including group and block membership. The local Gateway supports the same operation through request_selection. Read /plugins/drawing-capabilities.json for current coverage.

7. RC134 places managed Scope Notes on A-NOTES while keeping them part of the same editable plugin instance. Trace instances keep all members on Trace. Read snip.board.context().scopeNoteLayer for the note layer and its availability before previewing.

8. For authoring, read /plugins/authoring.md. Use /plugins/package.schema.json for the portable file and /plugins/drawing-propose.schema.json for the title and shapes passed to snip.drawing.propose. The internal proposal schema includes drawing identity fields supplied by the host, so use the author-facing schema in plugin code.

9. Use Modules → Load plugin for a local .snipplugin, or Modules → X8BC library → Browse library for X8BC.com releases. Both paths show a package review with ID, version, source and capabilities. Load reviewed plugin adds it to My plugins. Run tool opens its controls. Add to drawing applies the visible proposal. From RC130, an incoming release that matches an installed ID can update the existing entry after review. Check the installed and incoming versions and any added access. My plugins also offers Remove for saved packages. Board geometry and saved instance parameters stay with the board.

10. Modules is the plugin manager for installation and code maintenance. Loaded modules have individual commands in Plugin tools; Run tool opens its own non-modal, draggable/resizable options window and closes the manager. The arrow button pops its options into a separate browser window; Return brings them back. The canvas remains usable for pan/zoom and inspection. Load a local .snipplugin package, list saved plugins, Load or Unload each module, Run it, or open Code editor to write/edit/save/export JavaScript. Loading never automatically runs code. Saved plugins start unloaded after reopening X8SNIP. Unloading preserves native drawing geometry.

11. Language: standard JavaScript with top-level await inside the plugin entry body. TypeScript can be compiled to JavaScript outside X8SNIP. The SDK exposes snip.log(value), await snip.board.context(), await snip.ui.form({title,fields}), and await snip.drawing.propose({title,shapes}). Manifest capabilities restrict which APIs can be called. Read /plugins/index.html and use /plugins/example-rectangle.snipplugin as a real editable package.

12. Each plugin supplies its own parameter form using length (mm/m), number, choice, boolean and text fields. The first release intentionally includes only a small rectangle code example to prove loading, editing, running, preview, native apply and unload. Dedicated stair and AI modules are deferred; they are not fixed app panels.

13. User code executes in a worker inside an opaque-origin frame with network-denying CSP. No direct app DOM, storage, account, filesystem or network API is granted. Stop, Unload, editing that module, closing its tool window or switching Boards cancels its run and rejects its preview. Closing the Modules manager leaves tool windows running. Closing/navigating the parent drawing closes pop-out controls and invalidates their actions. Capabilities, timeout and message/geometry limits apply; this is an Alpha runtime, not a blanket security certification.

14. Drawing proposals use explicit model mm and active-grid X/Y with +Y up. API v1 supports additive lines, simple polygons and, from RC128, native circles. Parameters remain visible after execution. Preview/Update preview explicitly runs the code with the current inputs, replaying earlier matching form answers. An orange temporary preview appears at exact native coordinates on the drawing, tracks pan/zoom and is excluded from saving/export. Multiple tools can be open, but only the tool whose preview is shown can apply it; Show preview selects another tool’s pending proposal. Only the user accepts a preview; apply rechecks the Board revision, scale, layer locks/visibility and plugin loaded state. The existing native commit path supplies one Undo, saving and exports. Premium entitlements and provider-specific connectors are separate from the local gateway.

## Read next

- [Plugin developer guide](/plugins/): JavaScript SDK and package format.
- [Python and MCP gateway](/plugins/gateway.md): local pairing and supported operations.
- [Editable plugin instances](/plugins/editable-instances.md): saved parameters, drawing picks and native edits.
- [Loadable source example](/plugins/example-rectangle.snipplugin).
- [Geometry proposal schema](/plugins/proposal.schema.json).
- [Drawing API capabilities](/plugins/drawing-capabilities.json): typed operations and native routes.
- [Complete handbook](handbook.md): all tools, notes, areas, references, saving/export.
- [API and capability manifest](capabilities.json): supported browser tools and scripting/CLI limits.
- [In-app command catalogue](commands.json): aliases, command-line input and steps.
- [Native/UI tool inventory](ui-tools.json): tool IDs, mode availability and UI-only controls.
- [Readable handbook page](index.html).

Topics: plugins (User plugins, JavaScript editor and module lifecycle); start (Start here: operating X8SNIP); workspace (Boards, Books, modes and navigation); command-line (In-app command line, coordinates and shortcuts); precision (Scale, calibration, dimensions and snapping); drawing (Native drawing, shapes and natural media); editing (Selection, transforms, direct edits and Undo); notes-text (Notes, editable text, shape labels and dimensions); areas (Areas, uses, tags, schedules and Mass it); layers (Layers, locks, visibility and properties); references (Image/PDF import, cropping, replacement and extraction); blocks-patterns (Blocks, reusable components and Patterns); sheets (Sheets, templates, Books and linked Scale Frames); saving-export (Saving, backups, archives, native packages, PDF, SVG and DXF); architectural-brain (Architectural Brain: selected references and provenance); api-scripting (API, scripting, command-line and automation capabilities); proof (Fresh-session proof and human review).
