docs(cli): fix droid exec tutorial output format, models, and reasoning default

[lukealvoeiro]

Gap

DOC-N52 (F, P2). The "Building Interactive Apps with Droid Exec" tutorial (EN + JP) has three wrong facts:

1. It tells readers to use --output-format debug and says droid then emits SSE (event: tool_call / data: ...). In fact debug is a hidden, deprecated alias of stream-json, and droid writes JSON Lines to stdout. The SSE events come from the example app's server, not from droid.
2. It uses the model ids glm-4.7 and gpt-5-codex. Both are rejected by the CLI.
3. It says low is the default reasoning effort for -r. The real default depends on the model.

Evidence

• Docs: docs/guides/building/droid-exec-tutorial.mdx:72,79,102,194 (debug and SSE), :81-82,108-109,314,379 (glm-4.7, gpt-5-codex), :114,315 ("low (default)"). The JP mirror has the same lines.
• Code (factory-mono apps/cli):
  • src/entrypoints/exec/assertValidOptions.ts:24-34: 'debug' is listed with the comment "deprecated alias for 'stream-json'". It is not in the --help format list (text|json|stream-json|stream-jsonrpc|acp).
  • src/exec/types.ts:204-305: the JSONL event types are system/init, message, reasoning, tool_call, tool_result, error and completion.
  • src/entrypoints/exec/help.ts:114: -r, --reasoning-effort <level> Reasoning effort (defaults per model).
• Commands (hermetic wrapper, network blocked):
  • droid exec -o debug 'hi' prints {"type":"system","subtype":"init",...,"reasoning_effort":"high"} then {"type":"error","source":"cli",...}: JSON Lines, not SSE, identical to -o stream-json.
  • droid exec --model glm-4.7 x fails with Invalid model: glm-4.7 and lists the available models.
  • droid exec -o stream-json -m gpt-5-codex hi fails with Invalid model: gpt-5-codex (exit 1).
  • The init event reports "reasoning_effort":"high" when -r is omitted for several models, not low.

Why it matters

Readers copying the snippets rely on a hidden, deprecated output format, expect droid to emit SSE and write the wrong parser, hit Invalid model immediately, and are told the wrong reasoning default.

Fix

• Use --output-format stream-json everywhere and describe it as JSON Lines.
• Show an accurate, abbreviated JSONL sample (valid JSON on every line); explain that the example server re-emits these as its own SSE events, and keep the existing SSE block as the app's events.
• Replace glm-4.7 with glm-5.3 and gpt-5-codex with gpt-5.3-codex.
• Drop "(default)" from low; state that supported levels vary by model and that omitting -r uses the model default. DROID_REASONING in .env is now optional.
• Same factual fixes in the JP page.

Validation

• grep -n 'debug\|glm-4\|gpt-5-codex' on both pages: no matches.
• Every JSONL sample line parses with json.loads on both pages.
• With the hermetic wrapper, each command gets past option and model validation and stops only at the expected auth failure: droid exec --output-format stream-json -m glm-5.3 hi, ... -m gpt-5.3-codex hi, ... -m claude-sonnet-4-5-20250929 hi, ... -m glm-5.3 -r low hi.
• Not checked: site rendering, and whether the external Factory-AI/examples/droid-chat repo (which the snippets are "simplified from") still uses debug/glm-4.7/gpt-5-codex; it likely needs a matching fix.

Found by the scheduled CLI arguments audit.

[factory-droid]

Droid finished @lukealvoeiro's task —— View job

---

LGTM. No actionable issues found in the tutorial updates or security review.

0 inline comments posted