From 0ba8e30fbc50abd8f9c3d2705e93f574191130e1 Mon Sep 17 00:00:00 2001
From: MarekSpodBiedry <73122968+MarekSpodBiedry@users.noreply.github.com>
Date: Thu, 15 Oct 2026 17:17:51 +0200
Subject: [PATCH] docs: document perf --instances in the CLI reference (#391)

---
 docs/cli.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/cli.md b/docs/cli.md
index ab6c1ea8..93d9aef6 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -145,7 +145,7 @@ size and SHA-256. The server's key comes from the address or, better, from the
 lists); it is never printed. The bundle is checked before it is sent and again by the server. See
 [plugins.md](plugins.md#plugin-directories).
 
-### `perf [--layers N[,N...]]`
+### `perf [--layers N[,N...]] [--instances N[,N...]]`
 
 Builds synthetic documents of each size (default `1000,10000` layers: screens with an auto layout
 header, a card group, button instances and a grid of shapes and text) and prints a Markdown table of
@@ -154,3 +154,11 @@ and hover, single-layer edits through the engine (fill, move, text in auto layou
 with all its instances), undo/redo, a drag preview frame, `normalize` after a one-node edit,
 `document.inspect` and select-all + move. Use a release build for meaningful numbers;
 `cargo xtask bench` runs it at 1k/10k/50k layers together with the UI frame benchmarks.
+
+`--layers` picks the document sizes (each value is clamped to 10 to 2,000,000 layers). `--instances`
+picks the component workloads (default `2000`): for each count the command builds a synthetic design
+system (about 300 components, variables and styles, nested four deep) with that many instances that
+carry overrides at every level, in one file and as a library in another. It then prints a second
+table with the build time and edits of a deep main component (icon colour, glyph size, an added
+layer) and of the 72 button mains, where all copies follow. Zeros are dropped and counts above
+100,000 are capped to 100,000; `--instances 0` skips this table.