docs: Add more content and TODO items

Author: zah

.obsidian/workspace.json

@@ -20,6 +20,30 @@
               "icon": "lucide-file",
               "title": "cli-spec"
             }
+          },
+          {
+            "id": "cec459d507bf0a2b",
+            "type": "leaf",
+            "state": {
+              "type": "markdown",
+              "state": {
+                "file": "specs/fs-snapshots/overview.md",
+                "mode": "source",
+                "source": false,
+                "backlinks": true,
+                "backlinkOpts": {
+                  "collapseAll": false,
+                  "extraContext": false,
+                  "sortOrder": "alphabetical",
+                  "showSearch": false,
+                  "searchQuery": "",
+                  "backlinkCollapsed": false,
+                  "unlinkedCollapsed": true
+                }
+              },
+              "icon": "lucide-file",
+              "title": "overview"
+            }
           }
         ]
       }
@@ -53,7 +77,7 @@
             "state": {
               "type": "search",
               "state": {
-                "query": "",
+                "query": "incremental",
                 "matchingCase": false,
                 "explainSearch": false,
                 "collapseAll": false,
@@ -170,9 +194,33 @@
   },
   "active": "01bf72509d2b5652",
   "lastOpenFiles": [
-    "docs/state-persistence.md",
-    "specs/configuration.md",
+    "specs/@initial-developer-input/Configuration.md",
     "specs/cli-spec.md",
-    "specs/connectivity-layer.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/agent-time-travel.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/agents/_template.md",
+    "specs/@research"
   ]
 }

specs/@initial-developer-input/Configuration.md

@@ -0,0 +1,15 @@
+Help me create a specification for the configuration system of the Blocksense-network agents-workflow project (you can find it on GitHub) The configuration will respect multiple layers:
+
+1) Default values provided by the projects maintainers.
+2) OS-level configuration values that may be specified by a Linux distribution maintainer or a system administrator managing a team of users.
+3) User preferences stored in the profile
+4) Settings specified for a particular project in its GitHub repository.
+5) Per-project settings that may be overridden by the user.
+6) Settings specified in ENV variables
+7) Settings specified on the command line.
+
+The order above matches the order of priority with one exception. The system administrator can enforce certain setting preventing the user from overriding them. The system should be cross-platform. It will offer the same interface across all operating systems, but optionally may support OS-specific mechanisms that system administrators typically use for managing employee configurations in enterprise environments.
+
+We'll use TOML as the configuration format. I’m open to suggestions regarding the admin settings enforcement, but file system permissions seem like a reasonable way to handle this (or other similar read-only configuration stores). Our design should aim to provide consistent user experience across platforms, but it may provide an opt-in support for platform-specific approaches where this would enhance the ability of system administrators to manage the configuration of the employee’s computers in an enterprise environment. The agents workflow project is expected to have mobile clients/front-ends (iOS, Android, etc), so exploring their configurability options to cover our requirements will be good.
+
+We’ll prefix all ENV variables with AGENTS_WORKFLOW_ for maximum clarity in scripts where they are used. Each setting will have its own flag (e.g. —log-level) 3). We will support the `~/.config/…` directory on Windows too, as some users might prefer the consistency. When settings are available in both `APPDATA` and `~/.config`, the later will take precedence. Agents workflow already uses an `.agents` folder in the user’s repo, so we can store the per-project configuration files there. There will be a command `aw config` for reading and applying changes to the various configuration files. When you ask for a value of a particular setting, the tool will give you a detailed report in which files the setting appeared. This would serve as an explanation why it was enforced when this is the case. When the log level is increased to debug, the CLI tools will report the config files they are trying to read. The agent-task command presents an editor where the user enters the task description. Within the loaded editor, there are commented out lines that explain what the user must do. Within this message there will be also an indication of the action that will be executed after the editor is closed. This action will depend on the loaded configuration, so the message will indicate which configuration source specified it. This requires that the configuration loading system maintains information about the origin of each setting.  

specs/@initial-developer-input/WebUI, TUI, REST Service.md

@@ -0,0 +1,19 @@
+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.  
+  
+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.  
+  
+3) There will be a similar TUI, providing a dashboard of currently running tasks and allowing the launching of new tasks. It needs a PRD document and detailed spec of its UI. The TUI will be built around tmux, zellij or screen (all of them will be supported). The default view is a dashboard of the currently running tasks, featuring an easy way to start a new task. When a new task is launched, a new tmux windows is created split in two - on the right side the user sees the AI agent working. On the left side, a terminal is launched within the newly created per-task FS mount. The user can also decide to launch a text editor like vim, emacs or another instead of a terminal (since these editors have built-in terminal).  
+  
+4) The user will also be able to spawn the new task inside Visual Studio Code, Cursor or Windsurf (using their built-in agents).  
+  
+5) The user will be able to spawn a terminal-based agent, such as Claude Code next to a GUI editor launched in the task-specific FS mount.  
+  
+Usually the agents work in devcontainers, but it's possible to launch the agent locally with a more minimal sandbox or no sandbox at all (this is intended for environments that are already well-sandboxed, such as VMs)
+
+The WebUI will feature a list of repositories on the left. Each repo will feature a plus button that is used for the creation of a new task. In the central feed, the user sees the list of submitted tasks according to their chnological order. Each task card has sufficient status indicators and potentially a single line that live-updates with the last action of the agent. Clicking on a task adds another pane on the right with a live log of the task or a final report including the created diff. The feed of tasks and the list of projects can be collapsed to the left to take less space.
+
+When the new task button is pressed, this creates a new task card at the top of the task list. The card has a vertically resizable input box for the task description.  
+  
+Below it, there is a combo-box for selecting a branch, which comes preconfigured to the default branch for task creating in the repo (typically the main branch). You can also specify the coding agent and the number of concurrent instances (available for some of the agents). There is a right aligned button start. Before pressing start, any edits are auto saved in a draft mode. You can have multiple tasks as drafts. There is a button for deleting a draft.

specs/@research/Can SSH work over HTTPS?.md

@@ -0,0 +1,91 @@
+Yes—SSH can traverse an **HTTPS proxy**, but SSH itself doesn’t “speak HTTPS.” You have a few practical ways to make it work:
+
+# 1) HTTP/HTTPS CONNECT tunnel (most common)
+
+Use the proxy’s **CONNECT** method to create a raw TCP tunnel to your SSH server. From SSH’s point of view, it’s a normal TCP connection.
+
+- **No proxy auth (HTTP proxy on :8080):**
+    
+
+```bash
+ssh -o 'ProxyCommand=nc -X connect -x proxy.company.com:8080 %h %p' [email protected]
+```
+
+(Requires the OpenBSD flavor of `nc` that supports `-X connect -x`.)
+
+- **Proxy requires auth or TLS (“HTTPS proxy” on :443):**  
+    Use a helper that understands CONNECT + (optional) TLS and auth, e.g. **proxytunnel** or **corkscrew**.
+    
+
+```bash
+# HTTPS proxy (with or without Basic auth)
+ssh -o 'ProxyCommand=proxytunnel -p proxy.company.com:443 -d %h:%p' [email protected]
+# If needed, add auth:  -P user:pass
+```
+
+```bash
+# HTTP proxy with Basic auth
+ssh -o 'ProxyCommand=corkscrew proxy.company.com 8080 %h %p ~/.proxy-auth' [email protected]
+```
+
+> Notes
+> 
+> - Many corporate proxies only allow CONNECT to ports like **443**. If so, have your SSH server listen on 443 (or use a port-forwarder on the server) and CONNECT to that.
+>     
+> - Some proxies do TLS interception and require a real TLS handshake (ALPN/SNI). In that case, raw SSH on :443 won’t pass—use the TLS-wrapped options below.
+>     
+
+# 2) Wrap SSH in TLS so it “looks like HTTPS”
+
+If the proxy (or middleboxes) insist on seeing TLS, run a TLS wrapper on both ends and tunnel SSH through it.
+
+**Server (stunnel)**
+
+```ini
+[ssh]
+accept = 0.0.0.0:443
+cert   = /etc/ssl/certs/fullchain.pem
+key    = /etc/ssl/private/privkey.pem
+connect = 127.0.0.1:22
+```
+
+**Client (stunnel)**
+
+```ini
+[ssh]
+client = yes
+accept = 127.0.0.1:2222
+connect = your.domain.tld:443
+verifyChain = yes
+CAfile = /path/to/ca.pem
+```
+
+Then:
+
+```bash
+ssh -p 2222 [email protected]
+```
+
+This satisfies “HTTPS-like” inspection because a real TLS session is established first.
+
+# 3) SSH over WebSocket/HTTP2 (when CONNECT is restricted)
+
+Use a tool that tunnels TCP over **WSS** (WebSocket over TLS), e.g. **chisel**, **websocat**, etc. This often passes strict proxies/firewalls that permit only browser-like traffic.
+
+- Run a WSS server behind the proxy and a client locally, then point SSH at the local forwarded port.
+    
+
+---
+
+## Common pitfalls & tips
+
+- **Proxy policies:** Some proxies restrict CONNECT targets; use port 443 on the SSH server if necessary.
+    
+- **Auth schemes:** Basic is easy; NTLM/Kerberos may require a local helper like **cntlm** to convert to Basic for tools like corkscrew/proxytunnel.
+    
+- **OpenSSH options:** `ProxyCommand` is the knob for all of the above. (`ProxyJump` is for SSH jump hosts, not HTTP proxies.)
+    
+- **Security:** Still validate TLS (CAfile/verifyChain) when using TLS-wrappers; don’t send proxy creds in shell history.
+    
+
+If you share your OS and the proxy’s auth type (none/Basic/NTLM) I can give a copy-pasteable config tailored to your setup.