[Feature]: Make the filee command easier for scripts and AI agents to drive #753

What would you like Filee to do?

Make a few small additions to the filee command so scripts and AI coding agents (Claude Code, Codex, Cursor, Copilot) can use an installed Filee as a local tool without parsing console text. Existing output stays as it is; these mostly add to it (the one change is in item 1).

1. JSON for formats and presets: accept --json and print one JSON document. For formats <format>, list what it converts to now and what it would convert to with optional engines. Today --json is accepted there but ignored, and the text table comes out, so those two calls would start printing JSON instead.
2. Why a file failed, as data: in convert --json, add the existing error key (for example error.no_route) to failed files. When a conversion only needs an optional engine, also list which engines would make it possible.
3. Which engines converted a file (optional): the ids of the converters that actually ran for each file in convert --json (a route can have several steps, and it can change while running). Core would need to record them on FileResult, so only if you want it.
4. A short guide for agents: one page telling an agent how to call filee (always --json and -o, exit code 0 means nothing failed so check converted/state/outputs, point the user to Settings → Engines when an engine is missing). It could be an Agent Skills SKILL.md in the repo, a short section on filee.sh/cli, or both.

1 and 2 are the main part. 4 would be written against them.

Why / when would you use it?

filee is already a good fit for this: it runs offline, needs no prompts, has convert --json and clear exit codes, and Setup puts it on PATH. The gaps are in the places where a program has to decide what to do next.

Can this file become X? Answering this means splitting text like:

Markdown (md, markdown) converts to:
  png, jpg, webp, ... pdf, docx, ... txtz
With optional engines (install them in Filee, Settings → Engines):
  hwp, pptx, pptm, ... tcr

Is it impossible, or does it just need an engine? Without optional engines, md → pptx (listed above as possible with an engine; Pandoc does it) fails the same way as txt → mp3, which no engine can do:

"error": "No engine can do this conversion (md \u2192 pptx)"
"error": "No engine can do this conversion (txt \u2192 mp3)"

A caller can't tell these apart from the conversion JSON alone; it has to parse the formats text or guess what to try next, instead of telling the user "install Pandoc in Settings → Engines". filee formats already knows the difference, but convert doesn't show it.

The same additions help plain shell and PowerShell scripts, not only AI tools.

Ideas for how it could work

A possible shape (names are up to you):

// filee formats md --json
{ "format": "md", "to": ["pdf", "docx", "html"], "withOptionalEngines": ["pptx", "mobi"] }

// a failed file in filee convert doc.md --to pptx --json
{ "source": "doc.md", "state": "failed", "outputs": [],
  "error": "No engine can do this conversion (md → pptx)",
  "errorKey": "error.no_route", "needsEngines": ["pandoc"] }

• Compatibility: existing convert --json keys, states and exit codes stay as they are, and output without --json doesn't change. The only change is that formats --json and presets --json print JSON instead of ignoring the flag. Messages stay in English, as decided in i18n(cli): add European Portuguese and preserve JSON output #552. New behaviour gets tests in Filee.Cli.Tests.
• Engine ids: the ids already used for engines and engine priority (pandoc, libreoffice, …). needsEngines would only name engines offered in Settings → Engines (the EngineDownloads.Packages list), never bundled or system parts like 7-Zip or the Windows JPEG XR codec. It's the missing ones on one route that works once they're installed (all of them together, not alternatives). The JSON list of "with optional engines" targets in item 1 would use the same rule.
• No MCP server: a local MCP server would only wrap filee and be one more thing to maintain. With JSON output and exit codes the command can be used directly.
• Not included: installing engines from the command line, and a --dry-run mode (1 and 2 cover most of what it would show).

I'd like to work on this myself. I'd send 1 and 2 together as one PR, then 3 and 4 separately if you want them. A few things I'd like your call on:

1. Scope: is this okay to do, and how far (1–4)?
2. Engines per file (3): worth recording them on FileResult in Core?
3. Agent guide (4): in the repo as SKILL.md, on filee.sh/cli, or both?

Please let me know whether I can go ahead with this. If you have any thoughts, I'll take them into account.