diff --git a/docs.json b/docs.json
index 08f7416..441c37c 100644
--- a/docs.json
+++ b/docs.json
@@ -380,6 +380,27 @@
               }
             ]
           },
+          {
+            "group": "@qawolf/cli",
+            "icon": "terminal",
+            "pages": [
+              {
+                "group": "API Reference",
+                "pages": [
+                  "qawolf/libraries/cli/api-reference/index",
+                  "qawolf/libraries/cli/api-reference/commands",
+                  "qawolf/libraries/cli/api-reference/configuration",
+                  "qawolf/libraries/cli/api-reference/environment-variables"
+                ]
+              },
+              {
+                "group": "Troubleshooting",
+                "pages": [
+                  "qawolf/libraries/cli/troubleshooting"
+                ]
+              }
+            ]
+          },
           {
             "group": "REST",
             "icon": "code",
@@ -465,6 +486,18 @@
               "qawolf/Azure-DevOps-Boards-29c5b2a994fb81b09697f2f1e4f9fdf1",
               "qawolf/Integrate-with-webhooks-29c5b2a994fb818d9682eb32ff11feff"
             ]
+          },
+          {
+            "group": "Local execution",
+            "icon": "terminal",
+            "pages": [
+              "qawolf/local-execution/authenticate",
+              "qawolf/local-execution/run-flows-locally",
+              "qawolf/local-execution/pull-flows",
+              "qawolf/local-execution/install-dependencies",
+              "qawolf/local-execution/set-up-a-project",
+              "qawolf/local-execution/diagnose-problems"
+            ]
           }
         ]
       },
diff --git a/qawolf/libraries/cli/api-reference/commands.mdx b/qawolf/libraries/cli/api-reference/commands.mdx
new file mode 100644
index 0000000..4b350a2
--- /dev/null
+++ b/qawolf/libraries/cli/api-reference/commands.mdx
@@ -0,0 +1,149 @@
+---
+title: "Commands Reference"
+description: "Reference notes for every qawolf CLI command and flag."
+sidebarTitle: "Commands"
+---
+
+The qawolf CLI exposes five top-level commands. Each section below documents the command's purpose, accepted arguments, and flags.
+
+## `auth`
+
+Manages authentication with the QA Wolf platform. Credentials are read from the `QAWOLF_API_KEY` environment variable first, then from the system keychain, then from a config file fallback.
+
+### `auth login`
+
+Prompts for an API key, validates it against the platform, and stores it locally. Requires an interactive terminal — in non-interactive contexts, set `QAWOLF_API_KEY` directly.
+
+```bash
+qawolf auth login
+```
+
+### `auth logout`
+
+Removes stored credentials. Credentials set via the `QAWOLF_API_KEY` environment variable cannot be removed by this command.
+
+```bash
+qawolf auth logout
+```
+
+### `auth whoami`
+
+Displays the authenticated team name, ID, optional slug, and the credential source.
+
+```bash
+qawolf auth whoami
+```
+
+## `flows`
+
+Manages and runs QA Wolf flows.
+
+### `flows run [pattern]`
+
+Runs flows matching `[pattern]`, or every flow when omitted. The default pattern matches `**/*.flow.{ts,js}` in the current working directory and in `.qawolf/<env>/` subdirectories.
+
+```bash
+qawolf flows run
+qawolf flows run "flows/checkout/**"
+qawolf flows run checkout --env staging --headed
+```
+
+Options:
+
+- `--retries <n>` — number of retries for each failing flow. Default: `0`.
+- `--bail` — stop after the first failure. Default: `false`.
+- `--workers <n>` — parallel worker count for web flows. Default: `1`. Android flows must run with `--workers 1`; the CLI errors out if Android flows are selected with a higher value.
+- `--timeout <ms>` — per-flow timeout in milliseconds. Default: `30000`.
+- `--junit [path]` — write a JUnit XML report. With no value, writes to `<output-dir>/junit-report.xml`. Pass an explicit path to override.
+- `--video <mode>` — `on`, `off`, or `retain-on-failure`. Default: `off`.
+- `--trace <mode>` — Playwright trace mode. `on`, `off`, or `retain-on-failure`. Default: `off`.
+- `--har <mode>` — HAR capture mode. `on`, `off`, or `retain-on-failure`. Default: `off`.
+- `--har-content <mode>` — `omit` or `full`. `full` includes response bodies and uses more memory. Default: `omit`.
+- `--output-dir <path>` — directory for artifacts. Default: `qawolf-output`.
+- `--headed` — show the browser window instead of running headless. Default: `false`.
+- `--env <env>` — environment ID. When set, missing flows are pulled before the run.
+
+Exit codes: `0` when all flows pass, `1` when one or more flows fail, `2` for invalid arguments or an unrecognized flow target. See [Exit codes](/qawolf/libraries/cli/api-reference/index#exit-codes).
+
+### `flows list [pattern]`
+
+Lists flows matching `[pattern]`. By default, lists local flows; with `--remote`, lists flows from the QA Wolf platform.
+
+```bash
+qawolf flows list
+qawolf flows list "flows/checkout/**"
+qawolf flows list --remote
+```
+
+Options:
+
+- `--remote` — list flows from the QA Wolf platform instead of the local project. Default: `false`.
+
+### `flows pull`
+
+Downloads an environment's flows into the local `.qawolf/<env>/` cache.
+
+```bash
+qawolf flows pull --env staging
+qawolf flows pull --env 4e9c... --out ./snapshot
+qawolf flows pull --env staging --yes
+```
+
+Options:
+
+- `--env <env>` — required. The environment ID to pull from.
+- `--out <path>` — destination directory. Defaults to `.qawolf/<env>/`.
+- `--yes` — overwrite locally-modified files without prompting. Default: `false`.
+
+## `install`
+
+Installs every runtime dependency the project's flows need. With a `[pattern]` argument, only the dependencies for the matching flows are installed.
+
+```bash
+qawolf install
+qawolf install "flows/checkout/**"
+```
+
+### `install browsers [pattern]`
+
+Installs the Playwright browsers used by the project's web flows.
+
+```bash
+qawolf install browsers
+qawolf install browsers "flows/web/**"
+```
+
+### `install android [pattern]`
+
+Installs Android system images, AVDs, and the Appium driver used by the project's Android flows. Requires `ANDROID_HOME` or `ANDROID_SDK_ROOT`.
+
+```bash
+qawolf install android
+qawolf install android "flows/mobile/**"
+```
+
+## `init`
+
+Scaffolds a QA Wolf project in the current directory. Creates `qawolf.config.ts`, an example flow at `src/flows/example.flow.ts`, and `.qawolf/.gitignore`. Adds the `@qawolf/flows` dependency and a `test:e2e` script to `package.json`.
+
+```bash
+qawolf init
+qawolf init --yes
+```
+
+Options:
+
+- `--yes` — overwrite existing files without prompting. Default: `false`.
+
+## `doctor`
+
+Diagnoses problems running flows locally. Checks the CLI version, Node.js version, Playwright installation, browser availability for web flows, and the Android SDK for Android flows.
+
+```bash
+qawolf doctor
+qawolf doctor --all
+```
+
+Options:
+
+- `--all` — run every platform check, including platforms the project does not use. Default: `false`.
diff --git a/qawolf/libraries/cli/api-reference/configuration.mdx b/qawolf/libraries/cli/api-reference/configuration.mdx
new file mode 100644
index 0000000..1071014
--- /dev/null
+++ b/qawolf/libraries/cli/api-reference/configuration.mdx
@@ -0,0 +1,31 @@
+---
+title: "Configuration Reference"
+description: "Reference notes for the qawolf.config.ts file."
+sidebarTitle: "Configuration"
+---
+
+The qawolf CLI reads a `qawolf.config.ts` file at the project root. `qawolf init` generates this file with the defaults shown below. Fields set on the command line override the config.
+
+```typescript
+export default {
+  outputDir: ".qawolf",
+  timeout: 60_000,
+  retries: 0,
+  video: "retain-on-failure",
+};
+```
+
+## Fields
+
+- `outputDir` — directory for run artifacts such as videos, traces, and HAR files. Overridden by `--output-dir`.
+- `timeout` — per-flow timeout in milliseconds. Overridden by `--timeout`.
+- `retries` — number of retries for each failing flow. Overridden by `--retries`.
+- `video` — video capture mode. One of `"on"`, `"off"`, or `"retain-on-failure"`. Overridden by `--video`.
+
+## Generated Project Layout
+
+`qawolf init` writes the following files alongside `qawolf.config.ts`:
+
+- `src/flows/example.flow.ts` — a minimal web flow used as a starting point.
+- `.qawolf/.gitignore` — ignores the contents of `.qawolf/` except for the file itself.
+- `package.json` — created or updated to include `"type": "module"`, the `@qawolf/flows` dependency, and a `"test:e2e": "qawolf flows run"` script.
diff --git a/qawolf/libraries/cli/api-reference/environment-variables.mdx b/qawolf/libraries/cli/api-reference/environment-variables.mdx
new file mode 100644
index 0000000..d922c54
--- /dev/null
+++ b/qawolf/libraries/cli/api-reference/environment-variables.mdx
@@ -0,0 +1,41 @@
+---
+title: "Environment Variables"
+description: "Environment variables read by the qawolf CLI."
+sidebarTitle: "Environment Variables"
+---
+
+The qawolf CLI reads the following environment variables.
+
+## `QAWOLF_API_KEY`
+
+API key for the QA Wolf platform. Used by `flows pull`, `flows list --remote`, and `flows run --env`. Required for any command that talks to the platform. Takes precedence over credentials stored via `qawolf auth login`.
+
+## `QAWOLF_API_URL`
+
+Base URL for the QA Wolf platform API. Defaults to `https://app.qawolf.com`. Trailing slashes are stripped.
+
+## `ANDROID_HOME`
+
+Path to the Android SDK root. Required by `qawolf install android` and by Android flow execution. `ANDROID_SDK_ROOT` is accepted as a fallback.
+
+## `ANDROID_SDK_ROOT`
+
+Fallback path to the Android SDK root, used when `ANDROID_HOME` is not set.
+
+## CI Detection
+
+The CLI treats the following variables as a signal that it is running in CI and switches the default output format to JSON:
+
+- `CI`
+- `GITHUB_ACTIONS`
+- `GITLAB_CI`
+- `CIRCLECI`
+- `JENKINS_URL`
+- `BUILDKITE`
+
+## Agent Detection
+
+The CLI treats the following variables as a signal that it is running inside an agent and switches the default output format to agent mode:
+
+- `CLAUDE_CODE`
+- `CURSOR_SESSION_ID`
diff --git a/qawolf/libraries/cli/api-reference/index.mdx b/qawolf/libraries/cli/api-reference/index.mdx
new file mode 100644
index 0000000..7b8669a
--- /dev/null
+++ b/qawolf/libraries/cli/api-reference/index.mdx
@@ -0,0 +1,46 @@
+---
+title: "API Reference"
+description: "API landing page for the qawolf CLI."
+sidebarTitle: "API Reference"
+---
+
+Use this section for stable command descriptions, flags, configuration, environment variables, and exit codes.
+
+## Commands
+
+- [`qawolf auth`](/qawolf/libraries/cli/api-reference/commands#auth) — manage authentication.
+- [`qawolf flows`](/qawolf/libraries/cli/api-reference/commands#flows) — run, list, and pull flows.
+- [`qawolf install`](/qawolf/libraries/cli/api-reference/commands#install) — install runtime dependencies for the project.
+- [`qawolf init`](/qawolf/libraries/cli/api-reference/commands#init) — scaffold a project in the current directory.
+- [`qawolf doctor`](/qawolf/libraries/cli/api-reference/commands#doctor) — diagnose problems running flows locally.
+
+Example invocation:
+
+```bash
+qawolf auth login
+qawolf flows pull --env <env>
+qawolf flows run
+```
+
+## Global Options
+
+The following flags apply to every command:
+
+- `--verbose` — emits debug logs to stderr.
+- `--json` — formats output as JSON.
+- `--agent` — formats output for agent consumption.
+
+When a recognized CI environment is detected (`CI`, `GITHUB_ACTIONS`, `GITLAB_CI`, `CIRCLECI`, `JENKINS_URL`, `BUILDKITE`), output defaults to JSON. When a recognized agent environment is detected (`CLAUDE_CODE`, `CURSOR_SESSION_ID`), output defaults to agent mode.
+
+## Exit Codes
+
+Every qawolf CLI command exits with one of the codes below.
+
+| Code | Name | Meaning |
+| --- | --- | --- |
+| `0` | `success` | The command completed successfully. |
+| `1` | `testFailure` | One or more flows failed. |
+| `2` | `invalidArgs` | A Commander parse error, an unknown subcommand, or a bad flag value. |
+| `3` | `auth` | `QAWOLF_API_KEY` is missing or invalid. |
+| `4` | `network` | The QA Wolf API was unreachable, a download from storage failed, or a registry was unreachable. |
+| `5` | `config` | `qawolf.config.ts` is invalid, or a file collision occurred during `qawolf init`. |
diff --git a/qawolf/libraries/cli/troubleshooting.mdx b/qawolf/libraries/cli/troubleshooting.mdx
new file mode 100644
index 0000000..2ef1e37
--- /dev/null
+++ b/qawolf/libraries/cli/troubleshooting.mdx
@@ -0,0 +1,99 @@
+---
+title: "CLI Troubleshooting"
+description: "Common issues when running the qawolf CLI."
+sidebarTitle: "CLI Troubleshooting"
+---
+
+## `QAWOLF_API_KEY` Is Not Set
+
+Cause: The CLI could not find an API key in the environment, the system keychain, or the local config file.
+
+Check:
+
+- the `QAWOLF_API_KEY` environment variable is set in the current shell
+- credentials have been stored locally with `qawolf auth login`
+- the value has not been overwritten by another shell profile
+
+## QA Wolf API Rejected The Request (HTTP 401)
+
+Cause: The API key is invalid or has been revoked.
+
+Check:
+
+- the key matches one issued for the current workspace
+- the key was not truncated or copied with surrounding whitespace
+- `qawolf auth whoami` returns the expected team
+
+## QA Wolf API Rejected The Request (HTTP 403)
+
+Cause: The API key is valid but does not have access to the requested environment.
+
+Check:
+
+- the key was issued for a workspace that contains this environment
+- the environment ID matches one returned by the platform
+
+## Could Not Reach The QA Wolf API
+
+Cause: The CLI could not connect to the platform at `QAWOLF_API_URL`.
+
+Check:
+
+- the network can reach `https://app.qawolf.com` (or the URL configured in `QAWOLF_API_URL`)
+- `QAWOLF_API_URL` does not contain a typo or unexpected trailing path
+- corporate proxy and VPN settings allow outbound HTTPS
+
+## Flow Bundle Download Link Has Expired
+
+Cause: The signed URL the CLI received from the platform has expired before the bundle was downloaded.
+
+Check:
+
+- re-run `qawolf flows pull --env <env>` to fetch a fresh link
+- network conditions are not slowing the download past the link's expiration window
+
+## Android SDK Not Found
+
+Cause: `qawolf install android` could not locate the Android SDK at the path given by `ANDROID_HOME` or `ANDROID_SDK_ROOT`.
+
+Check:
+
+- `ANDROID_HOME` is exported in the current shell and points at the SDK root
+- the SDK is installed via Android Studio or via the standalone `cmdline-tools` package
+- `sdkmanager` exists at `$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager`
+
+## iOS Targets Are Not Supported
+
+Cause: The selected flow targets an iOS device. iOS execution is not yet supported by the CLI.
+
+Check:
+
+- the flow's `target` is set to a web or Android value
+- iOS flows are filtered out of the run with a pattern argument
+
+## Could Not Load `@qawolf/testkit`
+
+Cause: The runner could not resolve `@qawolf/testkit` from the project directory.
+
+Check:
+
+- `@qawolf/testkit` is listed in `package.json` and installed
+- the command is being run from the project root, or from a directory inside a pulled environment
+
+## Android Flows Are Not Supported With `--workers > 1`
+
+Cause: `--workers <n>` was set to a value greater than `1` and at least one Android flow was selected for the run.
+
+Check:
+
+- rerun the Android flows with `--workers 1`
+- split the run into a web-only invocation with `--workers <n>` and an Android-only invocation with `--workers 1`
+
+## Basic Target Flow Cannot Be Executed
+
+Cause: The flow targets `"Basic"`, the Node-only platform type. The CLI does not execute Basic flows.
+
+Check:
+
+- the flow has been ported to a supported target, or
+- the flow is excluded from the run with a pattern argument
diff --git a/qawolf/local-execution/authenticate.mdx b/qawolf/local-execution/authenticate.mdx
new file mode 100644
index 0000000..e707645
--- /dev/null
+++ b/qawolf/local-execution/authenticate.mdx
@@ -0,0 +1,87 @@
+---
+title: "Authenticate the QA Wolf CLI"
+description: "Install the qawolf CLI and connect it to your workspace so it can pull and run your flows."
+sidebarTitle: "Authenticate"
+icon: "key"
+---
+
+Before the CLI can pull flows from your workspace or run flows that depend on environment variables, it needs an API key. You can log in interactively for local development, or pass the key through an environment variable for CI.
+
+## Install the CLI
+
+The CLI ships in two forms: an npm package and a precompiled standalone binary.
+
+### Install with npm
+
+<Check>
+  Node.js 24 or later is required.
+</Check>
+
+```bash
+npm install -g @qawolf/cli
+```
+
+### Install a precompiled binary
+
+Download the binary for your platform from [GitHub Releases](https://github.com/qawolf/cli/releases). Builds are published for Linux x64, macOS (Apple Silicon and Intel), and Windows x64. The binary has no Node.js runtime dependency. Extract the archive, then move the binary into a directory on your `PATH`.
+
+### Verify
+
+```bash
+qawolf --version
+```
+
+## Log in for local development
+
+<Steps>
+  <Step>
+    Generate an API key in your QA Wolf workspace under **Workspace settings → API keys**.
+  </Step>
+  <Step>
+    Run the login command:
+
+    ```bash
+    qawolf auth login
+    ```
+
+    The CLI prompts for your API key, validates it against the platform, and stores it in your system keychain. When a keychain is not available, the CLI falls back to a local config file in your user profile directory.
+  </Step>
+  <Step>
+    Confirm the connection:
+
+    ```bash
+    qawolf auth whoami
+    ```
+
+    The output shows the team name, ID, and where the credential was loaded from.
+  </Step>
+</Steps>
+
+## Authenticate in CI
+
+CI environments cannot prompt for input. Set the `QAWOLF_API_KEY` environment variable instead:
+
+```bash
+export QAWOLF_API_KEY=<your-api-key>
+qawolf flows pull --env staging
+```
+
+The CLI prefers `QAWOLF_API_KEY` over any credential stored by `qawolf auth login`, so the same machine can switch between accounts by setting or unsetting the variable.
+
+## Log out
+
+```bash
+qawolf auth logout
+```
+
+`qawolf auth logout` only removes credentials stored by `qawolf auth login`. Credentials set through `QAWOLF_API_KEY` cannot be removed by this command — unset the variable in your shell instead.
+
+## Switch the API URL
+
+By default the CLI talks to `https://app.qawolf.com`. Override this with `QAWOLF_API_URL` if your workspace uses a different host:
+
+```bash
+export QAWOLF_API_URL=https://qawolf.example.com
+```
+
+See the [Environment variables reference](/qawolf/libraries/cli/api-reference/environment-variables) for the full list of variables the CLI reads.
diff --git a/qawolf/local-execution/diagnose-problems.mdx b/qawolf/local-execution/diagnose-problems.mdx
new file mode 100644
index 0000000..ef98a52
--- /dev/null
+++ b/qawolf/local-execution/diagnose-problems.mdx
@@ -0,0 +1,58 @@
+---
+title: "Diagnose problems running flows"
+description: "Use qawolf doctor to check your environment, find missing dependencies, and read the CLI's log file."
+sidebarTitle: "Diagnose problems"
+icon: "stethoscope"
+---
+
+When a flow run fails for reasons that aren't in the flow itself — a missing browser, an Android SDK that isn't on the path, a Node.js version mismatch — `qawolf doctor` is the first thing to run.
+
+## Run the diagnostics
+
+<Steps>
+  <Step>
+    From the project root, run:
+
+    ```bash
+    qawolf doctor
+    ```
+
+    The CLI checks:
+
+    - the CLI version
+    - the Node.js version against the required minimum
+    - the Playwright installation, if any flow targets a browser
+    - browser availability for each target the project uses
+    - the Android SDK, if any flow targets Android
+  </Step>
+  <Step>
+    Read the output. Each check reports a pass, a warning, or a failure, with a remediation hint when it fails.
+  </Step>
+</Steps>
+
+## Check every platform
+
+`qawolf doctor` only checks the platforms your project actually uses. Pass `--all` to run every check, including platforms not used by the current project:
+
+```bash
+qawolf doctor --all
+```
+
+This is useful when copying the project to a new machine and you want a single command that surfaces every missing dependency.
+
+## Read the log file
+
+The CLI writes structured logs to the platform's user cache directory:
+
+- macOS: `~/Library/Caches/qawolf/qawolf.log`
+- Linux: `$XDG_CACHE_HOME/qawolf/qawolf.log` or `~/.cache/qawolf/qawolf.log`
+
+Run with `--verbose` to mirror debug logs to stderr in real time:
+
+```bash
+qawolf flows run --verbose
+```
+
+## Common issues
+
+The [CLI Troubleshooting reference](/qawolf/libraries/cli/troubleshooting) covers the specific errors the CLI emits, including authentication failures, missing Android SDK, expired download links, and the `@qawolf/testkit` resolution error.
diff --git a/qawolf/local-execution/install-dependencies.mdx b/qawolf/local-execution/install-dependencies.mdx
new file mode 100644
index 0000000..26d50f4
--- /dev/null
+++ b/qawolf/local-execution/install-dependencies.mdx
@@ -0,0 +1,58 @@
+---
+title: "Install runtime dependencies"
+description: "Install the Playwright browsers, Android system images, and drivers your flows need to run."
+sidebarTitle: "Install dependencies"
+icon: "download"
+---
+
+[`qawolf flows run --env <env>`](/qawolf/local-execution/run-flows-locally) installs runtime dependencies automatically before its first run, so most users never invoke `qawolf install` directly. Reach for it when you want to install ahead of time — for example, to warm a CI cache between the checkout step and the run step — or when you're running flows from a [local-only project](/qawolf/local-execution/set-up-a-project).
+
+## Install everything the project needs
+
+<Steps>
+  <Step>
+    From the project root, run:
+
+    ```bash
+    qawolf install
+    ```
+
+    The CLI scans the project for flows, looks at each flow's `target`, and installs the dependencies required by every target it finds.
+  </Step>
+</Steps>
+
+## Install only for specific flows
+
+Pass a pattern to limit which flows are considered:
+
+```bash
+qawolf install "checkout/**"
+```
+
+This is useful in CI when a job only runs a subset of the suite.
+
+## Install browsers only
+
+```bash
+qawolf install browsers
+qawolf install browsers "flows/web/**"
+```
+
+Equivalent to running `playwright install` for the browsers your web flows target.
+
+## Install Android dependencies only
+
+<Check>
+  Set `ANDROID_HOME` (or `ANDROID_SDK_ROOT`) to the path of your Android SDK before running this command. Install the SDK through Android Studio's **SDK Manager** or the standalone `cmdline-tools` package.
+</Check>
+
+```bash
+qawolf install android
+qawolf install android "flows/mobile/**"
+```
+
+The command installs the Appium uiautomator2 driver, downloads the Android system images for each target the matching flows use, and creates the corresponding AVDs.
+
+## iOS support
+
+iOS flows are not yet executable by the CLI. `qawolf install` skips them and prints a clear error if you select an iOS-only pattern. iOS support requires macOS with Xcode when it ships.
diff --git a/qawolf/local-execution/pull-flows.mdx b/qawolf/local-execution/pull-flows.mdx
new file mode 100644
index 0000000..b1b226e
--- /dev/null
+++ b/qawolf/local-execution/pull-flows.mdx
@@ -0,0 +1,69 @@
+---
+title: "Pull your team's flows"
+description: "Download an environment's flows into a local cache without running them."
+sidebarTitle: "Pull flows"
+icon: "cloud-download"
+---
+
+For most workflows, [`qawolf flows run --env <env>`](/qawolf/local-execution/run-flows-locally) is enough — it pulls the environment's flows for you when they are not already cached locally. Reach for `qawolf flows pull` when you want to download the flow files without running them: to inspect them, commit them to a repository, or refresh a stale cache.
+
+<Check>
+  Authenticate the CLI first. See [Authenticate the QA Wolf CLI](/qawolf/local-execution/authenticate).
+</Check>
+
+## Pull an environment
+
+<Steps>
+  <Step>
+    Find the environment's ID in your QA Wolf workspace under **Workspace settings → Environments**.
+  </Step>
+  <Step>
+    Pull the flows:
+
+    ```bash
+    qawolf flows pull --env staging
+    ```
+
+    The CLI writes flows to `.qawolf/staging/` by default. To use a different destination, pass `--out`:
+
+    ```bash
+    qawolf flows pull --env staging --out ./snapshot
+    ```
+  </Step>
+  <Step>
+    List the pulled flows:
+
+    ```bash
+    qawolf flows list
+    ```
+  </Step>
+</Steps>
+
+## What `pull` writes
+
+Inside `.qawolf/<env>/`, the CLI stores:
+
+- the flow source files
+- a manifest tracking what was pulled and when
+- a `.env` file with the environment's variables, loaded automatically by `qawolf flows run`
+
+## Refresh a pulled environment
+
+Run `qawolf flows pull --env <env>` again. The CLI prompts before overwriting any file that has been modified locally. To skip the prompt and overwrite, pass `--yes`:
+
+```bash
+qawolf flows pull --env staging --yes
+```
+
+## List flows on the platform
+
+To see what is available on the platform without pulling, use `--remote`:
+
+```bash
+qawolf flows list --remote
+qawolf flows list "checkout/**" --remote
+```
+
+## What's not pulled
+
+File assets stored in QA Wolf cloud storage are not pulled. Web flows that read paths from `QAWOLF_*_DIR` environment variables cannot run locally until the assets are available on the machine. Mobile flows reference the APK or IPA build through an environment variable — make sure that path is set before running.
diff --git a/qawolf/local-execution/run-flows-locally.mdx b/qawolf/local-execution/run-flows-locally.mdx
new file mode 100644
index 0000000..9219470
--- /dev/null
+++ b/qawolf/local-execution/run-flows-locally.mdx
@@ -0,0 +1,134 @@
+---
+title: "Run flows locally"
+description: "Run your team's flows on your own machine — the CLI pulls, installs, and runs in one command."
+sidebarTitle: "Run flows locally"
+icon: "play"
+---
+
+`qawolf flows run --env <env>` is the recommended path. It runs your team's flows from the local `.qawolf/<env>/` cache, pulling them first only if they are not already cached locally, then installs the runtime dependencies they need (Playwright browsers, Android system images and AVDs) and runs them.
+
+<Check>
+  Authenticate the CLI first. See [Authenticate the QA Wolf CLI](/qawolf/local-execution/authenticate).
+</Check>
+
+## Run an environment
+
+<Steps>
+  <Step>
+    Find the environment's ID in your QA Wolf workspace under **Workspace settings → Environments**.
+  </Step>
+  <Step>
+    From any directory, run:
+
+    ```bash
+    qawolf flows run --env staging
+    ```
+
+    The CLI:
+
+    1. checks the local `.qawolf/staging/` cache, and pulls the environment's flows only if they are not already cached
+    2. loads the environment's `.env` file
+    3. installs the Playwright browsers and Android dependencies the flows need
+    4. runs every flow
+
+    To refresh the local cache against the platform, run `qawolf flows pull --env staging`. See [Pull your team's flows](/qawolf/local-execution/pull-flows).
+  </Step>
+</Steps>
+
+## Run a subset
+
+Pass a glob pattern to limit which flows run:
+
+```bash
+qawolf flows run --env staging "checkout/**"
+qawolf flows run --env staging "src/flows/login.flow.ts"
+```
+
+Patterns are matched against absolute paths in the current directory and against the pulled cache under `.qawolf/<env>/`.
+
+## Watch the browser
+
+Pass `--headed` to see the browser window during a web run:
+
+```bash
+qawolf flows run --env staging --headed
+```
+
+`--headed` does not apply to Android flows.
+
+## Capture artifacts on failure
+
+By default, no video or trace is recorded. To keep artifacts only when a flow fails, set the mode to `retain-on-failure`:
+
+```bash
+qawolf flows run --env staging --video retain-on-failure --trace retain-on-failure
+```
+
+Artifacts land in `qawolf-output/` (or the directory set by `--output-dir`).
+
+To record HAR files of network traffic:
+
+```bash
+qawolf flows run --env staging --har retain-on-failure
+```
+
+By default the HAR captures headers and timing only. To include response bodies, pass `--har-content full`. Response bodies use significantly more memory and disk.
+
+## Retry failing flows
+
+```bash
+qawolf flows run --env staging --retries 2
+```
+
+The CLI retries each failing flow up to the given number of times. A flow that passes on retry is counted as a pass for exit-code purposes.
+
+## Stop after the first failure
+
+```bash
+qawolf flows run --env staging --bail
+```
+
+`--bail` is useful when iterating on a single flow and you want to fail fast.
+
+## Run web flows in parallel
+
+```bash
+qawolf flows run --env staging --workers 4
+```
+
+`--workers` controls how many web flows run concurrently. Android flows must run with `--workers 1` — the CLI errors out if Android flows are selected with a higher value.
+
+## Write a JUnit XML report
+
+```bash
+qawolf flows run --env staging --junit
+```
+
+The CLI writes a JUnit XML report to `qawolf-output/junit-report.xml` (or under the directory set by `--output-dir`). Pass an explicit path to override the default:
+
+```bash
+qawolf flows run --env staging --junit ./reports/results.xml
+```
+
+The XML report is written alongside the console output and is independent of `--json` and `--agent`.
+
+## Run flows you authored locally
+
+If you've scaffolded a [local-only project](/qawolf/local-execution/set-up-a-project) with `qawolf init`, run without `--env`:
+
+```bash
+qawolf flows run
+```
+
+The CLI discovers flows matching `**/*.flow.{ts,js}` in the current directory and runs them against locally-installed runtime dependencies. See [Install dependencies](/qawolf/local-execution/install-dependencies) if you need to install browsers or Android tooling explicitly.
+
+## Exit codes
+
+`qawolf flows run` exits with `0` when every flow passes and `1` when one or more fail. See [Exit codes](/qawolf/libraries/cli/api-reference/index#exit-codes) for the full list.
+
+## Current limitations
+
+- Android flows must run with `--workers 1`. Parallel execution is supported for web flows only.
+- iOS flows are not executed. The CLI prints a clear error if an iOS flow is selected for a run.
+- Flows that target the legacy `"Basic"` platform pull successfully but cannot be executed by the CLI.
+- Dynamic-target flows — flows where `target` is a computed value rather than a string literal — are included in every run because the CLI cannot determine the platform ahead of time.
diff --git a/qawolf/local-execution/set-up-a-project.mdx b/qawolf/local-execution/set-up-a-project.mdx
new file mode 100644
index 0000000..9965fad
--- /dev/null
+++ b/qawolf/local-execution/set-up-a-project.mdx
@@ -0,0 +1,66 @@
+---
+title: "Set up a local-only project"
+description: "Scaffold a project for hand-authoring flows that don't live on the QA Wolf platform."
+sidebarTitle: "Set up a project"
+icon: "folder-plus"
+---
+
+`qawolf init` scaffolds a project for writing flow files by hand. Most users should [pull flows from QA Wolf](/qawolf/local-execution/pull-flows) instead — the platform is where flow creation, AI-powered test generation, and team collaboration live, and `qawolf flows pull` brings those flows into a local cache the CLI can run from. Reach for `qawolf init` only when you want to author flows locally without the platform.
+
+## Scaffold a new project
+
+<Steps>
+  <Step>
+    Open a terminal in the directory you want to use as the project root:
+
+    ```bash
+    cd path/to/your/project
+    ```
+  </Step>
+  <Step>
+    Run the init command:
+
+    ```bash
+    qawolf init
+    ```
+
+    The CLI prompts before overwriting any existing files. To skip the prompts, pass `--yes`.
+  </Step>
+</Steps>
+
+The command creates the following files:
+
+- `qawolf.config.ts` — the project configuration. See the [Configuration reference](/qawolf/libraries/cli/api-reference/configuration) for the full list of fields.
+- `src/flows/example.flow.ts` — a minimal web flow you can edit or delete.
+- `.qawolf/.gitignore` — ignores artifacts produced by `qawolf flows run` and flows pulled from the platform.
+
+If your directory has no `package.json`, the CLI creates one. Otherwise, it adds the `@qawolf/flows` dependency and a `test:e2e` script that runs `qawolf flows run`.
+
+## Write a flow
+
+Flow files live anywhere in your project as long as they match the glob `**/*.flow.{ts,js}`. The example flow is a good starting point:
+
+```typescript
+import { expect, flow } from "@qawolf/flows/web";
+
+export default flow(
+  "Example",
+  { launch: true, target: "Web - Chrome" },
+  async ({ page, test }) => {
+    await test("navigate to example.com", async () => {
+      await page.goto("https://example.com");
+      await expect(page).toHaveTitle(/Example/);
+    });
+  },
+);
+```
+
+For the full flow authoring surface, see the [@qawolf/flows API reference](/qawolf/libraries/flows/api-reference/index).
+
+## Verify the setup
+
+```bash
+qawolf flows list
+```
+
+The command lists every flow the CLI can find in the project. If the example flow appears, the project is ready to run.