feat(docs): read this guide one section at a time

[clementcopper]

Where the tokens actually go

The README makes the case that figma-cli costs an agent far fewer tokens than an API-based MCP. Measuring a session end to end, the commands hold up their side — but the guide dominates everything:

Item	Tokens	When
CLAUDE.md (the guide)	~10,200	every session that follows "read the guide first"
REFERENCE.md	~6,100	on demand
canvas info / var list / find	40–500 each	per call
verify (PNG on disk, not base64)	~40	per call

So the per-command work is already lean, and verify writing the PNG to disk instead of inlining base64 was the right call. What's left is the guide: an agent pays ~10k tokens up front even when the task is "render one frame" and it needs the JSX section and nothing else.

The change

figma-cli docs <topic> prints one ## section. figma-cli docs lists what's available with each topic's cost:

$ figma-cli docs

  CLAUDE.md — 19 topics, ~10,211 tokens in full

  quick-reference               1456 tok  Quick Reference
  key-rules                     1851 tok  Key Rules
  jsx-syntax                     924 tok  JSX Syntax (render command)
  critical-pitfalls              917 tok  Critical Pitfalls
  motion                         927 tok  Motion (Figma Animation, Config 2026 Beta)
  …

Measured against reading the whole guide:

Task	Topics needed	Tokens	Saved
render a component	jsx-syntax + critical-pitfalls	1,850	−82%
general session start	key-rules + quick-reference	3,317	−68%
add an animation	motion	932	−91%
set up validation	deterministic-validation	722	−93%

Behavioural details:

• Ranked matching — exact slug, then whole word (plural-tolerant), then substring, then heading text. jsx, jsx-syntax and render all reach the JSX section.
• Ambiguity is reported, not guessed. docs token matches both Design Tokens and Token Hygiene, so it lists both and exits 1 rather than silently picking one.
• Pipes cleanly — the section goes to stdout, listings and errors to stderr, so figma-cli docs jsx-syntax > /tmp/jsx.md works.
• --file <path> overrides the guide location; without it the command looks for docs/FIGMA-USAGE.md first, then CLAUDE.md, so a checkout that keeps a short CLAUDE.md for repo instructions still works.

Two bullets in the guide point at it: one in Token Hygiene, one in Other Commands.

Implementation

Splitting and matching are pure functions in src/lib/doc-sections.js, following the browserDebugArgs / connect-plan pattern, with 10 unit tests in tests/doc-sections.test.js — no disk access, no Figma. src/commands/docs.js only does I/O, and src/lib/command-map.js gains the two lines the lazy loader needs (tests/lazy-command-map.test.js enforces that).

npm test → 531 passing.

Notes

### subsections deliberately stay inside their parent topic — they're detail of that topic, not topics of their own. If you'd rather have deeper granularity, or different topic names than the auto-slugs, both are a small change.