Add flat output option to docs command

[david-crespo]

See #1278 (comment). This does two things:

• Add a --format flag to oxide docs with two options: json and flat
• Makes the default flat so that the typical user doesn't have to pass the flag
  • We only use the json format to generate the schema used by the docs site, and that's versioned in docs/cli.json, so we never actually have to pass the flag

I think this is useful for both people and agents.

$ ./target/debug/oxide docs | head
oxide alert class list — List alert classes
oxide alert receiver delete — Delete alert receiver
oxide alert receiver list — List alert receivers
oxide alert receiver log — List delivery attempts to alert receiver
oxide alert receiver probe — Send liveness probe to alert receiver
oxide alert receiver resend — Request re-delivery of alert
oxide alert receiver subscribe — Add alert receiver subscription
oxide alert receiver unsubscribe — Remove alert receiver subscription
oxide alert receiver view — Fetch alert receiver
oxide alert receiver webhook create — Create webhook receiver

It's not quite @taspelund's idea of built-in command search, but you can pipe it to fzf just fine:

2026-04-08-cli-docs-fzf.mp4

I also improved the help output for the command to say "List all CLI commands" so that you can find this command more easily from oxide -h.

[ahl]

Great idea

[ahl]

What do you think about "text" as the alternative? I'd also suggest we not document one-per-line because I could imagine writing richer docs possibly with more info such as parameters.

[david-crespo]

I considered text, I'm happy with that — only concern would be what if we had a compact text format like this for LLMs and fzf use, and then a more verbose version with the full docs. In that case I might prefer to call this compact.

[jmcarp]

• I think flat and text are both defensible format names, since the thing we're doing is flattening a nested json document into a text document. Maybe a slight preference for text, since my main reaction to the previous default of the big json blob was "I want text instead of json".
• I was curious about this in the first place because cc can have a hard time discovering cli commands, so I tried it out. It doesn't seem to occur to claude to look at the docs command at all without prompting—even opus seems to guess commands at random, then try oxide --help. Telling it to check oxide docs gives better results. I think it would be fine to write a global "memory" about this, although it would be nice if some convention existed for llm-friendly docs from clis.
• For completeness, cc also managed to find the right commands with oxide docs --format json, but it decided to write a python script to search the output rather than ingesting it directly. That would probably mostly work, especially as claude includes more oxide content in its training materials, but I think giving it the flat/text format will be more robust. Also, it would be nice for this to work well with dumb models!