specs: New repository structure with additional instructions and new TODO items

Author: zah

.agents/codebase-insights.txt

@@ -39,3 +39,10 @@
 ## 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.
+
+## 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`).
+- 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.

.obsidian/workspace.json

@@ -13,12 +13,12 @@
             "state": {
               "type": "markdown",
               "state": {
-                "file": "specs/AGENTS.md",
+                "file": "specs/Public/3rd-Party Agents/3rd-Party Agent Description Template.md",
                 "mode": "source",
                 "source": false
               },
               "icon": "lucide-file",
-              "title": "AGENTS"
+              "title": "3rd-Party Agent Description Template"
             }
           },
           {
@@ -27,7 +27,7 @@
             "state": {
               "type": "markdown",
               "state": {
-                "file": "specs/fs-snapshots/overview.md",
+                "file": "specs/Public/FS Snapshots/FS Snapshots Overview.md",
                 "mode": "source",
                 "source": false,
                 "backlinks": true,
@@ -42,7 +42,7 @@
                 }
               },
               "icon": "lucide-file",
-              "title": "overview"
+              "title": "FS Snapshots Overview"
             }
           }
         ]
@@ -102,7 +102,7 @@
       }
     ],
     "direction": "horizontal",
-    "width": 300
+    "width": 384.5
   },
   "right": {
     "id": "6bab4bb451c2c34d",
@@ -194,33 +194,38 @@
   },
   "active": "01bf72509d2b5652",
   "lastOpenFiles": [
-    "specs/agent-time-travel.md",
-    "specs/AGENTS.md",
-    "specs/cli-spec.md",
-    "specs/@initial-developer-input/Configuration.md",
-    "specs/@initial-developer-input/WebUI, TUI, REST Service.md",
-    "specs/@initial-developer-input",
-    "specs/local-mode.md",
-    "specs/fs-snapshots/overview.md",
-    "specs/fs-snapshots/milestone_5.md",
-    "specs/fs-snapshots/milestone_4.md",
-    "specs/fs-snapshots/milestone_3.md",
-    "specs/fs-snapshots/milestone_2.md",
-    "specs/fs-snapshots/milestone_1.md",
-    "specs/webui-prd.md",
-    "specs/tui-prd.md",
-    "specs/rest-service.md",
-    "specs/sandbox-profiles.md",
-    "specs/remote-mode.md",
-    "specs/prompt-engineering.md",
-    "specs/multi-os-testing.md",
-    "specs/lima-vm-images.md",
-    "specs/extras-framework.md",
-    "specs/devcontainer-setup.md",
-    "specs/devcontainer-design.md",
-    "specs/connectivity-layer.md",
-    "specs/configuration.md",
-    "specs/schemas/AGENTS.md",
-    "specs/@research"
+    "specs/Public/Nix Devcontainer/Devcontainer User Setup.md",
+    "specs/Public/Nix Devcontainer/Devcontainer Design.md",
+    "specs/Public/Nix Devcontainer/Devcontainer Test Suite.md",
+    "specs/Public/Nix Devcontainer/Devcontainer Cache Guidelines.md",
+    "specs/Public/FS Snapshots/FS Snapshots Overview.md",
+    "specs/Public/Agent Browsers/Agent Browser Profiles.md",
+    "specs/Public/Browser Automation/Codex.md",
+    "specs/Public/Extras Framework.md",
+    "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",
+    "specs/Public",
+    "specs/Public/Connectivity Layer.md",
+    "specs/Public/Prompt Engineering.md",
+    "specs/Public/REST Service.md",
+    "specs/Public/Sandbox Profiles.md",
+    "specs/Public/Multi-OS Testing.md",
+    "specs/Public/Remote Mode.md",
+    "specs/Public/Local Mode.md",
+    "agent-task-0.1.0.gem",
+    "test/logs/temp_output_20250828_001209.log",
+    "test/temp_test_runner_1756329129.rb",
+    "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/AGENTS.md

@@ -1,6 +1,6 @@
 I'd like to write few more specs in the docs folder. Before we start please read the existing docs.  
 
-1) It will be possible to launch agents-workflow as a REST service. The service will be able to spawn tasks on demand and list currently active coding sessions (as explained in [fs-snapshots-overview](../fs-snapshots/overview.md)). We need a document describing the purpose of this service and its specification. It's intended for usage by companies that set up on-premise or private cloud clusters for running coding tasks or for developers who prefer a WebUI experience.  
+1) It will be possible to launch agents-workflow as a REST service. The service will be able to spawn tasks on demand and list currently active coding sessions (as explained in [fs-snapshots-overview](../Public/FS%20Snapshots/FS%20Snapshots%20Overview.md)). We need a document describing the purpose of this service and its specification. It's intended for usage by companies that set up on-premise or private cloud clusters for running coding tasks or for developers who prefer a WebUI experience.  
 
 2) There will be a WebUI front-end that will consume the REST service. It needs something like PRD document and detailed spec of its UI.  
 

specs/@initial-developer-input/Configuration.md renamed to specs/Initial Developer Input/Configuration.md

@@ -0,0 +1,15 @@
+This folder contains a work-in-progress specification for the next iteration of the agents-workflow product.
+
+The main ideas of the product are described in the [marketing-one-pager](../../docs/marketing-one-pager.md) document. Please read it.
+
+Currently, the spec is not finalized and we are not ready to start the implementation of the software. The folder `specs/Initial Developer Input` contains files that should be treated as a ground truth for the specification effort. You are expected to work on the markdown files in the `specs/Public` folder, which should detail everything with a much higher precision, but please note that not all information in them has been fully reviewed by the development team yet.
+
+Files in the public folder should never refer to documents in the `specs/Initial Developer Input` folder or the `specs/Research` folder, where we put preliminary-research findings that also haven't been fully vetted.
+
+Your goal is to build a very comprehensive specification, meeting the goals stated in the initial developer input and expanding upon them with solid research and engineering. You may use the information provided in the preliminary research findings, but please verify it, potentially by building a small PoC programs.
+
+The public spec should be a stand-alone document that never references other folders. In other words, your job is to transform the content from the other folders into a high-quality spec.
+
+For each file in the `spec/Public` folder, there will be a corresponding file in the `spec/Implementation Progress` folder. This is a place to store information regarding what was already prototyped or implemented for production use. The files in this folder should contain references to source code files that are a good starting point for someone who wants to see the code behind the spec.
+
+Some of the markdown files have standardized Obsidian headers indicating their current review status. Avoid modifying files with status "Reviewed" or "Final" unless explicitly asked.