Still working it out as I build more of these CLIs.

That being said:

- every single command you write MUST have a help text. that help text should also tell agents what the easiest path forward it. for example, the locator system in this CLI relies on the positions on paragraphs. these can change after an edit. so I prompt in the help text to use batch edits.

- errors must be clearly marked. for example, if an agent is doing a replace, but the replace comes back with "0 edits made", that's an error. otherwise the agents carry on going on obliviously.

- a lot of the CLI tools decide to use JSON as the default output. I started out that way as well. for agents, that immediately means having to invoke jq or a similar other tool to get it to be understood. the weaker the model, the worse they do on that. I found that providing markdown with annotations beats JSON on most tasks.

- use image reading as a last resort. if it's possible to give the model the information it needs as text, it will do a better job working with it than it will thinking through an image. thus, for this CLI, i do have a render command, but explicitly prompt in the help texts to use it for things that are not obvious from the markdown like layout.

also, batched commands do wonders. if the agent wants to make multiple changes at once, give it the facility to do so. this is done via --batch in the CLI and is especially important since the underlying positional markers shift.