feat(patterns): add cross-project pattern catalog (six seed patterns)

A good interaction-design pattern surfaces in one project, then gets lost, so the next project re-derives it. Pearl shipped six worked examples and the principle they share, but they sat as four raw notes in docs/design/ with nothing making them reusable.

I added a patterns/ directory, one file per pattern, each with frontmatter (name, principle, problem, tags, source, examples) and a Problem / Do / Anti-pattern / Applicability / Related body. The six seeds: one-prompt-picker-typed-prefix, transient-state-buttons, no-empty-input-as-meaningful, label-matches-behavior, default-most-common-friction-proportional, collapse-orthogonal-prompts. Patterns 3-6 cross-link as facets of one root principle: the choices the user has should all be on screen, accurately labeled, ordered by what they'll most often want, with friction sized to the cost of being wrong.

The catalog lives in rulesets because every project's agent already pulls from here. A thin claude-rules/patterns.md pointer tells the agent the catalog exists and when to consult it, so it reads one pattern on demand instead of carrying all of them. The pointer auto-installs via the Makefile RULES glob. README.org holds the root principle, the frontmatter contract, and the capture-on-landing/promote-on-review intake cadence.

The patterns are .org files with #+KEYWORD frontmatter. The pointer stays .md because the rules layer and the Makefile glob require it. Seed patterns keep their concrete Elisp examples. Generalize on the second caller, not up front.

1 files changed, 29 insertions, 0 deletions

diff --git a/patterns/transient-state-buttons.org b/patterns/transient-state-buttons.org
new file mode 100644
index 0000000..7b7358d
--- /dev/null
+++ b/patterns/transient-state-buttons.org
@@ -0,0 +1,29 @@
+#+TITLE: Transient state-buttons
+#+SLUG: transient-state-buttons
+#+PRINCIPLE: Put all the levers in one place with their current state and key bindings visible, reachable by one chord from anywhere.
+#+PROBLEM: Scattered commands with invisible state force the user to remember what's toggled and which key does what.
+#+TAGS: transient menu ui affordances state
+#+SOURCE: Craig's magit transient.el reference, handoff note 2026-05-27
+#+EXAMPLES: magit transient.el, pearl pearl-menu (C-; L m)
+
+* Problem
+
+A feature accumulates several toggles and actions, each on its own command and keybinding. The state lives in variables the user can't see, and the keys live in muscle memory or a manual. The user has to remember what's currently on and which chord flips it.
+
+* Do
+
+A single popup (magit's =transient.el= is the reference implementation) that shows every lever as a button row: the current state of each toggle, the key that flips it printed inline, summoned by one chord from anywhere. All the affordances are visible at once, and nothing about the current state is hidden.
+
+This is the "all the levers in one place, affordances visible, one chord to get there" shape. The everyday analogue is the music-player transport bar: play, pause, shuffle, repeat state all shown, all reachable.
+
+* Anti-pattern
+
+A set of independent commands whose combined state is invisible, where the user learns what's toggled only by triggering something and watching what happens.
+
+* Applicability
+
+Worth it when a feature has three or more pieces of toggleable state or a cluster of related actions. Overkill for a single command with no state. A light transient (a command menu with no state shown) is a partial step. The full value comes from showing toggle state in the buttons, not just listing actions.
+
+* Related
+
+The visible-affordances half of the root principle (see [[file:README.org][README]]), applied to a control surface rather than a single prompt.