Initial commit with translated description

references/agent-browser-command-map.md

@@ -0,0 +1,28 @@
+# Agent Browser Command Map
+
+> Note: Command availability can vary by version. Use `agent-browser help` to confirm.
+
+## Safe defaults (typical)
+- `open`, `click`, `dblclick`, `fill`, `type`, `press`, `hover`, `select`
+- `check`, `uncheck`, `scroll`, `screenshot`, `snapshot`, `close`
+- `back`, `forward`, `reload`
+- `wait`, `wait --text`, `wait --url`, `wait --load networkidle`
+- `get text`, `get html`, `get value`, `get attr`, `get title`, `get url`
+- `find role`, `find text`, `find label`, `find placeholder`
+
+## Sensitive / explicit approval
+- `eval` (arbitrary JS execution)
+- `download <selector> <path>` (writes to disk)
+- `set credentials`, `cookies`, `storage` (stateful secrets)
+- `network route` / `network requests` (traffic interception)
+- `set headers`, `--proxy` (traffic manipulation)
+- `--allow-file-access` (local file access)
+- `--executable-path`, `--args`, `--cdp` (custom runtime control)
+
+## Debug and state
+- `trace start/stop`, `console`, `errors`, `highlight`
+- `state save`, `state load` (treat state files as sensitive)
+
+## Tabs and frames
+- `tab`, `tab new`, `tab <n>`, `tab close`
+- `frame <selector>`, `frame main`

references/agent-browser-overview.md

@@ -0,0 +1,33 @@
+# Agent Browser Overview
+
+## 1) What it is
+- A fast Rust-based headless browser automation CLI with a Node.js fallback.
+- Designed for AI agents to navigate, click, type, and snapshot pages via structured commands.
+- Uses a background daemon and Playwright for browser control.
+
+## 2) Install and setup (hardened)
+- Pin the version you trust:
+  - `npm install -g agent-browser@<version>`
+- Prefer a dedicated environment or container for installs.
+- Avoid running with elevated OS privileges.
+- Install browser runtime:
+  - `agent-browser install`
+- Linux dependencies (if needed):
+  - `agent-browser install --with-deps`
+  - or `npx playwright install-deps chromium`
+
+## 3) Browser engines
+- Chromium is the default browser engine.
+- Firefox and WebKit are supported through Playwright.
+
+## 4) Snapshot concept
+- `snapshot` returns a structured view with stable element refs.
+- Refs are designed for compact, deterministic automation.
+
+## 5) Sessions
+- The CLI supports multiple sessions so agents can isolate work.
+
+## 6) Security posture
+- Treat the CLI as high privilege; run with strict allowlists.
+- Avoid file access and arbitrary script execution unless required.
+- Keep profiles and state files ephemeral by default.

references/agent-browser-safety.md

@@ -0,0 +1,25 @@
+# Safety and Risk Controls
+
+## High-risk capabilities
+- `eval` (arbitrary JavaScript)
+- `--allow-file-access` (local file access)
+- `--executable-path`, `--args`, `--cdp` (custom runtime control)
+- `network route` / `set headers` / `--proxy` (traffic manipulation)
+- `set credentials`, cookies, storage, and state files (secret handling)
+
+## Safe mode checklist
+1. Allowlist target domains; block localhost and private networks.
+2. Disallow `eval` unless explicitly required.
+3. Disallow local file access unless explicitly required.
+4. Avoid downloads and filesystem writes by default.
+5. Use ephemeral sessions; avoid persistent profiles when possible.
+6. Redact tokens in logs and outputs.
+
+## Escalation policy
+- Require explicit human approval before using any high-risk capability.
+- Record the reason and scope of the approval (which URLs, which action).
+
+## Supply-chain hygiene
+- Pin CLI version and review upgrades.
+- Install in a dedicated environment.
+- Avoid running with elevated OS privileges.

references/agent-browser-troubleshooting.md

@@ -0,0 +1,17 @@
+# Troubleshooting
+
+## CLI runs but no browser opens
+- Run `agent-browser install` to download Chromium.
+- On Linux, run `agent-browser install --with-deps` if dependencies are missing.
+
+## Native binary not available
+- The CLI falls back to the Node.js daemon automatically.
+- Ensure Node.js is installed and available.
+
+## Debugging
+- Use `--headed` to see the browser UI.
+- Use `--debug` for verbose logs.
+
+## Instability in DOM targeting
+- Resnapshot after any navigation or DOM changes.
+- Prefer refs from `snapshot` over brittle CSS selectors.

references/agent-browser-workflows.md

@@ -0,0 +1,26 @@
+# Agent Browser Workflows
+
+## 1) Snapshot-first loop
+1. `open <url>`
+2. `snapshot -i` and extract refs
+3. Act using refs: `click @e12`, `fill @e14 "text"`
+4. `snapshot -i` again after DOM changes
+
+## 2) JSON mode for agents
+- Prefer `snapshot -i` and `--json` outputs for deterministic parsing.
+- Keep a local map of ref -> intent.
+
+## 3) Authentication and reuse
+- Log in once and `state save`.
+- Reuse with `state load` in later runs.
+- Treat state files as secrets and rotate when needed.
+
+## 4) Stability tips
+- Wait for load state before actions: `wait --load networkidle`.
+- Use `wait --text` or `wait --url` for dynamic flows.
+- Prefer refs from `snapshot` over brittle CSS selectors.
+
+## 5) Safe automation loop
+- Validate URL against an allowlist before `open`.
+- Avoid `eval` and file access unless explicitly approved.
+- Prefer read-only operations when possible.