add config (#494)

* add config

* improvements

* cleaner flags

* fixes

* fixes

docs/src/app/configuration/page.mdx

@@ -0,0 +1,136 @@
+export const metadata = { title: "Configuration" }
+
+# Configuration
+
+Create an `agent-browser.json` file to set persistent defaults instead of repeating flags on every command.
+
+## Config File Locations
+
+agent-browser checks two locations, merged in priority order:
+
+| Priority | Location | Scope |
+|----------|----------|-------|
+| 1 (lowest) | `~/.agent-browser/config.json` | User-level defaults |
+| 2 | `./agent-browser.json` | Project-level overrides |
+| 3 | `AGENT_BROWSER_*` env vars | Override config values |
+| 4 (highest) | CLI flags | Override everything |
+
+Project-level values override user-level values. Environment variables override both. CLI flags always win.
+
+Use `--config <path>` or the `AGENT_BROWSER_CONFIG` environment variable to load a specific config file instead of the default locations:
+
+```bash
+agent-browser --config ./ci-config.json open example.com
+AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com
+```
+
+## Example Config
+
+```json
+{
+  "headed": true,
+  "proxy": "http://localhost:8080",
+  "profile": "./browser-data",
+  "userAgent": "my-agent/1.0",
+  "ignoreHttpsErrors": true
+}
+```
+
+## All Options
+
+Every CLI flag can be set in the config file using its camelCase equivalent:
+
+| Config Key | CLI Flag | Type |
+|------------|----------|------|
+| `headed` | `--headed` | boolean |
+| `json` | `--json` | boolean |
+| `full` | `--full, -f` | boolean |
+| `debug` | `--debug` | boolean |
+| `session` | `--session` | string |
+| `sessionName` | `--session-name` | string |
+| `executablePath` | `--executable-path` | string |
+| `extensions` | `--extension` | string[] |
+| `profile` | `--profile` | string |
+| `state` | `--state` | string |
+| `proxy` | `--proxy` | string |
+| `proxyBypass` | `--proxy-bypass` | string |
+| `args` | `--args` | string |
+| `userAgent` | `--user-agent` | string |
+| `provider` | `-p, --provider` | string |
+| `device` | `--device` | string |
+| `ignoreHttpsErrors` | `--ignore-https-errors` | boolean |
+| `allowFileAccess` | `--allow-file-access` | boolean |
+| `cdp` | `--cdp` | string |
+| `autoConnect` | `--auto-connect` | boolean |
+| `headers` | `--headers` | string (JSON) |
+
+## Common Configurations
+
+### Local Development
+
+```json
+{
+  "headed": true,
+  "profile": "./browser-data"
+}
+```
+
+### Behind a Proxy
+
+```json
+{
+  "proxy": "http://proxy.corp.example.com:8080",
+  "proxyBypass": "localhost,*.internal.com",
+  "ignoreHttpsErrors": true
+}
+```
+
+### CI / Devcontainer
+
+```json
+{
+  "args": "--no-sandbox,--disable-gpu",
+  "ignoreHttpsErrors": true
+}
+```
+
+### iOS Testing
+
+```json
+{
+  "provider": "ios",
+  "device": "iPhone 16 Pro"
+}
+```
+
+## Overriding Boolean Options
+
+Boolean flags accept an optional `true`/`false` value to override config settings:
+
+```bash
+agent-browser --headed false open example.com
+```
+
+A bare flag is equivalent to passing `true`:
+
+```bash
+agent-browser --headed open example.com       # same as --headed true
+agent-browser --headed true open example.com  # explicit
+```
+
+This applies to all boolean flags: `--headed`, `--debug`, `--json`, `--ignore-https-errors`, `--allow-file-access`, `--auto-connect`.
+
+## Extensions Merging
+
+Extensions from user-level and project-level configs are **concatenated**, not replaced. For example, if `~/.agent-browser/config.json` specifies `["/ext1"]` and `./agent-browser.json` specifies `["/ext2"]`, the result is `["/ext1", "/ext2"]`.
+
+The `AGENT_BROWSER_EXTENSIONS` environment variable and CLI `--extension` flags follow the standard priority rules (env replaces config, CLI appends).
+
+## Error Handling
+
+- **Auto-discovered config files** (`~/.agent-browser/config.json`, `./agent-browser.json`) that are missing are silently ignored.
+- **`--config <path>`** with a missing or malformed file exits with an error.
+- **Malformed JSON** in auto-discovered files prints a warning to stderr and continues without that file.
+- **Unknown keys** are silently ignored for forward compatibility.
+
+> **Tip:** If your project-level `agent-browser.json` contains environment-specific values (paths, proxies), consider adding it to `.gitignore`.

docs/src/components/header.tsx

@@ -66,7 +66,7 @@ export function Header() {
             >
               <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z" />
             </svg>
-            <span>13.4k</span>
+            <span>14k</span>
           </a>
           <a
             href="https://www.npmjs.com/package/agent-browser"

docs/src/lib/docs-navigation.ts

@@ -21,6 +21,7 @@ export const navigation: NavSection[] = [
     title: "Reference",
     items: [
       { name: "Commands", href: "/commands" },
+      { name: "Configuration", href: "/configuration" },
       { name: "Selectors", href: "/selectors" },
       { name: "Snapshots", href: "/snapshots" },
     ],