operator! walkthrough and vscode further adjustments

.github/workflows/vscode-extension.yaml

@@ -168,7 +168,7 @@ jobs:
     name: Publish to Marketplace
     needs: build-vsix
     runs-on: ubuntu-latest
-    if: github.event_name == 'workflow_dispatch' && github.event.inputs.publish == 'true'
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     steps:
       - uses: actions/checkout@v4
 

Cargo.toml

@@ -62,6 +62,7 @@ regex = "1"
 once_cell = "1"
 lazy_static = "1"
 backon = "1"
+which = "7"
 
 # System info (for core count)
 sysinfo = "0.32"

README.md

@@ -1,4 +1,4 @@
-![Operator! logo](./img/operator_logo.svg)
+![Operator! logo](docs/assets/img/operator_logo.svg)
 
 # Operator!
 

bindings/OperatorOutput.ts

@@ -0,0 +1,53 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Standardized agent output for progress tracking and step transitions.
+ *
+ * Agents output a status block in their response which is parsed into this structure.
+ * Used for progress tracking, loop detection, and intelligent step transitions.
+ */
+export type OperatorOutput = { 
+/**
+ * Current work status: in_progress, complete, blocked, failed
+ */
+status: string, 
+/**
+ * Agent signals done with step (true) or more work remains (false)
+ */
+exit_signal: boolean, 
+/**
+ * Agent's confidence in completion (0-100%)
+ */
+confidence: number | null, 
+/**
+ * Number of files changed this iteration
+ */
+files_modified: number | null, 
+/**
+ * Test suite status: passing, failing, skipped, not_run
+ */
+tests_status: string | null, 
+/**
+ * Number of errors encountered
+ */
+error_count: number | null, 
+/**
+ * Number of sub-tasks completed this iteration
+ */
+tasks_completed: number | null, 
+/**
+ * Estimated remaining sub-tasks
+ */
+tasks_remaining: number | null, 
+/**
+ * Brief description of work done (max 500 chars)
+ */
+summary: string | null, 
+/**
+ * Suggested next action (max 200 chars)
+ */
+recommendation: string | null, 
+/**
+ * Issues preventing progress (signals intervention needed)
+ */
+blockers: Array<string> | null, };

bindings/StepCompleteRequest.ts

@@ -1,4 +1,5 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { OperatorOutput } from "./OperatorOutput";
 
 /**
  * Request to report step completion (from opr8r wrapper)
@@ -27,4 +28,8 @@ duration_secs: bigint,
 /**
  * Sample of the output (first N chars for debugging)
  */
-output_sample: string | null, };
+output_sample: string | null, 
+/**
+ * Structured output from agent (parsed OPERATOR_STATUS block)
+ */
+output: OperatorOutput | null, };

bindings/StepCompleteResponse.ts

@@ -6,7 +6,7 @@ import type { NextStepInfo } from "./NextStepInfo";
  */
 export type StepCompleteResponse = { 
 /**
- * Status of the step: "completed", "awaiting_review", "failed"
+ * Status of the step: "completed", "awaiting_review", "failed", "iterate"
  */
 status: string, 
 /**
@@ -20,4 +20,36 @@ auto_proceed: boolean,
 /**
  * Command to execute for the next step (opr8r wrapped)
  */
-next_command: string | null, };
+next_command: string | null, 
+/**
+ * Whether OperatorOutput was successfully parsed from agent output
+ */
+output_valid: boolean, 
+/**
+ * Agent has more work (exit_signal=false) - indicates iteration needed
+ */
+should_iterate: boolean, 
+/**
+ * How many times this step has run (for circuit breaker)
+ */
+iteration_count: number, 
+/**
+ * Circuit breaker state: closed (normal), half_open (monitoring), open (halted)
+ */
+circuit_state: string, 
+/**
+ * Summary from previous step's OperatorOutput
+ */
+previous_summary: string | null, 
+/**
+ * Recommendation from previous step's OperatorOutput
+ */
+previous_recommendation: string | null, 
+/**
+ * Cumulative files modified across iterations
+ */
+cumulative_files_modified: number, 
+/**
+ * Cumulative errors across iterations
+ */
+cumulative_errors: number, };

docs/_includes/head.html

@@ -4,8 +4,8 @@
   <title>{% if page.title %}{{ page.title }} | {% endif %}{{ site.title }}</title>
   <meta name="description" content="{{ page.description | default: site.description }}">
 
-  <link rel="icon" type="image/png" href="{{ '/assets/patricia_512.png' | relative_url }}">
-  <link rel="apple-touch-icon" href="{{ '/assets/patricia_512.png' | relative_url }}">
+  <link rel="icon" type="image/png" href="{{ '/assets/img/patricia_512.png' | relative_url }}">
+  <link rel="apple-touch-icon" href="{{ '/assets/img/patricia_512.png' | relative_url }}">
 
   <script>
     (function() {

docs/getting-started/installation.md

@@ -6,29 +6,54 @@ layout: doc
 
 # Installation
 
-This guide covers installing Operator on macOS.
+This guide covers installing Operator on macOS, Linux, and Windows.
 
-## Download
+## VS Code Extension (Recommended)
 
-Get the latest release from the [Downloads](/downloads/) page or use the command line:
+The **VS Code Extension** is the recommended way to get started with Operator.
+<a href="https://marketplace.visualstudio.com/items?itemName=untra.operator-terminals" target="_blank" class="button">Install from VS Code Marketplace</a>
+
+Works on **macOS**, **Linux**, and **Windows** - no additional setup required.
+
+For detailed setup instructions, see the [VS Code Extension documentation](/getting-started/sessions/vscode/).
+
+---
+
+## CLI Installation (Alternative)
+
+For headless servers, CI/CD pipelines, or advanced workflows, install the CLI binary for your platform.
+
+### macOS
 
 ```bash
 # Apple Silicon (M1/M2/M3)
 curl -L https://github.com/untra/operator/releases/latest/download/operator-macos-arm64 -o operator
-
-# Intel Mac
-curl -L https://github.com/untra/operator/releases/latest/download/operator-macos-x86_64 -o operator
+chmod +x operator
+sudo mv operator /usr/local/bin/
 ```
 
-## Install
-
-Move the binary to your PATH:
+### Linux
 
 ```bash
+# ARM64
+curl -L https://github.com/untra/operator/releases/latest/download/operator-linux-arm64 -o operator
+
+# x86_64
+curl -L https://github.com/untra/operator/releases/latest/download/operator-linux-x86_64 -o operator
+
 chmod +x operator
 sudo mv operator /usr/local/bin/
 ```
 
+### Windows (PowerShell)
+
+```powershell
+Invoke-WebRequest -Uri "https://github.com/untra/operator/releases/latest/download/operator-windows-x86_64.exe" -OutFile "operator.exe"
+# Add to PATH or move to desired location
+```
+
+For checksums and all available downloads, see the [Downloads](/downloads/) page.
+
 ## Verify Installation
 
 Confirm Operator is installed correctly:
@@ -45,12 +70,15 @@ Create a configuration file:
 operator init
 ```
 
-This creates `~/.config/operator/config.toml` with default settings.
+This creates the configuration file with default settings:
+- **macOS/Linux**: `~/.config/operator/config.toml`
+- **Windows**: `%APPDATA%\operator\config.toml`
 
 ## Next Steps
 
 Configure your integrations:
 
+- [Set up a Session Manager](/getting-started/sessions/)
 - [Set up a Coding Agent](/getting-started/agents/claude/)
 - [Connect your Kanban Provider](/getting-started/kanban/jira/)
 - [Link your Git Repository](/getting-started/git/github/)

docs/getting-started/kanban/jira.md

@@ -6,7 +6,7 @@ layout: doc
 
 # Jira Cloud
 
-Connect Operator to Jira Cloud for issue tracking and project management.
+Connect Operator to [**Jira Cloud**](https://www.atlassian.com/software/jira) for issue tracking and project management.
 
 ## Prerequisites
 

docs/getting-started/kanban/linear.md

@@ -6,7 +6,7 @@ layout: doc
 
 # Linear
 
-Connect Operator to Linear for modern issue tracking and project management.
+Connect Operator to [**Linear**](https://linear.app/features) for modern issue tracking and project management.
 
 ## Prerequisites