docs: Various unsaved edits

Author: zah

docs/agent-browsers/spec.md

@@ -4,9 +4,9 @@
 
 Defines a shared, cross‑platform convention for storing named browser profiles used by automated agents that require authenticated access to particular websites. A profile represents a persistent browser user data directory plus lightweight metadata that describes login expectations and provenance. This spec’s primary purpose is to make such profiles discoverable by applications while allowing users to transparently know which profile and authentication will be used by the application. The same profile name can be referenced by multiple applications. A default profile is used when none is specified.
 
-#### Motivating example
+#### Motivation
 
-Multiple agentic applications (e.g., a research assistant, an issue triager, and an expense reporter) need to act on behalf of the user across several websites (e.g., `chatgpt.com`, `jira.example.com`, `expense.example.com`). Instead of each app asking the user to log in separately, they discover existing agent browser profiles by matching `loginExpectations` (site `id`/`origins`) and reuse the corresponding user data directories. Typically these apps run headless using a browser automation framework such as Playwright. When an expected login is not actually present, the app restarts the automation engine in a visible state so the user can complete the login, then resumes and finishes the task.
+Multiple agentic applications (e.g., a research assistant, an issue triager, and an expense reporter) need to act on behalf of the user across several websites (e.g., `chatgpt.com`, `jira.example.com`, `expense.example.com`). Instead of each app asking the user to log in separately, they discover existing agent browser profiles by matching the sites/username metadata that each profile provides. Typically these apps run headless using a browser automation framework such as Playwright. When an expected login is not actually acomplished, the app restarts the automation engine in a visible state so the user can complete the login, then resumes and finishes the task.
 
 If the app discovers multiple candidate profiles for the same website (for example, different `username` values), our guidance is to ask the user which profile to use for the current task. Applications should communicate profile names clearly and expose options to create new profiles or rename existing ones. Users are expected to become familiar with these profile names, which are reused across applications.
 
@@ -58,7 +58,6 @@ Format: JSON, UTF‑8. Unknown fields must be ignored for forward compatibility.
   "createdBy": ["my-app", "v1.2.3"],
   "loginExpectations": [
     {
-      "id": "chatgpt-com",
       "origins": ["https://chatgpt.com"],
       "username": "[email protected]"
     }
@@ -73,17 +72,10 @@ Field definitions:
 - `createdAt` / `updatedAt` (RFC3339 strings): For auditing.
 - `createdBy` (array<string>): Application and version that created this profile, e.g., `["app-name", "v1.2.3"]`.
 - `loginExpectations` (array): Zero or more per‑site discovery hints. Each entry:
-  - `id` (string): Stable identifier for the site (e.g., `chatgpt-com`).
   - `origins` (array<string>): Allowed origins for the site (schemes required).
   - `username` (string): Account identifier expected to be logged in (email, handle, or user ID).
   Applications MAY include additional, application‑specific keys inside `loginExpectations` entries to support their own check mechanisms; such keys are not standardized by this spec.
 
-Semantics:
-- Applications MAY add engine‑specific data under `browsers/*` and MUST NOT modify fields they do not own.
-- This spec does not define a login‑check format. Applications and libraries are expected to implement authentication checks in an application‑specific way and may publish reusable packages for popular sites.
-- Recommended (non‑normative) UX guidance: start headless; if a check indicates login is required, relaunch the same user data directory headful to allow the user to complete login, then continue the task.
-- Discoverability intent: when an application needs to act on a site (e.g., `chatgpt.com`), it can search for profiles with matching `loginExpectations.id`/`origins`. If multiple profiles exist with different `username` values, the application may select automatically per policy or prompt the user to choose which account to use for the task.
-
 ### Environment Variables
 
 - `AGENT_BROWSER_PROFILES_DIR`: Absolute path override for the base directory.
@@ -93,6 +85,5 @@ Semantics:
 
 - Profile contents may include cookies and tokens protected by OS keychains. Profiles generally do not port across different machines/OSes. Treat them as per‑user, per‑machine.
 - Never commit profile directories to source control.
-- Prefer role/aria selectors in `selector-present` checks to minimize locale‑specific fragility.
 
 

docs/browser-automation/README.md

@@ -12,5 +12,3 @@ Each document in this folder describes an automation targeting a specific site t
 - Use Playwright persistent contexts bound to a selected profile.
 - Prefer headless execution when the profile’s login expectations are met; otherwise, switch to headful and guide the user.
 - Detect UI drift and fail fast with actionable diagnostics. When possible, surface the browser window to help the user investigate.
-
-

docs/cli-spec.md

@@ -36,6 +36,8 @@ Configuration mapping examples:
 - `editor.default` ↔ `--editor`
 - `browserAutomation.enabled` ↔ `--browser-automation`, `AGENTS_WORKFLOW_BROWSER_AUTOMATION_ENABLED`
 - `browserAutomation.profile` ↔ `--browser-profile`, `AGENTS_WORKFLOW_BROWSER_PROFILE`
+- `browserAutomation.chatgptUsername` ↔ `--chatgpt-username`, `AGENTS_WORKFLOW_BROWSER_AUTOMATION_CHATGPT_USERNAME`
+- `codex.workspace` ↔ `--codex-workspace`, `AGENTS_WORKFLOW_CODEX_WORKSPACE`
 
 ### Subcommands
 
@@ -58,14 +60,15 @@ Task launch behavior in TUI:
 
 #### 2) Tasks
 
-- `aw task [create] [--prompt <TEXT> | --prompt-file <FILE>] [--repo <PATH|URL>] [--branch <NAME>] [--agent <TYPE>[@VERSION]] [--instances <N>] [--runtime <devcontainer|local|unsandboxed>] [--devcontainer-path <PATH>] [--labels k=v ...] [--delivery <pr|branch|patch>] [--target-branch <NAME>] [--browser-automation <true|false>] [--browser-profile <NAME>] [--yes]`
+- `aw task [create] [--prompt <TEXT> | --prompt-file <FILE>] [--repo <PATH|URL>] [--branch <NAME>] [--agent <TYPE>[@VERSION]] [--instances <N>] [--runtime <devcontainer|local|unsandboxed>] [--devcontainer-path <PATH>] [--labels k=v ...] [--delivery <pr|branch|patch>] [--target-branch <NAME>] [--browser-automation <true|false>] [--browser-profile <NAME>] [--chatgpt-username <NAME>] [--codex-workspace <WORKSPACE>] [--yes]`
 
 Behavior:
 
 - In local mode, prepares a per-task workspace using snapshot preference order (ZFS > Btrfs > Overlay > copy) and launches the agent.
 - In rest mode, calls `POST /api/v1/tasks` with the provided parameters.
 - Creates/updates a local PID-like session record when launching locally (see “Local Discovery”).
 - When `--browser-automation true` (default), launches site-specific browser automation (e.g., Codex) using the selected agent browser profile. When `false`, web automation is skipped.
+- Codex integration: if `--browser-profile` is not specified, discovers or creates a ChatGPT profile per `docs/browser-automation/codex.md`, optionally filtered by `--chatgpt-username`. Workspace is taken from `--codex-workspace` or config; branch is taken from `--branch`.
 - Branch autocompletion uses standard git protocol:
   - Local mode: `git for-each-ref` on the repo; cached with debounce.
   - REST mode: server uses `git ls-remote`/refs against admin-configured URL to populate its cache; CLI/Web query capability endpoints for suggestions.

docs/configuration.md

@@ -1,9 +1,25 @@
 
-Thanks for the clarifications. I’ll revise the specification to include:
+## AW Configuration
+
+### Overview
 
 * `aw config` subcommand with Git-like interface for reading and updating configuration.
 * Schema validation on both config file loading and CLI-based modification.
 * Precedence for `~/.config` over `%APPDATA%` on Windows only when both are present.
-* Motivation and support for tracking the origin of each configuration value, with use cases such as: debug-level log reporting, enforced setting explanation, and editor pre-fill messages.
+* Motivation and support for tracking the origin of each configuration value, with use cases such as: debug-level log reporting, enforced setting explanation, and editor pre-fill mes
+sages.
+
+Layered configuration supports system, user, project, and project-user scopes. Values can also be supplied via environment variables and CLI flags. See `docs/cli-spec.md` for flag mappings.
+
+### Keys
+
+- browserAutomation.enabled: boolean — enable/disable site automation.
+- browserAutomation.profile: string — preferred agent browser profile name.
+- browserAutomation.chatgptUsername: string — optional default ChatGPT username used for profile discovery.
+- codex.workspace: string — default Codex workspace to select before pressing "Code".
+
+### Behavior
 
-I’ll update the specification accordingly and present a refined version that reflects these requirements.
+- CLI flags override environment, which override project-user, project, user, then system scope.
+- On Windows, `~/.config` takes precedence over `%APPDATA%` only when both are present.
+- The CLI can read, write, and explain config values via `aw config`.