Oracle (CLI), best use

Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat outputs as advisory: verify against the codebase + tests.

Main use case (browser, GPT‑5.5 Pro)

Default workflow here: --engine browser with GPT‑5.5 Pro in ChatGPT. This is the “human in the loop” path: it can take ~10 minutes to ~1 hour; expect a stored session you can reattach to.

Recommended defaults:

• Engine: browser (--engine browser)
• Model: GPT‑5.5 Pro (either --model gpt-5.5-pro or a ChatGPT picker label like --model "5.5 Pro")
• Attachments: directories/globs + excludes; avoid secrets.

Golden path (fast + reliable)

1. Pick a tight file set (fewest files that still contain the truth).
2. Preview what you’re about to send (--dry-run + --files-report when needed).
3. Run in browser mode for the usual GPT‑5.5 Pro ChatGPT workflow; use API only when you explicitly want it.
4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).

Commands (preferred)

• Show help (once/session):

  • npx -y @steipete/oracle --help

• Preview (no tokens):

  • npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"
  • npx -y @steipete/oracle --dry-run full -p "<task>" --file "src/**"

• Token/cost sanity:

  • npx -y @steipete/oracle --dry-run summary --files-report -p "<task>" --file "src/**"

• Startup/perf trace:

  • npx -y @steipete/oracle --perf-trace --perf-trace-path /tmp/oracle-perf.json --dry-run summary -p "<task>" --file "src/**"
  • Use when CLI startup or time-to-first-output feels slow; inspect first-output and exit.

• Browser run (main path; long-running is normal):

  • npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"