3. The command registry and the one write path

 Figma MCP tool          ud get_metadata --nodeId 1:2       src/mcp/tools/*.ts     (layer 1)
        │                ud use_figma --code-file a.js
        ▼
 Plugin API              node.fills = [...]                 src/plugin-api          (layer 2)
        │                figma.createFrame()
        ▼
 Command registry        registry.run("fill.set", {...})    src/commands            (layer 3)
        │
        ▼
 document core           draft → events → commit group      src/core

// src/commands/types.ts
export interface CommandDef<P = unknown, R = unknown> {
	id: string;                       // "node.align" — stable, versioned API (CMD-23)
	title: string;                    // "Align Left" — palette, tooltips, quick actions
	category: CommandCategory;        // "node" | "text" | "layout" | "component" | "variable" | "export" | "view" | …
	summary: string;                  // one line (ud commands, palette description)
	help: string;                     // long text with at least one example (ud help, docs site)
	params: JsonSchema;               // JSON Schema 2020-12 subset (§3.3)
	result?: JsonSchema;
	flags: {
		mutates: boolean;             // produces events
		needsSelection?: boolean;     // uses ctx.targets; headless requires a target (CMD-25)
		uiOnly?: boolean;             // pointer feedback only; must produce no events (CMD-20)
		hostOnly?: boolean;           // needs host services (raster, file system, clipboard): never predicted in the webview
	};
	licence?: "read" | "free" | "paid"; // default: mutates ? "paid" : "read" (§3.4 step 2)
	targets?: TargetSpec;             // which params name nodes, and whether the selection is a fallback
	pluginApi: string[] | "registry-only"; // Plugin API members that map here (CMD-19)
	since: string;                    // "0.1"
	deprecated?: { since: string; replacedBy?: string };
	aliases?: string[];               // old ids kept for one minor version
	prepare?(ctx: PrepareContext, params: P): Promise<void>; // load fonts, decode images, read files
	run(ctx: CommandContext, params: P): R;                  // synchronous, deterministic
}

export interface CommandContext {
	readonly draft: Draft;            // copy-on-write view of the document (§4.4)
	readonly targets: readonly NodeId[];
	readonly ids: IdSource;           // deterministic from the request seed (§3.6)
	readonly layout: LayoutReader;    // derived geometry of the draft, relaid out on demand
	readonly text: TextEngine;
	readonly services: HostServices;  // raster, assets, clipboard; absent members throw "host only"
	readonly actor: string;
	run<Q, S>(id: string, params: Q): S;  // nested command, same transaction
	warn(message: string): void;
	limit(kind: "nodes"): void;       // counts toward transaction limits (CMD-11)
}

// src/commands/layout/setAutoLayout.ts
export default defineCommand({
	id: "layout.setAutoLayout",
	title: "Add Auto Layout",
	category: "layout",
	summary: "Turn frames into auto layout frames, or change their auto layout settings.",
	help: `…\nExample:\n  ud run layout.setAutoLayout --node "Home/Card" --direction vertical --gap 16 --padding 24`,
	params: {
		type: "object",
		properties: {
			node: NODE_REF, query: QUERY,
			direction: { enum: ["horizontal", "vertical", "grid", "none"] },
			wrap: { type: "boolean" },
			gap: { oneOf: [{ type: "number" }, { const: "auto" }, VARIABLE_REF] },
			padding: PADDING,
		},
		additionalProperties: false,
	},
	flags: { mutates: true, needsSelection: true },
	targets: { from: ["node", "query"], selection: true, types: ["FRAME", "COMPONENT", "INSTANCE"] },
	pluginApi: ["FrameNode.layoutMode", "FrameNode.layoutWrap", "FrameNode.itemSpacing", "FrameNode.padding*"],
	since: "0.3",
	run(ctx, p) {
		for (const id of ctx.targets) {
			ctx.draft.set(id, autoLayoutProps(ctx.draft.get(id), p));
		}
	},
});

const result = await registry.transaction(async (tx) => {
	const card = tx.run("node.create", { type: "FRAME", parent: pageId, name: "Card" });
	tx.run("layout.setAutoLayout", { node: card.id, direction: "vertical", gap: 16 });
	return card.id;
}, { label: "Create card", actor: "Claude (opus)", source: "ud apply", ifVersion: "sha256:3f9a…c1e0" });