@aiiware/aii 0.17.13 → 0.17.15

package/README.md

@@ -539,6 +539,28 @@ Typing `/deploy staging` expands the file's body (with `$ARGUMENTS` → `staging
 | `--show-cost` | Show cost estimates |
 | `-v`, `--verbose` | Verbose output |
 | `-d`, `--debug` | Debug-level output |
+| `--output-format <fmt>` | `json` or `stream-json` (one-shot only) |
+| `--tools` / `--exclude-tools <list>` | Allow / deny specific tools |
+| `--max-turns <n>` | Cap ReAct iterations within a turn (0/unset = default 500) |
+| `--max-budget-usd <amt>` | Cumulative between-turns cost cap (0 = no cap) |
+| `--bare` | Result to stdout only; all chrome to stderr (one-shot) |
+| `--append-system-prompt <text>` | Append additive instructions to the run |
+| `--append-system-prompt-file <path>` | Append a workspace file of additive instructions |
+
+### Headless / CI Automation
+
+Aii is scriptable and safe to run unattended:
+
+```bash
+# Bounded, machine-readable, pipe-clean:
+aii "review the staged diff for correctness bugs" \
+  --bare --max-turns 12 --max-budget-usd 1.00 --output-format json | jq -r '.result'
+```
+
+- **`--max-turns`** is the hard cost bound for a one-shot run — it caps the agent's ReAct iterations per turn (enforced server-side). **`--max-budget-usd`** is a cumulative *between-turns* cap: fully effective for interactive / `--auto` runs; on a single one-shot turn it adds an advisory `over_budget` flag to the JSON output (pair it with `--max-turns` to bound a one-shot's cost).
+- **`--bare`** sends only the result to **stdout** and all status/chrome to **stderr**, so `RESULT=$(aii "…" --bare)` is clean. Compose with `--output-format json` for structured stdout.
+- **`--append-system-prompt[-file]`** injects an additive, escaped instruction (a review rubric, house style) without editing committed config. The file form reads only inside the workspace and rejects symlinks.
+- Ready-to-use **GitHub Actions** recipes live in [`examples/github-actions/`](examples/github-actions/): they use the `pull_request` trigger (never `pull_request_target` with a PR checkout), reference `AII_API_KEY` via `secrets.`, and consume Aii output as data (never `eval`).
 
 ---