The command editor¶
The command editor is where the desktop app will build commands. It is a ladder of three rungs. A command starts on the simplest rung and moves up only when it needs something that rung cannot express. Each rung authors the same profile files you can write by hand today, so this page is an orientation to which rung fits which command, not a set of steps.
Rung one: the structured editor¶
The structured editor is for a command that runs an action when you say a phrase.
You give it a spoken pattern, a response, synonyms, and a category. It has no logic
and no decisions. It writes a [[command]] with a simple response, the same shape as
a command with a lua one-liner. Most commands stay here.
This rung covers a spoken trigger and a single function call. If a command only presses a key or types a line, it never needs to leave.
Rung two: the block editor¶
The block editor is for logic without writing Lua by hand. You assemble visual blocks for conditions, return values, and handles, and the editor generates the Lua for you. A command reaches this rung when it has to make a decision, keep a value that a function hands back, or hold a handle to stop something later.
The block editor writes a script or lua command backed by generated Lua. The same
work is possible today by writing that script yourself, described in
Functions and Free-text and dictation.
Rung three: the text editor¶
The text editor opens the raw profile files for full control over the TOML and the Lua. It is for anything the higher rungs do not cover: multi-statement scripts, shared state, and profile structure such as includes and overlays. This rung is the profile directory you edit today, brought inside the app.
Why a command moves up¶
A command escalates only when it needs a return value, a handle, or a conditional.
Until then it stays on the rung below, where there is less to get wrong. Every rung
maps to something you can already write in a profile: a plain response, a script, or
the files themselves. The editor makes that authoring visual. It does not add anything
the profile format and the amri tool do not already provide.