specs: Fixes in the CLI and Configuration specs

Author: zah

.agents/codebase-insights.txt

@@ -37,12 +37,13 @@
 - Local state uses a canonical SQLite DB; there is no local daemon. See docs/state-persistence.md for selection rules and SQL schema.
 
 ## Config Mapping Notes
-- TOML preserves dashes in keys (e.g., `network.api-url`, `tui.default-mode`, `repo.task-runner`).
-- ENV/JSON use underscores for those keys (e.g., `AGENTS_WORKFLOW_NETWORK_API_URL`). See specs/configuration.md.
+- CLI flags are kebab-case (e.g., `--task-runner`, `--browser-automation`, `--browser-profile`, `--chatgpt-username`).
+- TOML preserves dashes in keys and matches CLI names unless it’s a subcommand section (e.g., `repo.task-runner`, `network-api-url` → now `service-base-url`, `browser-automation`, `browser-profile`, `chatgpt-username`).
+- ENV/JSON replace dashes with underscores: `AGENTS_WORKFLOW_REPO_TASK_RUNNER`, `AGENTS_WORKFLOW_BROWSER_AUTOMATION`, etc. See specs/Public/Configuration.md.
 
 ## 2025-08-28 — Spec TODOs addressed
-- Added `ui.default` config key (schema + docs) to control whether bare `aw` launches TUI or WebUI (default: `tui`).
-- Fixed CLI config mapping examples to follow mechanical rules (camelCase in nested keys like `apiUrl`, `chatgptUsername`).
+- Replaced `ui.default` with a single `ui` key (schema + docs). Bare `aw` reads `ui` to pick TUI/WebUI (default: `tui`).
+- Fixed CLI↔config↔ENV mapping to kebab-case ↔ lowerCamelCase ↔ UPPER_SNAKE.
 - Clarified snapshot selection semantics in CLI spec: strategy is chosen by the executing host; leader-only snapshots in fleets.
 - Expanded `sandbox-profiles` with motivations, predefined types, and OS guidance.
 - WebUI tech note now picks React + Vite + TypeScript as the non-binding default.

.gitignore

@@ -5,3 +5,6 @@ test/logs/
 
 # Debugger temp files
 .rdbgrc.breakpoints
+
+# linter cache
+.rubocop-cache/

.obsidian/workspace.json

@@ -13,12 +13,12 @@
             "state": {
               "type": "markdown",
               "state": {
-                "file": "specs/Public/3rd-Party Agents/3rd-Party Agent Description Template.md",
+                "file": "specs/Public/CLI.md",
                 "mode": "source",
                 "source": false
               },
               "icon": "lucide-file",
-              "title": "3rd-Party Agent Description Template"
+              "title": "CLI"
             }
           },
           {
@@ -102,7 +102,7 @@
       }
     ],
     "direction": "horizontal",
-    "width": 384.5
+    "width": 266.5
   },
   "right": {
     "id": "6bab4bb451c2c34d",
@@ -194,6 +194,10 @@
   },
   "active": "01bf72509d2b5652",
   "lastOpenFiles": [
+    "scripts/md-mermaid-validate.sh",
+    "specs/Public/Configuration.md",
+    "specs/Public/CLI.md",
+    "specs/Public/3rd-Party Agents/3rd-Party Agent Description Template.md",
     "specs/Public/Nix Devcontainer/Devcontainer User Setup.md",
     "specs/Public/Nix Devcontainer/Devcontainer Design.md",
     "specs/Public/Nix Devcontainer/Devcontainer Test Suite.md",
@@ -205,8 +209,6 @@
     "specs/Public/Lima VM Images.md",
     "specs/Public/AGENTS.md",
     "specs/Public/Agent Time Travel.md",
-    "specs/Public/Configuration.md",
-    "specs/Public/CLI.md",
     "specs/Public/WebUI PRD.md",
     "specs/Public/TUI PRD.md",
     "specs/Initial Developer Input/WebUI, TUI, REST Service.md",
@@ -224,8 +226,6 @@
     "test/logs/test_run_20250828_001209.log",
     "specs/Initial Developer Input/Configuration.md",
     "specs/Initial Developer Input",
-    "specs/Public/FS Snapshots/milestone_5.md",
-    "specs/Public/FS Snapshots/milestone_4.md",
     "specs/Research"
   ]
 }

specs/Public/Browser Automation/Codex.md

@@ -16,7 +16,7 @@ Automate the Codex WebUI to initiate a coding session for a repository/branch us
 6. Launch Playwright with a persistent context in headless mode.
 7. If the expected login is not present, relaunch in visible mode to let the user authenticate, then continue.
 8. Navigate to Codex, select workspace and branch, enter the task description, and press "Code":
-   - Workspace comes from `--codex-workspace` or `config: codex.workspace` (see `docs/configuration.md`).
+   - Workspace comes from `--codex-workspace` or `config: codex-workspace` (see `docs/configuration.md`).
    - Branch comes from the `aw task --branch` value.
 9. Record success.
 
@@ -32,11 +32,10 @@ Controlled via AW configuration (see `docs/cli-spec.md` and `docs/configuration.
 
 - Enable/disable automation for `aw task`.
 - Select or override the agent browser profile name.
-- Set default Codex workspace: `codex.workspace`.
+- Set default Codex workspace: `codex-workspace`.
 
 ### Notes
 
 - Playwright selectors should prefer role/aria/test id attributes to resist UI text changes.
 - Use stable navigation points inside Codex (workspace and branch selectors) and fail fast with helpful error messages when not found; optionally open DevTools in headful mode for investigation.
 
-

specs/Public/CLI.md

@@ -25,9 +25,9 @@ The CLI honors the layered configuration model in [Configuration](Configuration.
 - **Sandbox profiles (orthogonal):** When launching locally, sandbox profiles define the isolation level (container, VM, bwrap/firejail, or unsandboxed per policy). See [Sandbox Profiles](Sandbox%20Profiles.md) and configuration mapping below.
 
 ### Global Behavior and Flags
-TODO: we don't use config values like `ui.default`. See our naming convention in [Mapping Rules (Flags ↔ Config ↔ ENV/JSON)](Configuration.md#Mapping%20Rules%20(Flags%20↔%20Config%20↔%20ENV/JSON)). This should be renamed to something like `ui`
+Naming consistency: the config key controlling UI selection is `ui`, not `ui.default`.
 
-- `aw` (no args): Launches the default UI (TUI by default). Config key `ui.default` controls TUI vs WebUI; built‑in default is `tui`.
+- `aw` (no args): Launches the default UI (TUI by default). Config key `ui` controls TUI vs WebUI; built‑in default is `tui`.
 - Common global flags (apply to all subcommands unless noted):  
   - `--remote-server <NAME|URL>`: If provided, use the REST API at this server (by name lookup in config or raw URL). Otherwise use local SQLite state.
   - `--repo <PATH|URL>`: Target repository (filesystem path in local runs; git URL may be used by some servers). If omitted, AW auto-detects a VCS root by walking parent directories and checking all supported VCS.
@@ -56,20 +56,21 @@ Behavior overview:
 - Sandbox/runtime: Local runs honor `--runtime`: `devcontainer` (default when available), `local` (process sandbox/profile), or `unsandboxed` (policy‑gated). See [Sandbox Profiles](Sandbox%20Profiles.md) and [FS Snapshots/FS Snapshots Overview](FS%20Snapshots/FS%20Snapshots%20Overview.md).
 
 Flow (high‑level):
-TODO: the following mermaid diagram has a syntax issues. Please install tools in you nix flake, so you can debug them and fix them (you'll have to use `nix develop --command` when launching the tools)
 
 ```mermaid
 flowchart TD
   A[aw task ...] --> B{remote-server?}
-  B -- yes --> C[REST: POST /tasks]
-  C --> D{agent on server or 3rd-party cloud?}
-  D -- server --> E[Provision runtime + snapshot]
-  D -- 3rd-party --> F[Call provider API (capability‑gated flags)]
-  B -- no --> G{runtime}
-  G -- devcontainer --> H[Devcontainer: mount snapshot workspace]
-  G -- local --> I[Process sandbox profile]
-  G -- unsandboxed --> J[Host process (policy‑gated)]
-  H & I & J --> K[Run agent + record session]
+  B -->|yes| C[REST POST /tasks]
+  C --> D{agent runs where?}
+  D -->|server| E[Provision runtime and snapshot]
+  D -->|third party| F[Call provider API capability gated flags]
+  B -->|no| G{runtime}
+  G -->|devcontainer| H[Devcontainer mount snapshot workspace]
+  G -->|local| I[Process sandbox profile]
+  G -->|unsandboxed| J[Host process policy gated]
+  H --> K[Run agent + record session]
+  I --> K
+  J --> K
 ```
 
 Behavior:
@@ -230,14 +231,7 @@ Mirrors `docs/configuration.md` including provenance, precedence, and Windows be
 - `aw webui [--bind (default=127.0.0.1)] [--port <P>] [--rest <URL>]`
   - Serves the WebUI for local use; in `--local` it binds to `127.0.0.1` and hides admin features.
 
-#### 9) Utilities
-#### 10) Followers and Multi‑OS
-
-- `aw followers list` — List configured follower hosts and tags (used for diagnostic purposes).
-- `aw followers sync-fence [--timeout <sec>] [--tag <k=v>]... [--host <name>]... [--all]` — Perform a synchronization fence, ensuring followers match the leader workspace state.
-- `aw run-everywhere [--tag <k=v>]... [--host <name>]... [--all] [--] <command> [args...]` — Invoke run‑everywhere on selected followers.
-
-#### 11) Connectivity (Overlay/Relay)
+#### 9) Connectivity (Overlay/Relay)
 
 - `aw connect keys [--provider netbird|tailscale|auto] [--tag <name>]...` — Request session connectivity credentials.
 - `aw connect handshake --session <id> [--hosts <list>] [--timeout <sec>]` — Initiate and wait for follower acks; prints per‑host status.
@@ -250,11 +244,13 @@ Mirrors `docs/configuration.md` including provenance, precedence, and Windows be
 - `aw doctor` — Environment diagnostics (snapshot providers, multiplexer availability, docker/devcontainer, git).
 - `aw completion [bash|zsh|fish|pwsh]` — Shell completions.
 
-Agent-only utilities and startup performance:
-
-- Subcommands used only in agent dev environments move under `aw agent ...` (e.g., the legacy `get-task` and `start-work` helpers, and the `followers` command). This keeps end‑user command space clean while still scriptable for agents.
-  
-  TODO: You must update the document above, so it matches the intention here. `get-task` and `start-work` should be defined in the spec with their existing functionality and semantics. The `followers` command just need to be moved under the new `agent` sub-command section. Once this is done, you can remove the above bullet point.
+#### 10) Agent Utilities (`aw agent ...`)
+*  Subcommands used only in agent dev environments live under `aw agent ...`. This keeps end‑user command space clean while still scriptable for agents.
+- `aw agent get-task` — Helper used by terminal‑style agents to fetch the next task payload (prompt, repo, settings) from the local state or configured REST service and print it as JSON. Honors the same `--remote-server` and `--repo` resolution as `aw task`.
+- `aw agent start-work` — Helper to mark the current task as started (transition status, open logs) and emit initial SessionMoment metadata so timeline recording aligns with agent startup. Prints the session id.
+- `aw agent followers list` — List configured follower hosts and tags (diagnostics; same data as `GET /api/v1/followers` when in REST mode).
+- `aw agent followers sync-fence [--timeout <sec>] [--tag <k=v>]... [--host <name>]... [--all]` — Perform a synchronization fence ensuring followers match the leader snapshot before execution; emits per‑host status.
+- `aw agent run-everywhere [--tag <k=v>]... [--host <name>]... [--all] [--] <command> [args...]` — Invoke run‑everywhere on selected followers.
 
 ### Subcommand Implementation Strategy
 
@@ -268,7 +264,7 @@ Local enumeration and management of running sessions is backed by the canonical
 
 Selection:
 
-- `--multiplexer` flag or `terminal.multiplexer` config determines which tool is used. Autodetect if unset (tmux > zellij > screen if found in PATH).
+- `--multiplexer` flag or `terminal-multiplexer` config determines which tool is used. Autodetect if unset (tmux > zellij > screen if found in PATH).
 
 Layout on launch:
 
@@ -309,14 +305,22 @@ aw task \
   --instances 2
 ```
 
-TODO: This example is potentially confusing. The browser profile will be used only when the automation is enabled. The labels suggest codex is used, but this is not specified on the command-line with --agent codex
-
-Specify a browser profile and disable automation explicitly:
+Specify Codex with automation enabled and a specific browser profile:
 
 ```bash
 aw task \
   --prompt "Kick off Codex" \
+  --agent codex \
   --browser-profile work-codex \
+  --browser-automation true
+```
+
+Run without web automation (browser profile is ignored when automation is disabled):
+
+```bash
+aw task \
+  --prompt "Run without web automation" \
+  --agent openhands \
   --browser-automation false
 ```
 

specs/Public/Configuration.md

@@ -30,7 +30,7 @@ Paths are illustrative; the CLI prints the exact search order in `aw config --ex
 
 Enterprise deployments may enforce specific keys at the System scope. Enforced values are read‑only to lower scopes. The CLI surfaces enforcement in `aw config get --explain <key>` output and prevents writes with a clear error. See the initial rationale in [Configuration](../Initial%20Developer%20Input/Configuration.md).
 
-TODO: In other documents, there are still suggested options that don't match the convention below (for example, `ui.default`). Per this convention, the option can be named just `ui`, because this would read best on the command line `aw --ui web`. Look for other similar violations and fix them.
+Use a single key `ui` (not `ui.default`) to control the default UI.
 
 ### Mapping Rules (Flags ↔ Config ↔ ENV/JSON)
 To keep things mechanical and predictable:
@@ -44,16 +44,16 @@ Examples:
 
 - Flag `--remote-server` ↔ TOML `remote-server` ↔ ENV `AGENTS_WORKFLOW_REMOTE_SERVER`
 - Per-server URLs are defined under `[[server]]` entries; `remote-server` may refer to a server `name` or be a raw URL.
-- Flag `--network-api-url` (rarely needed) maps to a specific server entry’s `url`.
+- WebUI-only: key `service-base-url` selects the REST base URL used by the browser client when the WebUI is hosted persistently at a fixed origin.
 - Flag `--task-runner` ↔ TOML `repo.task-runner` ↔ ENV `AGENTS_WORKFLOW_REPO_TASK_RUNNER`
 
 ### Keys
 
-- ui.default: string — default UI to launch with bare `aw` (`"tui"` | `"webui"`).
-- 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".
+- ui: string — default UI to launch with bare `aw` (`"tui"` | `"webui"`).
+- browser-automation: boolean — enable/disable site automation.
+- browser-profile: string — preferred agent browser profile name.
+- chatgpt-username: string — optional default ChatGPT username used for profile discovery.
+- codex-workspace: string — default Codex workspace to select before pressing "Code".
 - remote-server: string — either a known server `name` (from `[[server]]`) or a raw URL. If set, AW uses REST; otherwise it uses local SQLite state.
 
 ### Behavior
@@ -142,29 +142,26 @@ type = "container"      # predefined types with their own options
 Flags and mapping:
 - `--remote-server <NAME|URL>` selects a server (overrides `remote-server` in config).
 - `--fleet <NAME>` selects a fleet; default is the fleet named `default`.
-- Bare `aw` uses `ui.default` to decide between TUI and WebUI (defaults to `tui`).
+- Bare `aw` uses `ui` to decide between TUI and WebUI (defaults to `tui`).
 
 ### Example TOML (partial)
 
 ```toml
-logLevel = "info"
+log-level = "info"
 
-[terminal]
-multiplexer = "tmux"
+terminal-multiplexer = "tmux"
 
-[editor]
-default = "nvim"
+editor = "nvim"
 
-[network]
-api-url = "https://deprecated.example.invalid"  # prefer [[server]] + remote-server
+service-base-url = "https://aw.office-1.corp/api"  # WebUI fetch base; browser calls this URL
 
-[browserAutomation]
-enabled = true
-profile = "work-codex"
+# Browser automation (no subcommand section; single keys match CLI flags)
+browser-automation = true
+browser-profile = "work-codex"
 chatgpt-username = "[email protected]"
 
-[codex]
-workspace = "main"
+# Codex workspace (single key)
+codex-workspace = "main"
 
 [repo]
 supported-agents = "all" # or ["codex","claude","cursor"]
@@ -178,7 +175,7 @@ supported-agents = "all" # or ["codex","claude","cursor"]
 ```
 
 Notes:
-- `supported-agents` accepts "all" or an explicit array of agent names; the CLI may normalize this value internally.
+- `supportedAgents` accepts "all" or an explicit array of agent names; the CLI may normalize this value internally.
 - `devenv` accepts values like `nix`, `spack`, `bazel`, `none`/`no`, or `custom`.
 
 ENV examples:

specs/Public/Multi-OS Testing.md

@@ -103,9 +103,9 @@ run-everywhere --host win-12 -- lint
 
 ### CLI Additions (high‑level)
 
-- `aw followers list` — show followers and status.
-- `aw followers sync-fence [--timeout s] [--tag ... | --host ... | --all]`
-- `aw run-everywhere <action> [args...] [--tag ... | --host ... | --all]`
+- `aw agent followers list` — show followers and status.
+- `aw agent followers sync-fence [--timeout s] [--tag ... | --host ... | --all]`
+- `aw agent run-everywhere <action> [args...] [--tag ... | --host ... | --all]`
 
 ### Time‑Travel Integration
 
@@ -137,4 +137,3 @@ See `docs/connectivity-layer.md` for overlay options (Tailscale/Headscale, NetBi
 
 Fallback relay: If overlays are unavailable, the coordinator can act as a relay by subscribing to per-host SSE logs and forwarding messages (pub/sub) between leader and followers. This preserves basic run‑everywhere semantics at higher latency.
 
-

specs/Public/Schemas/config.schema.json

@@ -39,13 +39,7 @@
     "UiDefault": { "type": "string", "enum": ["tui", "webui"] }
   },
   "properties": {
-    "ui": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "default": { "$ref": "#/$defs/UiDefault" }
-      }
-    },
+    "ui": { "$ref": "#/$defs/UiDefault" },
     "tui": {
       "type": "object",
       "additionalProperties": false,

specs/Public/WebUI PRD.md

@@ -176,7 +176,8 @@ The WebUI provides a browser-based experience for creating, monitoring, and mana
 - Invocation: `webui --local [--port <port>]` (command name illustrative). In this mode:
   - Network binding: HTTP server listens on localhost only.
   - Auth and tenancy: No RBAC/tenants; implicit single user. Admin pages are hidden (Agents/Runtimes/Hosts/Settings for multi-tenant ops).
-  - Config discovery: API base URL resolved from config key `network.apiUrl` or env `AGENTS_WORKFLOW_NETWORK_API_URL`; otherwise defaults to `http://127.0.0.1:<default-port>`.
+  - Config discovery: API base URL resolved from config key `service-base-url` or env `AGENTS_WORKFLOW_SERVICE_BASE_URL`; otherwise defaults to `http://127.0.0.1:<default-port>`.
+  - Intention: `service-base-url` is primarily for deployments hosting a persistent WebUI at a fixed URL (e.g., behind an ingress/LB) so the browser knows which REST origin to call. In local development, leave it unset and the WebUI will target localhost by default.
   - IDE integration: Unchanged; IDE launch helpers assume local filesystem access to the workspace mount.
   - Persistence: Uses browser local storage for UI preferences. No external DB required.
   - Security: No TLS in local mode; not intended for remote access.
@@ -187,4 +188,3 @@ The WebUI provides a browser-based experience for creating, monitoring, and mana
   - Hidden sections: Agents, Runtimes, Hosts, multi-tenant Settings.
   - Sessions, Create Task, and basic Settings (local) remain.
   - Delivery flows (PR/branch/patch) are available; features gated by what the local service advertises via `/api/v1/*` capability endpoints.
-