@steipete/oracle 1.1.0 → 1.3.0

package/README.md

@@ -20,6 +20,12 @@ Oracle gives your agents a simple, reliable way to **bundle a prompt plus the ri
 
 If you omit `--engine`, Oracle prefers the API engine when `OPENAI_API_KEY` is present; otherwise it falls back to browser mode. Switch explicitly with `-e, --engine {api|browser}` when you want to override the auto choice. Everything else (prompt assembly, file handling, session logging) stays the same.
 
+Note: Browser engine is considered experimental, requires an OpenAI Pro account and only works on macOS with Chrome.
+Windows/Linux browser support is in progress; until then, use `--engine api` or bundle files and paste manually.
+Your system password is needed to copy cookies. To skip Chrome/Keychain entirely, pass inline cookies via
+`--browser-inline-cookies <json|base64>` or `--browser-inline-cookies-file <path>` (fallback files at
+`~/.oracle/cookies.json` or `~/.oracle/cookies.base64`). API engine is stable and should be preferred.
+
 ## Quick start
 
 ```bash
@@ -35,6 +41,12 @@ npx -y @steipete/oracle -p "Review the TS data layer" --file "src/**/*.ts" --fil
 # Mixed glob + single file
 npx -y @steipete/oracle -p "Audit data layer" --file "src/**/*.ts" --file README.md
 
+# Dry-run (no API call) with summary estimate
+oracle --dry-run summary -p "Check release notes" --file docs/release-notes.md
+
+# Alternate base URL (LiteLLM, Azure, self-hosted gateways)
+OPENAI_API_KEY=sk-... oracle --base-url https://litellm.example.com/v1 -p "Summarize the risk register"
+
 # Inspect past sessions
 oracle status --clear --hours 168   # prune a week of cached runs
 oracle status                       # list runs; grab an ID
@@ -43,8 +55,23 @@ oracle session <id>                 # replay a run locally
 
 ## How do I integrate this?
 
-- **One-liner in CI** — `OPENAI_API_KEY=sk-... npx -y @steipete/oracle --prompt "Smoke-check latest PR" --file src/ docs/ --preview summary` (add to your pipeline as a non-blocking report step).
-- **Package script** — In `package.json`: `"oracle": "oracle --prompt \"Review the diff\" --file ."` then run `OPENAI_API_KEY=... pnpm oracle`.
+**CLI** (direct calls; great for CI or scripted tasks)
+- One-liner in CI: `OPENAI_API_KEY=sk-... npx -y @steipete/oracle --prompt "Smoke-check latest PR" --file src/ docs/ --preview summary`.
+- Package script: add `"oracle": "oracle --prompt \"Review the diff\" --file ."` to `package.json`, then run `OPENAI_API_KEY=... pnpm oracle`.
+- Don’t want to export the key? Inline works: `OPENAI_API_KEY=sk-... oracle -p "Quick check" --file src/`.
+
+**MCP** (tools + resources; mix-and-match with the CLI sessions)
+- Run the bundled stdio server: `pnpm mcp` (or `oracle-mcp`) after `pnpm build`. Tools: `consult`, `sessions`; resources: `oracle-session://{id}/{metadata|log|request}`. Details in [docs/mcp.md](docs/mcp.md).
+- mcporter config (stdio):
+  ```json
+  {
+    "name": "oracle",
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@steipete/oracle", "oracle-mcp"]
+  }
+  ```
+- You can call the MCP tools against sessions created by the CLI (shared `~/.oracle/sessions`), and vice versa.
 
 ## Highlights
 
@@ -56,20 +83,24 @@ oracle session <id>                 # replay a run locally
 - **File safety** — Per-file token accounting and size guards; `--files-report` shows exactly what you’re sending.
 - **Readable previews** — `--preview` / `--render-markdown` let you inspect the bundle before spending.
 
+## Configuration
+
+Put per-user defaults in `~/.oracle/config.json` (parsed as JSON5, so comments/trailing commas are fine). Example settings cover default engine/model, notifications, browser defaults, and prompt suffixes. See `docs/configuration.md` for a complete example and precedence.
+
 ## Flags you’ll actually use
 
 | Flag | Purpose |
 | --- | --- |
 | `-p, --prompt <text>` | Required prompt. |
 | `-f, --file <paths...>` | Attach files/dirs (supports globs and `!` excludes). |
-| `-e, --engine <api|browser>` | Choose API or browser automation. Omitted: API when `OPENAI_API_KEY` is set, otherwise browser. |
+| `-e, --engine <api\|browser>` | Choose API or browser automation. Omitted: API when `OPENAI_API_KEY` is set, otherwise browser. |
 | `-m, --model <name>` | `gpt-5-pro` (default) or `gpt-5.1`. |
+| `--base-url <url>` | Point the API engine at any OpenAI-compatible endpoint (LiteLLM, Azure, etc.). |
+| `--azure-endpoint <url>` | Use Azure OpenAI (switches client automatically). |
 | `--files-report` | Print per-file token usage. |
-| `--preview [summary|json|full]` | Inspect the request without sending. |
-| `--render-markdown` | Print the assembled `[SYSTEM]/[USER]/[FILE]` bundle. |
-| `-v, --verbose` | Extra logging (also surfaces advanced flags with `--help`). |
+| `--dry-run [summary\|json\|full]` | Inspect the request without sending (alias: `--preview`). |
 
-More knobs (`--max-input`, cookie sync controls for browser mode, etc.) live behind `oracle --help --verbose`.
+See [docs/openai-endpoints.md](docs/openai-endpoints.md) for advanced Azure/LiteLLM configuration.
 
 ## Sessions & background runs
 
@@ -78,6 +109,8 @@ Add `--render` (alias `--render-markdown`) when attaching to pretty-print the st
 
 **Recommendation:** Prefer the API engine when you have an API key (`--engine api` or just set `OPENAI_API_KEY`). The API delivers more reliable results and supports longer, uninterrupted runs than the browser engine in most cases.
 
+**Wait vs no-wait:** gpt-5-pro API runs default to detaching (shows a reattach hint); add `--wait` to stay attached. gpt-5.1 and browser runs block by default. You can reattach anytime via `oracle session <id>`.
+
 ## Testing
 
 ```bash