# FlashBoards SDK 0.1 — Experimental

> Build bounded reusable tools for your local board, with optional panels, through the experimental FlashBoards SDK 0.1 contracts.

Source: https://flashboards.yaroflasher.com/docs/integrations/sdk

Last verified: 2026-10-25 (checked against FlashBoards app build 1710ec2f754c)

Use **FlashBoards SDK 0.1 — Experimental** for behavior you want to reuse: a selected-note cleanup action, a selection layout, or a small reporting tool. A tool can run without showing a panel; an optional panel calls the same authored actions. For a single board edit, use an existing [board action](https://flashboards.yaroflasher.com/docs/integrations/mcp.md#edit-a-board).

The SDK has one experimental 0.1.x release line. Package `formatVersion`, runtime-contract `sdkVersion` and `request.version` are independent compatibility markers, not SDK release numbers. Keep their exact values from live discovery; do not replace them with 0.1 or renumber saved packages. Discover supported operations and capabilities instead of inferring them from a version.

> **Note: Limited rollout.** Plugin execution is available only to eligible pilot accounts with a fully loaded, signed-in local board. A paid subscription alone does not enable it. Shared boards are excluded. **Settings → Plugins** appears only with the required access. Reading this guide or an SDK schema does not enable execution.

## Start with an agent

Connect over [MCP](https://flashboards.yaroflasher.com/docs/integrations/mcp.md) or the [Public API](https://flashboards.yaroflasher.com/docs/integrations/api.md). Ask the agent to read `get_skill` with `skillId: "flashboards-sdk"`, then discover the connected version's contracts. The [SDK guide](https://flashboards.yaroflasher.com/skills/flashboards-sdk/SKILL.md) is also available as a public Markdown file. Live schemas and receipts govern which capabilities that version accepts. For named-action tools, discover `tool-artifact`, `tool-context` and `tool-installations` as shown below. The live contracts describe authored actions, bounded context and independent installed tools.

Where **Settings → Plugins** is available, **Build with Assistant** opens a customization request in the sidebar; **Copy instructions for my agent** supplies connection instructions; **Read SDK guide** opens the same guide. These controls do not install a package.

## Discover before writing

The public guide and `describe_board_action` envelope schema can be read without SDK pilot access. Live extension schemas and installed-tool discovery through `extensionsRequest` require an eligible pilot account and local-board tab, even for read-only requests; they do not require installation consent.

With that access, first call `list_board_sessions` and `get_board_snapshot` for the intended tab. Then send `extensionsRequest` through `execute_board_action`, with the snapshot's `activeBoardId` as the outer `expectedBoardId` and `sessionId` when needed:

```json
{
  "operation": "execute_board_action",
  "input": {
    "action": "extensionsRequest",
    "args": { "operation": "describe", "section": "tool-artifact" },
    "expectedBoardId": "BOARD_ID_FROM_SNAPSHOT",
    "sessionId": "SESSION_ID_FROM_DISCOVERY"
  }
}
```

This is the Public API envelope. For MCP, send its `input` object as the arguments to `execute_board_action`. Replace the placeholder IDs with returned values. Request `section: "tool-context"` separately to inspect the bounded context schema, then `section: "tool-installations"` for version-4 installation requests.

Execution, including invocation without a visible panel, uses the authorized local-board tab. It does not run on the server against an arbitrary board. WebMCP's browser tools do not expose plugin execution.

## Choose the package contract

| Package                  | Contract                                                                                                                   |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| Named-action custom tool | `formatVersion: 3`, `kind: "custom-tool"`, `sdkVersion: 2`; 1–16 named actions, optional panel                             |
| Event-based custom panel | `formatVersion: 2`, `kind: "custom-panel"`, `sdkVersion: 1`; event-based panel logic that can also be invoked while hidden |
| Alignment toolbar        | `formatVersion: 1`; native layout recipes or a bounded placement script, with its own draft and activation flow            |

A named action reads bounded context, requests item pages, then returns a result or one declared effect. Its program is stored as function-body strings in JSON. It cannot access arbitrary page DOM, network requests, files, shell commands or paid generation.

Tool capability grants are explicit:

* **Item reads.** `board.items.read` returns up to 32 summaries per page, including IDs, kinds and available geometry. It excludes note bodies and media URLs. Continue with the returned offset and revision.
* **Select and focus.** These effects require matching capabilities and IDs from the captured selection or latest item page.
* **Note editing.** `notes.read` exposes one supported selected note. `notes.write` also needs that read grant and can update only that captured note's title, content, font size, text color and background color. The body limit is 2 KiB UTF-8 and the title limit is 256 bytes.
* **Selection layout.** `board.layout` also requires `selection.geometry`. One position-only layout must cover exactly the captured selection of 1–32 items. Paged or remembered IDs cannot expand that authority. Missing, extra, duplicate or stale targets refuse the whole effect. Bound arrows can follow moved targets; `changedIds` reports the directly positioned items.

The invocation has a two-second deadline and at most eight reads; eight reads are a ceiling, not a guaranteed throughput. Arguments and results are at most 2 KiB, state and each step at most 16 KiB. Agent installation accepts at most 8 KiB of serialized package JSON. Discover the exact schemas before authoring.

## Install and invoke deliberately

Before an agent installs, replaces or invokes a plugin, a human must enable **Allow my connected agents to install panels, save toolbar drafts and run local plugins here** under **Settings → Plugins → Official Alignment**. The agent must wait for that Settings action. A shared file or connected app does not supply consent.

Up to eight independent tools can be installed. Discover `tool-installations`, then use `operation: "panel"` with `request.version: 4`. Keep the installation ID and entry revision. Obtain fresh context with `get` before `invokeAction`, using the same ID, revision and token. Updates, enable/disable and removal require the entry revision. See the [SDK guide](https://flashboards.yaroflasher.com/skills/flashboards-sdk/SKILL.md) and live schema for complete requests.

Metadata reads do not require agent consent; writes, context and execution do. Installation does not invoke an action. Hiding a panel leaves its tool installed. Obtain fresh context after board, selection or installation changes.

Event-based panel requests (`request.version: 2`) and single-slot tool requests (`request.version: 3`) share the separate legacy single slot. The alignment toolbar has its own slot. Inspect its occupant before intentional replacement; these requests do not target version-4 installations.

Read the full receipt. Applied edits use normal Undo; pending persistence does not confirm durable saving. Version-4 `committed: "runtime"` acknowledges transient state; `"registry"` acknowledges an installation-registry write. Legacy receipts may use `stateCommitted: true`. Inspect withheld or uncertain results; never automatically replay them.

## Share a definition

Exported packages transfer their JSON definition, code and optional CSS. They do not transfer private runtime state, live context tokens, account authority or consent. Check the editor text before export: export downloads the current editor text, including unsaved changes. Import the actual file when transferring a definition, then discover fresh context on the receiving board. Switching local boards alone does not normally require reimporting an installed tool.

An unsupported package or declared capability is refused and asks you to save your work and refresh. Refresh does not automatically replay an invocation.

## Related

- [Connect an AI agent](https://flashboards.yaroflasher.com/docs/integrations/mcp.md)
- [Public API](https://flashboards.yaroflasher.com/docs/integrations/api.md)
- [Docs for AI agents](https://flashboards.yaroflasher.com/docs/reference/ai-agents.md)